Pattern Builder 2.0: theme pattern files become the single source of truth

[pbking]

Pattern Builder 2.0

This is the 2.0 upgrade following the architecture Synced Patterns for Themes 2.0 proved out: no custom post type hiding the patterns, no REST interception — theme pattern files are the single source of truth, and every 1.x feature is rebuilt on mechanisms WordPress core already uses.

Companion PR: Twenty-Bellows/synced-patterns-for-themes#6 — the companion now stands down entirely when this plugin is active.

The architecture

Theme patterns are file-backed REST entities — the wp_template model. A rowless pb_pattern post type (zero DB rows, ever) hangs Pattern_Builder_REST_Patterns_Controller off core routing at /pattern-builder/v1/patterns, with string IDs (theme-slug/pattern-name). Reads come from the pattern files (child and parent theme); writes go back to the files. Because the type is show_in_rest, the block editor auto-creates a matching client-side entity from /wp/v2/types — undo, dirty tracking, and the save flow all come from core's entity layer, with zero masquerade.

Synced patterns ride the core/pattern content runtime vendored from Synced Patterns for Themes 2.0: core/pattern gets a content attribute + pattern/overrides context (the exact shape core/block has), a render callback attaches the pattern's blocks as inner blocks, and core's own core/pattern-overrides binding source resolves overrides. An inserted synced theme pattern is a plain pattern block:

<!-- wp:pattern {"slug":"my-theme/hero","content":{...}} /-->

No post ID anywhere, and per-instance overrides stay isolated. Synced user patterns stay core-native: they insert as core/block references.

