This article is a quick reference map of every file and class a block developer may need to interact with. It is not a tutorial, each system has its own dedicated chapter.
Plugin Directory Layout
wptruss/
├── truss.php Main plugin file. Boots all subsystems.
├── custom-blocks/ Installed custom blocks live here (flat).
│ └── {slug}/
│ ├── block.json
│ ├── index.js
│ ├── index.asset.php
│ ├── style.css
│ └── render.php
├── src/
│ ├── elements.js Cascade resolver. Exposes window.wptElements.
│ ├── element-validator.js Validates loaded element definitions on editor boot.
│ ├── override.elements.js Powers the element override modal UI.
│ ├── elements/ 18 element definition files (IIFE globals).
│ │ ├── heading.js
│ │ ├── button.js
│ │ ├── description.js
│ │ └── ... (15 more)
│ ├── override-elements/ 18 matching override UI definition files.
│ ├── blocks/shared/ Shared React panel components (used in plugin settings, not blocks directly).
│ │ ├── StructurePanel.js
│ │ ├── SpacingPanel.js
│ │ ├── LayoutPanel.js
│ │ ├── icons.js
│ │ └── utils.js
│ ├── registry/
│ │ └── substitutions.json Value migration map — runs on plugin update.
│ └── settings/ Admin settings UI (React, requires build).
├── includes/
│ ├── blocks/
│ │ ├── class-wptruss-block-registry.php Scans custom-blocks/ and registers blocks.
│ │ └── class-wptruss-block-validator.php Governance validator (12 rules).
│ ├── class-wpt-element-registry.php PHP side of element registry (script registration, user defaults, substitutions, REST API).
│ ├── class-wptruss-panel-registry.php Panel Registry storage and re-registration API.
│ └── ... (other subsystem classes)
└── assets/ Compiled settings UI JS/CSS.
Where to Go for Each Task
| Task | Where |
|---|---|
| Change panel option values (heading levels, spacing scale) | Admin: Custom Blocks → Panel Registry |
| Change element defaults site-wide (heading font size, button style) | Admin: Custom Blocks → Elements |
| Upload or manage installed blocks | Admin: Custom Blocks → Blocks |
| Audit registered blocks (panel sync status) | Admin: Custom Blocks → Block Audit |
| View element validation results | Admin: Custom Blocks → Debug Panel |
| Write block inspector JS | custom-blocks/{slug}/index.js |
| Write block frontend PHP | custom-blocks/{slug}/render.php |
| Write block CSS | custom-blocks/{slug}/style.css |
| Declare block dependencies | custom-blocks/{slug}/index.asset.php |
| Add the block to the marketplace | {package}/registry/manifest.json |
| Migrate element override values on plugin update | src/registry/substitutions.json |