Developer notes for the rootstuff-block-permissions WordPress plugin. User-facing documentation lives in readme.txt (which is what WordPress.org renders).

• Backend: PHP 7.4+, two singleton classes under includes/.
• Frontend: React via @wordpress/element, @wordpress/components, built with @wordpress/scripts.
• Persistence: A single WordPress option (rootstuff_bp_settings).
• Save channel: A scoped REST endpoint (/wp-json/rootstuff-block-permissions/v1/settings).

rootstuff-block-permissions/
├── rootstuff-block-permissions.php   # plugin header, bootstraps singletons
├── includes/
│   ├── class-rootstuff-block-permissions.php        # runtime: rule resolution, filters
│   └── class-rootstuff-block-permissions-admin.php  # admin menu, REST, asset enqueue
├── src/
│   ├── admin.js     # React entry point
│   ├── App.jsx      # main settings UI
│   └── state.js     # pure state helpers
├── assets/
│   └── admin.css    # design tokens + layout for the settings page
├── build/           # wp-scripts output (committed for distribution convenience)
├── languages/       # translation .mo/.po files (empty in source)
├── scripts/
│   ├── render-wporg-assets.mjs  # SVG -> PNG renderer (sharp)
│   └── package.mjs              # build a clean release ZIP
├── wporg-assets/    # icon, banner, screenshots for the WP.org listing
├── readme.txt       # user-facing docs (WP.org format)
└── uninstall.php    # cleans up options on plugin delete

Persisted under the rootstuff_bp_settings option:

[
    'applyToAdmins'         => bool,
    'disableCorePatterns'   => bool,
    'disableRemotePatterns' => bool,
    'rules' => [
        '*::*'         => ['hiddenBlocks' => [...names], 'hiddenPatterns' => [...names]],
        'editor::page' => ['hiddenBlocks' => [...names], 'hiddenPatterns' => [...names]],
        // Only "override on" rules are persisted. Missing keys fall back to
        // the most-specific match: role::pt, role::*, *::pt, *::*.
    ],
]

The React UI works in terms of allowed sets for ergonomic toggling but converts back to hidden arrays in buildSavePayload before sending to the REST endpoint. That keeps the on-disk shape stable when new blocks/patterns are registered later (they default to allowed).

npm install
npm run start    # webpack watch mode for src/
npm run build    # one-off production build
npm run lint:js
npm run format

The settings page is at Settings → Rootstuff Block Permissions after activating the plugin.

npm run wporg:assets   # render icon/banner PNGs from SVG sources
npm run package        # produce dist/rootstuff-block-permissions.zip

The release ZIP excludes src/, node_modules/, scripts/, wporg-assets/, and other dev artifacts. It contains only the runtime files needed by WordPress.

GPL-2.0-or-later.