Pattern Builder 2.1: the patternbuilderwp.com cloud module

[pbking]

The client half of Pattern Builder 2.1 — companion to Twenty-Bellows/patternbuilderwp.com#2. Everything is additive: disconnected, the plugin behaves exactly as 2.0.

The branch has moved a long way since it was opened, and this description has been rewritten to match the current head. Several commit titles describe designs that were later replaced — in particular the OAuth/PKCE connect flow, the two-entry cloud rail, and AI generation in the create modal. The history is left as it happened; what follows is what the code actually does now.

Connecting

Credential auth inside wp-admin, not OAuth. The connect panel posts credentials to this site's own proxy, which relays them server-side to the service's /auth/login / /auth/signup and stores only the returned bearer token in user meta. The browser never visits the service and credentials are never logged or stored. The PKCE surface still exists on the service as the protocol path for social sign-in and third parties; the product UI doesn't use it.

The service URL is the pattern_builder_cloud_url option, overridable by a PATTERN_BUILDER_CLOUD_URL wp-config constant — the declarative choice for dev setups, since it survives DB resets — and filterable.

PHP

• Pattern_Builder_Cloud — per-WP-user connection state, authenticated + multipart HTTP to the service, and the cloud-link map (pattern_builder_cloud_links site option) that drives Update-vs-New on re-upload. The map records a content hash at upload time and whether the cloud copy is ours (owned), so a pattern downloaded from somebody else's library is linked but never offered an update. Whitelists the configured service origin only through core's hardened URL validation, so dev services on nonstandard localhost ports work.
• Pattern_Builder_Cloud_Porter — local pattern ↔ Portable Pattern Package. Export bundles local images as pbp-asset:// placeholders + files, matching every reference the service checks (src, a block attribute's url, CSS url()) by host and path so a query string or an http/https difference can't hide one; it drops attachment ids and wp-image-N classes on the way out, and fails loudly naming any image it can't carry. Import fetches assets only from the configured service origin (asset URLs are re-rooted onto it, so a service that self-identifies by a different URL still works), re-sanitizes the markup (KSES + scheme checks — never trust the wire, even our own service), then lands as a wp_block or flows through Pattern_File_Store::update_theme_pattern() for theme destinations.
• Pattern_Builder_Cloud_Tokens — design tokens that travel with a pattern. A download carrying tokens this site lacks shows them first, then writes only the missing ones into the destination already chosen for the pattern: theme.json for a theme pattern, Global Styles for a user one.
• Pattern_Builder_Cloud_Controller — the /pattern-builder/v1/cloud/* proxy routes (edit_theme_options + REST nonce): status, login/signup/disconnect, library + directory + collections, links, pattern-state, upload, download, tokens/check, delete.
• Pattern_Builder_Abilities — eight abilities under pattern-builder/* on core's Abilities API, so any agent that can authenticate to the site can read its design system, block types and patterns, store finished markup, and fetch the pattern-authoring guides. Nothing takes a prompt. The guide set is filtered (pattern_builder_authoring_guides) so a theme can add its own house rules to what an agent is told.

JS

src/cloud/CloudBrowser.js is mounted behind the browse app's Uploaded and Community tabs. The browse screen is a Site-Editor-style library: four collection tabs (User / Theme / Uploaded / Community), each with its own search and category rail, over a grid of fixed-size square tiles.

Tile scaling is CSS-only. Every preview, local or cloud, renders at one design width (1400px) and is scaled by a constant the stylesheet computes from the two sizes (src/_pattern-tiles.scss) — nothing measures anything in JavaScript, so a short pattern is centred and a tall one cropped at the same point in both grids.

Because that grid renders block previews on a screen that never boots an editor, it does two things core's editor screens do for themselves: the page prints the server-registered block bindings sources (without those label-bearing stubs core's own registerBlockBindingsSource() refuses every source silently, and a pattern filling another's slots renders the other pattern's placeholder copy), and the browse app registers the read half of core/pattern-overrides itself (src/admin/preview-bindings.js), since the working half is a private API only an editor boot can reach.

Editing is one editor for every pattern. Both kinds open in core's edit-post editor — a post editor already on screen swaps the entity into its canvas; everywhere else the Appearance page boots wp.editPost.initializeEditor against it, with a validated back URL. The Site Editor's canvas is never used, because theme patterns can never enter it.

Uploading is gated on the editor's own block validation (src/utils/blockValidity.js). Only a browser can make this call, because a block's save() is JavaScript and no server can re-run it (WP_Block_Type has no save; serialize_block() replays what it parsed). Core answers two questions here and the panel asks both:

• parse() decides what is invalid — markup a block type would not have written itself, which renders fine but reads as "unexpected or invalid content" the moment any editor opens it. That disables the upload button and names the offending blocks.
• validateBlock() decides what is stale. parse() is tolerant on purpose: every block keeps its old save() implementations (core/paragraph has six) and markup matching any of them is accepted and silently migrated. What that hides is a block-supports class missing from the file — {"backgroundColor":"primary"} with no has-primary-background-color renders with no background at all — and, by comparing the authored attributes against the parsed ones, a setting the migration threw away outright. This only warns: the markup renders and no editor will complain, so it is worth saying and not worth blocking.

Two cases are exempt by design: an attribute core relocated rather than dropped (block library 10.5 moved text alignment into a typography support, so the value lives on under style.typography.textAlign), and any block carrying Pattern Overrides bindings, whose content comes from the binding source at render and so cannot be held to a save computed from the file's own attributes.

The same two checks back the pattern-author skill's validate-pattern.mjs, and the service approximates the invalid half in PHP as a backstop.

Not included: AI generation

The service has it (/ai/generations, the job pipeline, both providers) and keeps it. The plugin doesn't call it — the create modal makes blank patterns only, and there is no /cloud/generate proxy. Pulled deliberately, to be designed properly later rather than shipped half-wired.

Testing

• PHPUnit — suites for the porter, cloud auth, design tokens, pattern-state, and the abilities (including the authoring-guide filter).
• JS unit tests, including the block-validity gate — invalid, old-form, dropped-attribute, and both exemptions — and the preview bindings registration.
• tests/e2e/cloud-roundtrip.php — the round trip over the wire (upload → update → download) against a live service, run with wp eval-file. Manual because it needs a second WordPress: every automated test of this path mocks pre_http_request, so nothing else exercises the real multipart upload, the service's sanitization and asset rehosting, or the download that fetches those assets back.
• lint:js (one pre-existing warning), lint:css, PHPCS, and a production build all clean.

Notes for review

• wp-phpunit bumped ^6.6 → ^7.1 to match current WordPress in test environments.
• Update uploads go over POST, not PUT: PHP only parses multipart bodies on POST.
• The Claude Code review/responder workflows are deleted in 69561e3.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[pbking]

The claude-review job on this PR errored inside the review action's own runtime (run — the model step failed before producing a report; the report step shows skipped). Nothing in this PR's diff feeds that workflow, so there's no in-branch fix. I don't have permission to re-run workflows here (403); if a bot review is wanted, a maintainer can hit Re-run failed jobs on that run. I'm watching the PR and will address any review findings that land.

---

Generated by Claude Code

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[pbking]

Root cause found for the failing claude-review check (both run 31 and run 32) — this supersedes my earlier "runtime error" diagnosis. The action's model step dies with:

Error: 401 {"type":"authentication_error","message":"OAuth access token has been revoked."}

The CLAUDE_CODE_OAUTH_TOKEN secret this repo's claude-code-review.yml uses has been revoked, so every review run will fail until it's re-minted (claude setup-token locally, then update the repository secret). Not related to this PR's diff — it's the only workflow in this repo, so nothing else gates 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.