Coexistence is one check in one place. Pattern Builder always registers the full stack — the vendored runtime (kept logic-identical to the companion's) plus the editing layer. When both plugins are installed, the companion sees PATTERN_BUILDER_VERSION at plugins_loaded and stays entirely unloaded; deactivate Pattern Builder and the companion takes over with identical rendering. Pattern Builder also clears the companion's per-theme transient after file writes, so the companion never wakes to a stale cache.

Editing surfaces — always the WordPress editor, never a custom one:

• Post editor: in-context — the sidebar's Edit button swaps the pb_pattern (or wp_block) entity into the canvas without leaving the post; the entity is pre-resolved first to avoid an empty-content race.
• Site Editor: user patterns are edited in place via core's /wp_block route. Theme patterns cannot bind to the Site Editor canvas — core hard-codes the entity types its canvas resolves and keeps route registration private — so Edit opens core's own edit-post editor bound to the pattern file entity, and its Back button returns to the exact Site Editor screen you left (server-validated back URL).
• Appearance → Pattern Builder is a Site-Editor-style library: a category rail with counts, a grid of uniform 1:1 pattern cards, and a details sidebar for the selected pattern carrying the same panels the editor shows, with Save and Edit actions. Clicking Edit on a user pattern opens the Site Editor's pattern canvas; a theme pattern boots core's edit-post editor (wp.editPost.initializeEditor) against the pb_pattern entity — the genuine post-editor chrome saving straight to the file. Deep-linkable via &pattern={id}; a history.replaceState guard keeps the page's URL, and the app pins its bottom edge to the viewport so the panes scroll internally.

Feature work

• All pattern metadata round-trips through the file header: title, description, categories, keywords, block types, post types, template types, viewport width (1.x read it and lost it on save), inserter visibility, synced status. New Metadata panel; Bindings panel re-enabled as the slot-authoring UI.
• Synced status is editable both ways for user patterns too — core registers the wp_pattern_sync_status meta with enum [partial, unsynced], so "synced" is the absence of the meta; the panel writes null (the REST meta delete) instead of an enum-rejected empty string.
• Edit Pattern in the block toolbar: selecting a synced theme pattern instance (core/pattern) on the canvas offers Edit Pattern next to the runtime's Reset/Detach — in-context in the post editor, the Pattern Builder editor elsewhere. Shown only when the slug resolves to a file-backed pattern. (Synced user instances are core/block, where core provides Edit original.)
• Conversions both ways as real REST semantics: POST /patterns {fromWpBlock: N} converts user→theme (images imported as theme assets, post deleted); PUT /patterns/{id} {source:"user"} converts theme→user (images exported to the media library, file deleted).
• Migration runs once on upgrade: wp:block {"ref":N} references to 1.x mirror posts are rewritten to wp:pattern slugs in post content and theme files while the rows still exist as the ID→slug map, then the mirror posts and 1.x capabilities are removed. uninstall.php added (1.x had none).
• WordPress.org shipping workflow (same as the companion's): npm run plugin-ship / :dry-run / :reset — preflight version agreement, .distignore-defined ship set, wp.org assets in .wordpress-org/, SVN trunk + tag + assets committed in one go. Rehearsed end-to-end against a local SVN repository.
• Theme patterns now appear in the core inserter per their own Inserter: header (1.x hid them all and re-listed them as fake wp_blocks).
• The REST response advertises wp:action-publish, so the editor's save button reads Save/Update instead of degrading to "Submit for Review".

Removed / fixed

• The tbell_pattern_block CPT, its capability family, and the per-request DB upserts (TWE-369 — the performance issue is gone by construction).
• All four /wp/v2/blocks interception filters — including the unauthenticated file deletion and unauthenticated edit-context read paths that rode rest_pre_dispatch ahead of permission callbacks. Every route now has a permission callback (edit_posts read / edit_theme_options write), and a test pins that no rest_pre_dispatch filter remains.
• Pattern_Builder_Security was declared in the global namespace but called from namespaced code — a latent fatal on every file write. Fixed.
• TWE-370 (create-time "Theme" choice was cosmetic), TWE-371 (-x-x- slug encoding), TWE-373 (parent theme ignored), TWE-374 (sidebar not refreshing after create), the broken drag payload, the user-pattern list truncated at 10, and the fixture theme's template referencing patterns from the wrong namespace.
• Requires WordPress 6.8 / PHP 7.4 (the render layer needs WP_Block::refresh_context_dependents(); 1.x already called a 6.8-only function despite its 6.6 header).

Testing

• PHP: 91 tests / 276 assertions in wp-env — the rewritten REST suite (list/read/write/metadata round-trip/conversions/delete/auth/action links), the migration suite, the vendored runtime suites (render, resolver, editor REST, synced lookup), and the 28 localization tests.
• JS: 14 tests (override transforms + utils), lint:js, lint:css, and phpcs all clean.
• Real browser (Playwright/Chromium against wp-env, WP trunk 7.2-alpha):
  • Pattern Builder page: category rail counts/filtering, uniform square cards, details sidebar Save writing the theme file, Edit opening the real edit-post editor → type → Save → the theme .php file on disk updated with an intact header; page reload survives; Back returns to the origin screen; no page scrolling.
  • Site Editor round-trip: sidebar Edit on a theme pattern → core editor with back URL → Back lands on the exact Site Editor screen. User patterns edited in place in the Site Editor (/wp_block route), from within it and deep-linked from the grid.
  • Post editor: sidebar insert of a synced theme pattern lands as core/pattern (not a copy) and renders on the front end through the runtime; a synced user pattern lands as core/block {ref} and renders; in-context pb_pattern entity editing; Edit Pattern toolbar button navigates in-context.
  • Sync toggle: an unsynced user pattern flips to synced (meta deleted server-side) and the collection endpoint reports it synced.
  • Override editing: typing in an instance slot stores on the host block's content attribute; a second instance of the same pattern stays isolated.
  • Coexistence, both directions: with both plugins active, the companion's classes are not loaded and this plugin's Pattern_Block owns the core/pattern render callback; deactivating Pattern Builder hands rendering back to the companion identically.

Notes for reviewers

• includes/class-pattern-block.php, class-pattern-resolver.php, class-block-markup.php, class-inner-html-processor.php, class-synced-patterns.php, class-editor-support.php and src/runtime/* are vendored from synced-patterns-for-themes (namespace/identifier renames only) and should be kept logic-identical to it — that release-time invariant is what makes the coexistence hand-off invisible.
• docs/architecture.md is marked historical; the new design is in docs/architecture-2.0.md.
• Rowless-entity trade-off, documented: no revisions for theme patterns (files + version control are the history), and no autosaves (lockPostAutosaving is dispatched; the editor's one autosave probe 404s harmlessly).
• If core ever opens Site Editor route registration to plugins, theme patterns can move fully into the Site Editor canvas — the only thing that changes is the URL the Edit button targets.

🤖 Generated with Claude Code

https://claude.ai/code/session_01W5Y7NJdKZ2BenQmGVtDbVB

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[pbking]

CI status: the claude-review check failed for infrastructure reasons, not because of this PR's changes.

The job errored before producing a review: API Error: 401 {"type":"authentication_error","message":"OAuth access token has been revoked."} (job log). The workflow's stored Anthropic OAuth token has been revoked — the last successful run of this workflow was in March; this PR is the first to trigger it since. Nothing in this diff touches the workflow or its credentials, and there's no in-repo fix I can port — a repository admin needs to refresh the claude-code-review workflow's OAuth token secret.

I'm re-running the check once to confirm it reproduces, and will keep the PR watched. For reference, the change itself is fully validated outside this check: 92 PHP tests / 276 assertions and 14 JS tests green in wp-env, phpcs/eslint/stylelint clean, and the editor flows verified in a real browser (details in the PR description).

---

Generated by Claude Code

[pbking]

Correction to the above: I don't have permission to re-run the failed job (the API returns 403 for this integration), so the single confirming re-run isn't available to me. The failure is deterministic in any case — a revoked OAuth token will 401 on every run until the secret is refreshed. Once an admin rotates the token, re-running the claude-review job on this run (or pushing any new commit) will re-trigger it. I'll keep checking in on the PR.

---

Generated by Claude Code

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.