From e782ae52d0f92ce3e35e9789acc9f8531a81b72c Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 15:17:46 -0400
Subject: [PATCH 001/113] feat(blocks-engine): scaffold package with
 exact-pinned deps + version-lock test

---
 .github/workflows/js.yml                      |   45 +
 packages/blocks-engine/.gitignore             |    2 +
 packages/blocks-engine/.npmrc                 |    2 +
 packages/blocks-engine/package.json           |   37 +
 packages/blocks-engine/pnpm-lock.yaml         | 5867 +++++++++++++++++
 .../src/__tests__/version-lock.test.ts        |   10 +
 packages/blocks-engine/src/index.ts           |    3 +
 packages/blocks-engine/tsconfig.json          |   18 +
 packages/blocks-engine/tsup.config.ts         |   10 +
 packages/blocks-engine/vitest.config.ts       |    8 +
 10 files changed, 6002 insertions(+)
 create mode 100644 .github/workflows/js.yml
 create mode 100644 packages/blocks-engine/.gitignore
 create mode 100644 packages/blocks-engine/.npmrc
 create mode 100644 packages/blocks-engine/package.json
 create mode 100644 packages/blocks-engine/pnpm-lock.yaml
 create mode 100644 packages/blocks-engine/src/__tests__/version-lock.test.ts
 create mode 100644 packages/blocks-engine/src/index.ts
 create mode 100644 packages/blocks-engine/tsconfig.json
 create mode 100644 packages/blocks-engine/tsup.config.ts
 create mode 100644 packages/blocks-engine/vitest.config.ts

diff --git a/.github/workflows/js.yml b/.github/workflows/js.yml
new file mode 100644
index 00000000..f6d93cc5
--- /dev/null
+++ b/.github/workflows/js.yml
@@ -0,0 +1,45 @@
+name: JS Transformer
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/js.yml"
+      - "packages/blocks-engine/**"
+  push:
+    branches:
+      - trunk
+    paths:
+      - ".github/workflows/js.yml"
+      - "packages/blocks-engine/**"
+
+jobs:
+  validate:
+    name: Install, build, and test
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        working-directory: packages/blocks-engine
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Run tests
+        run: pnpm test
diff --git a/packages/blocks-engine/.gitignore b/packages/blocks-engine/.gitignore
new file mode 100644
index 00000000..b9470778
--- /dev/null
+++ b/packages/blocks-engine/.gitignore
@@ -0,0 +1,2 @@
+node_modules/
+dist/
diff --git a/packages/blocks-engine/.npmrc b/packages/blocks-engine/.npmrc
new file mode 100644
index 00000000..4c2f52b3
--- /dev/null
+++ b/packages/blocks-engine/.npmrc
@@ -0,0 +1,2 @@
+auto-install-peers=true
+strict-peer-dependencies=false
diff --git a/packages/blocks-engine/package.json b/packages/blocks-engine/package.json
new file mode 100644
index 00000000..3ec1e05f
--- /dev/null
+++ b/packages/blocks-engine/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "@automattic/blocks-engine",
+  "version": "0.0.0",
+  "license": "GPL-3.0-or-later",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./wp": {
+      "import": "./dist/wp/index.js",
+      "require": "./dist/wp/index.cjs",
+      "types": "./dist/wp/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "cheerio": "1.2.0",
+    "@wordpress/block-serialization-default-parser": "5.47.0",
+    "@wordpress/blocks": "15.15.0",
+    "@wordpress/block-editor": "15.15.0",
+    "@wordpress/block-library": "9.42.0",
+    "@wordpress/data": "10.42.0",
+    "@wordpress/hooks": "4.42.0",
+    "jsdom": "29.0.1"
+  },
+  "devDependencies": {
+    "tsup": "8.0.0",
+    "vitest": "2.0.0",
+    "typescript": "5.7.3"
+  }
+}
diff --git a/packages/blocks-engine/pnpm-lock.yaml b/packages/blocks-engine/pnpm-lock.yaml
new file mode 100644
index 00000000..62b3cfd2
--- /dev/null
+++ b/packages/blocks-engine/pnpm-lock.yaml
@@ -0,0 +1,5867 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      '@wordpress/block-editor':
+        specifier: 15.15.0
+        version: 15.15.0(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/block-library':
+        specifier: 9.42.0
+        version: 9.42.0(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/block-serialization-default-parser':
+        specifier: 5.47.0
+        version: 5.47.0
+      '@wordpress/blocks':
+        specifier: 15.15.0
+        version: 15.15.0(react@18.3.1)
+      '@wordpress/data':
+        specifier: 10.42.0
+        version: 10.42.0(react@18.3.1)
+      '@wordpress/hooks':
+        specifier: 4.42.0
+        version: 4.42.0
+      cheerio:
+        specifier: 1.2.0
+        version: 1.2.0
+      jsdom:
+        specifier: 29.0.1
+        version: 29.0.1
+    devDependencies:
+      tsup:
+        specifier: 8.0.0
+        version: 8.0.0(postcss@8.5.15)(typescript@5.7.3)
+      typescript:
+        specifier: 5.7.3
+        version: 5.7.3
+      vitest:
+        specifier: 2.0.0
+        version: 2.0.0(jsdom@29.0.1)
+
+packages:
+
+  '@ampproject/remapping@2.3.0':
+    resolution: {integrity: sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw==, tarball: https://registry.npmjs.org/@ampproject/remapping/-/remapping-2.3.0.tgz}
+    engines: {node: '>=6.0.0'}
+
+  '@ariakit/components@0.1.2':
+    resolution: {integrity: sha512-tvh2P0x1cJnoPXnmDEJwdRk3z7x6cTB8ArctcZdAUXlRg9tuwW/rJoBFJMzD5qMI9CDDlQ3Zctx58HvENw4BYw==, tarball: https://registry.npmjs.org/@ariakit/components/-/components-0.1.2.tgz}
+
+  '@ariakit/react-components@0.1.2':
+    resolution: {integrity: sha512-SM+SPMAVlOZmGAfWNBza+0k9y4mkA5/dJhDoOyhE96cbNARy665uLdwowSJl1JGuFfcZzuzAwGon7f/rYeyfkQ==, tarball: https://registry.npmjs.org/@ariakit/react-components/-/react-components-0.1.2.tgz}
+    peerDependencies:
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  '@ariakit/react-store@0.1.2':
+    resolution: {integrity: sha512-1r1Gn0tqhnOS0LFvHNGzn5/8C5aOANO5vb0Gxh94oR/be4zwCSE2zfQjOjRfpL+BBDhOcProME2+G6UslEJxbg==, tarball: https://registry.npmjs.org/@ariakit/react-store/-/react-store-0.1.2.tgz}
+    peerDependencies:
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  '@ariakit/react-utils@0.1.2':
+    resolution: {integrity: sha512-Rnl6D1542Mqu80xK++oUv1JXS0PtNmKXd9nkdud5nyvySiBDTrmPqRW44/D+5GbuZrboreQuY3tPYwKL7a7onQ==, tarball: https://registry.npmjs.org/@ariakit/react-utils/-/react-utils-0.1.2.tgz}
+    peerDependencies:
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  '@ariakit/react@0.4.29':
+    resolution: {integrity: sha512-SLXlsddWHSwfUol4Yi0zULlalNWjzWjpS3zg7B7aaPd64saONQ5ktWf9KMxqBklcpjMLeF2dB9BAHAvpPVdCIQ==, tarball: https://registry.npmjs.org/@ariakit/react/-/react-0.4.29.tgz}
+    peerDependencies:
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  '@ariakit/store@0.1.2':
+    resolution: {integrity: sha512-SS7bV4+a+1q9M9i0WV6DD4P/ypRKlCvII8soo2UMe1yuaxZA/Fc0htHe+EZwjJ6TMLjHfHh2TDSnXyrjC7QImA==, tarball: https://registry.npmjs.org/@ariakit/store/-/store-0.1.2.tgz}
+
+  '@ariakit/utils@0.1.2':
+    resolution: {integrity: sha512-lBJhtBWpKjIck/9i7G8cahvaUgLsyGklI/Pjv+VtY9KTzyuzX5GpRbbLKMS/e1qLnFPS4C3CybYB70b1bVcAkw==, tarball: https://registry.npmjs.org/@ariakit/utils/-/utils-0.1.2.tgz}
+
+  '@arraypress/waveform-player@1.2.1':
+    resolution: {integrity: sha512-PsgOZStUN+1GnY0tujbwk2PYE3HMT/Vl3wEvunqH16hIJWzisf8GEngy5EbswTAjQ1aV3Tk4XBkAskc8eslY1A==, tarball: https://registry.npmjs.org/@arraypress/waveform-player/-/waveform-player-1.2.1.tgz}
+    engines: {node: '>=14.0.0'}
+
+  '@asamuzakjp/css-color@5.1.11':
+    resolution: {integrity: sha512-KVw6qIiCTUQhByfTd78h2yD1/00waTmm9uy/R7Ck/ctUyAPj+AEDLkQIdJW0T8+qGgj3j5bpNKK7Q3G+LedJWg==, tarball: https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-5.1.11.tgz}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
+
+  '@asamuzakjp/dom-selector@7.1.1':
+    resolution: {integrity: sha512-67RZDnYRc8H/8MLDgQCDE//zoqVFwajkepHZgmXrbwybzXOEwOWGPYGmALYl9J2DOLfFPPs6kKCqmbzV895hTQ==, tarball: https://registry.npmjs.org/@asamuzakjp/dom-selector/-/dom-selector-7.1.1.tgz}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
+
+  '@asamuzakjp/generational-cache@1.0.1':
+    resolution: {integrity: sha512-wajfB8KqzMCN2KGNFdLkReeHncd0AslUSrvHVvvYWuU8ghncRJoA50kT3zP9MVL0+9g4/67H+cdvBskj9THPzg==, tarball: https://registry.npmjs.org/@asamuzakjp/generational-cache/-/generational-cache-1.0.1.tgz}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
+
+  '@asamuzakjp/nwsapi@2.3.9':
+    resolution: {integrity: sha512-n8GuYSrI9bF7FFZ/SjhwevlHc8xaVlb/7HmHelnc/PZXBD2ZR49NnN9sMMuDdEGPeeRQ5d0hqlSlEpgCX3Wl0Q==, tarball: https://registry.npmjs.org/@asamuzakjp/nwsapi/-/nwsapi-2.3.9.tgz}
+
+  '@babel/code-frame@7.29.7':
+    resolution: {integrity: sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==, tarball: https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.7.tgz}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/generator@7.29.7':
+    resolution: {integrity: sha512-DkXD5OJQaAQIdZ1bt3UZdEnHAn9Imd3IVBdX03UFe+ony9Ojw5pzr9YVKGDY1jt+Gcn/FnGkNf8r+Vj5NOJWtQ==, tarball: https://registry.npmjs.org/@babel/generator/-/generator-7.29.7.tgz}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-globals@7.29.7':
+    resolution: {integrity: sha512-3nQVUAtvkKH9zahfWgw96Jc/uFOmjACE1kQz82E2lqWmHBgjzbNlsC22nuQTfahmWeQtTq5nQ/4Nnd2A1wj4zA==, tarball: https://registry.npmjs.org/@babel/helper-globals/-/helper-globals-7.29.7.tgz}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-imports@7.29.7':
+    resolution: {integrity: sha512-ejHwrQQYcm9xnTivShn2IDOlIzInN34AXskvq9QicvCtEzq1Vzclu/tKF8Jq1Cg8JG2GL6/EmjgsCT7lXepE3g==, tarball: https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.29.7.tgz}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-string-parser@7.29.7':
+    resolution: {integrity: sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==, tarball: https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.7.tgz}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-identifier@7.29.7':
+    resolution: {integrity: sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==, tarball: https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/parser@7.29.7':
+    resolution: {integrity: sha512-hnORnjP/1P/zFEndoeX+n+t1RwWRJiJpM/jO7FW32Kn9r5+sJB2JWOdYo4L6k78j15eCwY3Gm/7364B1EMwtNg==, tarball: https://registry.npmjs.org/@babel/parser/-/parser-7.29.7.tgz}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  '@babel/runtime@7.29.7':
+    resolution: {integrity: sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==, tarball: https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.7.tgz}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/template@7.29.7':
+    resolution: {integrity: sha512-puq+Gf35oI24FeN11LkoUQFqv9uwNeWpxXZi/Ji3rRIoKAzKnxRaZ+Gkj0vKS9ZCiTESfng1N9LyOyXvo+m+Gg==, tarball: https://registry.npmjs.org/@babel/template/-/template-7.29.7.tgz}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/traverse@7.29.7':
+    resolution: {integrity: sha512-EhlfNQtZ+NK22w5BM61ciuiq1m58ed33Wr1Xan//ZRTy6hgjnwyCffRYwzsGXdASJSUJ1guZILsErh1eQcl+zw==, tarball: https://registry.npmjs.org/@babel/traverse/-/traverse-7.29.7.tgz}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/types@7.29.7':
+    resolution: {integrity: sha512-4zBIxpPzowiZpusoFkyGVwakdRJUyuH5PxQ/PrqghfdFWWasvnCdPfQXHrenDai+gyLARulZjZowCOj6fjT4pA==, tarball: https://registry.npmjs.org/@babel/types/-/types-7.29.7.tgz}
+    engines: {node: '>=6.9.0'}
+
+  '@base-ui/react@1.6.0':
+    resolution: {integrity: sha512-/jzjTWJYXhRFO45Bev9lc3cHbmjzCMpUqbMZ2AgKy/z25mY9B6shGSNcXcjQar9n5doM0KYW1W8fcFv2jZBuMw==, tarball: https://registry.npmjs.org/@base-ui/react/-/react-1.6.0.tgz}
+    engines: {node: '>=14.0.0'}
+    peerDependencies:
+      '@date-fns/tz': ^1.2.0
+      '@types/react': ^17 || ^18 || ^19
+      date-fns: ^4.0.0
+      react: ^17 || ^18 || ^19
+      react-dom: ^17 || ^18 || ^19
+    peerDependenciesMeta:
+      '@date-fns/tz':
+        optional: true
+      '@types/react':
+        optional: true
+      date-fns:
+        optional: true
+
+  '@base-ui/utils@0.3.1':
+    resolution: {integrity: sha512-gFFiltORVmW/N6IILTGxizP3PBpVpysqML1ALY5Vk0mH+7faVkCknOU31goYHN5Aoek2dkjxva1XOD2Ce9WuIg==, tarball: https://registry.npmjs.org/@base-ui/utils/-/utils-0.3.1.tgz}
+    peerDependencies:
+      '@types/react': ^17 || ^18 || ^19
+      react: ^17 || ^18 || ^19
+      react-dom: ^17 || ^18 || ^19
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@bramus/specificity@2.4.2':
+    resolution: {integrity: sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==, tarball: https://registry.npmjs.org/@bramus/specificity/-/specificity-2.4.2.tgz}
+    hasBin: true
+
+  '@csstools/color-helpers@6.0.2':
+    resolution: {integrity: sha512-LMGQLS9EuADloEFkcTBR3BwV/CGHV7zyDxVRtVDTwdI2Ca4it0CCVTT9wCkxSgokjE5Ho41hEPgb8OEUwoXr6Q==, tarball: https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-6.0.2.tgz}
+    engines: {node: '>=20.19.0'}
+
+  '@csstools/css-calc@3.2.1':
+    resolution: {integrity: sha512-DtdHlgXh5ZkA43cwBcAm+huzgJiwx3ZTWVjBs94kwz2xKqSimDA3lBgCjphYgwgVUMWatSM0pDd8TILB1yrVVg==, tarball: https://registry.npmjs.org/@csstools/css-calc/-/css-calc-3.2.1.tgz}
+    engines: {node: '>=20.19.0'}
+    peerDependencies:
+      '@csstools/css-parser-algorithms': ^4.0.0
+      '@csstools/css-tokenizer': ^4.0.0
+
+  '@csstools/css-color-parser@4.1.8':
+    resolution: {integrity: sha512-3chWb7PRLijpJpPIKkDxdu6IBeO5MrFACND57On0j8OPpc0wZibcGc3xAHrSEbOx/KDRyMHoIxGn0w1PhXMYHw==, tarball: https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-4.1.8.tgz}
+    engines: {node: '>=20.19.0'}
+    peerDependencies:
+      '@csstools/css-parser-algorithms': ^4.0.0
+      '@csstools/css-tokenizer': ^4.0.0
+
+  '@csstools/css-parser-algorithms@4.0.0':
+    resolution: {integrity: sha512-+B87qS7fIG3L5h3qwJ/IFbjoVoOe/bpOdh9hAjXbvx0o8ImEmUsGXN0inFOnk2ChCFgqkkGFQ+TpM5rbhkKe4w==, tarball: https://registry.npmjs.org/@csstools/css-parser-algorithms/-/css-parser-algorithms-4.0.0.tgz}
+    engines: {node: '>=20.19.0'}
+    peerDependencies:
+      '@csstools/css-tokenizer': ^4.0.0
+
+  '@csstools/css-syntax-patches-for-csstree@1.1.5':
+    resolution: {integrity: sha512-oNjBvzLq2GPZtJphCjLqXow/cHySHSgtxvKZb7OqSZ/xHgw6NWNhfad+6AB9cLeVm6eA9d/qMll3JdEHjy6M+A==, tarball: https://registry.npmjs.org/@csstools/css-syntax-patches-for-csstree/-/css-syntax-patches-for-csstree-1.1.5.tgz}
+    peerDependencies:
+      css-tree: ^3.2.1
+    peerDependenciesMeta:
+      css-tree:
+        optional: true
+
+  '@csstools/css-tokenizer@4.0.0':
+    resolution: {integrity: sha512-QxULHAm7cNu72w97JUNCBFODFaXpbDg+dP8b/oWFAZ2MTRppA3U00Y2L1HqaS4J6yBqxwa/Y3nMBaxVKbB/NsA==, tarball: https://registry.npmjs.org/@csstools/css-tokenizer/-/css-tokenizer-4.0.0.tgz}
+    engines: {node: '>=20.19.0'}
+
+  '@date-fns/tz@1.5.0':
+    resolution: {integrity: sha512-lwYN/vDPeNRULcepoE/LO2Pgx+7/RV+S9ARfbc9lr2DtGkOD7pAiruHvbR1RX3Qyf6ja47EWJDMsNK5vK08DJg==, tarball: https://registry.npmjs.org/@date-fns/tz/-/tz-1.5.0.tgz}
+
+  '@date-fns/utc@2.1.1':
+    resolution: {integrity: sha512-SlJDfG6RPeEX8wEVv6ZB3kak4MmbtyiI2qX/5zuKdordbrhB/iaJ58GVMZgJ6P1sJaM1gMgENFYYeg1JWrCFrA==, tarball: https://registry.npmjs.org/@date-fns/utc/-/utc-2.1.1.tgz}
+
+  '@emotion/babel-plugin@11.13.5':
+    resolution: {integrity: sha512-pxHCpT2ex+0q+HH91/zsdHkw/lXd468DIN2zvfvLtPKLLMo6gQj7oLObq8PhkrxOZb/gGCq03S3Z7PDhS8pduQ==, tarball: https://registry.npmjs.org/@emotion/babel-plugin/-/babel-plugin-11.13.5.tgz}
+
+  '@emotion/cache@11.14.0':
+    resolution: {integrity: sha512-L/B1lc/TViYk4DcpGxtAVbx0ZyiKM5ktoIyafGkH6zg/tj+mA+NE//aPYKG0k8kCHSHVJrpLpcAlOBEXQ3SavA==, tarball: https://registry.npmjs.org/@emotion/cache/-/cache-11.14.0.tgz}
+
+  '@emotion/css@11.13.5':
+    resolution: {integrity: sha512-wQdD0Xhkn3Qy2VNcIzbLP9MR8TafI0MJb7BEAXKp+w4+XqErksWR4OXomuDzPsN4InLdGhVe6EYcn2ZIUCpB8w==, tarball: https://registry.npmjs.org/@emotion/css/-/css-11.13.5.tgz}
+
+  '@emotion/hash@0.9.2':
+    resolution: {integrity: sha512-MyqliTZGuOm3+5ZRSaaBGP3USLw6+EGykkwZns2EPC5g8jJ4z9OrdZY9apkl3+UP9+sdz76YYkwCKP5gh8iY3g==, tarball: https://registry.npmjs.org/@emotion/hash/-/hash-0.9.2.tgz}
+
+  '@emotion/is-prop-valid@1.4.0':
+    resolution: {integrity: sha512-QgD4fyscGcbbKwJmqNvUMSE02OsHUa+lAWKdEUIJKgqe5IwRSKd7+KhibEWdaKwgjLj0DRSHA9biAIqGBk05lw==, tarball: https://registry.npmjs.org/@emotion/is-prop-valid/-/is-prop-valid-1.4.0.tgz}
+
+  '@emotion/memoize@0.9.0':
+    resolution: {integrity: sha512-30FAj7/EoJ5mwVPOWhAyCX+FPfMDrVecJAM+Iw9NRoSl4BBAQeqj4cApHHUXOVvIPgLVDsCFoz/hGD+5QQD1GQ==, tarball: https://registry.npmjs.org/@emotion/memoize/-/memoize-0.9.0.tgz}
+
+  '@emotion/react@11.14.0':
+    resolution: {integrity: sha512-O000MLDBDdk/EohJPFUqvnp4qnHeYkVP5B0xEG0D/L7cOKP9kefu2DXn8dj74cQfsEzUqh+sr1RzFqiL1o+PpA==, tarball: https://registry.npmjs.org/@emotion/react/-/react-11.14.0.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      react: '>=16.8.0'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@emotion/serialize@1.3.3':
+    resolution: {integrity: sha512-EISGqt7sSNWHGI76hC7x1CksiXPahbxEOrC5RjmFRJTqLyEK9/9hZvBbiYn70dw4wuwMKiEMCUlR6ZXTSWQqxA==, tarball: https://registry.npmjs.org/@emotion/serialize/-/serialize-1.3.3.tgz}
+
+  '@emotion/sheet@1.4.0':
+    resolution: {integrity: sha512-fTBW9/8r2w3dXWYM4HCB1Rdp8NLibOw2+XELH5m5+AkWiL/KqYX6dc0kKYlaYyKjrQ6ds33MCdMPEwgs2z1rqg==, tarball: https://registry.npmjs.org/@emotion/sheet/-/sheet-1.4.0.tgz}
+
+  '@emotion/styled@11.14.1':
+    resolution: {integrity: sha512-qEEJt42DuToa3gurlH4Qqc1kVpNq8wO8cJtDzU46TjlzWjDlsVyevtYCRijVq3SrHsROS+gVQ8Fnea108GnKzw==, tarball: https://registry.npmjs.org/@emotion/styled/-/styled-11.14.1.tgz}
+    peerDependencies:
+      '@emotion/react': ^11.0.0-rc.0
+      '@types/react': '*'
+      react: '>=16.8.0'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@emotion/unitless@0.10.0':
+    resolution: {integrity: sha512-dFoMUuQA20zvtVTuxZww6OHoJYgrzfKM1t52mVySDJnMSEa08ruEvdYQbhvyu6soU+NeLVd3yKfTfT0NeV6qGg==, tarball: https://registry.npmjs.org/@emotion/unitless/-/unitless-0.10.0.tgz}
+
+  '@emotion/use-insertion-effect-with-fallbacks@1.2.0':
+    resolution: {integrity: sha512-yJMtVdH59sxi/aVJBpk9FQq+OR8ll5GT8oWd57UpeaKEVGab41JWaCFA7FRLoMLloOZF/c/wsPoe+bfGmRKgDg==, tarball: https://registry.npmjs.org/@emotion/use-insertion-effect-with-fallbacks/-/use-insertion-effect-with-fallbacks-1.2.0.tgz}
+    peerDependencies:
+      react: '>=16.8.0'
+
+  '@emotion/utils@1.4.2':
+    resolution: {integrity: sha512-3vLclRofFziIa3J2wDh9jjbkUz9qk5Vi3IZ/FSTKViB0k+ef0fPV7dYrUIugbgupYDx7v9ud/SjrtEP8Y4xLoA==, tarball: https://registry.npmjs.org/@emotion/utils/-/utils-1.4.2.tgz}
+
+  '@emotion/weak-memoize@0.4.0':
+    resolution: {integrity: sha512-snKqtPW01tN0ui7yu9rGv69aJXr/a/Ywvl11sUjNtEcRc+ng/mQriFL0wLXMef74iHa/EkftbDzU9F8iFbH+zg==, tarball: https://registry.npmjs.org/@emotion/weak-memoize/-/weak-memoize-0.4.0.tgz}
+
+  '@esbuild/aix-ppc64@0.19.12':
+    resolution: {integrity: sha512-bmoCYyWdEL3wDQIVbcyzRyeKLgk2WtWLTWz1ZIAZF/EGbNOwSA6ew3PftJ1PqMiOOGu0OyFMzG53L0zqIpPeNA==, tarball: https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/aix-ppc64@0.21.5':
+    resolution: {integrity: sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==, tarball: https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.19.12':
+    resolution: {integrity: sha512-P0UVNGIienjZv3f5zq0DP3Nt2IE/3plFzuaS96vihvD0Hd6H/q4WXUGpCxD/E8YrSXfNyRPbpTq+T8ZQioSuPA==, tarball: https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm64@0.21.5':
+    resolution: {integrity: sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==, tarball: https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.19.12':
+    resolution: {integrity: sha512-qg/Lj1mu3CdQlDEEiWrlC4eaPZ1KztwGJ9B6J+/6G+/4ewxJg7gqj8eVYWvao1bXrqGiW2rsBZFSX3q2lcW05w==, tarball: https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-arm@0.21.5':
+    resolution: {integrity: sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==, tarball: https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.19.12':
+    resolution: {integrity: sha512-3k7ZoUW6Q6YqhdhIaq/WZ7HwBpnFBlW905Fa4s4qWJyiNOgT1dOqDiVAQFwBH7gBRZr17gLrlFCRzF6jFh7Kew==, tarball: https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/android-x64@0.21.5':
+    resolution: {integrity: sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==, tarball: https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.19.12':
+    resolution: {integrity: sha512-B6IeSgZgtEzGC42jsI+YYu9Z3HKRxp8ZT3cqhvliEHovq8HSX2YX8lNocDn79gCKJXOSaEot9MVYky7AKjCs8g==, tarball: https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-arm64@0.21.5':
+    resolution: {integrity: sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==, tarball: https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.19.12':
+    resolution: {integrity: sha512-hKoVkKzFiToTgn+41qGhsUJXFlIjxI/jSYeZf3ugemDYZldIXIxhvwN6erJGlX4t5h417iFuheZ7l+YVn05N3A==, tarball: https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.21.5':
+    resolution: {integrity: sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==, tarball: https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.19.12':
+    resolution: {integrity: sha512-4aRvFIXmwAcDBw9AueDQ2YnGmz5L6obe5kmPT8Vd+/+x/JMVKCgdcRwH6APrbpNXsPz+K653Qg8HB/oXvXVukA==, tarball: https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-arm64@0.21.5':
+    resolution: {integrity: sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==, tarball: https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.19.12':
+    resolution: {integrity: sha512-EYoXZ4d8xtBoVN7CEwWY2IN4ho76xjYXqSXMNccFSx2lgqOG/1TBPW0yPx1bJZk94qu3tX0fycJeeQsKovA8gg==, tarball: https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.21.5':
+    resolution: {integrity: sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==, tarball: https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.19.12':
+    resolution: {integrity: sha512-EoTjyYyLuVPfdPLsGVVVC8a0p1BFFvtpQDB/YLEhaXyf/5bczaGeN15QkR+O4S5LeJ92Tqotve7i1jn35qwvdA==, tarball: https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm64@0.21.5':
+    resolution: {integrity: sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==, tarball: https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.19.12':
+    resolution: {integrity: sha512-J5jPms//KhSNv+LO1S1TX1UWp1ucM6N6XuL6ITdKWElCu8wXP72l9MM0zDTzzeikVyqFE6U8YAV9/tFyj0ti+w==, tarball: https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.21.5':
+    resolution: {integrity: sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==, tarball: https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.19.12':
+    resolution: {integrity: sha512-Thsa42rrP1+UIGaWz47uydHSBOgTUnwBwNq59khgIwktK6x60Hivfbux9iNR0eHCHzOLjLMLfUMLCypBkZXMHA==, tarball: https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.21.5':
+    resolution: {integrity: sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==, tarball: https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.19.12':
+    resolution: {integrity: sha512-LiXdXA0s3IqRRjm6rV6XaWATScKAXjI4R4LoDlvO7+yQqFdlr1Bax62sRwkVvRIrwXxvtYEHHI4dm50jAXkuAA==, tarball: https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.21.5':
+    resolution: {integrity: sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==, tarball: https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.19.12':
+    resolution: {integrity: sha512-fEnAuj5VGTanfJ07ff0gOA6IPsvrVHLVb6Lyd1g2/ed67oU1eFzL0r9WL7ZzscD+/N6i3dWumGE1Un4f7Amf+w==, tarball: https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.21.5':
+    resolution: {integrity: sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==, tarball: https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.19.12':
+    resolution: {integrity: sha512-nYJA2/QPimDQOh1rKWedNOe3Gfc8PabU7HT3iXWtNUbRzXS9+vgB0Fjaqr//XNbd82mCxHzik2qotuI89cfixg==, tarball: https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.21.5':
+    resolution: {integrity: sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==, tarball: https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.19.12':
+    resolution: {integrity: sha512-2MueBrlPQCw5dVJJpQdUYgeqIzDQgw3QtiAHUC4RBz9FXPrskyyU3VI1hw7C0BSKB9OduwSJ79FTCqtGMWqJHg==, tarball: https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.21.5':
+    resolution: {integrity: sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==, tarball: https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.19.12':
+    resolution: {integrity: sha512-+Pil1Nv3Umes4m3AZKqA2anfhJiVmNCYkPchwFJNEJN5QxmTs1uzyy4TvmDrCRNT2ApwSari7ZIgrPeUx4UZDg==, tarball: https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.21.5':
+    resolution: {integrity: sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==, tarball: https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.19.12':
+    resolution: {integrity: sha512-B71g1QpxfwBvNrfyJdVDexenDIt1CiDN1TIXLbhOw0KhJzE78KIFGX6OJ9MrtC0oOqMWf+0xop4qEU8JrJTwCg==, tarball: https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.21.5':
+    resolution: {integrity: sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==, tarball: https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-x64@0.19.12':
+    resolution: {integrity: sha512-3ltjQ7n1owJgFbuC61Oj++XhtzmymoCihNFgT84UAmJnxJfm4sYCiSLTXZtE00VWYpPMYc+ZQmB6xbSdVh0JWA==, tarball: https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.21.5':
+    resolution: {integrity: sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==, tarball: https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-x64@0.19.12':
+    resolution: {integrity: sha512-RbrfTB9SWsr0kWmb9srfF+L933uMDdu9BIzdA7os2t0TXhCRjrQyCeOt6wVxr79CKD4c+p+YhCj31HBkYcXebw==, tarball: https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.21.5':
+    resolution: {integrity: sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==, tarball: https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/sunos-x64@0.19.12':
+    resolution: {integrity: sha512-HKjJwRrW8uWtCQnQOz9qcU3mUZhTUQvi56Q8DPTLLB+DawoiQdjsYq+j+D3s9I8VFtDr+F9CjgXKKC4ss89IeA==, tarball: https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/sunos-x64@0.21.5':
+    resolution: {integrity: sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==, tarball: https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.19.12':
+    resolution: {integrity: sha512-URgtR1dJnmGvX864pn1B2YUYNzjmXkuJOIqG2HdU62MVS4EHpU2946OZoTMnRUHklGtJdJZ33QfzdjGACXhn1A==, tarball: https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-arm64@0.21.5':
+    resolution: {integrity: sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==, tarball: https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.19.12':
+    resolution: {integrity: sha512-+ZOE6pUkMOJfmxmBZElNOx72NKpIa/HFOMGzu8fqzQJ5kgf6aTGrcJaFsNiVMH4JKpMipyK+7k0n2UXN7a8YKQ==, tarball: https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.21.5':
+    resolution: {integrity: sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==, tarball: https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.19.12':
+    resolution: {integrity: sha512-T1QyPSDCyMXaO3pzBkF96E8xMkiRYbUEZADd29SyPGabqxMViNoii+NcK7eWJAEoU6RZyEm5lVSIjTmcdoB9HA==, tarball: https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.19.12.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.21.5':
+    resolution: {integrity: sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==, tarball: https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.21.5.tgz}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [win32]
+
+  '@exodus/bytes@1.15.1':
+    resolution: {integrity: sha512-S6mL0yNB/Abt9Ei4tq8gDhcczc4S3+vQ4ra7vxnAf+YHC02srtqxKKZghx2Dq6p0e66THKwR6r8N6P95wEty7Q==, tarball: https://registry.npmjs.org/@exodus/bytes/-/bytes-1.15.1.tgz}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
+    peerDependencies:
+      '@noble/hashes': ^1.8.0 || ^2.0.0
+    peerDependenciesMeta:
+      '@noble/hashes':
+        optional: true
+
+  '@floating-ui/core@1.7.5':
+    resolution: {integrity: sha512-1Ih4WTWyw0+lKyFMcBHGbb5U5FtuHJuujoyyr5zTaWS5EYMeT6Jb2AuDeftsCsEuchO+mM2ij5+q9crhydzLhQ==, tarball: https://registry.npmjs.org/@floating-ui/core/-/core-1.7.5.tgz}
+
+  '@floating-ui/dom@1.7.6':
+    resolution: {integrity: sha512-9gZSAI5XM36880PPMm//9dfiEngYoC6Am2izES1FF406YFsjvyBMmeJ2g4SAju3xWwtuynNRFL2s9hgxpLI5SQ==, tarball: https://registry.npmjs.org/@floating-ui/dom/-/dom-1.7.6.tgz}
+
+  '@floating-ui/react-dom@2.0.8':
+    resolution: {integrity: sha512-HOdqOt3R3OGeTKidaLvJKcgg75S6tibQ3Tif4eyd91QnIJWr0NLvoXFpJA/j8HqkFSL68GDca9AuyWEHlhyClw==, tarball: https://registry.npmjs.org/@floating-ui/react-dom/-/react-dom-2.0.8.tgz}
+    peerDependencies:
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
+
+  '@floating-ui/react-dom@2.1.8':
+    resolution: {integrity: sha512-cC52bHwM/n/CxS87FH0yWdngEZrjdtLW/qVruo68qg+prK7ZQ4YGdut2GyDVpoGeAYe/h899rVeOVm6Oi40k2A==, tarball: https://registry.npmjs.org/@floating-ui/react-dom/-/react-dom-2.1.8.tgz}
+    peerDependencies:
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
+
+  '@floating-ui/utils@0.2.11':
+    resolution: {integrity: sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==, tarball: https://registry.npmjs.org/@floating-ui/utils/-/utils-0.2.11.tgz}
+
+  '@jest/schemas@29.6.3':
+    resolution: {integrity: sha512-mo5j5X+jIZmJQveBKeS/clAueipV7KgiX1vMgCxam1RNYiqE1w62n0/tJJnHtjW8ZHcQco5gY85jA3mi0L+nSA==, tarball: https://registry.npmjs.org/@jest/schemas/-/schemas-29.6.3.tgz}
+    engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0}
+
+  '@jridgewell/gen-mapping@0.3.13':
+    resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==, tarball: https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz}
+
+  '@jridgewell/resolve-uri@3.1.2':
+    resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==, tarball: https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz}
+    engines: {node: '>=6.0.0'}
+
+  '@jridgewell/sourcemap-codec@1.5.5':
+    resolution: {integrity: sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==, tarball: https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==, tarball: https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz}
+
+  '@nodelib/fs.scandir@2.1.5':
+    resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==, tarball: https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz}
+    engines: {node: '>= 8'}
+
+  '@nodelib/fs.stat@2.0.5':
+    resolution: {integrity: sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==, tarball: https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz}
+    engines: {node: '>= 8'}
+
+  '@nodelib/fs.walk@1.2.8':
+    resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==, tarball: https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz}
+    engines: {node: '>= 8'}
+
+  '@preact/signals-core@1.14.3':
+    resolution: {integrity: sha512-m0K3vnbSLC5rHs2ZVfeAMvBtT1zIyq4mxx5OlNncSgMj5Iz6W5Rn3kPrDxAC+iIKmiVe0lSl6U37t5ZkEWoVAw==, tarball: https://registry.npmjs.org/@preact/signals-core/-/signals-core-1.14.3.tgz}
+
+  '@preact/signals@1.3.4':
+    resolution: {integrity: sha512-TPMkStdT0QpSc8FpB63aOwXoSiZyIrPsP9Uj347KopdS6olZdAYeeird/5FZv/M1Yc1ge5qstub2o8VDbvkT4g==, tarball: https://registry.npmjs.org/@preact/signals/-/signals-1.3.4.tgz}
+    peerDependencies:
+      preact: 10.x
+
+  '@radix-ui/primitive@1.1.4':
+    resolution: {integrity: sha512-7AdCK9PQyiljKoBDbN8OuctCbd/esdwZPQ8RtOE3SsyQtUpiPb+ND75q0jEhC1m1ecBI0MFNeLJvwIh9iKHRcQ==, tarball: https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.4.tgz}
+
+  '@radix-ui/react-compose-refs@1.1.3':
+    resolution: {integrity: sha512-rYOP8OMnuuPMQF1uhPVlGNcCDlkokKqGFE3JcxFViIkAXP7EvFWUliJAstrapypaBLJNHbZL6jGhbVDGTwmVhA==, tarball: https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.3.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-context@1.1.4':
+    resolution: {integrity: sha512-QwH4PO5urrbO+FaGd5Aglg+YJgWTyyuZ3g/6mKvsqraLkglDdckw9JafgL5McL5VEJ6EPNduPaT3ZE9BttDAqg==, tarball: https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.1.4.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-dialog@1.1.17':
+    resolution: {integrity: sha512-TDTYmpdq8dI2+Xgvgj9AJ8Ghqq+Eph/TRVEdaFQPDItIY+6QSkU7MJMeevw1568Yw/2Ijz8BTphPSP2XejKphw==, tarball: https://registry.npmjs.org/@radix-ui/react-dialog/-/react-dialog-1.1.17.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-dismissable-layer@1.1.13':
+    resolution: {integrity: sha512-2v+zNAWWe0ySxgC0D0yeXMPQ23xZVgXZTerTz+JKlmdRj6gfTqmCcR29jb6d290DezXPGgruHWDX/vYUebtErg==, tarball: https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.1.13.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-focus-guards@1.1.4':
+    resolution: {integrity: sha512-cot/aB/mOm0IYVYTTmQcEEK1M48lZWi8FlYe5nDPQQ8NYZUlXEFgncJ9p2Kzer3RKSrY7cTTpEMLZKNo9QoP5Q==, tarball: https://registry.npmjs.org/@radix-ui/react-focus-guards/-/react-focus-guards-1.1.4.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-focus-scope@1.1.10':
+    resolution: {integrity: sha512-Fas/lXQqhVvqwAb64s5RFeHiHYElZ6SUQbZaNd6EkfhP/Al7wTIQ9WIR4QVX475tlu5yFCEdDcJH6/UwsZjMWw==, tarball: https://registry.npmjs.org/@radix-ui/react-focus-scope/-/react-focus-scope-1.1.10.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-id@1.1.2':
+    resolution: {integrity: sha512-orBC88futVpqCmhX1p4cvquNHsELQ+w+vBJnuj3ftETI5bJb0bZn3Tqu3SWN2IOcPycTnMGnhwoermvISt72sA==, tarball: https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.1.2.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-portal@1.1.12':
+    resolution: {integrity: sha512-m309havGzsjLHHaIX50G5PlvRs3xkgPCsGk/5PTvYm8D5q33yG0J7w/712PTOhid7NTaFETtnSXjngHQavvhVw==, tarball: https://registry.npmjs.org/@radix-ui/react-portal/-/react-portal-1.1.12.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-presence@1.1.6':
+    resolution: {integrity: sha512-zdTk4PlUO0E18HnZ3wYbW0KkJJxWCdiNYp6g6X1PtONFhxVkg01vliTJAmwIszU6mHiyBOoW9P0rAugl5/hULQ==, tarball: https://registry.npmjs.org/@radix-ui/react-presence/-/react-presence-1.1.6.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-primitive@2.1.6':
+    resolution: {integrity: sha512-wetd0QI77DbvrPpTAvH1SqOxsYF2wZe5TNxqwOd5Ty4XDpV3dpV0s8K/1MGMJBeY5o7lg8ub5VIt1Ub+yVen6g==, tarball: https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.6.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-slot@1.3.0':
+    resolution: {integrity: sha512-MojKku4U/miO8Av4Dkb+ctMAQx7JmY96LmtDQlAarCRtd7rN52QCSzBF+XAvr5S6coSVj9HEPBgHAHKEJVk/WA==, tarball: https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.3.0.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-callback-ref@1.1.2':
+    resolution: {integrity: sha512-xCso9j1/u8sEgP1RNHjFrXJLApL8LiqOkI1R4ywuN00rxWdYg4oQXuwKLS3i0j5NWLromUD27/4nlxj2UFVvIw==, tarball: https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.2.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-controllable-state@1.2.3':
+    resolution: {integrity: sha512-PLzC90MS+ReootmjC597dvopoelpZ8Q61HJkDXZSExitIq7PL55vHNnesAHwguHK0aPfBnpdNzQtv1uliaqQrA==, tarball: https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.2.3.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-effect-event@0.0.3':
+    resolution: {integrity: sha512-6c8ZqvPTWILEKnyVkP53EGRCcpnJiKTC21sS/6R1GF5xKyHJJWQEPfkqlcgUkdRQivd6tb23abUwe4ngWmY0JA==, tarball: https://registry.npmjs.org/@radix-ui/react-use-effect-event/-/react-use-effect-event-0.0.3.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-escape-keydown@1.1.2':
+    resolution: {integrity: sha512-2uVLvLjgO7NZCWw01/FdqRwmA42J0BcjPMUCA+koFEOAb+zjqIP7SiFz/7zWPrKnVmSqr76Omq2ALyCuX4dhLw==, tarball: https://registry.npmjs.org/@radix-ui/react-use-escape-keydown/-/react-use-escape-keydown-1.1.2.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-layout-effect@1.1.2':
+    resolution: {integrity: sha512-jrBWOxZITuGcnjRCM2t2U5ZPkCLxD+Ym6DjfssS5haTj2iiak/DOb64JeN6OdLfLgptb6/e2kKR+ZuTrGoZTPA==, tarball: https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.2.tgz}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@react-spring/animated@9.7.5':
+    resolution: {integrity: sha512-Tqrwz7pIlsSDITzxoLS3n/v/YCUHQdOIKtOJf4yL6kYVSDTSmVK1LI1Q3M/uu2Sx4X3pIWF3xLUhlsA6SPNTNg==, tarball: https://registry.npmjs.org/@react-spring/animated/-/animated-9.7.5.tgz}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0
+
+  '@react-spring/core@9.7.5':
+    resolution: {integrity: sha512-rmEqcxRcu7dWh7MnCcMXLvrf6/SDlSokLaLTxiPlAYi11nN3B5oiCUAblO72o+9z/87j2uzxa2Inm8UbLjXA+w==, tarball: https://registry.npmjs.org/@react-spring/core/-/core-9.7.5.tgz}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0
+
+  '@react-spring/rafz@9.7.5':
+    resolution: {integrity: sha512-5ZenDQMC48wjUzPAm1EtwQ5Ot3bLIAwwqP2w2owG5KoNdNHpEJV263nGhCeKKmuA3vG2zLLOdu3or6kuDjA6Aw==, tarball: https://registry.npmjs.org/@react-spring/rafz/-/rafz-9.7.5.tgz}
+
+  '@react-spring/shared@9.7.5':
+    resolution: {integrity: sha512-wdtoJrhUeeyD/PP/zo+np2s1Z820Ohr/BbuVYv+3dVLW7WctoiN7std8rISoYoHpUXtbkpesSKuPIw/6U1w1Pw==, tarball: https://registry.npmjs.org/@react-spring/shared/-/shared-9.7.5.tgz}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0
+
+  '@react-spring/types@9.7.5':
+    resolution: {integrity: sha512-HVj7LrZ4ReHWBimBvu2SKND3cDVUPWKLqRTmWe/fNY6o1owGOX0cAHbdPDTMelgBlVbrTKrre6lFkhqGZErK/g==, tarball: https://registry.npmjs.org/@react-spring/types/-/types-9.7.5.tgz}
+
+  '@react-spring/web@9.7.5':
+    resolution: {integrity: sha512-lmvqGwpe+CSttsWNZVr+Dg62adtKhauGwLyGE/RRyZ8AAMLgb9x3NDMA5RMElXo+IMyTkPp7nxTB8ZQlmhb6JQ==, tarball: https://registry.npmjs.org/@react-spring/web/-/web-9.7.5.tgz}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0
+
+  '@rollup/rollup-android-arm-eabi@4.62.2':
+    resolution: {integrity: sha512-6o7ZLZK+BeenkZCFNDXqpbjw9bD6nuWonvS/lwQJp7NoVVxm6p3qE7qQ5jGuBjiFsgvqjD8mZAU5oWxTmbOeOg==, tarball: https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.62.2.tgz}
+    cpu: [arm]
+    os: [android]
+
+  '@rollup/rollup-android-arm64@4.62.2':
+    resolution: {integrity: sha512-BaH7BllCACHoH1LguOU56UItGfUWjujlO65kS9LAodViaN4bwIKd7oeW/ZHJ/4ljr/7MIiENnNy3HJ0zXv8Zkw==, tarball: https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.62.2.tgz}
+    cpu: [arm64]
+    os: [android]
+
+  '@rollup/rollup-darwin-arm64@4.62.2':
+    resolution: {integrity: sha512-v39RCCvj4He82I9sFmk+M1VZ0PLM9sfsLVikjfx2hYBNALhrrOR2D3JjQA6AhlaSOgcR+RzrKY7e1+bT6SUO/A==, tarball: https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.62.2.tgz}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rollup/rollup-darwin-x64@4.62.2':
+    resolution: {integrity: sha512-yl0y2vq3S3lHeuXhEdss6TWfKW8vkujImO12tn4ZkG/4oghr09LvdYm2RElVjokTQiUvDUGXLGsYeLqUMCKpGA==, tarball: https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.62.2.tgz}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rollup/rollup-freebsd-arm64@4.62.2':
+    resolution: {integrity: sha512-tT4pvt4qXD+vEoezupCWi+a1F0vvDiksiHc+PxRlYTOH1I6/X4id9jPxTP+Fg+545euaFT1jJVs4CEdHZAU1vw==, tarball: https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.62.2.tgz}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@rollup/rollup-freebsd-x64@4.62.2':
+    resolution: {integrity: sha512-6nU5F2wCW+qvCBhTn1pdIU3bzsIoF7EUwsCDRxilWGprQR6yd508YnH9+OKFCwpfS8pjZqDUmnCAr7exax0XCg==, tarball: https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.62.2.tgz}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rollup/rollup-linux-arm-gnueabihf@4.62.2':
+    resolution: {integrity: sha512-n1GJHPOvpIfhi3TmrCeh6S6URt9BFCt0KQE3qvexyGCTAKpR4Lg+eWvNZEqu7epxwus/8ElT3hacYEucm49SZg==, tarball: https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.62.2.tgz}
+    cpu: [arm]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm-musleabihf@4.62.2':
+    resolution: {integrity: sha512-JqgflS8wEB+UXV/vS1RpRbifGBeN4D5lz8D8oOFbFZw4vedvdOgCFAjfBmIMdW3yL10XpQQ0Ambepw6MXrhOnA==, tarball: https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.62.2.tgz}
+    cpu: [arm]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm64-gnu@4.62.2':
+    resolution: {integrity: sha512-wnFJkogWvN4jm/hQRF2UBaeUmk20j5+DmHvoyWii2b8HJDyvz1MF2OU/6ynXt2KR63rbZLWkFpoytpdc/yBuSA==, tarball: https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.62.2.tgz}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm64-musl@4.62.2':
+    resolution: {integrity: sha512-HVu2bp0zhvJ8xHEV9+UUs7S90VadmBSY3LcIMvozbPo4AuMGDWlz3ymHLHZPX4hR67TKTt8Qp5PJ5RBg/i+RMQ==, tarball: https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.62.2.tgz}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rollup/rollup-linux-loong64-gnu@4.62.2':
+    resolution: {integrity: sha512-mQqqAV8QaoSgr9I2fKDLY2BAVvmKjWoGiu/cSYQonsLvtqwEn1E4QYfnCOcp5zoEqNhsDYin1s6jx/VJmrxlZg==, tarball: https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.62.2.tgz}
+    cpu: [loong64]
+    os: [linux]
+
+  '@rollup/rollup-linux-loong64-musl@4.62.2':
+    resolution: {integrity: sha512-IxKLoxCQ2IWi6bT2akyDUBGsOImDKB+sPp4EsTmwFQ/fMwpCKm8uLSSgP/Kx/QYUgKis6SEZ5/Nlhup0DIA0PQ==, tarball: https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.62.2.tgz}
+    cpu: [loong64]
+    os: [linux]
+
+  '@rollup/rollup-linux-ppc64-gnu@4.62.2':
+    resolution: {integrity: sha512-Mk5ha2RQSgyFfmYYLkBpPnUk8D8FriBxesO1u9O75X0mHgXL1UQcH5Itl2lurWL2tj0RxV9b9tJgipac0hRY9A==, tarball: https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.62.2.tgz}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@rollup/rollup-linux-ppc64-musl@4.62.2':
+    resolution: {integrity: sha512-CjvEnqJL/0/TQ3TXX3OPIJ/kmBellrWd4heXUmHeJlTnmwjKpSJzoehLaL6Xk0ZnMHBu9dZuFADNOrtjF4v+2w==, tarball: https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.62.2.tgz}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@rollup/rollup-linux-riscv64-gnu@4.62.2':
+    resolution: {integrity: sha512-1SiZbzwdkaDURsew/tSOrooKiYy7EQGT6m8ufavAi9NEyQb/6VuIxFXAL1fqa4iZe3g4NbNk4P7J32z2tw5Mgg==, tarball: https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.62.2.tgz}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@rollup/rollup-linux-riscv64-musl@4.62.2':
+    resolution: {integrity: sha512-nQts12zJ3NQRoE6uYljOH89v7szzLDvG2JD/vsX+vGXU8w/At1GowTZ5/7qeFQ8m7L55rpR8Okugnuo5bgjy2Q==, tarball: https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.62.2.tgz}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@rollup/rollup-linux-s390x-gnu@4.62.2':
+    resolution: {integrity: sha512-E9/ll019jhPIJgpzfZoIkBGhcz+kKNgVWYRY0zr9srBdPPFVpvOKW8VaJKUbeK+eZXyQF9ltME+Kk6affeaPgg==, tarball: https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.62.2.tgz}
+    cpu: [s390x]
+    os: [linux]
+
+  '@rollup/rollup-linux-x64-gnu@4.62.2':
+    resolution: {integrity: sha512-5BqxR/pshjey51iliyzTD5Xi3EN0aLmQ2lZ3lvefVV9c82BvrLo2/6OT55iifpWBufs6kdwWbuOKS841DrmK9A==, tarball: https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.62.2.tgz}
+    cpu: [x64]
+    os: [linux]
+
+  '@rollup/rollup-linux-x64-musl@4.62.2':
+    resolution: {integrity: sha512-uNN83XxQrRAh/w0/pmAfibcwyb6YWt4gP+dpnQKPVJshAloQ785ii8CT8ZCIxkGg9opVsvAlGhFitSm6D1Jjpg==, tarball: https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.62.2.tgz}
+    cpu: [x64]
+    os: [linux]
+
+  '@rollup/rollup-openbsd-x64@4.62.2':
+    resolution: {integrity: sha512-srjEIxSH3LRnJN6THczDHWQplqEMFiAJrTab0msUryh9kwNpkICf3Ea6q6MN/2cZwRFUNx5w+h6Hpi4QuHS6Zg==, tarball: https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.62.2.tgz}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@rollup/rollup-openharmony-arm64@4.62.2':
+    resolution: {integrity: sha512-8hOJnxgbyObnCm5AlRA3A931xX19xq80RjVTKgJOvEKWqJruP/Uf12IbAOaDjjEXYRewwHLfmF0YRIdK3OwKWA==, tarball: https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.62.2.tgz}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rollup/rollup-win32-arm64-msvc@4.62.2':
+    resolution: {integrity: sha512-mmF4AY1i0hG/bLWUctUq59gtmgaSIRa3cu/A3JFRp/sCNEme2bgDEiDS22P9FbnJB8NJNF4jPJiSP5RHQpUTDg==, tarball: https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.62.2.tgz}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rollup/rollup-win32-ia32-msvc@4.62.2':
+    resolution: {integrity: sha512-DZgkknc6jhHrk46V25vbAM0zZkyP0nSDkJB8/dRkLTxv470dOmWDqGoEJl/9A0dFfS7yE3REOwNDxpHwSLSt0Q==, tarball: https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.62.2.tgz}
+    cpu: [ia32]
+    os: [win32]
+
+  '@rollup/rollup-win32-x64-gnu@4.62.2':
+    resolution: {integrity: sha512-T6xr6ucWSFto+VGajA8YH26LdpHRuP4YLHEKAtCWvJDOlnmWcDZVCI2Jmjr+IFHDlt2zRaTAKE4tfjTaWLgJBg==, tarball: https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.62.2.tgz}
+    cpu: [x64]
+    os: [win32]
+
+  '@rollup/rollup-win32-x64-msvc@4.62.2':
+    resolution: {integrity: sha512-BfzEnDJOt9T8M989/lA37EcJgat01wLRnoi5dQf3QzOH7jzpqTAzdDbVfRljVr5r+jzKqpbHeyOfAaXxAd0PAA==, tarball: https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.62.2.tgz}
+    cpu: [x64]
+    os: [win32]
+
+  '@sinclair/typebox@0.27.10':
+    resolution: {integrity: sha512-MTBk/3jGLNB2tVxv6uLlFh1iu64iYOQ2PbdOSK3NW8JZsmlaOh2q6sdtKowBhfw8QFLmYNzTW4/oK4uATIi6ZA==, tarball: https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.27.10.tgz}
+
+  '@tabby_ai/hijri-converter@1.0.5':
+    resolution: {integrity: sha512-r5bClKrcIusDoo049dSL8CawnHR6mRdDwhlQuIgZRNty68q0x8k3Lf1BtPAMxRf/GgnHBnIO4ujd3+GQdLWzxQ==, tarball: https://registry.npmjs.org/@tabby_ai/hijri-converter/-/hijri-converter-1.0.5.tgz}
+    engines: {node: '>=16.0.0'}
+
+  '@tannin/compile@1.1.0':
+    resolution: {integrity: sha512-n8m9eNDfoNZoxdvWiTfW/hSPhehzLJ3zW7f8E7oT6mCROoMNWCB4TYtv041+2FMAxweiE0j7i1jubQU4MEC/Gg==, tarball: https://registry.npmjs.org/@tannin/compile/-/compile-1.1.0.tgz}
+
+  '@tannin/evaluate@1.2.0':
+    resolution: {integrity: sha512-3ioXvNowbO/wSrxsDG5DKIMxC81P0QrQTYai8zFNY+umuoHWRPbQ/TuuDEOju9E+jQDXmj6yI5GyejNuh8I+eg==, tarball: https://registry.npmjs.org/@tannin/evaluate/-/evaluate-1.2.0.tgz}
+
+  '@tannin/plural-forms@1.1.0':
+    resolution: {integrity: sha512-xl9R2mDZO/qiHam1AgMnAES6IKIg7OBhcXqy6eDsRCdXuxAFPcjrej9HMjyCLE0DJ/8cHf0i5OQTstuBRhpbHw==, tarball: https://registry.npmjs.org/@tannin/plural-forms/-/plural-forms-1.1.0.tgz}
+
+  '@tannin/postfix@1.1.0':
+    resolution: {integrity: sha512-oocsqY7g0cR+Gur5jRQLSrX2OtpMLMse1I10JQBm8CdGMrDkh1Mg2gjsiquMHRtBs4Qwu5wgEp5GgIYHk4SNPw==, tarball: https://registry.npmjs.org/@tannin/postfix/-/postfix-1.1.0.tgz}
+
+  '@tannin/sprintf@1.3.3':
+    resolution: {integrity: sha512-RwARl+hFwhzy0tg9atWcchLFvoQiOh4rrP7uG2N5E4W80BPCUX0ElcUR9St43fxB9EfjsW2df9Qp+UsTbvQDjA==, tarball: https://registry.npmjs.org/@tannin/sprintf/-/sprintf-1.3.3.tgz}
+
+  '@types/estree@1.0.9':
+    resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==, tarball: https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz}
+
+  '@types/gradient-parser@1.1.0':
+    resolution: {integrity: sha512-SaEcbgQscHtGJ1QL+ajgDTmmqU2f6T+00jZRcFlVHUW2Asivc84LNUev/UQFyu117AsdyrtI+qpwLvgjJXJxmw==, tarball: https://registry.npmjs.org/@types/gradient-parser/-/gradient-parser-1.1.0.tgz}
+
+  '@types/highlight-words-core@1.2.1':
+    resolution: {integrity: sha512-9VZUA5omXBfn+hDxFjUDu1FOJTBM3LmvqfDey+Z6Aa8B8/JmF5SMj6FBrjfgJ/Q3YXOZd3qyTDfJyMZSs/wCUA==, tarball: https://registry.npmjs.org/@types/highlight-words-core/-/highlight-words-core-1.2.1.tgz}
+
+  '@types/highlight-words-core@1.2.3':
+    resolution: {integrity: sha512-PWNU/NR0CaYEsK38mcCTyDzeS2TlEGK9kRhRMz1i86jVAe836ZlA3gl6QYpu+CG6IpfNKTgWpEnJuRededvC0g==, tarball: https://registry.npmjs.org/@types/highlight-words-core/-/highlight-words-core-1.2.3.tgz}
+
+  '@types/mousetrap@1.6.15':
+    resolution: {integrity: sha512-qL0hyIMNPow317QWW/63RvL1x5MVMV+Ru3NaY9f/CuEpCqrmb7WeuK2071ZY5hczOnm38qExWM2i2WtkXLSqFw==, tarball: https://registry.npmjs.org/@types/mousetrap/-/mousetrap-1.6.15.tgz}
+
+  '@types/parse-json@4.0.2':
+    resolution: {integrity: sha512-dISoDXWWQwUquiKsyZ4Ng+HX2KsPL7LyHKHQwgGFEA3IaKac4Obd+h2a/a6waisAoepJlBcx9paWqjA8/HVjCw==, tarball: https://registry.npmjs.org/@types/parse-json/-/parse-json-4.0.2.tgz}
+
+  '@types/prop-types@15.7.15':
+    resolution: {integrity: sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==, tarball: https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.15.tgz}
+
+  '@types/react-dom@18.3.7':
+    resolution: {integrity: sha512-MEe3UeoENYVFXzoXEWsvcpg6ZvlrFNlOQ7EOsvhI3CfAXwzPfO8Qwuxd40nepsYKqyyVQnTdEfv68q91yLcKrQ==, tarball: https://registry.npmjs.org/@types/react-dom/-/react-dom-18.3.7.tgz}
+    peerDependencies:
+      '@types/react': ^18.0.0
+
+  '@types/react@18.3.31':
+    resolution: {integrity: sha512-vfEqpXTvwT91yhmwdfouStN2hSKwTvyRs8qpLfADyrq/kxDw0hZM7Wk9Ug1FELj8hIby+S/+kQCSRFF32nv2Qw==, tarball: https://registry.npmjs.org/@types/react/-/react-18.3.31.tgz}
+
+  '@use-gesture/core@10.3.1':
+    resolution: {integrity: sha512-WcINiDt8WjqBdUXye25anHiNxPc0VOrlT8F6LLkU6cycrOGUDyY/yyFmsg3k8i5OLvv25llc0QC45GhR/C8llw==, tarball: https://registry.npmjs.org/@use-gesture/core/-/core-10.3.1.tgz}
+
+  '@use-gesture/react@10.3.1':
+    resolution: {integrity: sha512-Yy19y6O2GJq8f7CHf7L0nxL8bf4PZCPaVOCgJrusOeFHY1LvHgYXnmnXg6N5iwAnbgbZCDjo60SiM6IPJi9C5g==, tarball: https://registry.npmjs.org/@use-gesture/react/-/react-10.3.1.tgz}
+    peerDependencies:
+      react: '>= 16.8.0'
+
+  '@vitest/expect@2.0.0':
+    resolution: {integrity: sha512-5BSfZ0+dAVmC6uPF7s+TcKx0i7oyYHb1WQQL5gg6G2c+Qkaa5BNrdRM74sxDfUIZUgYCr6bfCqmJp+X5bfcNxQ==, tarball: https://registry.npmjs.org/@vitest/expect/-/expect-2.0.0.tgz}
+
+  '@vitest/runner@2.0.0':
+    resolution: {integrity: sha512-OovFmlkfRmdhevbWImBUtn9IEM+CKac8O+m9p6W9jTATGVBnDJQ6/jb1gpHyWxsu0ALi5f+TLi+Uyst7AAimMw==, tarball: https://registry.npmjs.org/@vitest/runner/-/runner-2.0.0.tgz}
+
+  '@vitest/snapshot@2.0.0':
+    resolution: {integrity: sha512-B520cSAQwtWgocPpARadnNLslHCxFs5tf7SG2TT96qz+SZgsXqcB1xI3w3/S9kUzdqykEKrMLvW+sIIpMcuUdw==, tarball: https://registry.npmjs.org/@vitest/snapshot/-/snapshot-2.0.0.tgz}
+
+  '@vitest/spy@2.0.0':
+    resolution: {integrity: sha512-0g7ho4wBK09wq8iNZFtUcQZcUcbPmbLWFotL0GXel0fvk5yPi4nTEKpIvZ+wA5eRyqPUCIfIUl10AWzLr67cmA==, tarball: https://registry.npmjs.org/@vitest/spy/-/spy-2.0.0.tgz}
+
+  '@vitest/utils@2.0.0':
+    resolution: {integrity: sha512-t0jbx8VugWEP6A29NbyfQKVU68Vo6oUw0iX3a8BwO3nrZuivfHcFO4Y5UsqXlplX+83P9UaqEvC2YQhspC0JSA==, tarball: https://registry.npmjs.org/@vitest/utils/-/utils-2.0.0.tgz}
+
+  '@wordpress/a11y@4.48.1':
+    resolution: {integrity: sha512-BPU7wRoz2XRmP3ZgVtENPKS4iO5/+bKNid/xLrvD6cP1qMhIGowQsBNqmkP1V5+q71hQM/ID6tpFjeLhmogfPg==, tarball: https://registry.npmjs.org/@wordpress/a11y/-/a11y-4.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/api-fetch@7.48.1':
+    resolution: {integrity: sha512-RyEEY5C1XGLxJnluYFGVz4xFiw0jFjwL9Oiu4rDZjCGcxyu0sD6HPBcG6sIRpFKv062cwLccwpCeD8rc8U6Ctg==, tarball: https://registry.npmjs.org/@wordpress/api-fetch/-/api-fetch-7.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/autop@4.48.1':
+    resolution: {integrity: sha512-vMOdHhXIv559fYsg72AnWACblxZdojIerVeWxlX7a/ptoZK8MjqA0ZVhFsHezTBqdfiFyoRtiRECSFYLXWlSZg==, tarball: https://registry.npmjs.org/@wordpress/autop/-/autop-4.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/base-styles@10.0.1':
+    resolution: {integrity: sha512-Kkayj4f6KzcMW2TFaahADE0aoDpYeqadIinvIp0hxY6+zn/uqK1Ml7x5idLZ/jbyzzbVlI31eid3HtblGY3+og==, tarball: https://registry.npmjs.org/@wordpress/base-styles/-/base-styles-10.0.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/base-styles@6.20.0':
+    resolution: {integrity: sha512-Dsug4Zxz2xOFtK6CGThKYXwCqC9Yztw2STKQzwztrX4yW+o6iDbzkxpcwdDhsaVJs0Jt9A4LmJpZPh+pUozzLA==, tarball: https://registry.npmjs.org/@wordpress/base-styles/-/base-styles-6.20.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/blob@4.48.1':
+    resolution: {integrity: sha512-iK3dtZu/UtnYpKfQ2aGZM2xrLXK5ff88QNU77XlraipaGV/C7zK2M0+sWY6cVL50TfMR7VX9prZ2XCpE5aRzSg==, tarball: https://registry.npmjs.org/@wordpress/blob/-/blob-4.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/block-editor@15.15.0':
+    resolution: {integrity: sha512-2IBkb17gOWW0mvZQewzB/0g+ANTrg00/U7AnAYmx/ldU6EP9dEINcfRCiTBRA4Z7d4oaQW9cpFdKVI255U1Syg==, tarball: https://registry.npmjs.org/@wordpress/block-editor/-/block-editor-15.15.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/block-editor@15.21.1':
+    resolution: {integrity: sha512-LCHp/NoYsR7MV0e7vPNBAgtjHqK3ST4VtduxF5nOgxl0K0zuyvDvanb14EQtY4KmR2Gjndgo72/aZ/kfdQbddg==, tarball: https://registry.npmjs.org/@wordpress/block-editor/-/block-editor-15.21.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/block-library@9.42.0':
+    resolution: {integrity: sha512-dEKby/j3MSEE4KNGR2IlSC3u4QzGyCHEhkQLYR3oD2aCCFt11jOwONsncJG2qsr94ujiK8gZTy9JDNW5Dj0s4g==, tarball: https://registry.npmjs.org/@wordpress/block-library/-/block-library-9.42.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/block-serialization-default-parser@5.47.0':
+    resolution: {integrity: sha512-xRZ026shHpau7VWDXLGBvfaU6s/yC1efzOGKiDGZ0fbTbTQcr09ma7ToaDyCiHIfMoSu9lMYnriLLOEKVht8Sg==, tarball: https://registry.npmjs.org/@wordpress/block-serialization-default-parser/-/block-serialization-default-parser-5.47.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/block-serialization-default-parser@5.48.1':
+    resolution: {integrity: sha512-REsjN6tT2lXekrjuiu2O0+FYW13QHhy23j7C458zzSjpYcxROtl/T8AozOJYRvG9SkdC9Og3PkEP/9/nGC4IVw==, tarball: https://registry.npmjs.org/@wordpress/block-serialization-default-parser/-/block-serialization-default-parser-5.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/blocks@15.15.0':
+    resolution: {integrity: sha512-xUlxCqIV8UuH5MjtPQBnxEwvhe2CCrZ+WqGJ+ffLxQQGHbe513zXl8sr79FdE2noec4Bj8VdOp1oH8zlESQEUA==, tarball: https://registry.npmjs.org/@wordpress/blocks/-/blocks-15.15.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+
+  '@wordpress/blocks@15.21.1':
+    resolution: {integrity: sha512-9VOQGCuDbmyBEp7/+HNgLKscOJfrqMEV6LYpOjF+LehZ7RwolqR03UGuU+xLSPKSVZw0wvmA0SjTm3a2GBxwjg==, tarball: https://registry.npmjs.org/@wordpress/blocks/-/blocks-15.21.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+
+  '@wordpress/commands@1.48.1':
+    resolution: {integrity: sha512-yFmQ2yB4tOWPqhO+tE8uYyFqcGwxtOJ9uc1yHYfH40oMls3p+TswktsdbBM2gEmoYxfD+d3Nhp/mXGS38pdTdw==, tarball: https://registry.npmjs.org/@wordpress/commands/-/commands-1.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/components@32.6.0':
+    resolution: {integrity: sha512-MpOr0mGTkKDRjxK5LKm86Uoj9p9Z6KkrvhkNVi5zVKCftyHVMK+tun7wL2Qn/JZVLbxZpB1kW5sJ5aMf3T2ToA==, tarball: https://registry.npmjs.org/@wordpress/components/-/components-32.6.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/components@35.0.1':
+    resolution: {integrity: sha512-EiTeufX2spZ09kjI8Aa4c7dG6A3WyRSGyHTcCsVnIoE/ykOnAjtGSxnVRAT1KefrJ9RGI8JaTld48wjrB/CS5A==, tarball: https://registry.npmjs.org/@wordpress/components/-/components-35.0.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/compose@7.46.0':
+    resolution: {integrity: sha512-6Yv9Wb6tlA4JYU9bdWWuIWpTTzBAVA1zrYu1GY9x2/mCOckk9iLcEEfbKULxdjwwcMo3SKqvyby4f6kEUw/Wsw==, tarball: https://registry.npmjs.org/@wordpress/compose/-/compose-7.46.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+
+  '@wordpress/compose@8.1.1':
+    resolution: {integrity: sha512-AEC9yOS5CuTk34F+oiWebhQrxgICnb/v/KScQBUVm6zbs1AMFtu5ku+Zk0A3YTD0tO/hNzXLbvsXhJdh1bGkRA==, tarball: https://registry.npmjs.org/@wordpress/compose/-/compose-8.1.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+
+  '@wordpress/core-data@7.48.1':
+    resolution: {integrity: sha512-ITnh9M8RStzvl4+zSlz0ORPWih3VXChN5X+hYEHj80KlB+pBBOuE+JghTPF3wYEH/VmYxDV1IJmsuOC2luor+w==, tarball: https://registry.npmjs.org/@wordpress/core-data/-/core-data-7.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/data@10.42.0':
+    resolution: {integrity: sha512-YHBnNmMSclYvCS6QjwmbtdpGVbN4v0VZIq25n4a6HxG0Co6LTnvhAvgtnw+NZpEiDHibH8JcSjbCQEBtToWSFQ==, tarball: https://registry.npmjs.org/@wordpress/data/-/data-10.42.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+
+  '@wordpress/data@10.48.1':
+    resolution: {integrity: sha512-74p4PiDLxS0SAd4tdkPEUF5rtHVtdRzoXExfhkZaumviE56tEceG07YbLjQWpZ+Vl1tZCvkyqLbMHK+Wj6ZerQ==, tarball: https://registry.npmjs.org/@wordpress/data/-/data-10.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+
+  '@wordpress/dataviews@13.1.0':
+    resolution: {integrity: sha512-nZQux6jhcgKQhkD+eBwC9YojA2xWerutShUvPWyBu6mLhArGWUSYniuX1An8rhSMkm6nwju7Omgui7BdvqJhhw==, tarball: https://registry.npmjs.org/@wordpress/dataviews/-/dataviews-13.1.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/dataviews@16.0.1':
+    resolution: {integrity: sha512-OyDOPvtCIL0AV4wTGSrFHhBVEYwkBJvmfleSjXzGWc09u3BPIiefazoGN4GvtJPJbvieSyelXuVyN+JARIRUug==, tarball: https://registry.npmjs.org/@wordpress/dataviews/-/dataviews-16.0.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/date@5.48.1':
+    resolution: {integrity: sha512-SD6AzzmxtsrTbSkZFV6nklYzYgZFDuCxX41kxRmIQGTBNP0f4DvLjwlUCpLN/lHEerctx4XdkZAghvGOHOKvbg==, tarball: https://registry.npmjs.org/@wordpress/date/-/date-5.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/deprecated@4.48.1':
+    resolution: {integrity: sha512-ZfJSCxWr4Ss5qGja9W7L6+8vcrbX0n+tKDe2TrYvTq6GiqEc+0MrajIl4vi/58jhceHbSze1ITX/ocC3Ed3NLg==, tarball: https://registry.npmjs.org/@wordpress/deprecated/-/deprecated-4.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/dom-ready@4.48.1':
+    resolution: {integrity: sha512-EYd2H8cYSk8H3wSnTK1wTtuC+hOCmMmZrCEBWzgHevs1n3B9g0nwBafSiRWpzc0vA2vculkNNtlSfy3ByJ2hag==, tarball: https://registry.npmjs.org/@wordpress/dom-ready/-/dom-ready-4.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/dom@4.48.1':
+    resolution: {integrity: sha512-UmouS3KAAUf6q90adAM37FZ3Tq+w+5UfNVUEKRtZjzbH3gMZJTKmYXpG9dkYyLLmicXgOrcG1GQ0qTX91MjAuA==, tarball: https://registry.npmjs.org/@wordpress/dom/-/dom-4.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/element@6.46.0':
+    resolution: {integrity: sha512-hjnrqZi0cZVdkmN0xQavKfSQJYAkb9pVSnDPpuX65OLxeD9/EWkIXvFzBb+nH8c4NzKKSqQU96XCTQrH37OCIA==, tarball: https://registry.npmjs.org/@wordpress/element/-/element-6.46.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/element@8.0.1':
+    resolution: {integrity: sha512-otYhxfm6ZKkcLCl/tI1rB70z6MVDvTL+RiPOWXi4qm0niJf4isSXCcB91ffj1gzJXKbEpszHfysIoU9L2gCSGQ==, tarball: https://registry.npmjs.org/@wordpress/element/-/element-8.0.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/escape-html@3.48.1':
+    resolution: {integrity: sha512-TQJK6sBcmMA5+xMjiAFuivcZ27wUgAfVCgB/fGf7YoxVC+BnCCIanAsHgpY0d4juGUK6LXzDEhU6ZgOpGkGqIQ==, tarball: https://registry.npmjs.org/@wordpress/escape-html/-/escape-html-3.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/global-styles-engine@1.15.1':
+    resolution: {integrity: sha512-jpMnDkAE1stcoSV19hyet0b2wySMz1kaplNivruKwUyQilkQRIhqlJFiEKBVt513m9I9CbEPA0WKcTpfqJxIMA==, tarball: https://registry.npmjs.org/@wordpress/global-styles-engine/-/global-styles-engine-1.15.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/hooks@4.42.0':
+    resolution: {integrity: sha512-isdznPKo+LEAGrP/o6SnWjxKYKn4KNzb5dmpnYPTbLh13gE/p8KctpLyzMsgR2GBXF8soAL+hpXMxxKoTQSabA==, tarball: https://registry.npmjs.org/@wordpress/hooks/-/hooks-4.42.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/hooks@4.48.1':
+    resolution: {integrity: sha512-QZh3Cv9TMJkrCQikuZSsDKTgX+6BBzYJe0MFKp7yP8drj/dtRpkqo5+eYmovBq3pk+HoyP7UJ1vTOb3GPJeU6Q==, tarball: https://registry.npmjs.org/@wordpress/hooks/-/hooks-4.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/html-entities@4.48.1':
+    resolution: {integrity: sha512-Gq6j3yl+m0pc0989jFjAgYbtdwHyUS/5PR39zg+hQfq1IWiqCwfhFlJAqc8ymwx/gSklrxf9mmyhBwmUPWtMcw==, tarball: https://registry.npmjs.org/@wordpress/html-entities/-/html-entities-4.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/i18n@6.21.1':
+    resolution: {integrity: sha512-qBbDJTRCtMfEzTVtzOa/fZf8XlU/JY3nI4MSdxyRQKduFanbXvzTRqJSSEIpZS4ACJTyUqafZX8zEZIH5CrNHQ==, tarball: https://registry.npmjs.org/@wordpress/i18n/-/i18n-6.21.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    hasBin: true
+
+  '@wordpress/icons@12.2.0':
+    resolution: {integrity: sha512-Fiw7bmfHDNPjTdCrBF23/9K0VN/GUi73d2ZPZaeWdXhTmIX62T9KYvb1c+WnlBkX7GpXgJO6Q8mypQCY9mw5SQ==, tarball: https://registry.npmjs.org/@wordpress/icons/-/icons-12.2.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+
+  '@wordpress/icons@14.0.1':
+    resolution: {integrity: sha512-Vf3wXrS8JWwozKGQ3vS8WQBwmzZyk0ih3W92kE+xPDK2K5QPrlW4MjbSV8gYbNAHC6NECPSWrEGI3DmbgvAP3w==, tarball: https://registry.npmjs.org/@wordpress/icons/-/icons-14.0.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+
+  '@wordpress/image-cropper@1.12.1':
+    resolution: {integrity: sha512-r7t5fzUGzeCt2Pkkp6lgh/a2UKsgW+okeR7Ldw29snE96JZcjYJHyJfRfqOGFZVxrCcoDe2XaEy+Q6PdL+aJhw==, tarball: https://registry.npmjs.org/@wordpress/image-cropper/-/image-cropper-1.12.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/interactivity-router@2.48.1':
+    resolution: {integrity: sha512-bMGGPK279FzP367ro5/nMPifvurAQDEHF5sZZpt/lktRIgQ1JJfEMiKMb92Q5S71Sj2CSQMSNmxKKNGU24FilA==, tarball: https://registry.npmjs.org/@wordpress/interactivity-router/-/interactivity-router-2.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/interactivity@6.48.1':
+    resolution: {integrity: sha512-Qc+VoBt2XNoOuVMZwjQtZJ8iQfh7mJsSjPlxzSMyYRHGPa+WqfWO50LY/vyXYPs5s5FoMsb3S64ty/p//1DI2w==, tarball: https://registry.npmjs.org/@wordpress/interactivity/-/interactivity-6.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/is-shallow-equal@5.48.1':
+    resolution: {integrity: sha512-qOn4doqp8Xr5vOdF7kni5BThkMLxFA9fZIUVZo/lzs+/rwV7rwdQQXtq/PXnHcOWDOqHSXBVlUciV7clDE6aeA==, tarball: https://registry.npmjs.org/@wordpress/is-shallow-equal/-/is-shallow-equal-5.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/keyboard-shortcuts@5.48.1':
+    resolution: {integrity: sha512-HYm/Q52G5UvF4rOleWWJaRvsRjWBOyqhcCdlXXtVAWn7qEq5V2Lm5RSdI4L66EVFqRAHAPsz9ouwwiU98N5NFQ==, tarball: https://registry.npmjs.org/@wordpress/keyboard-shortcuts/-/keyboard-shortcuts-5.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+
+  '@wordpress/keycodes@4.48.1':
+    resolution: {integrity: sha512-mVNex4sY0APJj69kxFfCmaoJVOaNd9Bu7oNecuXKEAI4sp/jvvn0x+IGwLt1lMrLqC3+bPEo+q+JV3KNXMOJIQ==, tarball: https://registry.npmjs.org/@wordpress/keycodes/-/keycodes-4.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/latex-to-mathml@1.16.1':
+    resolution: {integrity: sha512-6/3m9muj5Y1nyyZAoelcEfDjtIZyAJFA0cmyPfZXQPieu+eAbtea2GeEIyW3m6vfyX64dylwxZuUdM9EF6OFKA==, tarball: https://registry.npmjs.org/@wordpress/latex-to-mathml/-/latex-to-mathml-1.16.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/notices@5.48.1':
+    resolution: {integrity: sha512-igkUhvyvp+C61HcE7OBiCPkPYMae8k0BQBZblepXghkX82zlqVe5NiueepWTwY7pFDDEsZlxl9sYF2DWf6HF3w==, tarball: https://registry.npmjs.org/@wordpress/notices/-/notices-5.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+
+  '@wordpress/patterns@2.48.1':
+    resolution: {integrity: sha512-/Y3CgMXqGLMOBgDUeWpWm9DtK3Z3Thdwn3i83q6NLaHLx8Ihbqlva78qotrkXH3Bigj45qFC1QwYLpKneZDwKQ==, tarball: https://registry.npmjs.org/@wordpress/patterns/-/patterns-2.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/preferences@4.48.1':
+    resolution: {integrity: sha512-ETRFHFXRJ80UYXwjy5FQlAHlVZQjC3PUqvrW6KT8aJT/nsy8+uMLV0FUE1e37QqeAwdwMDj9jC/MNz0m3eRmOw==, tarball: https://registry.npmjs.org/@wordpress/preferences/-/preferences-4.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/primitives@4.48.1':
+    resolution: {integrity: sha512-nzAcsXhBxw9x2q/ImVa45Ft80TO+e/WgCDmWaU3Zb2trogwThxZTezkE0oeQ6PSxSeGYM6nBgk+qqFCG8wyMhQ==, tarball: https://registry.npmjs.org/@wordpress/primitives/-/primitives-4.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+
+  '@wordpress/priority-queue@3.48.1':
+    resolution: {integrity: sha512-6nPO/FU1f9r9Zilaz7TOFSTIH5ojPqk/mmDFofo0h2kIljqik/mLwBOIls6WdDrQ2kti+BRNohbjGElAcws7kg==, tarball: https://registry.npmjs.org/@wordpress/priority-queue/-/priority-queue-3.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/private-apis@1.48.1':
+    resolution: {integrity: sha512-KddQQq+qboNnc4fROsy9bsX4JENRfvBMtuBg5CjOq11hScFyh169ozoHozMEtNGXou4XFykEHCRwzM5MfSHjiA==, tarball: https://registry.npmjs.org/@wordpress/private-apis/-/private-apis-1.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/redux-routine@5.48.1':
+    resolution: {integrity: sha512-+mUHB2DxfqGODfc9Lwdhz8D7jjojjWqhoa8w0ckUCzh84ZERiR3BcoiGhCkiWVSl9XedKu9itLFna5Q4gilEZw==, tarball: https://registry.npmjs.org/@wordpress/redux-routine/-/redux-routine-5.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      redux: '>=4'
+
+  '@wordpress/reusable-blocks@5.48.1':
+    resolution: {integrity: sha512-7QVnJlm4u8goWh/0uvmvkb96gBAG6K33WTWluWFTuBmROB3bOc7Ei2PH9brqQms+cu0HkzCQzpL0oytTpFNf2g==, tarball: https://registry.npmjs.org/@wordpress/reusable-blocks/-/reusable-blocks-5.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/rich-text@7.48.1':
+    resolution: {integrity: sha512-pj+S2d2p4EUJ03V/tOhlvb9qGPixft7v1zj9KEyM70VY6nHD5mmVp95Q5ALtlioyDFWYhzSo609PEd9fJ8FTsQ==, tarball: https://registry.npmjs.org/@wordpress/rich-text/-/rich-text-7.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+
+  '@wordpress/server-side-render@6.24.1':
+    resolution: {integrity: sha512-ZlmtAdJQ3QEmNlvbpfdD0f0mq/eesSMziqKYvmnjS3eS6t12/S7a7fIiOpKxvRzHzgtRi/f+8u4f+IEoPJm8hA==, tarball: https://registry.npmjs.org/@wordpress/server-side-render/-/server-side-render-6.24.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/shortcode@4.48.1':
+    resolution: {integrity: sha512-zfOz45verEOIf3YIE4zOlMcQoZ2za+OFuJ4SKE+nmglUFLmF2I0iLGlNQO0BNLPI26+krSVZ8kclzJRaB5Z6Kw==, tarball: https://registry.npmjs.org/@wordpress/shortcode/-/shortcode-4.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/style-engine@2.48.1':
+    resolution: {integrity: sha512-biMD3eTjoUj5hlmA261kLAlgCN/bjxeeRe7XFrjG/bxQErmYp+hmMSejNTuLpg3j8I11eQ3Vo0iRCjGzn4xFEQ==, tarball: https://registry.npmjs.org/@wordpress/style-engine/-/style-engine-2.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/style-runtime@0.4.1':
+    resolution: {integrity: sha512-guZ0p9a5ZQyyCFPwVqDkhDNVXdXAhIqNkPGSNIGguEtt3OtSOskEMwYJHyXZYX8nlbH0FyKflGJhE4G6QlIWlw==, tarball: https://registry.npmjs.org/@wordpress/style-runtime/-/style-runtime-0.4.1.tgz}
+    engines: {node: '>=20.10.0', npm: '>=10.2.3'}
+
+  '@wordpress/sync@1.48.1':
+    resolution: {integrity: sha512-RLPTX9f7KdGPyzYDyxwMdnPTEqcAskjOt6AVEb/XJ0gzBmbtqxnoQVrBk/cVcKjaIPTAg2lJkM82RnvnopmoQw==, tarball: https://registry.npmjs.org/@wordpress/sync/-/sync-1.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/theme@0.15.1':
+    resolution: {integrity: sha512-0SqH40Sd4pKH8YkDjQ4JM2NJzdhliO19QTPHAOAGA+tXuh+YwHOwFxX8Mg0v/vvI4XJD11zuiKGr+grBI7icTQ==, tarball: https://registry.npmjs.org/@wordpress/theme/-/theme-0.15.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+      stylelint: ^16.8.2
+    peerDependenciesMeta:
+      stylelint:
+        optional: true
+
+  '@wordpress/theme@0.9.0':
+    resolution: {integrity: sha512-jxskNZVvWHIswQvWvswaNIAkBpXwdFcocBYxTWQnYgvb0QAEYsKsnqYMulZPrz/Dk4c+GF7ptwdLxb3rry9tcg==, tarball: https://registry.npmjs.org/@wordpress/theme/-/theme-0.9.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+      stylelint: ^16.8.2
+    peerDependenciesMeta:
+      stylelint:
+        optional: true
+
+  '@wordpress/token-list@3.48.1':
+    resolution: {integrity: sha512-hFAqE8xmTpq/4IVs3AHXxVA2FTrQ2BcOQHsdXJ9kELfcazTZWZsPU2hampfIGYZzyzLnTX06dUubuuy2++LUSQ==, tarball: https://registry.npmjs.org/@wordpress/token-list/-/token-list-3.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/ui@0.15.1':
+    resolution: {integrity: sha512-zFErzf84zc7dGXrCa9fPKUpMhYx86B8n5GeshC7Ut/nfE7yp09g/Bono5S7KhY1OJx7Z1Jur9t+4vnv5cocBbA==, tarball: https://registry.npmjs.org/@wordpress/ui/-/ui-0.15.1.tgz}
+    engines: {node: '>=20.10.0', npm: '>=10.2.3'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/ui@0.9.0':
+    resolution: {integrity: sha512-PXx0CU5ngJOaC69ylhyyS33Ac4njVudGMkrPjXuRd6cXZeizD3q6KO0ws1ECtm4FYlrWv5YvYyNhT5salP9hTg==, tarball: https://registry.npmjs.org/@wordpress/ui/-/ui-0.9.0.tgz}
+    engines: {node: '>=20.10.0', npm: '>=10.2.3'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/undo-manager@1.48.1':
+    resolution: {integrity: sha512-i/yHiUQ5S47yong7FXxIRpJgO1MbItEKfcyp1a3rRe66rw1RVPmAlJxyeKaQg9eZbCXOmmDz5cLzZNPyUDN6uA==, tarball: https://registry.npmjs.org/@wordpress/undo-manager/-/undo-manager-1.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/upload-media@0.27.0':
+    resolution: {integrity: sha512-p14rxOwpr5URUpqKPDhg+lIPhEek9d0XjvXOL8PPEAB0RcaBF6utBrmMtdxTdRfOqbQ4KBoIM5NrkLrBT6h0og==, tarball: https://registry.npmjs.org/@wordpress/upload-media/-/upload-media-0.27.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/upload-media@0.33.1':
+    resolution: {integrity: sha512-FjHJGZh7tjUyMbHXiPPHT8oRpM24ENwCOYG7OEoWRGP3NSU5v9Ff4TCksI25Ws420TkrNCFnHlU+xmALQAu30w==, tarball: https://registry.npmjs.org/@wordpress/upload-media/-/upload-media-0.33.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+      react-dom: ^18.0.0
+
+  '@wordpress/url@4.48.1':
+    resolution: {integrity: sha512-EiTMmEwotXY4Cu6casJ10HEe0ocsdVujkm1iZyA0vvu2qtR5IIQqlSVGxDx96cJBP6cB2b8x2ebGLWfnwow4/Q==, tarball: https://registry.npmjs.org/@wordpress/url/-/url-4.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/viewport@6.48.1':
+    resolution: {integrity: sha512-W/bpuh4ndoNUdH2Cfuq2N+vBWU5mSyPdG5bQOaHeK31c2YQfti/3sQTbGZ9h+wHCoUGfI1az87kimPMbqr9GqQ==, tarball: https://registry.npmjs.org/@wordpress/viewport/-/viewport-6.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+    peerDependencies:
+      react: ^18.0.0
+
+  '@wordpress/vips@1.6.0':
+    resolution: {integrity: sha512-TiQYzS5L2hVk6H9Xpk0tSzMu0cpCLUXNCXioiM/LZ2SvzP9ibwp+uXp2QwI2SS32aO06OeECaCJx+qgbIimv3A==, tarball: https://registry.npmjs.org/@wordpress/vips/-/vips-1.6.0.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/vips@2.1.1':
+    resolution: {integrity: sha512-3NvM0Bk4xrNhYI8Xgn9+dphE3FbJANhe9aNoU1J/Wqmqt3EpUJY5KoykFkfpHJWbdiLohSMkKIyVylGMdHpP7g==, tarball: https://registry.npmjs.org/@wordpress/vips/-/vips-2.1.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/warning@3.48.1':
+    resolution: {integrity: sha512-5YyMCOHycuHG+AjsVEUafpTqV4b4qjVv/tel5m1L8k8g8dUW5T/XKguFo1nhCqQc4HqoGBrJtKjaf6dMmg8uWg==, tarball: https://registry.npmjs.org/@wordpress/warning/-/warning-3.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/wordcount@4.48.1':
+    resolution: {integrity: sha512-/IdYqxbvAFgAf3O72lUj5ybeWMglG2dYwL8wz17koSHqH5XKlbIQrNGvz4XIvQueiewd4MvLOqIFt2TVHHU6/A==, tarball: https://registry.npmjs.org/@wordpress/wordcount/-/wordcount-4.48.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  '@wordpress/worker-threads@1.8.1':
+    resolution: {integrity: sha512-xrVypgVxciFPyc704/0fdQ6bf5BZrf2EXtTPQ4BSU0ylnvfSvgvTCYWdVzlI4VySq+FNfHgLHTCxKiKT23CrSQ==, tarball: https://registry.npmjs.org/@wordpress/worker-threads/-/worker-threads-1.8.1.tgz}
+    engines: {node: '>=18.12.0', npm: '>=8.19.2'}
+
+  ansi-regex@4.1.1:
+    resolution: {integrity: sha512-ILlv4k/3f6vfQ4OoP2AGvirOktlQ98ZEL1k9FaQjxa3L1abBgbuTDAdPOpvbGncC0BTVQrl+OM8xZGK6tWXt7g==, tarball: https://registry.npmjs.org/ansi-regex/-/ansi-regex-4.1.1.tgz}
+    engines: {node: '>=6'}
+
+  ansi-styles@3.2.1:
+    resolution: {integrity: sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==, tarball: https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz}
+    engines: {node: '>=4'}
+
+  ansi-styles@5.2.0:
+    resolution: {integrity: sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==, tarball: https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz}
+    engines: {node: '>=10'}
+
+  any-promise@1.3.0:
+    resolution: {integrity: sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==, tarball: https://registry.npmjs.org/any-promise/-/any-promise-1.3.0.tgz}
+
+  anymatch@3.1.3:
+    resolution: {integrity: sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==, tarball: https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz}
+    engines: {node: '>= 8'}
+
+  aria-hidden@1.2.6:
+    resolution: {integrity: sha512-ik3ZgC9dY/lYVVM++OISsaYDeg1tb0VtP5uL3ouh1koGOaUMDPpbFIei4JkFimWUFPn90sbMNMXQAIVOlnYKJA==, tarball: https://registry.npmjs.org/aria-hidden/-/aria-hidden-1.2.6.tgz}
+    engines: {node: '>=10'}
+
+  array-union@2.1.0:
+    resolution: {integrity: sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==, tarball: https://registry.npmjs.org/array-union/-/array-union-2.1.0.tgz}
+    engines: {node: '>=8'}
+
+  assertion-error@2.0.1:
+    resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==, tarball: https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz}
+    engines: {node: '>=12'}
+
+  autosize@4.0.4:
+    resolution: {integrity: sha512-5yxLQ22O0fCRGoxGfeLSNt3J8LB1v+umtpMnPW6XjkTWXKoN0AmXAIhelJcDtFT/Y/wYWmfE+oqU10Q0b8FhaQ==, tarball: https://registry.npmjs.org/autosize/-/autosize-4.0.4.tgz}
+
+  babel-plugin-macros@3.1.0:
+    resolution: {integrity: sha512-Cg7TFGpIr01vOQNODXOOaGz2NpCU5gl8x1qJFbb6hbZxR7XrcE2vtbAsTAbJ7/xwJtUuJEw8K8Zr/AE0LHlesg==, tarball: https://registry.npmjs.org/babel-plugin-macros/-/babel-plugin-macros-3.1.0.tgz}
+    engines: {node: '>=10', npm: '>=6'}
+
+  bidi-js@1.0.3:
+    resolution: {integrity: sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw==, tarball: https://registry.npmjs.org/bidi-js/-/bidi-js-1.0.3.tgz}
+
+  binary-extensions@2.3.0:
+    resolution: {integrity: sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==, tarball: https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.3.0.tgz}
+    engines: {node: '>=8'}
+
+  boolbase@1.0.0:
+    resolution: {integrity: sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==, tarball: https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz}
+
+  braces@3.0.3:
+    resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==, tarball: https://registry.npmjs.org/braces/-/braces-3.0.3.tgz}
+    engines: {node: '>=8'}
+
+  bundle-require@4.2.1:
+    resolution: {integrity: sha512-7Q/6vkyYAwOmQNRw75x+4yRtZCZJXUDmHHlFdkiV0wgv/reNjtJwpu1jPJ0w2kbEpIM0uoKI3S4/f39dU7AjSA==, tarball: https://registry.npmjs.org/bundle-require/-/bundle-require-4.2.1.tgz}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+    peerDependencies:
+      esbuild: '>=0.17'
+
+  cac@6.7.14:
+    resolution: {integrity: sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==, tarball: https://registry.npmjs.org/cac/-/cac-6.7.14.tgz}
+    engines: {node: '>=8'}
+
+  callsites@3.1.0:
+    resolution: {integrity: sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==, tarball: https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz}
+    engines: {node: '>=6'}
+
+  camel-case@4.1.2:
+    resolution: {integrity: sha512-gxGWBrTT1JuMx6R+o5PTXMmUnhnVzLQ9SNutD4YqKtI6ap897t3tKECYla6gCWEkplXnlNybEkZg9GEGxKFCgw==, tarball: https://registry.npmjs.org/camel-case/-/camel-case-4.1.2.tgz}
+
+  camelcase@5.3.1:
+    resolution: {integrity: sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==, tarball: https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz}
+    engines: {node: '>=6'}
+
+  capital-case@1.0.4:
+    resolution: {integrity: sha512-ds37W8CytHgwnhGGTi88pcPyR15qoNkOpYwmMMfnWqqWgESapLqvDx6huFjQ5vqWSn2Z06173XNA7LtMOeUh1A==, tarball: https://registry.npmjs.org/capital-case/-/capital-case-1.0.4.tgz}
+
+  chai@5.3.3:
+    resolution: {integrity: sha512-4zNhdJD/iOjSH0A05ea+Ke6MU5mmpQcbQsSOkgdaUMJ9zTlDTD/GYlwohmIE2u0gaxHYiVHEn1Fw9mZ/ktJWgw==, tarball: https://registry.npmjs.org/chai/-/chai-5.3.3.tgz}
+    engines: {node: '>=18'}
+
+  change-case@4.1.2:
+    resolution: {integrity: sha512-bSxY2ws9OtviILG1EiY5K7NNxkqg/JnRnFxLtKQ96JaviiIxi7djMrSd0ECT9AC+lttClmYwKw53BWpOMblo7A==, tarball: https://registry.npmjs.org/change-case/-/change-case-4.1.2.tgz}
+
+  check-error@2.1.3:
+    resolution: {integrity: sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA==, tarball: https://registry.npmjs.org/check-error/-/check-error-2.1.3.tgz}
+    engines: {node: '>= 16'}
+
+  cheerio-select@2.1.0:
+    resolution: {integrity: sha512-9v9kG0LvzrlcungtnJtpGNxY+fzECQKhK4EGJX2vByejiMX84MFNQw4UxPJl3bFbTMw+Dfs37XaIkCwTZfLh4g==, tarball: https://registry.npmjs.org/cheerio-select/-/cheerio-select-2.1.0.tgz}
+
+  cheerio@1.2.0:
+    resolution: {integrity: sha512-WDrybc/gKFpTYQutKIK6UvfcuxijIZfMfXaYm8NMsPQxSYvf+13fXUJ4rztGGbJcBQ/GF55gvrZ0Bc0bj/mqvg==, tarball: https://registry.npmjs.org/cheerio/-/cheerio-1.2.0.tgz}
+    engines: {node: '>=20.18.1'}
+
+  chokidar@3.6.0:
+    resolution: {integrity: sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==, tarball: https://registry.npmjs.org/chokidar/-/chokidar-3.6.0.tgz}
+    engines: {node: '>= 8.10.0'}
+
+  cliui@5.0.0:
+    resolution: {integrity: sha512-PYeGSEmmHM6zvoef2w8TPzlrnNpXIjTipYK780YswmIP9vjxmd6Y2a3CB2Ks6/AU8NHjZugXvo8w3oWM2qnwXA==, tarball: https://registry.npmjs.org/cliui/-/cliui-5.0.0.tgz}
+
+  clsx@2.1.1:
+    resolution: {integrity: sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==, tarball: https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz}
+    engines: {node: '>=6'}
+
+  cmdk@1.1.1:
+    resolution: {integrity: sha512-Vsv7kFaXm+ptHDMZ7izaRsP70GgrW9NBNGswt9OZaVBLlE0SNpDq8eu/VGXyF9r7M0azK3Wy7OlYXsuyYLFzHg==, tarball: https://registry.npmjs.org/cmdk/-/cmdk-1.1.1.tgz}
+    peerDependencies:
+      react: ^18 || ^19 || ^19.0.0-rc
+      react-dom: ^18 || ^19 || ^19.0.0-rc
+
+  color-convert@1.9.3:
+    resolution: {integrity: sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==, tarball: https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz}
+
+  color-name@1.1.3:
+    resolution: {integrity: sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==, tarball: https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz}
+
+  colord@2.9.3:
+    resolution: {integrity: sha512-jeC1axXpnb0/2nn/Y1LPuLdgXBLH7aDcHu4KEKfqw3CUhX7ZpfBSlPKyqXE6btIgEzfWtrX3/tyBCaCvXvMkOw==, tarball: https://registry.npmjs.org/colord/-/colord-2.9.3.tgz}
+
+  colorjs.io@0.6.1:
+    resolution: {integrity: sha512-8lyR2wHzuIykCpqHKgluGsqQi5iDm3/a2IgP2GBZrasn2sBRkE4NOGsglZxWLs/jZQoNkmA/KM/8NV16rLUdBg==, tarball: https://registry.npmjs.org/colorjs.io/-/colorjs.io-0.6.1.tgz}
+
+  comctx@1.7.5:
+    resolution: {integrity: sha512-0fsxsxr1Hg2T99wOIteUbsJOX6jMmnhAJepcVRqNRMWpcbxRhbm2+0R8qEuQEaE4gWjfdXaKeAGYAn0yeElylQ==, tarball: https://registry.npmjs.org/comctx/-/comctx-1.7.5.tgz}
+
+  commander@4.1.1:
+    resolution: {integrity: sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==, tarball: https://registry.npmjs.org/commander/-/commander-4.1.1.tgz}
+    engines: {node: '>= 6'}
+
+  computed-style@0.1.4:
+    resolution: {integrity: sha512-WpAmaKbMNmS3OProfHIdJiNleNJdgUrJfbKArXua28QF7+0CoZjlLn0lp6vlc+dl5r2/X9GQiQRQQU4BzSa69w==, tarball: https://registry.npmjs.org/computed-style/-/computed-style-0.1.4.tgz}
+
+  constant-case@3.0.4:
+    resolution: {integrity: sha512-I2hSBi7Vvs7BEuJDr5dDHfzb/Ruj3FyvFyh7KLilAjNQw3Be+xgqUBA2W6scVEcL0hL1dwPRtIqEPVUCKkSsyQ==, tarball: https://registry.npmjs.org/constant-case/-/constant-case-3.0.4.tgz}
+
+  convert-source-map@1.9.0:
+    resolution: {integrity: sha512-ASFBup0Mz1uyiIjANan1jzLQami9z1PoYSZCiiYW2FczPbenXc45FZdBZLzOT+r6+iciuEModtmCti+hjaAk0A==, tarball: https://registry.npmjs.org/convert-source-map/-/convert-source-map-1.9.0.tgz}
+
+  cosmiconfig@7.1.0:
+    resolution: {integrity: sha512-AdmX6xUzdNASswsFtmwSt7Vj8po9IuqXm0UXz7QKPuEUmPB4XyjGfaAr2PSuELMwkRMVH1EpIkX5bTZGRB3eCA==, tarball: https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-7.1.0.tgz}
+    engines: {node: '>=10'}
+
+  cross-spawn@7.0.6:
+    resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==, tarball: https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz}
+    engines: {node: '>= 8'}
+
+  css-select@5.2.2:
+    resolution: {integrity: sha512-TizTzUddG/xYLA3NXodFM0fSbNizXjOKhqiQQwvhlspadZokn1KDy0NZFS0wuEubIYAV5/c1/lAr0TaaFXEXzw==, tarball: https://registry.npmjs.org/css-select/-/css-select-5.2.2.tgz}
+
+  css-tree@3.2.1:
+    resolution: {integrity: sha512-X7sjQzceUhu1u7Y/ylrRZFU2FS6LRiFVp6rKLPg23y3x3c3DOKAwuXGDp+PAGjh6CSnCjYeAul8pcT8bAl+lSA==, tarball: https://registry.npmjs.org/css-tree/-/css-tree-3.2.1.tgz}
+    engines: {node: ^10 || ^12.20.0 || ^14.13.0 || >=15.0.0}
+
+  css-what@6.2.2:
+    resolution: {integrity: sha512-u/O3vwbptzhMs3L1fQE82ZSLHQQfto5gyZzwteVIEyeaY5Fc7R4dapF/BvRoSYFeqfBk4m0V1Vafq5Pjv25wvA==, tarball: https://registry.npmjs.org/css-what/-/css-what-6.2.2.tgz}
+    engines: {node: '>= 6'}
+
+  csstype@3.2.3:
+    resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==, tarball: https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz}
+
+  data-urls@7.0.0:
+    resolution: {integrity: sha512-23XHcCF+coGYevirZceTVD7NdJOqVn+49IHyxgszm+JIiHLoB2TkmPtsYkNWT1pvRSGkc35L6NHs0yHkN2SumA==, tarball: https://registry.npmjs.org/data-urls/-/data-urls-7.0.0.tgz}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
+
+  date-fns-jalali@4.1.0-0:
+    resolution: {integrity: sha512-hTIP/z+t+qKwBDcmmsnmjWTduxCg+5KfdqWQvb2X/8C9+knYY6epN/pfxdDuyVlSVeFz0sM5eEfwIUQ70U4ckg==, tarball: https://registry.npmjs.org/date-fns-jalali/-/date-fns-jalali-4.1.0-0.tgz}
+
+  date-fns@3.6.0:
+    resolution: {integrity: sha512-fRHTG8g/Gif+kSh50gaGEdToemgfj74aRX3swtiouboip5JDLAyDE9F11nHMIcvOaXeOC6D7SpNhi7uFyB7Uww==, tarball: https://registry.npmjs.org/date-fns/-/date-fns-3.6.0.tgz}
+
+  date-fns@4.4.0:
+    resolution: {integrity: sha512-+1UMbeh68lH1SegH83CGWwpb6OHHbpSgr3+s5Eww5M4CAgswBpoWS0AjTOfEJ33HiYKz1hdj/KTFprzXHmq/6w==, tarball: https://registry.npmjs.org/date-fns/-/date-fns-4.4.0.tgz}
+
+  debug@4.4.3:
+    resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==, tarball: https://registry.npmjs.org/debug/-/debug-4.4.3.tgz}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  decamelize@1.2.0:
+    resolution: {integrity: sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==, tarball: https://registry.npmjs.org/decamelize/-/decamelize-1.2.0.tgz}
+    engines: {node: '>=0.10.0'}
+
+  decimal.js@10.6.0:
+    resolution: {integrity: sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==, tarball: https://registry.npmjs.org/decimal.js/-/decimal.js-10.6.0.tgz}
+
+  deep-eql@5.0.2:
+    resolution: {integrity: sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q==, tarball: https://registry.npmjs.org/deep-eql/-/deep-eql-5.0.2.tgz}
+    engines: {node: '>=6'}
+
+  deepmerge@4.3.1:
+    resolution: {integrity: sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A==, tarball: https://registry.npmjs.org/deepmerge/-/deepmerge-4.3.1.tgz}
+    engines: {node: '>=0.10.0'}
+
+  dequal@2.0.3:
+    resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==, tarball: https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz}
+    engines: {node: '>=6'}
+
+  detect-node-es@1.1.0:
+    resolution: {integrity: sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ==, tarball: https://registry.npmjs.org/detect-node-es/-/detect-node-es-1.1.0.tgz}
+
+  diff-sequences@29.6.3:
+    resolution: {integrity: sha512-EjePK1srD3P08o2j4f0ExnylqRs5B9tJjcp9t1krH2qRi8CCdsYfwe9JgSLurFBWwq4uOlipzfk5fHNvwFKr8Q==, tarball: https://registry.npmjs.org/diff-sequences/-/diff-sequences-29.6.3.tgz}
+    engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0}
+
+  diff@4.0.4:
+    resolution: {integrity: sha512-X07nttJQkwkfKfvTPG/KSnE2OMdcUCao6+eXF3wmnIQRn2aPAHH3VxDbDOdegkd6JbPsXqShpvEOHfAT+nCNwQ==, tarball: https://registry.npmjs.org/diff/-/diff-4.0.4.tgz}
+    engines: {node: '>=0.3.1'}
+
+  diff@8.0.4:
+    resolution: {integrity: sha512-DPi0FmjiSU5EvQV0++GFDOJ9ASQUVFh5kD+OzOnYdi7n3Wpm9hWWGfB/O2blfHcMVTL5WkQXSnRiK9makhrcnw==, tarball: https://registry.npmjs.org/diff/-/diff-8.0.4.tgz}
+    engines: {node: '>=0.3.1'}
+
+  dir-glob@3.0.1:
+    resolution: {integrity: sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==, tarball: https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz}
+    engines: {node: '>=8'}
+
+  dom-serializer@2.0.0:
+    resolution: {integrity: sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg==, tarball: https://registry.npmjs.org/dom-serializer/-/dom-serializer-2.0.0.tgz}
+
+  domelementtype@2.3.0:
+    resolution: {integrity: sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==, tarball: https://registry.npmjs.org/domelementtype/-/domelementtype-2.3.0.tgz}
+
+  domhandler@5.0.3:
+    resolution: {integrity: sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==, tarball: https://registry.npmjs.org/domhandler/-/domhandler-5.0.3.tgz}
+    engines: {node: '>= 4'}
+
+  domutils@3.2.2:
+    resolution: {integrity: sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw==, tarball: https://registry.npmjs.org/domutils/-/domutils-3.2.2.tgz}
+
+  dot-case@3.0.4:
+    resolution: {integrity: sha512-Kv5nKlh6yRrdrGvxeJ2e5y2eRUpkUosIW4A2AS38zwSz27zu7ufDwQPi5Jhs3XAlGNetl3bmnGhQsMtkKJnj3w==, tarball: https://registry.npmjs.org/dot-case/-/dot-case-3.0.4.tgz}
+
+  emoji-regex@7.0.3:
+    resolution: {integrity: sha512-CwBLREIQ7LvYFB0WyRvwhq5N5qPhc6PMjD6bYggFlI5YyDgl+0vxq5VHbMOFqLg7hfWzmu8T5Z1QofhmTIhItA==, tarball: https://registry.npmjs.org/emoji-regex/-/emoji-regex-7.0.3.tgz}
+
+  encoding-sniffer@0.2.1:
+    resolution: {integrity: sha512-5gvq20T6vfpekVtqrYQsSCFZ1wEg5+wW0/QaZMWkFr6BqD3NfKs0rLCx4rrVlSWJeZb5NBJgVLswK/w2MWU+Gw==, tarball: https://registry.npmjs.org/encoding-sniffer/-/encoding-sniffer-0.2.1.tgz}
+
+  encoding@0.1.13:
+    resolution: {integrity: sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A==, tarball: https://registry.npmjs.org/encoding/-/encoding-0.1.13.tgz}
+
+  entities@4.5.0:
+    resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==, tarball: https://registry.npmjs.org/entities/-/entities-4.5.0.tgz}
+    engines: {node: '>=0.12'}
+
+  entities@6.0.1:
+    resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==, tarball: https://registry.npmjs.org/entities/-/entities-6.0.1.tgz}
+    engines: {node: '>=0.12'}
+
+  entities@7.0.1:
+    resolution: {integrity: sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==, tarball: https://registry.npmjs.org/entities/-/entities-7.0.1.tgz}
+    engines: {node: '>=0.12'}
+
+  entities@8.0.0:
+    resolution: {integrity: sha512-zwfzJecQ/Uej6tusMqwAqU/6KL2XaB2VZ2Jg54Je6ahNBGNH6Ek6g3jjNCF0fG9EWQKGZNddNjU5F1ZQn/sBnA==, tarball: https://registry.npmjs.org/entities/-/entities-8.0.0.tgz}
+    engines: {node: '>=20.19.0'}
+
+  equivalent-key-map@0.2.2:
+    resolution: {integrity: sha512-xvHeyCDbZzkpN4VHQj/n+j2lOwL0VWszG30X4cOrc9Y7Tuo2qCdZK/0AMod23Z5dCtNUbaju6p0rwOhHUk05ew==, tarball: https://registry.npmjs.org/equivalent-key-map/-/equivalent-key-map-0.2.2.tgz}
+
+  error-ex@1.3.4:
+    resolution: {integrity: sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ==, tarball: https://registry.npmjs.org/error-ex/-/error-ex-1.3.4.tgz}
+
+  es-errors@1.3.0:
+    resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==, tarball: https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz}
+    engines: {node: '>= 0.4'}
+
+  es-module-lexer@1.7.0:
+    resolution: {integrity: sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==, tarball: https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-1.7.0.tgz}
+
+  esbuild@0.19.12:
+    resolution: {integrity: sha512-aARqgq8roFBj054KvQr5f1sFu0D65G+miZRCuJyJ0G13Zwx7vRar5Zhn2tkQNzIXcBrNVsv/8stehpj+GAjgbg==, tarball: https://registry.npmjs.org/esbuild/-/esbuild-0.19.12.tgz}
+    engines: {node: '>=12'}
+    hasBin: true
+
+  esbuild@0.21.5:
+    resolution: {integrity: sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==, tarball: https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz}
+    engines: {node: '>=12'}
+    hasBin: true
+
+  escape-string-regexp@4.0.0:
+    resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==, tarball: https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz}
+    engines: {node: '>=10'}
+
+  estree-walker@3.0.3:
+    resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==, tarball: https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz}
+
+  execa@5.1.1:
+    resolution: {integrity: sha512-8uSpZZocAZRBAPIEINJj3Lo9HyGitllczc27Eh5YYojjMFMn8yHMDMaUHE2Jqfq05D/wucwI4JGURyXt1vchyg==, tarball: https://registry.npmjs.org/execa/-/execa-5.1.1.tgz}
+    engines: {node: '>=10'}
+
+  execa@8.0.1:
+    resolution: {integrity: sha512-VyhnebXciFV2DESc+p6B+y0LjSm0krU4OgJN44qFAhBY0TJ+1V61tYD2+wHusZ6F9n5K+vl8k0sTy7PEfV4qpg==, tarball: https://registry.npmjs.org/execa/-/execa-8.0.1.tgz}
+    engines: {node: '>=16.17'}
+
+  fast-average-color@9.5.2:
+    resolution: {integrity: sha512-FbaU8iPTPljP7tmnVhXbCyASNw/zxnmaNDf88gn5pTXlNvejl9w4FapeWMh6UNDwIjhJJU28EPfQWwW032YgPA==, tarball: https://registry.npmjs.org/fast-average-color/-/fast-average-color-9.5.2.tgz}
+    engines: {node: '>= 12'}
+
+  fast-deep-equal@3.1.3:
+    resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==, tarball: https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz}
+
+  fast-glob@3.3.3:
+    resolution: {integrity: sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==, tarball: https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.3.tgz}
+    engines: {node: '>=8.6.0'}
+
+  fastq@1.20.1:
+    resolution: {integrity: sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw==, tarball: https://registry.npmjs.org/fastq/-/fastq-1.20.1.tgz}
+
+  fdir@6.5.0:
+    resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==, tarball: https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz}
+    engines: {node: '>=12.0.0'}
+    peerDependencies:
+      picomatch: ^3 || ^4
+    peerDependenciesMeta:
+      picomatch:
+        optional: true
+
+  fill-range@7.1.1:
+    resolution: {integrity: sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==, tarball: https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz}
+    engines: {node: '>=8'}
+
+  find-root@1.1.0:
+    resolution: {integrity: sha512-NKfW6bec6GfKc0SGx1e07QZY9PE99u0Bft/0rzSD5k3sO/vwkVUpDUKVm5Gpp5Ue3YfShPFTX2070tDs5kB9Ng==, tarball: https://registry.npmjs.org/find-root/-/find-root-1.1.0.tgz}
+
+  find-up@3.0.0:
+    resolution: {integrity: sha512-1yD6RmLI1XBfxugvORwlck6f75tYL+iR0jqwsOrOxMZyGYqUuDhJ0l4AXdO1iX/FTs9cBAMEk1gWSEx1kSbylg==, tarball: https://registry.npmjs.org/find-up/-/find-up-3.0.0.tgz}
+    engines: {node: '>=6'}
+
+  framer-motion@11.18.2:
+    resolution: {integrity: sha512-5F5Och7wrvtLVElIpclDT0CBzMVg3dL22B64aZwHtsIY8RB4mXICLrkajK4G9R+ieSAGcgrLeae2SeUTg2pr6w==, tarball: https://registry.npmjs.org/framer-motion/-/framer-motion-11.18.2.tgz}
+    peerDependencies:
+      '@emotion/is-prop-valid': '*'
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@emotion/is-prop-valid':
+        optional: true
+      react:
+        optional: true
+      react-dom:
+        optional: true
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==, tarball: https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  function-bind@1.1.2:
+    resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==, tarball: https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz}
+
+  get-caller-file@2.0.5:
+    resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==, tarball: https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz}
+    engines: {node: 6.* || 8.* || >= 10.*}
+
+  get-nonce@1.0.1:
+    resolution: {integrity: sha512-FJhYRoDaiatfEkUK8HKlicmu/3SGFD51q3itKDGoSTysQJBnfOcxU5GxnhE1E6soB76MbT0MBtnKJuXyAx+96Q==, tarball: https://registry.npmjs.org/get-nonce/-/get-nonce-1.0.1.tgz}
+    engines: {node: '>=6'}
+
+  get-stream@6.0.1:
+    resolution: {integrity: sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg==, tarball: https://registry.npmjs.org/get-stream/-/get-stream-6.0.1.tgz}
+    engines: {node: '>=10'}
+
+  get-stream@8.0.1:
+    resolution: {integrity: sha512-VaUJspBffn/LMCJVoMvSAdmscJyS1auj5Zulnn5UoYcY531UWmdwhRWkcGKnGU93m5HSXP9LP2usOryrBtQowA==, tarball: https://registry.npmjs.org/get-stream/-/get-stream-8.0.1.tgz}
+    engines: {node: '>=16'}
+
+  gettext-parser@1.4.0:
+    resolution: {integrity: sha512-sedZYLHlHeBop/gZ1jdg59hlUEcpcZJofLq2JFwJT1zTqAU3l2wFv6IsuwFHGqbiT9DWzMUW4/em2+hspnmMMA==, tarball: https://registry.npmjs.org/gettext-parser/-/gettext-parser-1.4.0.tgz}
+
+  glob-parent@5.1.2:
+    resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==, tarball: https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz}
+    engines: {node: '>= 6'}
+
+  globby@11.1.0:
+    resolution: {integrity: sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==, tarball: https://registry.npmjs.org/globby/-/globby-11.1.0.tgz}
+    engines: {node: '>=10'}
+
+  gradient-parser@1.1.1:
+    resolution: {integrity: sha512-Hu0YfNU+38EsTmnUfLXUKFMXq9yz7htGYpF4x+dlbBhUCvIvzLt0yVLT/gJRmvLKFJdqNFrz4eKkIUjIXSr7Tw==, tarball: https://registry.npmjs.org/gradient-parser/-/gradient-parser-1.1.1.tgz}
+    engines: {node: '>=0.10.0'}
+
+  gradient-parser@1.2.0:
+    resolution: {integrity: sha512-6ABGa9CR7WR/0pAJicBy5SJkiikbFM6kf/JjykwX7x+t+s8ORWVnlbi6FkHeFFb36yWsjUpHqSYrygd7ofEUqA==, tarball: https://registry.npmjs.org/gradient-parser/-/gradient-parser-1.2.0.tgz}
+    engines: {node: '>=0.10.0'}
+
+  hasown@2.0.4:
+    resolution: {integrity: sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==, tarball: https://registry.npmjs.org/hasown/-/hasown-2.0.4.tgz}
+    engines: {node: '>= 0.4'}
+
+  header-case@2.0.4:
+    resolution: {integrity: sha512-H/vuk5TEEVZwrR0lp2zed9OCo1uAILMlx0JEMgC26rzyJJ3N1v6XkwHHXJQdR2doSjcGPM6OKPYoJgf0plJ11Q==, tarball: https://registry.npmjs.org/header-case/-/header-case-2.0.4.tgz}
+
+  highlight-words-core@1.2.3:
+    resolution: {integrity: sha512-m1O9HW3/GNHxzSIXWw1wCNXXsgLlxrP0OI6+ycGUhiUHkikqW3OrwVHz+lxeNBe5yqLESdIcj8PowHQ2zLvUvQ==, tarball: https://registry.npmjs.org/highlight-words-core/-/highlight-words-core-1.2.3.tgz}
+
+  hoist-non-react-statics@3.3.2:
+    resolution: {integrity: sha512-/gGivxi8JPKWNm/W0jSmzcMPpfpPLc3dY/6GxhX2hQ9iGj3aDfklV4ET7NjKpSinLpJ5vafa9iiGIEZg10SfBw==, tarball: https://registry.npmjs.org/hoist-non-react-statics/-/hoist-non-react-statics-3.3.2.tgz}
+
+  hpq@1.4.0:
+    resolution: {integrity: sha512-ycJQMRaRPBcfnoT1gS5I1XCvbbw9KO94Y0vkwksuOjcJMqNZtb03MF2tCItLI2mQbkZWSSeFinoRDPmjzv4tKg==, tarball: https://registry.npmjs.org/hpq/-/hpq-1.4.0.tgz}
+
+  html-dom-parser@5.1.2:
+    resolution: {integrity: sha512-9nD3Rj3/FuQt83AgIa1Y3ruzspwFFA54AJbQnohXN+K6fL1/bhcDQJJY5Ne4L4A163ADQFVESd/0TLyNoV0mfg==, tarball: https://registry.npmjs.org/html-dom-parser/-/html-dom-parser-5.1.2.tgz}
+
+  html-encoding-sniffer@6.0.0:
+    resolution: {integrity: sha512-CV9TW3Y3f8/wT0BRFc1/KAVQ3TUHiXmaAb6VW9vtiMFf7SLoMd1PdAc4W3KFOFETBJUb90KatHqlsZMWV+R9Gg==, tarball: https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-6.0.0.tgz}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
+
+  html-react-parser@5.2.11:
+    resolution: {integrity: sha512-WnSQVn/D1UTj64nSz5y8MriL+MrbsZH80Ytr1oqKqs8DGZnphWY1R1pl3t7TY3rpqTSu+FHA21P80lrsmrdNBA==, tarball: https://registry.npmjs.org/html-react-parser/-/html-react-parser-5.2.11.tgz}
+    peerDependencies:
+      '@types/react': 0.14 || 15 || 16 || 17 || 18 || 19
+      react: 0.14 || 15 || 16 || 17 || 18 || 19
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  htmlparser2@10.0.0:
+    resolution: {integrity: sha512-TwAZM+zE5Tq3lrEHvOlvwgj1XLWQCtaaibSN11Q+gGBAS7Y1uZSWwXXRe4iF6OXnaq1riyQAPFOBtYc77Mxq0g==, tarball: https://registry.npmjs.org/htmlparser2/-/htmlparser2-10.0.0.tgz}
+
+  htmlparser2@10.1.0:
+    resolution: {integrity: sha512-VTZkM9GWRAtEpveh7MSF6SjjrpNVNNVJfFup7xTY3UpFtm67foy9HDVXneLtFVt4pMz5kZtgNcvCniNFb1hlEQ==, tarball: https://registry.npmjs.org/htmlparser2/-/htmlparser2-10.1.0.tgz}
+
+  human-signals@2.1.0:
+    resolution: {integrity: sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw==, tarball: https://registry.npmjs.org/human-signals/-/human-signals-2.1.0.tgz}
+    engines: {node: '>=10.17.0'}
+
+  human-signals@5.0.0:
+    resolution: {integrity: sha512-AXcZb6vzzrFAUE61HnN4mpLqd/cSIwNQjtNWR0euPm6y0iqx3G4gOXaIDdtdDwZmhwe82LA6+zinmW4UBWVePQ==, tarball: https://registry.npmjs.org/human-signals/-/human-signals-5.0.0.tgz}
+    engines: {node: '>=16.17.0'}
+
+  iconv-lite@0.6.3:
+    resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==, tarball: https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz}
+    engines: {node: '>=0.10.0'}
+
+  ignore@5.3.2:
+    resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==, tarball: https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz}
+    engines: {node: '>= 4'}
+
+  import-fresh@3.3.1:
+    resolution: {integrity: sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ==, tarball: https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.1.tgz}
+    engines: {node: '>=6'}
+
+  inline-style-parser@0.2.7:
+    resolution: {integrity: sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==, tarball: https://registry.npmjs.org/inline-style-parser/-/inline-style-parser-0.2.7.tgz}
+
+  is-arrayish@0.2.1:
+    resolution: {integrity: sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==, tarball: https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz}
+
+  is-binary-path@2.1.0:
+    resolution: {integrity: sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==, tarball: https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz}
+    engines: {node: '>=8'}
+
+  is-core-module@2.16.2:
+    resolution: {integrity: sha512-evOr8xfXKxE6qSR0hSXL2r3sd7ALj8+7jQEUvPYcm5sgZFdJ+AYzT6yNmJenvIYQBgIGwfwz08sL8zoL7yq2BA==, tarball: https://registry.npmjs.org/is-core-module/-/is-core-module-2.16.2.tgz}
+    engines: {node: '>= 0.4'}
+
+  is-extglob@2.1.1:
+    resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==, tarball: https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz}
+    engines: {node: '>=0.10.0'}
+
+  is-fullwidth-code-point@2.0.0:
+    resolution: {integrity: sha512-VHskAKYM8RfSFXwee5t5cbN5PZeq1Wrh6qd5bkyiXIf6UQcN6w/A0eXM9r6t8d+GYOh+o6ZhiEnb88LN/Y8m2w==, tarball: https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-2.0.0.tgz}
+    engines: {node: '>=4'}
+
+  is-glob@4.0.3:
+    resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==, tarball: https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz}
+    engines: {node: '>=0.10.0'}
+
+  is-number@7.0.0:
+    resolution: {integrity: sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==, tarball: https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz}
+    engines: {node: '>=0.12.0'}
+
+  is-plain-object@5.0.0:
+    resolution: {integrity: sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==, tarball: https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz}
+    engines: {node: '>=0.10.0'}
+
+  is-potential-custom-element-name@1.0.1:
+    resolution: {integrity: sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==, tarball: https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz}
+
+  is-promise@4.0.0:
+    resolution: {integrity: sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==, tarball: https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz}
+
+  is-stream@2.0.1:
+    resolution: {integrity: sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==, tarball: https://registry.npmjs.org/is-stream/-/is-stream-2.0.1.tgz}
+    engines: {node: '>=8'}
+
+  is-stream@3.0.0:
+    resolution: {integrity: sha512-LnQR4bZ9IADDRSkvpqMGvt/tEJWclzklNgSw48V5EAaAeDd6qGvN8ei6k5p0tvxSR171VmGyHuTiAOfxAbr8kA==, tarball: https://registry.npmjs.org/is-stream/-/is-stream-3.0.0.tgz}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
+  isexe@2.0.0:
+    resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==, tarball: https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz}
+
+  isomorphic.js@0.2.5:
+    resolution: {integrity: sha512-PIeMbHqMt4DnUP3MA/Flc0HElYjMXArsw1qwJZcm9sqR8mq3l8NYizFMty0pWwE/tzIGH3EKK5+jes5mAr85yw==, tarball: https://registry.npmjs.org/isomorphic.js/-/isomorphic.js-0.2.5.tgz}
+
+  joycon@3.1.1:
+    resolution: {integrity: sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==, tarball: https://registry.npmjs.org/joycon/-/joycon-3.1.1.tgz}
+    engines: {node: '>=10'}
+
+  js-tokens@4.0.0:
+    resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==, tarball: https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz}
+
+  jsdom@29.0.1:
+    resolution: {integrity: sha512-z6JOK5gRO7aMybVq/y/MlIpKh8JIi68FBKMUtKkK2KH/wMSRlCxQ682d08LB9fYXplyY/UXG8P4XXTScmdjApg==, tarball: https://registry.npmjs.org/jsdom/-/jsdom-29.0.1.tgz}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24.0.0}
+    peerDependencies:
+      canvas: ^3.0.0
+    peerDependenciesMeta:
+      canvas:
+        optional: true
+
+  jsesc@3.1.0:
+    resolution: {integrity: sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==, tarball: https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  json-parse-even-better-errors@2.3.1:
+    resolution: {integrity: sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==, tarball: https://registry.npmjs.org/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz}
+
+  lib0@0.2.117:
+    resolution: {integrity: sha512-DeXj9X5xDCjgKLU/7RR+/HQEVzuuEUiwldwOGsHK/sfAfELGWEyTcf0x+uOvCvK3O2zPmZePXWL85vtia6GyZw==, tarball: https://registry.npmjs.org/lib0/-/lib0-0.2.117.tgz}
+    engines: {node: '>=16'}
+    hasBin: true
+
+  lilconfig@3.1.3:
+    resolution: {integrity: sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==, tarball: https://registry.npmjs.org/lilconfig/-/lilconfig-3.1.3.tgz}
+    engines: {node: '>=14'}
+
+  line-height@0.3.1:
+    resolution: {integrity: sha512-YExecgqPwnp5gplD2+Y8e8A5+jKpr25+DzMbFdI1/1UAr0FJrTFv4VkHLf8/6B590i1wUPJWMKKldkd/bdQ//w==, tarball: https://registry.npmjs.org/line-height/-/line-height-0.3.1.tgz}
+    engines: {node: '>= 4.0.0'}
+
+  lines-and-columns@1.2.4:
+    resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==, tarball: https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz}
+
+  load-tsconfig@0.2.5:
+    resolution: {integrity: sha512-IXO6OCs9yg8tMKzfPZ1YmheJbZCiEsnBdcB03l0OcfK9prKnJb96siuHCr5Fl37/yo9DnKU+TLpxzTUspw9shg==, tarball: https://registry.npmjs.org/load-tsconfig/-/load-tsconfig-0.2.5.tgz}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
+  locate-path@3.0.0:
+    resolution: {integrity: sha512-7AO748wWnIhNqAuaty2ZWHkQHRSNfPVIsPIfwEOWO22AmaoVrWavlOcMR5nzTLNYvp36X220/maaRsrec1G65A==, tarball: https://registry.npmjs.org/locate-path/-/locate-path-3.0.0.tgz}
+    engines: {node: '>=6'}
+
+  lodash.sortby@4.7.0:
+    resolution: {integrity: sha512-HDWXG8isMntAyRF5vZ7xKuEvOhT4AhlRt/3czTSjvGUxjYCBVRQY48ViDHyfYz9VIoBkW4TMGQNapx+l3RUwdA==, tarball: https://registry.npmjs.org/lodash.sortby/-/lodash.sortby-4.7.0.tgz}
+
+  loose-envify@1.4.0:
+    resolution: {integrity: sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==, tarball: https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz}
+    hasBin: true
+
+  loupe@3.2.1:
+    resolution: {integrity: sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ==, tarball: https://registry.npmjs.org/loupe/-/loupe-3.2.1.tgz}
+
+  lower-case@2.0.2:
+    resolution: {integrity: sha512-7fm3l3NAF9WfN6W3JOmf5drwpVqX78JtoGJ3A6W0a6ZnldM41w2fV5D490psKFTpMds8TJse/eHLFFsNHHjHgg==, tarball: https://registry.npmjs.org/lower-case/-/lower-case-2.0.2.tgz}
+
+  lru-cache@11.5.1:
+    resolution: {integrity: sha512-RPimw/7aMdv2oqRrxKwvZXcPfwBrn/JZ2xYcY9Hus/6LaS3VOAKVWKWgNLCFSiOm1ESXinjsDlidVU7JlnCN2A==, tarball: https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.1.tgz}
+    engines: {node: 20 || >=22}
+
+  magic-string@0.30.21:
+    resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==, tarball: https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz}
+
+  mdn-data@2.27.1:
+    resolution: {integrity: sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ==, tarball: https://registry.npmjs.org/mdn-data/-/mdn-data-2.27.1.tgz}
+
+  memize@2.1.1:
+    resolution: {integrity: sha512-8Nl+i9S5D6KXnruM03Jgjb+LwSupvR13WBr4hJegaaEyobvowCVupi79y2WSiWvO1mzBWxPwEYE5feCe8vyA5w==, tarball: https://registry.npmjs.org/memize/-/memize-2.1.1.tgz}
+
+  merge-stream@2.0.0:
+    resolution: {integrity: sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==, tarball: https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz}
+
+  merge2@1.4.1:
+    resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==, tarball: https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz}
+    engines: {node: '>= 8'}
+
+  micromatch@4.0.8:
+    resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==, tarball: https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz}
+    engines: {node: '>=8.6'}
+
+  mimic-fn@2.1.0:
+    resolution: {integrity: sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==, tarball: https://registry.npmjs.org/mimic-fn/-/mimic-fn-2.1.0.tgz}
+    engines: {node: '>=6'}
+
+  mimic-fn@4.0.0:
+    resolution: {integrity: sha512-vqiC06CuhBTUdZH+RYl8sFrL096vA45Ok5ISO6sE/Mr1jRbGH4Csnhi8f3wKVl7x8mO4Au7Ir9D3Oyv1VYMFJw==, tarball: https://registry.npmjs.org/mimic-fn/-/mimic-fn-4.0.0.tgz}
+    engines: {node: '>=12'}
+
+  moment-timezone@0.5.48:
+    resolution: {integrity: sha512-f22b8LV1gbTO2ms2j2z13MuPogNoh5UzxL3nzNAYKGraILnbGc9NEE6dyiiiLv46DGRb8A4kg8UKWLjPthxBHw==, tarball: https://registry.npmjs.org/moment-timezone/-/moment-timezone-0.5.48.tgz}
+
+  moment@2.30.1:
+    resolution: {integrity: sha512-uEmtNhbDOrWPFS+hdjFCBfy9f2YoyzRpwcl+DqpC6taX21FzsTLQVbMV/W7PzNSX6x/bhC1zA3c2UQ5NzH6how==, tarball: https://registry.npmjs.org/moment/-/moment-2.30.1.tgz}
+
+  motion-dom@11.18.1:
+    resolution: {integrity: sha512-g76KvA001z+atjfxczdRtw/RXOM3OMSdd1f4DL77qCTF/+avrRJiawSG4yDibEQ215sr9kpinSlX2pCTJ9zbhw==, tarball: https://registry.npmjs.org/motion-dom/-/motion-dom-11.18.1.tgz}
+
+  motion-utils@11.18.1:
+    resolution: {integrity: sha512-49Kt+HKjtbJKLtgO/LKj9Ld+6vw9BjH5d9sc40R/kVyH8GLAXgT42M2NnuPcJNuA3s9ZfZBUcwIgpmZWGEE+hA==, tarball: https://registry.npmjs.org/motion-utils/-/motion-utils-11.18.1.tgz}
+
+  mousetrap@1.6.5:
+    resolution: {integrity: sha512-QNo4kEepaIBwiT8CDhP98umTetp+JNfQYBWvC1pc6/OAibuXtRcxZ58Qz8skvEHYvURne/7R8T5VoOI7rDsEUA==, tarball: https://registry.npmjs.org/mousetrap/-/mousetrap-1.6.5.tgz}
+
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==, tarball: https://registry.npmjs.org/ms/-/ms-2.1.3.tgz}
+
+  mz@2.7.0:
+    resolution: {integrity: sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==, tarball: https://registry.npmjs.org/mz/-/mz-2.7.0.tgz}
+
+  nanoid@3.3.15:
+    resolution: {integrity: sha512-y7Wygv/7mEOvxTuEQDB8StXdMRBWf1kR/tlhAzBRUFkB2jfcLOAxO/SHmOO2zgz1pVgK29/kyupn059/bCHdjA==, tarball: https://registry.npmjs.org/nanoid/-/nanoid-3.3.15.tgz}
+    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
+  no-case@3.0.4:
+    resolution: {integrity: sha512-fgAN3jGAh+RoxUGZHTSOLJIqUc2wmoBwGR4tbpNAKmmovFoWq0OdRkb0VkldReO2a2iBT/OEulG9XSUc10r3zg==, tarball: https://registry.npmjs.org/no-case/-/no-case-3.0.4.tgz}
+
+  normalize-path@3.0.0:
+    resolution: {integrity: sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==, tarball: https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz}
+    engines: {node: '>=0.10.0'}
+
+  normalize-wheel@1.0.1:
+    resolution: {integrity: sha512-1OnlAPZ3zgrk8B91HyRj+eVv+kS5u+Z0SCsak6Xil/kmgEia50ga7zfkumayonZrImffAxPU/5WcyGhzetHNPA==, tarball: https://registry.npmjs.org/normalize-wheel/-/normalize-wheel-1.0.1.tgz}
+
+  npm-run-path@4.0.1:
+    resolution: {integrity: sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw==, tarball: https://registry.npmjs.org/npm-run-path/-/npm-run-path-4.0.1.tgz}
+    engines: {node: '>=8'}
+
+  npm-run-path@5.3.0:
+    resolution: {integrity: sha512-ppwTtiJZq0O/ai0z7yfudtBpWIoxM8yE6nHi1X47eFR2EWORqfbu6CnPlNsjeN683eT0qG6H/Pyf9fCcvjnnnQ==, tarball: https://registry.npmjs.org/npm-run-path/-/npm-run-path-5.3.0.tgz}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
+  nth-check@2.1.1:
+    resolution: {integrity: sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==, tarball: https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz}
+
+  object-assign@4.1.1:
+    resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==, tarball: https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz}
+    engines: {node: '>=0.10.0'}
+
+  onetime@5.1.2:
+    resolution: {integrity: sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==, tarball: https://registry.npmjs.org/onetime/-/onetime-5.1.2.tgz}
+    engines: {node: '>=6'}
+
+  onetime@6.0.0:
+    resolution: {integrity: sha512-1FlR+gjXK7X+AsAHso35MnyN5KqGwJRi/31ft6x0M194ht7S+rWAvd7PHss9xSKMzE0asv1pyIHaJYq+BbacAQ==, tarball: https://registry.npmjs.org/onetime/-/onetime-6.0.0.tgz}
+    engines: {node: '>=12'}
+
+  p-limit@2.3.0:
+    resolution: {integrity: sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==, tarball: https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz}
+    engines: {node: '>=6'}
+
+  p-locate@3.0.0:
+    resolution: {integrity: sha512-x+12w/To+4GFfgJhBEpiDcLozRJGegY+Ei7/z0tSLkMmxGZNybVMSfWj9aJn8Z5Fc7dBUNJOOVgPv2H7IwulSQ==, tarball: https://registry.npmjs.org/p-locate/-/p-locate-3.0.0.tgz}
+    engines: {node: '>=6'}
+
+  p-try@2.2.0:
+    resolution: {integrity: sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==, tarball: https://registry.npmjs.org/p-try/-/p-try-2.2.0.tgz}
+    engines: {node: '>=6'}
+
+  param-case@3.0.4:
+    resolution: {integrity: sha512-RXlj7zCYokReqWpOPH9oYivUzLYZ5vAPIfEmCTNViosC78F8F0H9y7T7gG2M39ymgutxF5gcFEsyZQSph9Bp3A==, tarball: https://registry.npmjs.org/param-case/-/param-case-3.0.4.tgz}
+
+  parent-module@1.0.1:
+    resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==, tarball: https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz}
+    engines: {node: '>=6'}
+
+  parse-json@5.2.0:
+    resolution: {integrity: sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==, tarball: https://registry.npmjs.org/parse-json/-/parse-json-5.2.0.tgz}
+    engines: {node: '>=8'}
+
+  parse5-htmlparser2-tree-adapter@7.1.0:
+    resolution: {integrity: sha512-ruw5xyKs6lrpo9x9rCZqZZnIUntICjQAd0Wsmp396Ul9lN/h+ifgVV1x1gZHi8euej6wTfpqX8j+BFQxF0NS/g==, tarball: https://registry.npmjs.org/parse5-htmlparser2-tree-adapter/-/parse5-htmlparser2-tree-adapter-7.1.0.tgz}
+
+  parse5-parser-stream@7.1.2:
+    resolution: {integrity: sha512-JyeQc9iwFLn5TbvvqACIF/VXG6abODeB3Fwmv/TGdLk2LfbWkaySGY72at4+Ty7EkPZj854u4CrICqNk2qIbow==, tarball: https://registry.npmjs.org/parse5-parser-stream/-/parse5-parser-stream-7.1.2.tgz}
+
+  parse5@7.3.0:
+    resolution: {integrity: sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==, tarball: https://registry.npmjs.org/parse5/-/parse5-7.3.0.tgz}
+
+  parse5@8.0.1:
+    resolution: {integrity: sha512-z1e/HMG90obSGeidlli3hj7cbocou0/wa5HacvI3ASx34PecNjNQeaHNo5WIZpWofN9kgkqV1q5YvXe3F0FoPw==, tarball: https://registry.npmjs.org/parse5/-/parse5-8.0.1.tgz}
+
+  parsel-js@1.2.2:
+    resolution: {integrity: sha512-AVJMlwQ4bL2Y0VvYJGk+Fp7eX4SCH2uFoNApmn4yKWACUewZ+alwW3tyoe1r5Z3aLYQTuAuPZIyGghMfO/Tlxw==, tarball: https://registry.npmjs.org/parsel-js/-/parsel-js-1.2.2.tgz}
+
+  pascal-case@3.1.2:
+    resolution: {integrity: sha512-uWlGT3YSnK9x3BQJaOdcZwrnV6hPpd8jFH1/ucpiLRPh/2zCVJKS19E4GvYHvaCcACn3foXZ0cLB9Wrx1KGe5g==, tarball: https://registry.npmjs.org/pascal-case/-/pascal-case-3.1.2.tgz}
+
+  path-case@3.0.4:
+    resolution: {integrity: sha512-qO4qCFjXqVTrcbPt/hQfhTQ+VhFsqNKOPtytgNKkKxSoEp3XPUQ8ObFuePylOIok5gjn69ry8XiULxCwot3Wfg==, tarball: https://registry.npmjs.org/path-case/-/path-case-3.0.4.tgz}
+
+  path-exists@3.0.0:
+    resolution: {integrity: sha512-bpC7GYwiDYQ4wYLe+FA8lhRjhQCMcQGuSgGGqDkg/QerRWw9CmGRT0iSOVRSZJ29NMLZgIzqaljJ63oaL4NIJQ==, tarball: https://registry.npmjs.org/path-exists/-/path-exists-3.0.0.tgz}
+    engines: {node: '>=4'}
+
+  path-key@3.1.1:
+    resolution: {integrity: sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==, tarball: https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz}
+    engines: {node: '>=8'}
+
+  path-key@4.0.0:
+    resolution: {integrity: sha512-haREypq7xkM7ErfgIyA0z+Bj4AGKlMSdlQE2jvJo6huWD1EdkKYV+G/T4nq0YEF2vgTT8kqMFKo1uHn950r4SQ==, tarball: https://registry.npmjs.org/path-key/-/path-key-4.0.0.tgz}
+    engines: {node: '>=12'}
+
+  path-parse@1.0.7:
+    resolution: {integrity: sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==, tarball: https://registry.npmjs.org/path-parse/-/path-parse-1.0.7.tgz}
+
+  path-to-regexp@6.3.0:
+    resolution: {integrity: sha512-Yhpw4T9C6hPpgPeA28us07OJeqZ5EzQTkbfwuhsUg0c237RomFoETJgmp2sa3F/41gfLE6G5cqcYwznmeEeOlQ==, tarball: https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-6.3.0.tgz}
+
+  path-type@4.0.0:
+    resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==, tarball: https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz}
+    engines: {node: '>=8'}
+
+  pathe@1.1.2:
+    resolution: {integrity: sha512-whLdWMYL2TwI08hn8/ZqAbrVemu0LNaNNJZX73O6qaIdCTfXutsLhMkjdENX0qhsQ9uIimo4/aQOmXkoon2nDQ==, tarball: https://registry.npmjs.org/pathe/-/pathe-1.1.2.tgz}
+
+  pathval@2.0.1:
+    resolution: {integrity: sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ==, tarball: https://registry.npmjs.org/pathval/-/pathval-2.0.1.tgz}
+    engines: {node: '>= 14.16'}
+
+  picocolors@1.1.1:
+    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==, tarball: https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz}
+
+  picomatch@2.3.2:
+    resolution: {integrity: sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==, tarball: https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz}
+    engines: {node: '>=8.6'}
+
+  picomatch@4.0.4:
+    resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==, tarball: https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz}
+    engines: {node: '>=12'}
+
+  pirates@4.0.7:
+    resolution: {integrity: sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==, tarball: https://registry.npmjs.org/pirates/-/pirates-4.0.7.tgz}
+    engines: {node: '>= 6'}
+
+  postcss-load-config@4.0.2:
+    resolution: {integrity: sha512-bSVhyJGL00wMVoPUzAVAnbEoWyqRxkjv64tUl427SKnPrENtq6hJwUojroMz2VB+Q1edmi4IfrAPpami5VVgMQ==, tarball: https://registry.npmjs.org/postcss-load-config/-/postcss-load-config-4.0.2.tgz}
+    engines: {node: '>= 14'}
+    peerDependencies:
+      postcss: '>=8.0.9'
+      ts-node: '>=9.0.0'
+    peerDependenciesMeta:
+      postcss:
+        optional: true
+      ts-node:
+        optional: true
+
+  postcss-prefix-selector@1.16.1:
+    resolution: {integrity: sha512-Umxu+FvKMwlY6TyDzGFoSUnzW+NOfMBLyC1tAkIjgX+Z/qGspJeRjVC903D7mx7TuBpJlwti2ibXtWuA7fKMeQ==, tarball: https://registry.npmjs.org/postcss-prefix-selector/-/postcss-prefix-selector-1.16.1.tgz}
+    peerDependencies:
+      postcss: '>4 <9'
+
+  postcss-urlrebase@1.4.0:
+    resolution: {integrity: sha512-rRaxMmWvXrn8Rk1PqsxmaJwldRHsr0WbbASKKCZYxXwotHkM/5X/6IrwaEe8pdzpbNGCEY86yhYMN0MhgOkADA==, tarball: https://registry.npmjs.org/postcss-urlrebase/-/postcss-urlrebase-1.4.0.tgz}
+    peerDependencies:
+      postcss: ^8.3.0
+
+  postcss-value-parser@4.2.0:
+    resolution: {integrity: sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==, tarball: https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz}
+
+  postcss@8.5.15:
+    resolution: {integrity: sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==, tarball: https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz}
+    engines: {node: ^10 || ^12 || >=14}
+
+  preact@10.29.2:
+    resolution: {integrity: sha512-7tNmwg/7mzzAoB/8kSg6Hl37JraAZw3Z3A0JSY7VXlZwo82Xn0G7wKbNNs2qoF4ZEEsQGTwDAroNdqKs1ofJxQ==, tarball: https://registry.npmjs.org/preact/-/preact-10.29.2.tgz}
+
+  pretty-format@29.7.0:
+    resolution: {integrity: sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ==, tarball: https://registry.npmjs.org/pretty-format/-/pretty-format-29.7.0.tgz}
+    engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0}
+
+  prop-types@15.8.1:
+    resolution: {integrity: sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg==, tarball: https://registry.npmjs.org/prop-types/-/prop-types-15.8.1.tgz}
+
+  punycode@2.3.1:
+    resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==, tarball: https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz}
+    engines: {node: '>=6'}
+
+  queue-microtask@1.2.3:
+    resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==, tarball: https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz}
+
+  re-resizable@6.11.2:
+    resolution: {integrity: sha512-2xI2P3OHs5qw7K0Ud1aLILK6MQxW50TcO+DetD9eIV58j84TqYeHoZcL9H4GXFXXIh7afhH8mv5iUCXII7OW7A==, tarball: https://registry.npmjs.org/re-resizable/-/re-resizable-6.11.2.tgz}
+    peerDependencies:
+      react: ^16.13.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.13.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  react-autosize-textarea@7.1.0:
+    resolution: {integrity: sha512-BHpjCDkuOlllZn3nLazY2F8oYO1tS2jHnWhcjTWQdcKiiMU6gHLNt/fzmqMSyerR0eTdKtfSIqtSeTtghNwS+g==, tarball: https://registry.npmjs.org/react-autosize-textarea/-/react-autosize-textarea-7.1.0.tgz}
+    peerDependencies:
+      react: ^0.14.0 || ^15.0.0 || ^16.0.0
+      react-dom: ^0.14.0 || ^15.0.0 || ^16.0.0
+
+  react-colorful@5.7.0:
+    resolution: {integrity: sha512-fuesYIemttah97XmsIHmz4OORDHiSFzyc9HMAIrCHJou2jaRQmL8cFJ76K4zQhhj8jzwOBlOi4BaGTjjOZCfTg==, tarball: https://registry.npmjs.org/react-colorful/-/react-colorful-5.7.0.tgz}
+    peerDependencies:
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
+
+  react-day-picker@9.14.0:
+    resolution: {integrity: sha512-tBaoDWjPwe0M5pGrum4H0SR6Lyk+BO9oHnp9JbKpGKW2mlraNPgP9BMfsg5pWpwrssARmeqk7YBl2oXutZTaHA==, tarball: https://registry.npmjs.org/react-day-picker/-/react-day-picker-9.14.0.tgz}
+    engines: {node: '>=18'}
+    peerDependencies:
+      react: '>=16.8.0'
+
+  react-dom@18.3.1:
+    resolution: {integrity: sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==, tarball: https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz}
+    peerDependencies:
+      react: ^18.3.1
+
+  react-easy-crop@5.5.7:
+    resolution: {integrity: sha512-kYo4NtMeXFQB7h1U+h5yhUkE46WQbQdq7if54uDlbMdZHdRgNehfvaFrXnFw5NR1PNoUOJIfTwLnWmEx/MaZnA==, tarball: https://registry.npmjs.org/react-easy-crop/-/react-easy-crop-5.5.7.tgz}
+    peerDependencies:
+      react: '>=16.4.0'
+      react-dom: '>=16.4.0'
+
+  react-is@16.13.1:
+    resolution: {integrity: sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ==, tarball: https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz}
+
+  react-is@18.3.1:
+    resolution: {integrity: sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==, tarball: https://registry.npmjs.org/react-is/-/react-is-18.3.1.tgz}
+
+  react-property@2.0.2:
+    resolution: {integrity: sha512-+PbtI3VuDV0l6CleQMsx2gtK0JZbZKbpdu5ynr+lbsuvtmgbNcS3VM0tuY2QjFNOcWxvXeHjDpy42RO+4U2rug==, tarball: https://registry.npmjs.org/react-property/-/react-property-2.0.2.tgz}
+
+  react-remove-scroll-bar@2.3.8:
+    resolution: {integrity: sha512-9r+yi9+mgU33AKcj6IbT9oRCO78WriSj6t/cF8DWBZJ9aOGPOTEDvdUDz1FwKim7QXWwmHqtdHnRJfhAxEG46Q==, tarball: https://registry.npmjs.org/react-remove-scroll-bar/-/react-remove-scroll-bar-2.3.8.tgz}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-remove-scroll@2.7.2:
+    resolution: {integrity: sha512-Iqb9NjCCTt6Hf+vOdNIZGdTiH1QSqr27H/Ek9sv/a97gfueI/5h1s3yRi1nngzMUaOOToin5dI1dXKdXiF+u0Q==, tarball: https://registry.npmjs.org/react-remove-scroll/-/react-remove-scroll-2.7.2.tgz}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-style-singleton@2.2.3:
+    resolution: {integrity: sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==, tarball: https://registry.npmjs.org/react-style-singleton/-/react-style-singleton-2.2.3.tgz}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react@18.3.1:
+    resolution: {integrity: sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==, tarball: https://registry.npmjs.org/react/-/react-18.3.1.tgz}
+    engines: {node: '>=0.10.0'}
+
+  readdirp@3.6.0:
+    resolution: {integrity: sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==, tarball: https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz}
+    engines: {node: '>=8.10.0'}
+
+  redux@5.0.1:
+    resolution: {integrity: sha512-M9/ELqF6fy8FwmkpnF0S3YKOqMyoWJ4+CS5Efg2ct3oY9daQvd/Pc71FpGZsVsbl3Cpb+IIcjBDUnnyBdQbq4w==, tarball: https://registry.npmjs.org/redux/-/redux-5.0.1.tgz}
+
+  rememo@4.0.2:
+    resolution: {integrity: sha512-NVfSP9NstE3QPNs/TnegQY0vnJnstKQSpcrsI2kBTB3dB2PkdfKdTa+abbjMIDqpc63fE5LfjLgfMst0ULMFxQ==, tarball: https://registry.npmjs.org/rememo/-/rememo-4.0.2.tgz}
+
+  remove-accents@0.5.0:
+    resolution: {integrity: sha512-8g3/Otx1eJaVD12e31UbJj1YzdtVvzH85HV7t+9MJYk/u3XmkOUJ5Ys9wQrf9PCPK8+xn4ymzqYCiZl6QWKn+A==, tarball: https://registry.npmjs.org/remove-accents/-/remove-accents-0.5.0.tgz}
+
+  requestidlecallback@0.3.0:
+    resolution: {integrity: sha512-TWHFkT7S9p7IxLC5A1hYmAYQx2Eb9w1skrXmQ+dS1URyvR8tenMLl4lHbqEOUnpEYxNKpkVMXUgknVpBZWXXfQ==, tarball: https://registry.npmjs.org/requestidlecallback/-/requestidlecallback-0.3.0.tgz}
+
+  require-directory@2.1.1:
+    resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==, tarball: https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz}
+    engines: {node: '>=0.10.0'}
+
+  require-from-string@2.0.2:
+    resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==, tarball: https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz}
+    engines: {node: '>=0.10.0'}
+
+  require-main-filename@2.0.0:
+    resolution: {integrity: sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg==, tarball: https://registry.npmjs.org/require-main-filename/-/require-main-filename-2.0.0.tgz}
+
+  reselect@5.2.0:
+    resolution: {integrity: sha512-AgZ3UOZm3YndfrJ4OYjgrT7bmCm/1iqkjvEfH/oYjzh6PD2qw4QuT3jjnXIrpdt4MTpMXclMT3lXbmRY+XRakw==, tarball: https://registry.npmjs.org/reselect/-/reselect-5.2.0.tgz}
+
+  resolve-from@4.0.0:
+    resolution: {integrity: sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==, tarball: https://registry.npmjs.org/resolve-from/-/resolve-from-4.0.0.tgz}
+    engines: {node: '>=4'}
+
+  resolve-from@5.0.0:
+    resolution: {integrity: sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==, tarball: https://registry.npmjs.org/resolve-from/-/resolve-from-5.0.0.tgz}
+    engines: {node: '>=8'}
+
+  resolve@1.22.12:
+    resolution: {integrity: sha512-TyeJ1zif53BPfHootBGwPRYT1RUt6oGWsaQr8UyZW/eAm9bKoijtvruSDEmZHm92CwS9nj7/fWttqPCgzep8CA==, tarball: https://registry.npmjs.org/resolve/-/resolve-1.22.12.tgz}
+    engines: {node: '>= 0.4'}
+    hasBin: true
+
+  reusify@1.1.0:
+    resolution: {integrity: sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==, tarball: https://registry.npmjs.org/reusify/-/reusify-1.1.0.tgz}
+    engines: {iojs: '>=1.0.0', node: '>=0.10.0'}
+
+  rollup@4.62.2:
+    resolution: {integrity: sha512-RFnrW4lhXA3s3eqHDZvN654g8OTjzRfqpIRJYczCGB6HzphckVAi/Qh4tbPUbRuDi7s1Llv8g/NspLkttY3gTA==, tarball: https://registry.npmjs.org/rollup/-/rollup-4.62.2.tgz}
+    engines: {node: '>=18.0.0', npm: '>=8.0.0'}
+    hasBin: true
+
+  run-parallel@1.2.0:
+    resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==, tarball: https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz}
+
+  rungen@0.3.2:
+    resolution: {integrity: sha512-zWl10xu2D7zoR8zSC2U6bg5bYF6T/Wk7rxwp8IPaJH7f0Ge21G03kNHVgHR7tyVkSSfAOG0Rqf/Cl38JftSmtw==, tarball: https://registry.npmjs.org/rungen/-/rungen-0.3.2.tgz}
+
+  safe-buffer@5.2.1:
+    resolution: {integrity: sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==, tarball: https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz}
+
+  safer-buffer@2.1.2:
+    resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==, tarball: https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz}
+
+  saxes@6.0.0:
+    resolution: {integrity: sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==, tarball: https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz}
+    engines: {node: '>=v12.22.7'}
+
+  scheduler@0.23.2:
+    resolution: {integrity: sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==, tarball: https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz}
+
+  sentence-case@3.0.4:
+    resolution: {integrity: sha512-8LS0JInaQMCRoQ7YUytAo/xUu5W2XnQxV2HI/6uM6U7CITS1RqPElr30V6uIqyMKM9lJGRVFy5/4CuzcixNYSg==, tarball: https://registry.npmjs.org/sentence-case/-/sentence-case-3.0.4.tgz}
+
+  set-blocking@2.0.0:
+    resolution: {integrity: sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==, tarball: https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz}
+
+  shebang-command@2.0.0:
+    resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==, tarball: https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz}
+    engines: {node: '>=8'}
+
+  shebang-regex@3.0.0:
+    resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==, tarball: https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz}
+    engines: {node: '>=8'}
+
+  showdown@1.9.1:
+    resolution: {integrity: sha512-9cGuS382HcvExtf5AHk7Cb4pAeQQ+h0eTr33V1mu+crYWV4KvWAw6el92bDrqGEk5d46Ai/fhbEUwqJ/mTCNEA==, tarball: https://registry.npmjs.org/showdown/-/showdown-1.9.1.tgz}
+    hasBin: true
+
+  siginfo@2.0.0:
+    resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==, tarball: https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz}
+
+  signal-exit@3.0.7:
+    resolution: {integrity: sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==, tarball: https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz}
+
+  signal-exit@4.1.0:
+    resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==, tarball: https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz}
+    engines: {node: '>=14'}
+
+  simple-html-tokenizer@0.5.11:
+    resolution: {integrity: sha512-C2WEK/Z3HoSFbYq8tI7ni3eOo/NneSPRoPpcM7WdLjFOArFuyXEjAoCdOC3DgMfRyziZQ1hCNR4mrNdWEvD0og==, tarball: https://registry.npmjs.org/simple-html-tokenizer/-/simple-html-tokenizer-0.5.11.tgz}
+
+  slash@3.0.0:
+    resolution: {integrity: sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==, tarball: https://registry.npmjs.org/slash/-/slash-3.0.0.tgz}
+    engines: {node: '>=8'}
+
+  snake-case@3.0.4:
+    resolution: {integrity: sha512-LAOh4z89bGQvl9pFfNF8V146i7o7/CqFPbqzYgP+yYzDIDeS9HaNFtXABamRW+AQzEVODcvE79ljJ+8a9YSdMg==, tarball: https://registry.npmjs.org/snake-case/-/snake-case-3.0.4.tgz}
+
+  source-map-js@1.2.1:
+    resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==, tarball: https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz}
+    engines: {node: '>=0.10.0'}
+
+  source-map@0.5.7:
+    resolution: {integrity: sha512-LbrmJOMUSdEVxIKvdcJzQC+nQhe8FUZQTXQy6+I75skNgn3OoQ0DZA8YnFa7gp8tqtL3KPf1kmo0R5DoApeSGQ==, tarball: https://registry.npmjs.org/source-map/-/source-map-0.5.7.tgz}
+    engines: {node: '>=0.10.0'}
+
+  source-map@0.8.0-beta.0:
+    resolution: {integrity: sha512-2ymg6oRBpebeZi9UUNsgQ89bhx01TcTkmNTGnNO88imTmbSgy4nfujrgVEFKWpMTEGA11EDkTt7mqObTPdigIA==, tarball: https://registry.npmjs.org/source-map/-/source-map-0.8.0-beta.0.tgz}
+    engines: {node: '>= 8'}
+    deprecated: The work that was done in this beta branch won't be included in future versions
+
+  stackback@0.0.2:
+    resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==, tarball: https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz}
+
+  std-env@3.10.0:
+    resolution: {integrity: sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==, tarball: https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz}
+
+  string-width@3.1.0:
+    resolution: {integrity: sha512-vafcv6KjVZKSgz06oM/H6GDBrAtz8vdhQakGjFIvNrHA6y3HCF1CInLy+QLq8dTJPQ1b+KDUqDFctkdRW44e1w==, tarball: https://registry.npmjs.org/string-width/-/string-width-3.1.0.tgz}
+    engines: {node: '>=6'}
+
+  strip-ansi@5.2.0:
+    resolution: {integrity: sha512-DuRs1gKbBqsMKIZlrffwlug8MHkcnpjs5VPmL1PAh+mA30U0DTotfDZ0d2UUsXpPmPmMMJ6W773MaA3J+lbiWA==, tarball: https://registry.npmjs.org/strip-ansi/-/strip-ansi-5.2.0.tgz}
+    engines: {node: '>=6'}
+
+  strip-final-newline@2.0.0:
+    resolution: {integrity: sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA==, tarball: https://registry.npmjs.org/strip-final-newline/-/strip-final-newline-2.0.0.tgz}
+    engines: {node: '>=6'}
+
+  strip-final-newline@3.0.0:
+    resolution: {integrity: sha512-dOESqjYr96iWYylGObzd39EuNTa5VJxyvVAEm5Jnh7KGo75V43Hk1odPQkNDyXNmUR6k+gEiDVXnjB8HJ3crXw==, tarball: https://registry.npmjs.org/strip-final-newline/-/strip-final-newline-3.0.0.tgz}
+    engines: {node: '>=12'}
+
+  style-to-js@1.1.21:
+    resolution: {integrity: sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ==, tarball: https://registry.npmjs.org/style-to-js/-/style-to-js-1.1.21.tgz}
+
+  style-to-object@1.0.14:
+    resolution: {integrity: sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==, tarball: https://registry.npmjs.org/style-to-object/-/style-to-object-1.0.14.tgz}
+
+  stylis@4.2.0:
+    resolution: {integrity: sha512-Orov6g6BB1sDfYgzWfTHDOxamtX1bE/zo104Dh9e6fqJ3PooipYyfJ0pUmrZO2wAvO8YbEyeFrkV91XTsGMSrw==, tarball: https://registry.npmjs.org/stylis/-/stylis-4.2.0.tgz}
+
+  sucrase@3.35.1:
+    resolution: {integrity: sha512-DhuTmvZWux4H1UOnWMB3sk0sbaCVOoQZjv8u1rDoTV0HTdGem9hkAZtl4JZy8P2z4Bg0nT+YMeOFyVr4zcG5Tw==, tarball: https://registry.npmjs.org/sucrase/-/sucrase-3.35.1.tgz}
+    engines: {node: '>=16 || 14 >=14.17'}
+    hasBin: true
+
+  supports-preserve-symlinks-flag@1.0.0:
+    resolution: {integrity: sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==, tarball: https://registry.npmjs.org/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz}
+    engines: {node: '>= 0.4'}
+
+  symbol-tree@3.2.4:
+    resolution: {integrity: sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==, tarball: https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz}
+
+  tabbable@6.5.0:
+    resolution: {integrity: sha512-wieBHXygIm7OyQOu5hQlkk62/WyCFYGlWg7L6/ZCUZwx0o398Zkn4pVmMyfYhfMG8kGrj/Krt8eIk6UKC6VzwA==, tarball: https://registry.npmjs.org/tabbable/-/tabbable-6.5.0.tgz}
+
+  tannin@1.2.0:
+    resolution: {integrity: sha512-U7GgX/RcSeUETbV7gYgoz8PD7Ni4y95pgIP/Z6ayI3CfhSujwKEBlGFTCRN+Aqnuyf4AN2yHL+L8x+TCGjb9uA==, tarball: https://registry.npmjs.org/tannin/-/tannin-1.2.0.tgz}
+
+  temml@0.10.34:
+    resolution: {integrity: sha512-f3b5CaPwPvMviA+CtHy0qoIGWvzpRrNpXmGRc/Y1jc9gAYy+xOlndJFyn7Vfcz7cBcS8QRvv8z0EEH59sHCQxg==, tarball: https://registry.npmjs.org/temml/-/temml-0.10.34.tgz}
+    engines: {node: '>=18.13.0'}
+
+  thenify-all@1.6.0:
+    resolution: {integrity: sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==, tarball: https://registry.npmjs.org/thenify-all/-/thenify-all-1.6.0.tgz}
+    engines: {node: '>=0.8'}
+
+  thenify@3.3.1:
+    resolution: {integrity: sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw==, tarball: https://registry.npmjs.org/thenify/-/thenify-3.3.1.tgz}
+
+  tinybench@2.9.0:
+    resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==, tarball: https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz}
+
+  tinyglobby@0.2.17:
+    resolution: {integrity: sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==, tarball: https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz}
+    engines: {node: '>=12.0.0'}
+
+  tinypool@1.1.1:
+    resolution: {integrity: sha512-Zba82s87IFq9A9XmjiX5uZA/ARWDrB03OHlq+Vw1fSdt0I+4/Kutwy8BP4Y/y/aORMo61FQ0vIb5j44vSo5Pkg==, tarball: https://registry.npmjs.org/tinypool/-/tinypool-1.1.1.tgz}
+    engines: {node: ^18.0.0 || >=20.0.0}
+
+  tinyspy@3.0.2:
+    resolution: {integrity: sha512-n1cw8k1k0x4pgA2+9XrOkFydTerNcJ1zWCO5Nn9scWHTD+5tp8dghT2x1uduQePZTZgd3Tupf+x9BxJjeJi77Q==, tarball: https://registry.npmjs.org/tinyspy/-/tinyspy-3.0.2.tgz}
+    engines: {node: '>=14.0.0'}
+
+  tldts-core@7.4.3:
+    resolution: {integrity: sha512-27ep5H9PzdBrNd5OFM/j3WCU8F3kPwM9D0BOaOf7uYfxMJfyr0K5Tjj69Gri+sZlh2WXd5buIm47NuPF29CDiw==, tarball: https://registry.npmjs.org/tldts-core/-/tldts-core-7.4.3.tgz}
+
+  tldts@7.4.3:
+    resolution: {integrity: sha512-A3BDQBeeukYPzB4QdQ1DtdlUmp4x2OCH8n5UVhEWbyANxNep8GavottKzd1xYKFJKjUgMyPT7EzOfnBO55s8Sg==, tarball: https://registry.npmjs.org/tldts/-/tldts-7.4.3.tgz}
+    hasBin: true
+
+  to-regex-range@5.0.1:
+    resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==, tarball: https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz}
+    engines: {node: '>=8.0'}
+
+  tough-cookie@6.0.1:
+    resolution: {integrity: sha512-LktZQb3IeoUWB9lqR5EWTHgW/VTITCXg4D21M+lvybRVdylLrRMnqaIONLVb5mav8vM19m44HIcGq4qASeu2Qw==, tarball: https://registry.npmjs.org/tough-cookie/-/tough-cookie-6.0.1.tgz}
+    engines: {node: '>=16'}
+
+  tr46@1.0.1:
+    resolution: {integrity: sha512-dTpowEjclQ7Kgx5SdBkqRzVhERQXov8/l9Ft9dVM9fmg0W0KQSVaXX9T4i6twCPNtYiZM53lpSSUAwJbFPOHxA==, tarball: https://registry.npmjs.org/tr46/-/tr46-1.0.1.tgz}
+
+  tr46@6.0.0:
+    resolution: {integrity: sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw==, tarball: https://registry.npmjs.org/tr46/-/tr46-6.0.0.tgz}
+    engines: {node: '>=20'}
+
+  tree-kill@1.2.2:
+    resolution: {integrity: sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==, tarball: https://registry.npmjs.org/tree-kill/-/tree-kill-1.2.2.tgz}
+    hasBin: true
+
+  ts-interface-checker@0.1.13:
+    resolution: {integrity: sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==, tarball: https://registry.npmjs.org/ts-interface-checker/-/ts-interface-checker-0.1.13.tgz}
+
+  tslib@2.8.1:
+    resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==, tarball: https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz}
+
+  tsup@8.0.0:
+    resolution: {integrity: sha512-9rOGn8LsFn2iAg2pCB1jnH7ygVuGjlzIomjw0jKXUxAii3iL5cXgm0jZMPKfFH1bSAjQovJ1DUVPSw+oDuIu8A==, tarball: https://registry.npmjs.org/tsup/-/tsup-8.0.0.tgz}
+    engines: {node: '>=18'}
+    hasBin: true
+    peerDependencies:
+      '@microsoft/api-extractor': ^7.36.0
+      '@swc/core': ^1
+      postcss: ^8.4.12
+      typescript: '>=4.5.0'
+    peerDependenciesMeta:
+      '@microsoft/api-extractor':
+        optional: true
+      '@swc/core':
+        optional: true
+      postcss:
+        optional: true
+      typescript:
+        optional: true
+
+  typescript@5.7.3:
+    resolution: {integrity: sha512-84MVSjMEHP+FQRPy3pX9sTVV/INIex71s9TL2Gm5FG/WG1SqXeKyZ0k7/blY/4FdOzI12CBy1vGc4og/eus0fw==, tarball: https://registry.npmjs.org/typescript/-/typescript-5.7.3.tgz}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici@7.28.0:
+    resolution: {integrity: sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA==, tarball: https://registry.npmjs.org/undici/-/undici-7.28.0.tgz}
+    engines: {node: '>=20.18.1'}
+
+  upper-case-first@2.0.2:
+    resolution: {integrity: sha512-514ppYHBaKwfJRK/pNC6c/OxfGa0obSnAl106u97Ed0I625Nin96KAjttZF6ZL3e1XLtphxnqrOi9iWgm+u+bg==, tarball: https://registry.npmjs.org/upper-case-first/-/upper-case-first-2.0.2.tgz}
+
+  upper-case@2.0.2:
+    resolution: {integrity: sha512-KgdgDGJt2TpuwBUIjgG6lzw2GWFRCW9Qkfkiv0DxqHHLYJHmtmdUIKcZd8rHgFSjopVTlw6ggzCm1b8MFQwikg==, tarball: https://registry.npmjs.org/upper-case/-/upper-case-2.0.2.tgz}
+
+  use-callback-ref@1.3.3:
+    resolution: {integrity: sha512-jQL3lRnocaFtu3V00JToYz/4QkNWswxijDaCVNZRiRTO3HQDLsdu1ZtmIUvV4yPp+rvWm5j0y0TG/S61cuijTg==, tarball: https://registry.npmjs.org/use-callback-ref/-/use-callback-ref-1.3.3.tgz}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  use-memo-one@1.1.3:
+    resolution: {integrity: sha512-g66/K7ZQGYrI6dy8GLpVcMsBp4s17xNkYJVSMvTEevGy3nDxHOfE6z8BVE22+5G5x7t3+bhzrlTDB7ObrEE0cQ==, tarball: https://registry.npmjs.org/use-memo-one/-/use-memo-one-1.1.3.tgz}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0
+
+  use-sidecar@1.1.3:
+    resolution: {integrity: sha512-Fedw0aZvkhynoPYlA5WXrMCAMm+nSWdZt6lzJQ7Ok8S6Q+VsHmHpRWndVRJ8Be0ZbkfPc5LRYH+5XrzXcEeLRQ==, tarball: https://registry.npmjs.org/use-sidecar/-/use-sidecar-1.1.3.tgz}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  use-sync-external-store@1.6.0:
+    resolution: {integrity: sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==, tarball: https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.6.0.tgz}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  uuid@14.0.1:
+    resolution: {integrity: sha512-6ZxzVpzDXDa3bJWaHilVayA+BH/1zmxCJoVgvmqJnid/gPoKHxUrS/aC/T6LGQtNHT+XHG9fXPJB4d+IrU30Ew==, tarball: https://registry.npmjs.org/uuid/-/uuid-14.0.1.tgz}
+    hasBin: true
+
+  uuid@9.0.1:
+    resolution: {integrity: sha512-b+1eJOlsR9K8HJpow9Ok3fiWOWSIcIzXodvv0rQjVoOVNpWMpxf1wZNpt4y9h10odCNrqnYp1OBzRktckBe3sA==, tarball: https://registry.npmjs.org/uuid/-/uuid-9.0.1.tgz}
+    deprecated: uuid@10 and below is no longer supported.  For ESM codebases, update to uuid@latest.  For CommonJS codebases, use uuid@11 (but be aware this version will likely be deprecated in 2028).
+    hasBin: true
+
+  vite-node@2.0.0:
+    resolution: {integrity: sha512-jZtezmjcgZTkMisIi68TdY8w/PqPTxK2pbfTU9/4Gqus1K3AVZqkwH0z7Vshe3CD6mq9rJq8SpqmuefDMIqkfQ==, tarball: https://registry.npmjs.org/vite-node/-/vite-node-2.0.0.tgz}
+    engines: {node: ^18.0.0 || >=20.0.0}
+    hasBin: true
+
+  vite@5.4.21:
+    resolution: {integrity: sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==, tarball: https://registry.npmjs.org/vite/-/vite-5.4.21.tgz}
+    engines: {node: ^18.0.0 || >=20.0.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^18.0.0 || >=20.0.0
+      less: '*'
+      lightningcss: ^1.21.0
+      sass: '*'
+      sass-embedded: '*'
+      stylus: '*'
+      sugarss: '*'
+      terser: ^5.4.0
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      less:
+        optional: true
+      lightningcss:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+
+  vitest@2.0.0:
+    resolution: {integrity: sha512-NvccE2tZhIoPSq3o3AoTBmItwhHNjzIxvOgfdzILIscyzSGOtw2+A1d/JJbS86HDVbc6TS5HnckQuCgTfp0HDQ==, tarball: https://registry.npmjs.org/vitest/-/vitest-2.0.0.tgz}
+    engines: {node: ^18.0.0 || >=20.0.0}
+    hasBin: true
+    peerDependencies:
+      '@edge-runtime/vm': '*'
+      '@types/node': ^18.0.0 || >=20.0.0
+      '@vitest/browser': 2.0.0
+      '@vitest/ui': 2.0.0
+      happy-dom: '*'
+      jsdom: '*'
+    peerDependenciesMeta:
+      '@edge-runtime/vm':
+        optional: true
+      '@types/node':
+        optional: true
+      '@vitest/browser':
+        optional: true
+      '@vitest/ui':
+        optional: true
+      happy-dom:
+        optional: true
+      jsdom:
+        optional: true
+
+  w3c-xmlserializer@5.0.0:
+    resolution: {integrity: sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==, tarball: https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz}
+    engines: {node: '>=18'}
+
+  wasm-vips@0.0.16:
+    resolution: {integrity: sha512-4/bEq8noAFt7DX3VT+Vt5AgNtnnOLwvmrDbduWfiv9AV+VYkbUU4f9Dam9e6khRqPinyClFHCqiwATTTJEiGwA==, tarball: https://registry.npmjs.org/wasm-vips/-/wasm-vips-0.0.16.tgz}
+    engines: {node: '>=16.4.0'}
+
+  wasm-vips@0.0.17:
+    resolution: {integrity: sha512-nhkqUNJDUymImoXGrVfImC4wzIFTb9KfBpAngb7dcEQNPP1gVTx4+WL3VVVDSXQpMsyeacsQDOx0+DM33Rpurg==, tarball: https://registry.npmjs.org/wasm-vips/-/wasm-vips-0.0.17.tgz}
+    engines: {node: '>=16.4.0'}
+
+  webidl-conversions@4.0.2:
+    resolution: {integrity: sha512-YQ+BmxuTgd6UXZW3+ICGfyqRyHXVlD5GtQr5+qjiNW7bF0cqrzX500HVXPBOvgXb5YnzDd+h0zqyv61KUD7+Sg==, tarball: https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-4.0.2.tgz}
+
+  webidl-conversions@8.0.1:
+    resolution: {integrity: sha512-BMhLD/Sw+GbJC21C/UgyaZX41nPt8bUTg+jWyDeg7e7YN4xOM05YPSIXceACnXVtqyEw/LMClUQMtMZ+PGGpqQ==, tarball: https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-8.0.1.tgz}
+    engines: {node: '>=20'}
+
+  whatwg-encoding@3.1.1:
+    resolution: {integrity: sha512-6qN4hJdMwfYBtE3YBTTHhoeuUrDBPZmbQaxWAqSALV/MeEnR5z1xd8UKud2RAkFoPkmB+hli1TZSnyi84xz1vQ==, tarball: https://registry.npmjs.org/whatwg-encoding/-/whatwg-encoding-3.1.1.tgz}
+    engines: {node: '>=18'}
+    deprecated: Use @exodus/bytes instead for a more spec-conformant and faster implementation
+
+  whatwg-mimetype@4.0.0:
+    resolution: {integrity: sha512-QaKxh0eNIi2mE9p2vEdzfagOKHCcj1pJ56EEHGQOVxp8r9/iszLUUV7v89x9O1p/T+NlTM5W7jW6+cz4Fq1YVg==, tarball: https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-4.0.0.tgz}
+    engines: {node: '>=18'}
+
+  whatwg-mimetype@5.0.0:
+    resolution: {integrity: sha512-sXcNcHOC51uPGF0P/D4NVtrkjSU2fNsm9iog4ZvZJsL3rjoDAzXZhkm2MWt1y+PUdggKAYVoMAIYcs78wJ51Cw==, tarball: https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-5.0.0.tgz}
+    engines: {node: '>=20'}
+
+  whatwg-url@16.0.1:
+    resolution: {integrity: sha512-1to4zXBxmXHV3IiSSEInrreIlu02vUOvrhxJJH5vcxYTBDAx51cqZiKdyTxlecdKNSjj8EcxGBxNf6Vg+945gw==, tarball: https://registry.npmjs.org/whatwg-url/-/whatwg-url-16.0.1.tgz}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
+
+  whatwg-url@7.1.0:
+    resolution: {integrity: sha512-WUu7Rg1DroM7oQvGWfOiAK21n74Gg+T4elXEQYkOhtyLeWiJFoOGLXPKI/9gzIie9CtwVLm8wtw6YJdKyxSjeg==, tarball: https://registry.npmjs.org/whatwg-url/-/whatwg-url-7.1.0.tgz}
+
+  which-module@2.0.1:
+    resolution: {integrity: sha512-iBdZ57RDvnOR9AGBhML2vFZf7h8vmBjhoaZqODJBFWHVtKkDmKuHai3cx5PgVMrX5YDNp27AofYbAwctSS+vhQ==, tarball: https://registry.npmjs.org/which-module/-/which-module-2.0.1.tgz}
+
+  which@2.0.2:
+    resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==, tarball: https://registry.npmjs.org/which/-/which-2.0.2.tgz}
+    engines: {node: '>= 8'}
+    hasBin: true
+
+  why-is-node-running@2.3.0:
+    resolution: {integrity: sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==, tarball: https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz}
+    engines: {node: '>=8'}
+    hasBin: true
+
+  wrap-ansi@5.1.0:
+    resolution: {integrity: sha512-QC1/iN/2/RPVJ5jYK8BGttj5z83LmSKmvbvrXPNCLZSEb32KKVDJDl/MOt2N01qU2H/FkzEa9PKto1BqDjtd7Q==, tarball: https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-5.1.0.tgz}
+    engines: {node: '>=6'}
+
+  xml-name-validator@5.0.0:
+    resolution: {integrity: sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==, tarball: https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz}
+    engines: {node: '>=18'}
+
+  xmlchars@2.2.0:
+    resolution: {integrity: sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==, tarball: https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz}
+
+  y-protocols@1.0.7:
+    resolution: {integrity: sha512-YSVsLoXxO67J6eE/nV4AtFtT3QEotZf5sK5BHxFBXso7VDUT3Tx07IfA6hsu5Q5OmBdMkQVmFZ9QOA7fikWvnw==, tarball: https://registry.npmjs.org/y-protocols/-/y-protocols-1.0.7.tgz}
+    engines: {node: '>=16.0.0', npm: '>=8.0.0'}
+    peerDependencies:
+      yjs: ^13.0.0
+
+  y18n@4.0.3:
+    resolution: {integrity: sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==, tarball: https://registry.npmjs.org/y18n/-/y18n-4.0.3.tgz}
+
+  yaml@1.10.3:
+    resolution: {integrity: sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA==, tarball: https://registry.npmjs.org/yaml/-/yaml-1.10.3.tgz}
+    engines: {node: '>= 6'}
+
+  yaml@2.9.0:
+    resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==, tarball: https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
+  yargs-parser@15.0.3:
+    resolution: {integrity: sha512-/MVEVjTXy/cGAjdtQf8dW3V9b97bPN7rNn8ETj6BmAQL7ibC7O1Q9SPJbGjgh3SlwoBNXMzj/ZGIj8mBgl12YA==, tarball: https://registry.npmjs.org/yargs-parser/-/yargs-parser-15.0.3.tgz}
+
+  yargs@14.2.3:
+    resolution: {integrity: sha512-ZbotRWhF+lkjijC/VhmOT9wSgyBQ7+zr13+YLkhfsSiTriYsMzkTUFP18pFhWwBeMa5gUc1MzbhrO6/VB7c9Xg==, tarball: https://registry.npmjs.org/yargs/-/yargs-14.2.3.tgz}
+
+  yjs@13.6.31:
+    resolution: {integrity: sha512-Eq+5BRfbeGyqGVrTJL3bEcr8gKkxPuyuoHmAwpk52fDb8kOVMrfVSTRPd6yiGgX5Fskb96qCRjzjbRjrL4YEnw==, tarball: https://registry.npmjs.org/yjs/-/yjs-13.6.31.tgz}
+    engines: {node: '>=16.0.0', npm: '>=8.0.0'}
+
+snapshots:
+
+  '@ampproject/remapping@2.3.0':
+    dependencies:
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@ariakit/components@0.1.2':
+    dependencies:
+      '@ariakit/store': 0.1.2
+      '@ariakit/utils': 0.1.2
+
+  '@ariakit/react-components@0.1.2(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@ariakit/components': 0.1.2
+      '@ariakit/react-store': 0.1.2(react@18.3.1)
+      '@ariakit/react-utils': 0.1.2(react@18.3.1)
+      '@ariakit/store': 0.1.2
+      '@ariakit/utils': 0.1.2
+      '@floating-ui/dom': 1.7.6
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
+  '@ariakit/react-store@0.1.2(react@18.3.1)':
+    dependencies:
+      '@ariakit/react-utils': 0.1.2(react@18.3.1)
+      '@ariakit/store': 0.1.2
+      '@ariakit/utils': 0.1.2
+      react: 18.3.1
+      use-sync-external-store: 1.6.0(react@18.3.1)
+
+  '@ariakit/react-utils@0.1.2(react@18.3.1)':
+    dependencies:
+      '@ariakit/store': 0.1.2
+      '@ariakit/utils': 0.1.2
+      react: 18.3.1
+
+  '@ariakit/react@0.4.29(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@ariakit/react-components': 0.1.2(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
+  '@ariakit/store@0.1.2':
+    dependencies:
+      '@ariakit/utils': 0.1.2
+
+  '@ariakit/utils@0.1.2': {}
+
+  '@arraypress/waveform-player@1.2.1': {}
+
+  '@asamuzakjp/css-color@5.1.11':
+    dependencies:
+      '@asamuzakjp/generational-cache': 1.0.1
+      '@csstools/css-calc': 3.2.1(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)
+      '@csstools/css-color-parser': 4.1.8(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)
+      '@csstools/css-parser-algorithms': 4.0.0(@csstools/css-tokenizer@4.0.0)
+      '@csstools/css-tokenizer': 4.0.0
+
+  '@asamuzakjp/dom-selector@7.1.1':
+    dependencies:
+      '@asamuzakjp/generational-cache': 1.0.1
+      '@asamuzakjp/nwsapi': 2.3.9
+      bidi-js: 1.0.3
+      css-tree: 3.2.1
+      is-potential-custom-element-name: 1.0.1
+
+  '@asamuzakjp/generational-cache@1.0.1': {}
+
+  '@asamuzakjp/nwsapi@2.3.9': {}
+
+  '@babel/code-frame@7.29.7':
+    dependencies:
+      '@babel/helper-validator-identifier': 7.29.7
+      js-tokens: 4.0.0
+      picocolors: 1.1.1
+
+  '@babel/generator@7.29.7':
+    dependencies:
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+      jsesc: 3.1.0
+
+  '@babel/helper-globals@7.29.7': {}
+
+  '@babel/helper-module-imports@7.29.7':
+    dependencies:
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-string-parser@7.29.7': {}
+
+  '@babel/helper-validator-identifier@7.29.7': {}
+
+  '@babel/parser@7.29.7':
+    dependencies:
+      '@babel/types': 7.29.7
+
+  '@babel/runtime@7.29.7': {}
+
+  '@babel/template@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+
+  '@babel/traverse@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/generator': 7.29.7
+      '@babel/helper-globals': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.7
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/types@7.29.7':
+    dependencies:
+      '@babel/helper-string-parser': 7.29.7
+      '@babel/helper-validator-identifier': 7.29.7
+
+  '@base-ui/react@1.6.0(@date-fns/tz@1.5.0)(@types/react@18.3.31)(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@babel/runtime': 7.29.7
+      '@base-ui/utils': 0.3.1(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@floating-ui/react-dom': 2.1.8(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@floating-ui/utils': 0.2.11
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      use-sync-external-store: 1.6.0(react@18.3.1)
+    optionalDependencies:
+      '@date-fns/tz': 1.5.0
+      '@types/react': 18.3.31
+      date-fns: 4.4.0
+
+  '@base-ui/utils@0.3.1(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@babel/runtime': 7.29.7
+      '@floating-ui/utils': 0.2.11
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      reselect: 5.2.0
+      use-sync-external-store: 1.6.0(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@bramus/specificity@2.4.2':
+    dependencies:
+      css-tree: 3.2.1
+
+  '@csstools/color-helpers@6.0.2': {}
+
+  '@csstools/css-calc@3.2.1(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)':
+    dependencies:
+      '@csstools/css-parser-algorithms': 4.0.0(@csstools/css-tokenizer@4.0.0)
+      '@csstools/css-tokenizer': 4.0.0
+
+  '@csstools/css-color-parser@4.1.8(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)':
+    dependencies:
+      '@csstools/color-helpers': 6.0.2
+      '@csstools/css-calc': 3.2.1(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)
+      '@csstools/css-parser-algorithms': 4.0.0(@csstools/css-tokenizer@4.0.0)
+      '@csstools/css-tokenizer': 4.0.0
+
+  '@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0)':
+    dependencies:
+      '@csstools/css-tokenizer': 4.0.0
+
+  '@csstools/css-syntax-patches-for-csstree@1.1.5(css-tree@3.2.1)':
+    optionalDependencies:
+      css-tree: 3.2.1
+
+  '@csstools/css-tokenizer@4.0.0': {}
+
+  '@date-fns/tz@1.5.0': {}
+
+  '@date-fns/utc@2.1.1': {}
+
+  '@emotion/babel-plugin@11.13.5':
+    dependencies:
+      '@babel/helper-module-imports': 7.29.7
+      '@babel/runtime': 7.29.7
+      '@emotion/hash': 0.9.2
+      '@emotion/memoize': 0.9.0
+      '@emotion/serialize': 1.3.3
+      babel-plugin-macros: 3.1.0
+      convert-source-map: 1.9.0
+      escape-string-regexp: 4.0.0
+      find-root: 1.1.0
+      source-map: 0.5.7
+      stylis: 4.2.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@emotion/cache@11.14.0':
+    dependencies:
+      '@emotion/memoize': 0.9.0
+      '@emotion/sheet': 1.4.0
+      '@emotion/utils': 1.4.2
+      '@emotion/weak-memoize': 0.4.0
+      stylis: 4.2.0
+
+  '@emotion/css@11.13.5':
+    dependencies:
+      '@emotion/babel-plugin': 11.13.5
+      '@emotion/cache': 11.14.0
+      '@emotion/serialize': 1.3.3
+      '@emotion/sheet': 1.4.0
+      '@emotion/utils': 1.4.2
+    transitivePeerDependencies:
+      - supports-color
+
+  '@emotion/hash@0.9.2': {}
+
+  '@emotion/is-prop-valid@1.4.0':
+    dependencies:
+      '@emotion/memoize': 0.9.0
+
+  '@emotion/memoize@0.9.0': {}
+
+  '@emotion/react@11.14.0(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@babel/runtime': 7.29.7
+      '@emotion/babel-plugin': 11.13.5
+      '@emotion/cache': 11.14.0
+      '@emotion/serialize': 1.3.3
+      '@emotion/use-insertion-effect-with-fallbacks': 1.2.0(react@18.3.1)
+      '@emotion/utils': 1.4.2
+      '@emotion/weak-memoize': 0.4.0
+      hoist-non-react-statics: 3.3.2
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+    transitivePeerDependencies:
+      - supports-color
+
+  '@emotion/serialize@1.3.3':
+    dependencies:
+      '@emotion/hash': 0.9.2
+      '@emotion/memoize': 0.9.0
+      '@emotion/unitless': 0.10.0
+      '@emotion/utils': 1.4.2
+      csstype: 3.2.3
+
+  '@emotion/sheet@1.4.0': {}
+
+  '@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@18.3.1))(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@babel/runtime': 7.29.7
+      '@emotion/babel-plugin': 11.13.5
+      '@emotion/is-prop-valid': 1.4.0
+      '@emotion/react': 11.14.0(@types/react@18.3.31)(react@18.3.1)
+      '@emotion/serialize': 1.3.3
+      '@emotion/use-insertion-effect-with-fallbacks': 1.2.0(react@18.3.1)
+      '@emotion/utils': 1.4.2
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+    transitivePeerDependencies:
+      - supports-color
+
+  '@emotion/unitless@0.10.0': {}
+
+  '@emotion/use-insertion-effect-with-fallbacks@1.2.0(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+
+  '@emotion/utils@1.4.2': {}
+
+  '@emotion/weak-memoize@0.4.0': {}
+
+  '@esbuild/aix-ppc64@0.19.12':
+    optional: true
+
+  '@esbuild/aix-ppc64@0.21.5':
+    optional: true
+
+  '@esbuild/android-arm64@0.19.12':
+    optional: true
+
+  '@esbuild/android-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/android-arm@0.19.12':
+    optional: true
+
+  '@esbuild/android-arm@0.21.5':
+    optional: true
+
+  '@esbuild/android-x64@0.19.12':
+    optional: true
+
+  '@esbuild/android-x64@0.21.5':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.19.12':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/darwin-x64@0.19.12':
+    optional: true
+
+  '@esbuild/darwin-x64@0.21.5':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.19.12':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.19.12':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-arm64@0.19.12':
+    optional: true
+
+  '@esbuild/linux-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-arm@0.19.12':
+    optional: true
+
+  '@esbuild/linux-arm@0.21.5':
+    optional: true
+
+  '@esbuild/linux-ia32@0.19.12':
+    optional: true
+
+  '@esbuild/linux-ia32@0.21.5':
+    optional: true
+
+  '@esbuild/linux-loong64@0.19.12':
+    optional: true
+
+  '@esbuild/linux-loong64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.19.12':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.21.5':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.19.12':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.19.12':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-s390x@0.19.12':
+    optional: true
+
+  '@esbuild/linux-s390x@0.21.5':
+    optional: true
+
+  '@esbuild/linux-x64@0.19.12':
+    optional: true
+
+  '@esbuild/linux-x64@0.21.5':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.19.12':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.21.5':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.19.12':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.21.5':
+    optional: true
+
+  '@esbuild/sunos-x64@0.19.12':
+    optional: true
+
+  '@esbuild/sunos-x64@0.21.5':
+    optional: true
+
+  '@esbuild/win32-arm64@0.19.12':
+    optional: true
+
+  '@esbuild/win32-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/win32-ia32@0.19.12':
+    optional: true
+
+  '@esbuild/win32-ia32@0.21.5':
+    optional: true
+
+  '@esbuild/win32-x64@0.19.12':
+    optional: true
+
+  '@esbuild/win32-x64@0.21.5':
+    optional: true
+
+  '@exodus/bytes@1.15.1': {}
+
+  '@floating-ui/core@1.7.5':
+    dependencies:
+      '@floating-ui/utils': 0.2.11
+
+  '@floating-ui/dom@1.7.6':
+    dependencies:
+      '@floating-ui/core': 1.7.5
+      '@floating-ui/utils': 0.2.11
+
+  '@floating-ui/react-dom@2.0.8(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@floating-ui/dom': 1.7.6
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
+  '@floating-ui/react-dom@2.1.8(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@floating-ui/dom': 1.7.6
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
+  '@floating-ui/utils@0.2.11': {}
+
+  '@jest/schemas@29.6.3':
+    dependencies:
+      '@sinclair/typebox': 0.27.10
+
+  '@jridgewell/gen-mapping@0.3.13':
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/resolve-uri@3.1.2': {}
+
+  '@jridgewell/sourcemap-codec@1.5.5': {}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    dependencies:
+      '@jridgewell/resolve-uri': 3.1.2
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  '@nodelib/fs.scandir@2.1.5':
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      run-parallel: 1.2.0
+
+  '@nodelib/fs.stat@2.0.5': {}
+
+  '@nodelib/fs.walk@1.2.8':
+    dependencies:
+      '@nodelib/fs.scandir': 2.1.5
+      fastq: 1.20.1
+
+  '@preact/signals-core@1.14.3': {}
+
+  '@preact/signals@1.3.4(preact@10.29.2)':
+    dependencies:
+      '@preact/signals-core': 1.14.3
+      preact: 10.29.2
+
+  '@radix-ui/primitive@1.1.4': {}
+
+  '@radix-ui/react-compose-refs@1.1.3(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-context@1.1.4(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-dialog@1.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-focus-scope': 1.1.10(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-portal': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.3.0(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      aria-hidden: 1.2.6
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
+  '@radix-ui/react-dismissable-layer@1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-escape-keydown': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
+  '@radix-ui/react-focus-guards@1.1.4(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-focus-scope@1.1.10(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
+  '@radix-ui/react-id@1.1.2(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-portal@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
+  '@radix-ui/react-presence@1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
+  '@radix-ui/react-primitive@2.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-slot': 1.3.0(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
+  '@radix-ui/react-slot@1.3.0(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-use-callback-ref@1.1.2(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-use-controllable-state@1.2.3(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-use-effect-event@0.0.3(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-use-escape-keydown@1.1.2(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-use-layout-effect@1.1.2(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@react-spring/animated@9.7.5(react@18.3.1)':
+    dependencies:
+      '@react-spring/shared': 9.7.5(react@18.3.1)
+      '@react-spring/types': 9.7.5
+      react: 18.3.1
+
+  '@react-spring/core@9.7.5(react@18.3.1)':
+    dependencies:
+      '@react-spring/animated': 9.7.5(react@18.3.1)
+      '@react-spring/shared': 9.7.5(react@18.3.1)
+      '@react-spring/types': 9.7.5
+      react: 18.3.1
+
+  '@react-spring/rafz@9.7.5': {}
+
+  '@react-spring/shared@9.7.5(react@18.3.1)':
+    dependencies:
+      '@react-spring/rafz': 9.7.5
+      '@react-spring/types': 9.7.5
+      react: 18.3.1
+
+  '@react-spring/types@9.7.5': {}
+
+  '@react-spring/web@9.7.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@react-spring/animated': 9.7.5(react@18.3.1)
+      '@react-spring/core': 9.7.5(react@18.3.1)
+      '@react-spring/shared': 9.7.5(react@18.3.1)
+      '@react-spring/types': 9.7.5
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
+  '@rollup/rollup-android-arm-eabi@4.62.2':
+    optional: true
+
+  '@rollup/rollup-android-arm64@4.62.2':
+    optional: true
+
+  '@rollup/rollup-darwin-arm64@4.62.2':
+    optional: true
+
+  '@rollup/rollup-darwin-x64@4.62.2':
+    optional: true
+
+  '@rollup/rollup-freebsd-arm64@4.62.2':
+    optional: true
+
+  '@rollup/rollup-freebsd-x64@4.62.2':
+    optional: true
+
+  '@rollup/rollup-linux-arm-gnueabihf@4.62.2':
+    optional: true
+
+  '@rollup/rollup-linux-arm-musleabihf@4.62.2':
+    optional: true
+
+  '@rollup/rollup-linux-arm64-gnu@4.62.2':
+    optional: true
+
+  '@rollup/rollup-linux-arm64-musl@4.62.2':
+    optional: true
+
+  '@rollup/rollup-linux-loong64-gnu@4.62.2':
+    optional: true
+
+  '@rollup/rollup-linux-loong64-musl@4.62.2':
+    optional: true
+
+  '@rollup/rollup-linux-ppc64-gnu@4.62.2':
+    optional: true
+
+  '@rollup/rollup-linux-ppc64-musl@4.62.2':
+    optional: true
+
+  '@rollup/rollup-linux-riscv64-gnu@4.62.2':
+    optional: true
+
+  '@rollup/rollup-linux-riscv64-musl@4.62.2':
+    optional: true
+
+  '@rollup/rollup-linux-s390x-gnu@4.62.2':
+    optional: true
+
+  '@rollup/rollup-linux-x64-gnu@4.62.2':
+    optional: true
+
+  '@rollup/rollup-linux-x64-musl@4.62.2':
+    optional: true
+
+  '@rollup/rollup-openbsd-x64@4.62.2':
+    optional: true
+
+  '@rollup/rollup-openharmony-arm64@4.62.2':
+    optional: true
+
+  '@rollup/rollup-win32-arm64-msvc@4.62.2':
+    optional: true
+
+  '@rollup/rollup-win32-ia32-msvc@4.62.2':
+    optional: true
+
+  '@rollup/rollup-win32-x64-gnu@4.62.2':
+    optional: true
+
+  '@rollup/rollup-win32-x64-msvc@4.62.2':
+    optional: true
+
+  '@sinclair/typebox@0.27.10': {}
+
+  '@tabby_ai/hijri-converter@1.0.5': {}
+
+  '@tannin/compile@1.1.0':
+    dependencies:
+      '@tannin/evaluate': 1.2.0
+      '@tannin/postfix': 1.1.0
+
+  '@tannin/evaluate@1.2.0': {}
+
+  '@tannin/plural-forms@1.1.0':
+    dependencies:
+      '@tannin/compile': 1.1.0
+
+  '@tannin/postfix@1.1.0': {}
+
+  '@tannin/sprintf@1.3.3': {}
+
+  '@types/estree@1.0.9': {}
+
+  '@types/gradient-parser@1.1.0': {}
+
+  '@types/highlight-words-core@1.2.1': {}
+
+  '@types/highlight-words-core@1.2.3': {}
+
+  '@types/mousetrap@1.6.15': {}
+
+  '@types/parse-json@4.0.2': {}
+
+  '@types/prop-types@15.7.15': {}
+
+  '@types/react-dom@18.3.7(@types/react@18.3.31)':
+    dependencies:
+      '@types/react': 18.3.31
+
+  '@types/react@18.3.31':
+    dependencies:
+      '@types/prop-types': 15.7.15
+      csstype: 3.2.3
+
+  '@use-gesture/core@10.3.1': {}
+
+  '@use-gesture/react@10.3.1(react@18.3.1)':
+    dependencies:
+      '@use-gesture/core': 10.3.1
+      react: 18.3.1
+
+  '@vitest/expect@2.0.0':
+    dependencies:
+      '@vitest/spy': 2.0.0
+      '@vitest/utils': 2.0.0
+      chai: 5.3.3
+
+  '@vitest/runner@2.0.0':
+    dependencies:
+      '@vitest/utils': 2.0.0
+      pathe: 1.1.2
+
+  '@vitest/snapshot@2.0.0':
+    dependencies:
+      magic-string: 0.30.21
+      pathe: 1.1.2
+      pretty-format: 29.7.0
+
+  '@vitest/spy@2.0.0':
+    dependencies:
+      tinyspy: 3.0.2
+
+  '@vitest/utils@2.0.0':
+    dependencies:
+      diff-sequences: 29.6.3
+      estree-walker: 3.0.3
+      loupe: 3.2.1
+      pretty-format: 29.7.0
+
+  '@wordpress/a11y@4.48.1':
+    dependencies:
+      '@wordpress/dom-ready': 4.48.1
+      '@wordpress/i18n': 6.21.1
+
+  '@wordpress/api-fetch@7.48.1':
+    dependencies:
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/url': 4.48.1
+
+  '@wordpress/autop@4.48.1': {}
+
+  '@wordpress/base-styles@10.0.1': {}
+
+  '@wordpress/base-styles@6.20.0': {}
+
+  '@wordpress/blob@4.48.1': {}
+
+  '@wordpress/block-editor@15.15.0(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@react-spring/web': 9.7.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/a11y': 4.48.1
+      '@wordpress/api-fetch': 7.48.1
+      '@wordpress/base-styles': 6.20.0
+      '@wordpress/blob': 4.48.1
+      '@wordpress/block-serialization-default-parser': 5.47.0
+      '@wordpress/blocks': 15.15.0(react@18.3.1)
+      '@wordpress/commands': 1.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/components': 32.6.0(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/compose': 7.46.0(react@18.3.1)
+      '@wordpress/data': 10.42.0(react@18.3.1)
+      '@wordpress/dataviews': 13.1.0(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/date': 5.48.1
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/dom': 4.48.1
+      '@wordpress/element': 6.46.0
+      '@wordpress/escape-html': 3.48.1
+      '@wordpress/global-styles-engine': 1.15.1(react@18.3.1)
+      '@wordpress/hooks': 4.42.0
+      '@wordpress/html-entities': 4.48.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/icons': 12.2.0(react@18.3.1)
+      '@wordpress/image-cropper': 1.12.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/interactivity': 6.48.1
+      '@wordpress/is-shallow-equal': 5.48.1
+      '@wordpress/keyboard-shortcuts': 5.48.1(react@18.3.1)
+      '@wordpress/keycodes': 4.48.1
+      '@wordpress/notices': 5.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/preferences': 4.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/priority-queue': 3.48.1
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/rich-text': 7.48.1(react@18.3.1)
+      '@wordpress/style-engine': 2.48.1
+      '@wordpress/token-list': 3.48.1
+      '@wordpress/upload-media': 0.27.0(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/url': 4.48.1
+      '@wordpress/warning': 3.48.1
+      '@wordpress/wordcount': 4.48.1
+      change-case: 4.1.2
+      clsx: 2.1.1
+      colord: 2.9.3
+      deepmerge: 4.3.1
+      diff: 4.0.4
+      fast-deep-equal: 3.1.3
+      memize: 2.1.1
+      parsel-js: 1.2.2
+      postcss: 8.5.15
+      postcss-prefix-selector: 1.16.1(postcss@8.5.15)
+      postcss-urlrebase: 1.4.0(postcss@8.5.15)
+      react: 18.3.1
+      react-autosize-textarea: 7.1.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react-dom: 18.3.1(react@18.3.1)
+      react-easy-crop: 5.5.7(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      remove-accents: 0.5.0
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - '@types/react'
+      - '@types/react-dom'
+      - stylelint
+      - supports-color
+
+  '@wordpress/block-editor@15.21.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@react-spring/web': 9.7.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@types/react': 18.3.31
+      '@wordpress/a11y': 4.48.1
+      '@wordpress/base-styles': 10.0.1
+      '@wordpress/blob': 4.48.1
+      '@wordpress/block-serialization-default-parser': 5.48.1
+      '@wordpress/blocks': 15.21.1(react@18.3.1)
+      '@wordpress/commands': 1.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/components': 35.0.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/compose': 8.1.1(react@18.3.1)
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      '@wordpress/dataviews': 16.0.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/date': 5.48.1
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/dom': 4.48.1
+      '@wordpress/element': 8.0.1
+      '@wordpress/escape-html': 3.48.1
+      '@wordpress/global-styles-engine': 1.15.1(react@18.3.1)
+      '@wordpress/hooks': 4.48.1
+      '@wordpress/html-entities': 4.48.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/icons': 14.0.1(react@18.3.1)
+      '@wordpress/image-cropper': 1.12.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/interactivity': 6.48.1
+      '@wordpress/is-shallow-equal': 5.48.1
+      '@wordpress/keyboard-shortcuts': 5.48.1(react@18.3.1)
+      '@wordpress/keycodes': 4.48.1
+      '@wordpress/notices': 5.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/preferences': 4.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/priority-queue': 3.48.1
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/rich-text': 7.48.1(react@18.3.1)
+      '@wordpress/style-engine': 2.48.1
+      '@wordpress/token-list': 3.48.1
+      '@wordpress/ui': 0.15.1(@date-fns/tz@1.5.0)(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/upload-media': 0.33.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/url': 4.48.1
+      '@wordpress/warning': 3.48.1
+      '@wordpress/wordcount': 4.48.1
+      change-case: 4.1.2
+      clsx: 2.1.1
+      colord: 2.9.3
+      deepmerge: 4.3.1
+      diff: 8.0.4
+      fast-deep-equal: 3.1.3
+      memize: 2.1.1
+      parsel-js: 1.2.2
+      postcss: 8.5.15
+      postcss-prefix-selector: 1.16.1(postcss@8.5.15)
+      postcss-urlrebase: 1.4.0(postcss@8.5.15)
+      react: 18.3.1
+      react-autosize-textarea: 7.1.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react-dom: 18.3.1(react@18.3.1)
+      react-easy-crop: 5.5.7(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      remove-accents: 0.5.0
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - '@types/react-dom'
+      - date-fns
+      - stylelint
+      - supports-color
+
+  '@wordpress/block-library@9.42.0(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@arraypress/waveform-player': 1.2.1
+      '@wordpress/a11y': 4.48.1
+      '@wordpress/api-fetch': 7.48.1
+      '@wordpress/autop': 4.48.1
+      '@wordpress/base-styles': 6.20.0
+      '@wordpress/blob': 4.48.1
+      '@wordpress/block-editor': 15.15.0(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/blocks': 15.15.0(react@18.3.1)
+      '@wordpress/components': 32.6.0(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/compose': 7.46.0(react@18.3.1)
+      '@wordpress/core-data': 7.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/data': 10.42.0(react@18.3.1)
+      '@wordpress/date': 5.48.1
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/dom': 4.48.1
+      '@wordpress/element': 6.46.0
+      '@wordpress/escape-html': 3.48.1
+      '@wordpress/hooks': 4.42.0
+      '@wordpress/html-entities': 4.48.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/icons': 12.2.0(react@18.3.1)
+      '@wordpress/interactivity': 6.48.1
+      '@wordpress/interactivity-router': 2.48.1
+      '@wordpress/keyboard-shortcuts': 5.48.1(react@18.3.1)
+      '@wordpress/keycodes': 4.48.1
+      '@wordpress/latex-to-mathml': 1.16.1
+      '@wordpress/notices': 5.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/patterns': 2.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/primitives': 4.48.1(react@18.3.1)
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/reusable-blocks': 5.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/rich-text': 7.48.1(react@18.3.1)
+      '@wordpress/server-side-render': 6.24.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/upload-media': 0.27.0(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/url': 4.48.1
+      '@wordpress/viewport': 6.48.1(react@18.3.1)
+      '@wordpress/wordcount': 4.48.1
+      change-case: 4.1.2
+      clsx: 2.1.1
+      colord: 2.9.3
+      fast-average-color: 9.5.2
+      fast-deep-equal: 3.1.3
+      html-react-parser: 5.2.11(@types/react@18.3.31)(react@18.3.1)
+      memize: 2.1.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      remove-accents: 0.5.0
+      uuid: 9.0.1
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - '@types/react'
+      - '@types/react-dom'
+      - date-fns
+      - stylelint
+      - supports-color
+
+  '@wordpress/block-serialization-default-parser@5.47.0': {}
+
+  '@wordpress/block-serialization-default-parser@5.48.1': {}
+
+  '@wordpress/blocks@15.15.0(react@18.3.1)':
+    dependencies:
+      '@wordpress/autop': 4.48.1
+      '@wordpress/blob': 4.48.1
+      '@wordpress/block-serialization-default-parser': 5.47.0
+      '@wordpress/data': 10.42.0(react@18.3.1)
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/dom': 4.48.1
+      '@wordpress/element': 6.46.0
+      '@wordpress/hooks': 4.42.0
+      '@wordpress/html-entities': 4.48.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/is-shallow-equal': 5.48.1
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/rich-text': 7.48.1(react@18.3.1)
+      '@wordpress/shortcode': 4.48.1
+      '@wordpress/warning': 3.48.1
+      change-case: 4.1.2
+      colord: 2.9.3
+      fast-deep-equal: 3.1.3
+      hpq: 1.4.0
+      is-plain-object: 5.0.0
+      memize: 2.1.1
+      react: 18.3.1
+      react-is: 18.3.1
+      remove-accents: 0.5.0
+      showdown: 1.9.1
+      simple-html-tokenizer: 0.5.11
+      uuid: 9.0.1
+
+  '@wordpress/blocks@15.21.1(react@18.3.1)':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/autop': 4.48.1
+      '@wordpress/blob': 4.48.1
+      '@wordpress/block-serialization-default-parser': 5.48.1
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/dom': 4.48.1
+      '@wordpress/element': 8.0.1
+      '@wordpress/hooks': 4.48.1
+      '@wordpress/html-entities': 4.48.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/is-shallow-equal': 5.48.1
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/rich-text': 7.48.1(react@18.3.1)
+      '@wordpress/shortcode': 4.48.1
+      '@wordpress/warning': 3.48.1
+      change-case: 4.1.2
+      colord: 2.9.3
+      fast-deep-equal: 3.1.3
+      hpq: 1.4.0
+      is-plain-object: 5.0.0
+      memize: 2.1.1
+      react: 18.3.1
+      react-is: 18.3.1
+      remove-accents: 0.5.0
+      showdown: 1.9.1
+      simple-html-tokenizer: 0.5.11
+      uuid: 14.0.1
+
+  '@wordpress/commands@1.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@wordpress/base-styles': 10.0.1
+      '@wordpress/components': 35.0.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      '@wordpress/element': 8.0.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/icons': 14.0.1(react@18.3.1)
+      '@wordpress/keyboard-shortcuts': 5.48.1(react@18.3.1)
+      '@wordpress/preferences': 4.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/warning': 3.48.1
+      clsx: 2.1.1
+      cmdk: 1.1.1(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - '@types/react'
+      - '@types/react-dom'
+      - stylelint
+      - supports-color
+
+  '@wordpress/components@32.6.0(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@ariakit/react': 0.4.29(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@date-fns/utc': 2.1.1
+      '@emotion/cache': 11.14.0
+      '@emotion/css': 11.13.5
+      '@emotion/react': 11.14.0(@types/react@18.3.31)(react@18.3.1)
+      '@emotion/serialize': 1.3.3
+      '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@18.3.1))(@types/react@18.3.31)(react@18.3.1)
+      '@emotion/utils': 1.4.2
+      '@floating-ui/react-dom': 2.0.8(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@types/gradient-parser': 1.1.0
+      '@types/highlight-words-core': 1.2.1
+      '@types/react': 18.3.31
+      '@use-gesture/react': 10.3.1(react@18.3.1)
+      '@wordpress/a11y': 4.48.1
+      '@wordpress/base-styles': 6.20.0
+      '@wordpress/compose': 7.46.0(react@18.3.1)
+      '@wordpress/date': 5.48.1
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/dom': 4.48.1
+      '@wordpress/element': 6.46.0
+      '@wordpress/escape-html': 3.48.1
+      '@wordpress/hooks': 4.48.1
+      '@wordpress/html-entities': 4.48.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/icons': 12.2.0(react@18.3.1)
+      '@wordpress/is-shallow-equal': 5.48.1
+      '@wordpress/keycodes': 4.48.1
+      '@wordpress/primitives': 4.48.1(react@18.3.1)
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/rich-text': 7.48.1(react@18.3.1)
+      '@wordpress/warning': 3.48.1
+      change-case: 4.1.2
+      clsx: 2.1.1
+      colord: 2.9.3
+      csstype: 3.2.3
+      date-fns: 3.6.0
+      deepmerge: 4.3.1
+      fast-deep-equal: 3.1.3
+      framer-motion: 11.18.2(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      gradient-parser: 1.1.1
+      highlight-words-core: 1.2.3
+      is-plain-object: 5.0.0
+      memize: 2.1.1
+      path-to-regexp: 6.3.0
+      re-resizable: 6.11.2(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-colorful: 5.7.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react-day-picker: 9.14.0(react@18.3.1)
+      react-dom: 18.3.1(react@18.3.1)
+      remove-accents: 0.5.0
+      uuid: 9.0.1
+    transitivePeerDependencies:
+      - '@emotion/is-prop-valid'
+      - supports-color
+
+  '@wordpress/components@35.0.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@ariakit/react': 0.4.29(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@date-fns/utc': 2.1.1
+      '@emotion/cache': 11.14.0
+      '@emotion/css': 11.13.5
+      '@emotion/react': 11.14.0(@types/react@18.3.31)(react@18.3.1)
+      '@emotion/serialize': 1.3.3
+      '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@18.3.1))(@types/react@18.3.31)(react@18.3.1)
+      '@emotion/utils': 1.4.2
+      '@floating-ui/react-dom': 2.1.8(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@types/gradient-parser': 1.1.0
+      '@types/highlight-words-core': 1.2.3
+      '@types/react': 18.3.31
+      '@use-gesture/react': 10.3.1(react@18.3.1)
+      '@wordpress/a11y': 4.48.1
+      '@wordpress/base-styles': 10.0.1
+      '@wordpress/compose': 8.1.1(react@18.3.1)
+      '@wordpress/date': 5.48.1
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/dom': 4.48.1
+      '@wordpress/element': 8.0.1
+      '@wordpress/escape-html': 3.48.1
+      '@wordpress/hooks': 4.48.1
+      '@wordpress/html-entities': 4.48.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/icons': 14.0.1(react@18.3.1)
+      '@wordpress/is-shallow-equal': 5.48.1
+      '@wordpress/keycodes': 4.48.1
+      '@wordpress/primitives': 4.48.1(react@18.3.1)
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/rich-text': 7.48.1(react@18.3.1)
+      '@wordpress/style-runtime': 0.4.1
+      '@wordpress/ui': 0.15.1(@date-fns/tz@1.5.0)(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/warning': 3.48.1
+      change-case: 4.1.2
+      clsx: 2.1.1
+      colord: 2.9.3
+      csstype: 3.2.3
+      date-fns: 4.4.0
+      deepmerge: 4.3.1
+      fast-deep-equal: 3.1.3
+      framer-motion: 11.18.2(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      gradient-parser: 1.2.0
+      highlight-words-core: 1.2.3
+      is-plain-object: 5.0.0
+      memize: 2.1.1
+      path-to-regexp: 6.3.0
+      re-resizable: 6.11.2(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-colorful: 5.7.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react-day-picker: 9.14.0(react@18.3.1)
+      react-dom: 18.3.1(react@18.3.1)
+      remove-accents: 0.5.0
+      uuid: 14.0.1
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - stylelint
+      - supports-color
+
+  '@wordpress/compose@7.46.0(react@18.3.1)':
+    dependencies:
+      '@types/mousetrap': 1.6.15
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/dom': 4.48.1
+      '@wordpress/element': 6.46.0
+      '@wordpress/is-shallow-equal': 5.48.1
+      '@wordpress/keycodes': 4.48.1
+      '@wordpress/priority-queue': 3.48.1
+      '@wordpress/undo-manager': 1.48.1
+      change-case: 4.1.2
+      mousetrap: 1.6.5
+      react: 18.3.1
+      use-memo-one: 1.1.3(react@18.3.1)
+
+  '@wordpress/compose@8.1.1(react@18.3.1)':
+    dependencies:
+      '@types/mousetrap': 1.6.15
+      '@types/react': 18.3.31
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/dom': 4.48.1
+      '@wordpress/element': 8.0.1
+      '@wordpress/is-shallow-equal': 5.48.1
+      '@wordpress/keycodes': 4.48.1
+      '@wordpress/priority-queue': 3.48.1
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/undo-manager': 1.48.1
+      change-case: 4.1.2
+      mousetrap: 1.6.5
+      react: 18.3.1
+      use-memo-one: 1.1.3(react@18.3.1)
+
+  '@wordpress/core-data@7.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/api-fetch': 7.48.1
+      '@wordpress/block-editor': 15.21.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/blocks': 15.21.1(react@18.3.1)
+      '@wordpress/compose': 8.1.1(react@18.3.1)
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/element': 8.0.1
+      '@wordpress/html-entities': 4.48.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/is-shallow-equal': 5.48.1
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/rich-text': 7.48.1(react@18.3.1)
+      '@wordpress/sync': 1.48.1
+      '@wordpress/undo-manager': 1.48.1
+      '@wordpress/url': 4.48.1
+      '@wordpress/warning': 3.48.1
+      change-case: 4.1.2
+      equivalent-key-map: 0.2.2
+      fast-deep-equal: 3.1.3
+      memize: 2.1.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      uuid: 14.0.1
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - '@types/react-dom'
+      - date-fns
+      - stylelint
+      - supports-color
+
+  '@wordpress/data@10.42.0(react@18.3.1)':
+    dependencies:
+      '@wordpress/compose': 7.46.0(react@18.3.1)
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/element': 6.46.0
+      '@wordpress/is-shallow-equal': 5.48.1
+      '@wordpress/priority-queue': 3.48.1
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/redux-routine': 5.48.1(redux@5.0.1)
+      deepmerge: 4.3.1
+      equivalent-key-map: 0.2.2
+      is-plain-object: 5.0.0
+      is-promise: 4.0.0
+      react: 18.3.1
+      redux: 5.0.1
+      rememo: 4.0.2
+      use-memo-one: 1.1.3(react@18.3.1)
+
+  '@wordpress/data@10.48.1(react@18.3.1)':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/compose': 8.1.1(react@18.3.1)
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/element': 8.0.1
+      '@wordpress/is-shallow-equal': 5.48.1
+      '@wordpress/priority-queue': 3.48.1
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/redux-routine': 5.48.1(redux@5.0.1)
+      deepmerge: 4.3.1
+      equivalent-key-map: 0.2.2
+      is-plain-object: 5.0.0
+      is-promise: 4.0.0
+      react: 18.3.1
+      redux: 5.0.1
+      rememo: 4.0.2
+      use-memo-one: 1.1.3(react@18.3.1)
+
+  '@wordpress/dataviews@13.1.0(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@ariakit/react': 0.4.29(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/base-styles': 6.20.0
+      '@wordpress/components': 32.6.0(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/compose': 7.46.0(react@18.3.1)
+      '@wordpress/data': 10.42.0(react@18.3.1)
+      '@wordpress/date': 5.48.1
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/element': 6.46.0
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/icons': 12.2.0(react@18.3.1)
+      '@wordpress/keycodes': 4.48.1
+      '@wordpress/primitives': 4.48.1(react@18.3.1)
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/ui': 0.9.0(@date-fns/tz@1.5.0)(@types/react@18.3.31)(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/warning': 3.48.1
+      clsx: 2.1.1
+      colord: 2.9.3
+      date-fns: 4.4.0
+      deepmerge: 4.3.1
+      fast-deep-equal: 3.1.3
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      remove-accents: 0.5.0
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - '@types/react'
+      - stylelint
+      - supports-color
+
+  '@wordpress/dataviews@16.0.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@ariakit/react': 0.4.29(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@types/react': 18.3.31
+      '@wordpress/base-styles': 10.0.1
+      '@wordpress/components': 35.0.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/compose': 8.1.1(react@18.3.1)
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      '@wordpress/date': 5.48.1
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/element': 8.0.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/icons': 14.0.1(react@18.3.1)
+      '@wordpress/keycodes': 4.48.1
+      '@wordpress/primitives': 4.48.1(react@18.3.1)
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/ui': 0.15.1(@date-fns/tz@1.5.0)(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/warning': 3.48.1
+      clsx: 2.1.1
+      colord: 2.9.3
+      date-fns: 4.4.0
+      deepmerge: 4.3.1
+      fast-deep-equal: 3.1.3
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      remove-accents: 0.5.0
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - stylelint
+      - supports-color
+
+  '@wordpress/date@5.48.1':
+    dependencies:
+      '@wordpress/deprecated': 4.48.1
+      moment: 2.30.1
+      moment-timezone: 0.5.48
+
+  '@wordpress/deprecated@4.48.1':
+    dependencies:
+      '@wordpress/hooks': 4.48.1
+
+  '@wordpress/dom-ready@4.48.1': {}
+
+  '@wordpress/dom@4.48.1':
+    dependencies:
+      '@wordpress/deprecated': 4.48.1
+
+  '@wordpress/element@6.46.0':
+    dependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+      '@wordpress/escape-html': 3.48.1
+      change-case: 4.1.2
+      is-plain-object: 5.0.0
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
+  '@wordpress/element@8.0.1':
+    dependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/escape-html': 3.48.1
+      change-case: 4.1.2
+      is-plain-object: 5.0.0
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
+  '@wordpress/escape-html@3.48.1': {}
+
+  '@wordpress/global-styles-engine@1.15.1(react@18.3.1)':
+    dependencies:
+      '@wordpress/blocks': 15.21.1(react@18.3.1)
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/style-engine': 2.48.1
+      colord: 2.9.3
+      deepmerge: 4.3.1
+      fast-deep-equal: 3.1.3
+      is-plain-object: 5.0.0
+      memize: 2.1.1
+    transitivePeerDependencies:
+      - react
+
+  '@wordpress/hooks@4.42.0': {}
+
+  '@wordpress/hooks@4.48.1': {}
+
+  '@wordpress/html-entities@4.48.1': {}
+
+  '@wordpress/i18n@6.21.1':
+    dependencies:
+      '@tannin/sprintf': 1.3.3
+      '@wordpress/hooks': 4.48.1
+      gettext-parser: 1.4.0
+      memize: 2.1.1
+      tannin: 1.2.0
+
+  '@wordpress/icons@12.2.0(react@18.3.1)':
+    dependencies:
+      '@wordpress/element': 6.46.0
+      '@wordpress/primitives': 4.48.1(react@18.3.1)
+      change-case: 4.1.2
+      react: 18.3.1
+
+  '@wordpress/icons@14.0.1(react@18.3.1)':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/element': 8.0.1
+      '@wordpress/primitives': 4.48.1(react@18.3.1)
+      change-case: 4.1.2
+      react: 18.3.1
+
+  '@wordpress/image-cropper@1.12.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/components': 35.0.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/element': 8.0.1
+      '@wordpress/i18n': 6.21.1
+      clsx: 2.1.1
+      dequal: 2.0.3
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      react-easy-crop: 5.5.7(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - stylelint
+      - supports-color
+
+  '@wordpress/interactivity-router@2.48.1':
+    dependencies:
+      '@wordpress/a11y': 4.48.1
+      '@wordpress/interactivity': 6.48.1
+      es-module-lexer: 1.7.0
+
+  '@wordpress/interactivity@6.48.1':
+    dependencies:
+      '@preact/signals': 1.3.4(preact@10.29.2)
+      preact: 10.29.2
+
+  '@wordpress/is-shallow-equal@5.48.1': {}
+
+  '@wordpress/keyboard-shortcuts@5.48.1(react@18.3.1)':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      '@wordpress/element': 8.0.1
+      '@wordpress/keycodes': 4.48.1
+      react: 18.3.1
+
+  '@wordpress/keycodes@4.48.1':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/i18n': 6.21.1
+
+  '@wordpress/latex-to-mathml@1.16.1':
+    dependencies:
+      temml: 0.10.34
+
+  '@wordpress/notices@5.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/a11y': 4.48.1
+      '@wordpress/components': 35.0.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      clsx: 2.1.1
+      react: 18.3.1
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - react-dom
+      - stylelint
+      - supports-color
+
+  '@wordpress/patterns@2.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@wordpress/a11y': 4.48.1
+      '@wordpress/base-styles': 10.0.1
+      '@wordpress/block-editor': 15.21.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/blocks': 15.21.1(react@18.3.1)
+      '@wordpress/components': 35.0.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/compose': 8.1.1(react@18.3.1)
+      '@wordpress/core-data': 7.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      '@wordpress/element': 8.0.1
+      '@wordpress/html-entities': 4.48.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/icons': 14.0.1(react@18.3.1)
+      '@wordpress/notices': 5.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/url': 4.48.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - '@types/react-dom'
+      - date-fns
+      - stylelint
+      - supports-color
+
+  '@wordpress/preferences@4.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/a11y': 4.48.1
+      '@wordpress/base-styles': 10.0.1
+      '@wordpress/components': 35.0.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/compose': 8.1.1(react@18.3.1)
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/element': 8.0.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/icons': 14.0.1(react@18.3.1)
+      '@wordpress/private-apis': 1.48.1
+      clsx: 2.1.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - stylelint
+      - supports-color
+
+  '@wordpress/primitives@4.48.1(react@18.3.1)':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/element': 8.0.1
+      clsx: 2.1.1
+      react: 18.3.1
+
+  '@wordpress/priority-queue@3.48.1':
+    dependencies:
+      requestidlecallback: 0.3.0
+
+  '@wordpress/private-apis@1.48.1': {}
+
+  '@wordpress/redux-routine@5.48.1(redux@5.0.1)':
+    dependencies:
+      is-plain-object: 5.0.0
+      is-promise: 4.0.0
+      redux: 5.0.1
+      rungen: 0.3.2
+
+  '@wordpress/reusable-blocks@5.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@wordpress/base-styles': 10.0.1
+      '@wordpress/block-editor': 15.21.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/blocks': 15.21.1(react@18.3.1)
+      '@wordpress/components': 35.0.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/core-data': 7.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(@types/react-dom@18.3.7(@types/react@18.3.31))(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      '@wordpress/element': 8.0.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/icons': 14.0.1(react@18.3.1)
+      '@wordpress/notices': 5.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/url': 4.48.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - '@types/react-dom'
+      - date-fns
+      - stylelint
+      - supports-color
+
+  '@wordpress/rich-text@7.48.1(react@18.3.1)':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/a11y': 4.48.1
+      '@wordpress/compose': 8.1.1(react@18.3.1)
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/dom': 4.48.1
+      '@wordpress/element': 8.0.1
+      '@wordpress/escape-html': 3.48.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/keycodes': 4.48.1
+      '@wordpress/private-apis': 1.48.1
+      colord: 2.9.3
+      memize: 2.1.1
+      react: 18.3.1
+
+  '@wordpress/server-side-render@6.24.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/api-fetch': 7.48.1
+      '@wordpress/blocks': 15.21.1(react@18.3.1)
+      '@wordpress/components': 35.0.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/compose': 8.1.1(react@18.3.1)
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      '@wordpress/deprecated': 4.48.1
+      '@wordpress/element': 8.0.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/url': 4.48.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - stylelint
+      - supports-color
+
+  '@wordpress/shortcode@4.48.1':
+    dependencies:
+      memize: 2.1.1
+
+  '@wordpress/style-engine@2.48.1':
+    dependencies:
+      '@types/react': 18.3.31
+      change-case: 4.1.2
+
+  '@wordpress/style-runtime@0.4.1': {}
+
+  '@wordpress/sync@1.48.1':
+    dependencies:
+      '@wordpress/api-fetch': 7.48.1
+      '@wordpress/hooks': 4.48.1
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/undo-manager': 1.48.1
+      diff: 8.0.4
+      fast-deep-equal: 3.1.3
+      lib0: 0.2.117
+      y-protocols: 1.0.7(yjs@13.6.31)
+      yjs: 13.6.31
+
+  '@wordpress/theme@0.15.1(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/element': 8.0.1
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/style-runtime': 0.4.1
+      colorjs.io: 0.6.1
+      memize: 2.1.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
+  '@wordpress/theme@0.9.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@wordpress/element': 6.46.0
+      '@wordpress/private-apis': 1.48.1
+      colorjs.io: 0.6.1
+      memize: 2.1.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
+  '@wordpress/token-list@3.48.1': {}
+
+  '@wordpress/ui@0.15.1(@date-fns/tz@1.5.0)(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@base-ui/react': 1.6.0(@date-fns/tz@1.5.0)(@types/react@18.3.31)(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@types/react': 18.3.31
+      '@wordpress/a11y': 4.48.1
+      '@wordpress/compose': 8.1.1(react@18.3.1)
+      '@wordpress/element': 8.0.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/icons': 14.0.1(react@18.3.1)
+      '@wordpress/keycodes': 4.48.1
+      '@wordpress/primitives': 4.48.1(react@18.3.1)
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/style-runtime': 0.4.1
+      '@wordpress/theme': 0.15.1(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      clsx: 2.1.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      tabbable: 6.5.0
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - date-fns
+      - stylelint
+
+  '@wordpress/ui@0.9.0(@date-fns/tz@1.5.0)(@types/react@18.3.31)(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@base-ui/react': 1.6.0(@date-fns/tz@1.5.0)(@types/react@18.3.31)(date-fns@4.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/a11y': 4.48.1
+      '@wordpress/compose': 7.46.0(react@18.3.1)
+      '@wordpress/element': 6.46.0
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/icons': 12.2.0(react@18.3.1)
+      '@wordpress/keycodes': 4.48.1
+      '@wordpress/primitives': 4.48.1(react@18.3.1)
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/theme': 0.9.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      clsx: 2.1.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@types/react'
+      - date-fns
+      - stylelint
+
+  '@wordpress/undo-manager@1.48.1':
+    dependencies:
+      '@wordpress/is-shallow-equal': 5.48.1
+
+  '@wordpress/upload-media@0.27.0(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@wordpress/blob': 4.48.1
+      '@wordpress/compose': 7.46.0(react@18.3.1)
+      '@wordpress/data': 10.42.0(react@18.3.1)
+      '@wordpress/element': 6.46.0
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/preferences': 4.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/url': 4.48.1
+      '@wordpress/vips': 1.6.0
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      uuid: 9.0.1
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - stylelint
+      - supports-color
+
+  '@wordpress/upload-media@0.33.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/blob': 4.48.1
+      '@wordpress/compose': 8.1.1(react@18.3.1)
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      '@wordpress/element': 8.0.1
+      '@wordpress/i18n': 6.21.1
+      '@wordpress/preferences': 4.48.1(@date-fns/tz@1.5.0)(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@wordpress/private-apis': 1.48.1
+      '@wordpress/url': 4.48.1
+      '@wordpress/vips': 2.1.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      uuid: 14.0.1
+    transitivePeerDependencies:
+      - '@date-fns/tz'
+      - '@emotion/is-prop-valid'
+      - stylelint
+      - supports-color
+
+  '@wordpress/url@4.48.1':
+    dependencies:
+      remove-accents: 0.5.0
+
+  '@wordpress/viewport@6.48.1(react@18.3.1)':
+    dependencies:
+      '@types/react': 18.3.31
+      '@wordpress/compose': 8.1.1(react@18.3.1)
+      '@wordpress/data': 10.48.1(react@18.3.1)
+      '@wordpress/element': 8.0.1
+      react: 18.3.1
+
+  '@wordpress/vips@1.6.0':
+    dependencies:
+      '@wordpress/worker-threads': 1.8.1
+      wasm-vips: 0.0.16
+
+  '@wordpress/vips@2.1.1':
+    dependencies:
+      '@wordpress/worker-threads': 1.8.1
+      wasm-vips: 0.0.17
+
+  '@wordpress/warning@3.48.1': {}
+
+  '@wordpress/wordcount@4.48.1': {}
+
+  '@wordpress/worker-threads@1.8.1':
+    dependencies:
+      comctx: 1.7.5
+
+  ansi-regex@4.1.1: {}
+
+  ansi-styles@3.2.1:
+    dependencies:
+      color-convert: 1.9.3
+
+  ansi-styles@5.2.0: {}
+
+  any-promise@1.3.0: {}
+
+  anymatch@3.1.3:
+    dependencies:
+      normalize-path: 3.0.0
+      picomatch: 2.3.2
+
+  aria-hidden@1.2.6:
+    dependencies:
+      tslib: 2.8.1
+
+  array-union@2.1.0: {}
+
+  assertion-error@2.0.1: {}
+
+  autosize@4.0.4: {}
+
+  babel-plugin-macros@3.1.0:
+    dependencies:
+      '@babel/runtime': 7.29.7
+      cosmiconfig: 7.1.0
+      resolve: 1.22.12
+
+  bidi-js@1.0.3:
+    dependencies:
+      require-from-string: 2.0.2
+
+  binary-extensions@2.3.0: {}
+
+  boolbase@1.0.0: {}
+
+  braces@3.0.3:
+    dependencies:
+      fill-range: 7.1.1
+
+  bundle-require@4.2.1(esbuild@0.19.12):
+    dependencies:
+      esbuild: 0.19.12
+      load-tsconfig: 0.2.5
+
+  cac@6.7.14: {}
+
+  callsites@3.1.0: {}
+
+  camel-case@4.1.2:
+    dependencies:
+      pascal-case: 3.1.2
+      tslib: 2.8.1
+
+  camelcase@5.3.1: {}
+
+  capital-case@1.0.4:
+    dependencies:
+      no-case: 3.0.4
+      tslib: 2.8.1
+      upper-case-first: 2.0.2
+
+  chai@5.3.3:
+    dependencies:
+      assertion-error: 2.0.1
+      check-error: 2.1.3
+      deep-eql: 5.0.2
+      loupe: 3.2.1
+      pathval: 2.0.1
+
+  change-case@4.1.2:
+    dependencies:
+      camel-case: 4.1.2
+      capital-case: 1.0.4
+      constant-case: 3.0.4
+      dot-case: 3.0.4
+      header-case: 2.0.4
+      no-case: 3.0.4
+      param-case: 3.0.4
+      pascal-case: 3.1.2
+      path-case: 3.0.4
+      sentence-case: 3.0.4
+      snake-case: 3.0.4
+      tslib: 2.8.1
+
+  check-error@2.1.3: {}
+
+  cheerio-select@2.1.0:
+    dependencies:
+      boolbase: 1.0.0
+      css-select: 5.2.2
+      css-what: 6.2.2
+      domelementtype: 2.3.0
+      domhandler: 5.0.3
+      domutils: 3.2.2
+
+  cheerio@1.2.0:
+    dependencies:
+      cheerio-select: 2.1.0
+      dom-serializer: 2.0.0
+      domhandler: 5.0.3
+      domutils: 3.2.2
+      encoding-sniffer: 0.2.1
+      htmlparser2: 10.1.0
+      parse5: 7.3.0
+      parse5-htmlparser2-tree-adapter: 7.1.0
+      parse5-parser-stream: 7.1.2
+      undici: 7.28.0
+      whatwg-mimetype: 4.0.0
+
+  chokidar@3.6.0:
+    dependencies:
+      anymatch: 3.1.3
+      braces: 3.0.3
+      glob-parent: 5.1.2
+      is-binary-path: 2.1.0
+      is-glob: 4.0.3
+      normalize-path: 3.0.0
+      readdirp: 3.6.0
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  cliui@5.0.0:
+    dependencies:
+      string-width: 3.1.0
+      strip-ansi: 5.2.0
+      wrap-ansi: 5.1.0
+
+  clsx@2.1.1: {}
+
+  cmdk@1.1.1(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-dialog': 1.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    transitivePeerDependencies:
+      - '@types/react'
+      - '@types/react-dom'
+
+  color-convert@1.9.3:
+    dependencies:
+      color-name: 1.1.3
+
+  color-name@1.1.3: {}
+
+  colord@2.9.3: {}
+
+  colorjs.io@0.6.1: {}
+
+  comctx@1.7.5: {}
+
+  commander@4.1.1: {}
+
+  computed-style@0.1.4: {}
+
+  constant-case@3.0.4:
+    dependencies:
+      no-case: 3.0.4
+      tslib: 2.8.1
+      upper-case: 2.0.2
+
+  convert-source-map@1.9.0: {}
+
+  cosmiconfig@7.1.0:
+    dependencies:
+      '@types/parse-json': 4.0.2
+      import-fresh: 3.3.1
+      parse-json: 5.2.0
+      path-type: 4.0.0
+      yaml: 1.10.3
+
+  cross-spawn@7.0.6:
+    dependencies:
+      path-key: 3.1.1
+      shebang-command: 2.0.0
+      which: 2.0.2
+
+  css-select@5.2.2:
+    dependencies:
+      boolbase: 1.0.0
+      css-what: 6.2.2
+      domhandler: 5.0.3
+      domutils: 3.2.2
+      nth-check: 2.1.1
+
+  css-tree@3.2.1:
+    dependencies:
+      mdn-data: 2.27.1
+      source-map-js: 1.2.1
+
+  css-what@6.2.2: {}
+
+  csstype@3.2.3: {}
+
+  data-urls@7.0.0:
+    dependencies:
+      whatwg-mimetype: 5.0.0
+      whatwg-url: 16.0.1
+    transitivePeerDependencies:
+      - '@noble/hashes'
+
+  date-fns-jalali@4.1.0-0: {}
+
+  date-fns@3.6.0: {}
+
+  date-fns@4.4.0: {}
+
+  debug@4.4.3:
+    dependencies:
+      ms: 2.1.3
+
+  decamelize@1.2.0: {}
+
+  decimal.js@10.6.0: {}
+
+  deep-eql@5.0.2: {}
+
+  deepmerge@4.3.1: {}
+
+  dequal@2.0.3: {}
+
+  detect-node-es@1.1.0: {}
+
+  diff-sequences@29.6.3: {}
+
+  diff@4.0.4: {}
+
+  diff@8.0.4: {}
+
+  dir-glob@3.0.1:
+    dependencies:
+      path-type: 4.0.0
+
+  dom-serializer@2.0.0:
+    dependencies:
+      domelementtype: 2.3.0
+      domhandler: 5.0.3
+      entities: 4.5.0
+
+  domelementtype@2.3.0: {}
+
+  domhandler@5.0.3:
+    dependencies:
+      domelementtype: 2.3.0
+
+  domutils@3.2.2:
+    dependencies:
+      dom-serializer: 2.0.0
+      domelementtype: 2.3.0
+      domhandler: 5.0.3
+
+  dot-case@3.0.4:
+    dependencies:
+      no-case: 3.0.4
+      tslib: 2.8.1
+
+  emoji-regex@7.0.3: {}
+
+  encoding-sniffer@0.2.1:
+    dependencies:
+      iconv-lite: 0.6.3
+      whatwg-encoding: 3.1.1
+
+  encoding@0.1.13:
+    dependencies:
+      iconv-lite: 0.6.3
+
+  entities@4.5.0: {}
+
+  entities@6.0.1: {}
+
+  entities@7.0.1: {}
+
+  entities@8.0.0: {}
+
+  equivalent-key-map@0.2.2: {}
+
+  error-ex@1.3.4:
+    dependencies:
+      is-arrayish: 0.2.1
+
+  es-errors@1.3.0: {}
+
+  es-module-lexer@1.7.0: {}
+
+  esbuild@0.19.12:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.19.12
+      '@esbuild/android-arm': 0.19.12
+      '@esbuild/android-arm64': 0.19.12
+      '@esbuild/android-x64': 0.19.12
+      '@esbuild/darwin-arm64': 0.19.12
+      '@esbuild/darwin-x64': 0.19.12
+      '@esbuild/freebsd-arm64': 0.19.12
+      '@esbuild/freebsd-x64': 0.19.12
+      '@esbuild/linux-arm': 0.19.12
+      '@esbuild/linux-arm64': 0.19.12
+      '@esbuild/linux-ia32': 0.19.12
+      '@esbuild/linux-loong64': 0.19.12
+      '@esbuild/linux-mips64el': 0.19.12
+      '@esbuild/linux-ppc64': 0.19.12
+      '@esbuild/linux-riscv64': 0.19.12
+      '@esbuild/linux-s390x': 0.19.12
+      '@esbuild/linux-x64': 0.19.12
+      '@esbuild/netbsd-x64': 0.19.12
+      '@esbuild/openbsd-x64': 0.19.12
+      '@esbuild/sunos-x64': 0.19.12
+      '@esbuild/win32-arm64': 0.19.12
+      '@esbuild/win32-ia32': 0.19.12
+      '@esbuild/win32-x64': 0.19.12
+
+  esbuild@0.21.5:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.21.5
+      '@esbuild/android-arm': 0.21.5
+      '@esbuild/android-arm64': 0.21.5
+      '@esbuild/android-x64': 0.21.5
+      '@esbuild/darwin-arm64': 0.21.5
+      '@esbuild/darwin-x64': 0.21.5
+      '@esbuild/freebsd-arm64': 0.21.5
+      '@esbuild/freebsd-x64': 0.21.5
+      '@esbuild/linux-arm': 0.21.5
+      '@esbuild/linux-arm64': 0.21.5
+      '@esbuild/linux-ia32': 0.21.5
+      '@esbuild/linux-loong64': 0.21.5
+      '@esbuild/linux-mips64el': 0.21.5
+      '@esbuild/linux-ppc64': 0.21.5
+      '@esbuild/linux-riscv64': 0.21.5
+      '@esbuild/linux-s390x': 0.21.5
+      '@esbuild/linux-x64': 0.21.5
+      '@esbuild/netbsd-x64': 0.21.5
+      '@esbuild/openbsd-x64': 0.21.5
+      '@esbuild/sunos-x64': 0.21.5
+      '@esbuild/win32-arm64': 0.21.5
+      '@esbuild/win32-ia32': 0.21.5
+      '@esbuild/win32-x64': 0.21.5
+
+  escape-string-regexp@4.0.0: {}
+
+  estree-walker@3.0.3:
+    dependencies:
+      '@types/estree': 1.0.9
+
+  execa@5.1.1:
+    dependencies:
+      cross-spawn: 7.0.6
+      get-stream: 6.0.1
+      human-signals: 2.1.0
+      is-stream: 2.0.1
+      merge-stream: 2.0.0
+      npm-run-path: 4.0.1
+      onetime: 5.1.2
+      signal-exit: 3.0.7
+      strip-final-newline: 2.0.0
+
+  execa@8.0.1:
+    dependencies:
+      cross-spawn: 7.0.6
+      get-stream: 8.0.1
+      human-signals: 5.0.0
+      is-stream: 3.0.0
+      merge-stream: 2.0.0
+      npm-run-path: 5.3.0
+      onetime: 6.0.0
+      signal-exit: 4.1.0
+      strip-final-newline: 3.0.0
+
+  fast-average-color@9.5.2: {}
+
+  fast-deep-equal@3.1.3: {}
+
+  fast-glob@3.3.3:
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      '@nodelib/fs.walk': 1.2.8
+      glob-parent: 5.1.2
+      merge2: 1.4.1
+      micromatch: 4.0.8
+
+  fastq@1.20.1:
+    dependencies:
+      reusify: 1.1.0
+
+  fdir@6.5.0(picomatch@4.0.4):
+    optionalDependencies:
+      picomatch: 4.0.4
+
+  fill-range@7.1.1:
+    dependencies:
+      to-regex-range: 5.0.1
+
+  find-root@1.1.0: {}
+
+  find-up@3.0.0:
+    dependencies:
+      locate-path: 3.0.0
+
+  framer-motion@11.18.2(@emotion/is-prop-valid@1.4.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+    dependencies:
+      motion-dom: 11.18.1
+      motion-utils: 11.18.1
+      tslib: 2.8.1
+    optionalDependencies:
+      '@emotion/is-prop-valid': 1.4.0
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
+  fsevents@2.3.3:
+    optional: true
+
+  function-bind@1.1.2: {}
+
+  get-caller-file@2.0.5: {}
+
+  get-nonce@1.0.1: {}
+
+  get-stream@6.0.1: {}
+
+  get-stream@8.0.1: {}
+
+  gettext-parser@1.4.0:
+    dependencies:
+      encoding: 0.1.13
+      safe-buffer: 5.2.1
+
+  glob-parent@5.1.2:
+    dependencies:
+      is-glob: 4.0.3
+
+  globby@11.1.0:
+    dependencies:
+      array-union: 2.1.0
+      dir-glob: 3.0.1
+      fast-glob: 3.3.3
+      ignore: 5.3.2
+      merge2: 1.4.1
+      slash: 3.0.0
+
+  gradient-parser@1.1.1: {}
+
+  gradient-parser@1.2.0: {}
+
+  hasown@2.0.4:
+    dependencies:
+      function-bind: 1.1.2
+
+  header-case@2.0.4:
+    dependencies:
+      capital-case: 1.0.4
+      tslib: 2.8.1
+
+  highlight-words-core@1.2.3: {}
+
+  hoist-non-react-statics@3.3.2:
+    dependencies:
+      react-is: 16.13.1
+
+  hpq@1.4.0: {}
+
+  html-dom-parser@5.1.2:
+    dependencies:
+      domhandler: 5.0.3
+      htmlparser2: 10.0.0
+
+  html-encoding-sniffer@6.0.0:
+    dependencies:
+      '@exodus/bytes': 1.15.1
+    transitivePeerDependencies:
+      - '@noble/hashes'
+
+  html-react-parser@5.2.11(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      domhandler: 5.0.3
+      html-dom-parser: 5.1.2
+      react: 18.3.1
+      react-property: 2.0.2
+      style-to-js: 1.1.21
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  htmlparser2@10.0.0:
+    dependencies:
+      domelementtype: 2.3.0
+      domhandler: 5.0.3
+      domutils: 3.2.2
+      entities: 6.0.1
+
+  htmlparser2@10.1.0:
+    dependencies:
+      domelementtype: 2.3.0
+      domhandler: 5.0.3
+      domutils: 3.2.2
+      entities: 7.0.1
+
+  human-signals@2.1.0: {}
+
+  human-signals@5.0.0: {}
+
+  iconv-lite@0.6.3:
+    dependencies:
+      safer-buffer: 2.1.2
+
+  ignore@5.3.2: {}
+
+  import-fresh@3.3.1:
+    dependencies:
+      parent-module: 1.0.1
+      resolve-from: 4.0.0
+
+  inline-style-parser@0.2.7: {}
+
+  is-arrayish@0.2.1: {}
+
+  is-binary-path@2.1.0:
+    dependencies:
+      binary-extensions: 2.3.0
+
+  is-core-module@2.16.2:
+    dependencies:
+      hasown: 2.0.4
+
+  is-extglob@2.1.1: {}
+
+  is-fullwidth-code-point@2.0.0: {}
+
+  is-glob@4.0.3:
+    dependencies:
+      is-extglob: 2.1.1
+
+  is-number@7.0.0: {}
+
+  is-plain-object@5.0.0: {}
+
+  is-potential-custom-element-name@1.0.1: {}
+
+  is-promise@4.0.0: {}
+
+  is-stream@2.0.1: {}
+
+  is-stream@3.0.0: {}
+
+  isexe@2.0.0: {}
+
+  isomorphic.js@0.2.5: {}
+
+  joycon@3.1.1: {}
+
+  js-tokens@4.0.0: {}
+
+  jsdom@29.0.1:
+    dependencies:
+      '@asamuzakjp/css-color': 5.1.11
+      '@asamuzakjp/dom-selector': 7.1.1
+      '@bramus/specificity': 2.4.2
+      '@csstools/css-syntax-patches-for-csstree': 1.1.5(css-tree@3.2.1)
+      '@exodus/bytes': 1.15.1
+      css-tree: 3.2.1
+      data-urls: 7.0.0
+      decimal.js: 10.6.0
+      html-encoding-sniffer: 6.0.0
+      is-potential-custom-element-name: 1.0.1
+      lru-cache: 11.5.1
+      parse5: 8.0.1
+      saxes: 6.0.0
+      symbol-tree: 3.2.4
+      tough-cookie: 6.0.1
+      undici: 7.28.0
+      w3c-xmlserializer: 5.0.0
+      webidl-conversions: 8.0.1
+      whatwg-mimetype: 5.0.0
+      whatwg-url: 16.0.1
+      xml-name-validator: 5.0.0
+    transitivePeerDependencies:
+      - '@noble/hashes'
+
+  jsesc@3.1.0: {}
+
+  json-parse-even-better-errors@2.3.1: {}
+
+  lib0@0.2.117:
+    dependencies:
+      isomorphic.js: 0.2.5
+
+  lilconfig@3.1.3: {}
+
+  line-height@0.3.1:
+    dependencies:
+      computed-style: 0.1.4
+
+  lines-and-columns@1.2.4: {}
+
+  load-tsconfig@0.2.5: {}
+
+  locate-path@3.0.0:
+    dependencies:
+      p-locate: 3.0.0
+      path-exists: 3.0.0
+
+  lodash.sortby@4.7.0: {}
+
+  loose-envify@1.4.0:
+    dependencies:
+      js-tokens: 4.0.0
+
+  loupe@3.2.1: {}
+
+  lower-case@2.0.2:
+    dependencies:
+      tslib: 2.8.1
+
+  lru-cache@11.5.1: {}
+
+  magic-string@0.30.21:
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  mdn-data@2.27.1: {}
+
+  memize@2.1.1: {}
+
+  merge-stream@2.0.0: {}
+
+  merge2@1.4.1: {}
+
+  micromatch@4.0.8:
+    dependencies:
+      braces: 3.0.3
+      picomatch: 2.3.2
+
+  mimic-fn@2.1.0: {}
+
+  mimic-fn@4.0.0: {}
+
+  moment-timezone@0.5.48:
+    dependencies:
+      moment: 2.30.1
+
+  moment@2.30.1: {}
+
+  motion-dom@11.18.1:
+    dependencies:
+      motion-utils: 11.18.1
+
+  motion-utils@11.18.1: {}
+
+  mousetrap@1.6.5: {}
+
+  ms@2.1.3: {}
+
+  mz@2.7.0:
+    dependencies:
+      any-promise: 1.3.0
+      object-assign: 4.1.1
+      thenify-all: 1.6.0
+
+  nanoid@3.3.15: {}
+
+  no-case@3.0.4:
+    dependencies:
+      lower-case: 2.0.2
+      tslib: 2.8.1
+
+  normalize-path@3.0.0: {}
+
+  normalize-wheel@1.0.1: {}
+
+  npm-run-path@4.0.1:
+    dependencies:
+      path-key: 3.1.1
+
+  npm-run-path@5.3.0:
+    dependencies:
+      path-key: 4.0.0
+
+  nth-check@2.1.1:
+    dependencies:
+      boolbase: 1.0.0
+
+  object-assign@4.1.1: {}
+
+  onetime@5.1.2:
+    dependencies:
+      mimic-fn: 2.1.0
+
+  onetime@6.0.0:
+    dependencies:
+      mimic-fn: 4.0.0
+
+  p-limit@2.3.0:
+    dependencies:
+      p-try: 2.2.0
+
+  p-locate@3.0.0:
+    dependencies:
+      p-limit: 2.3.0
+
+  p-try@2.2.0: {}
+
+  param-case@3.0.4:
+    dependencies:
+      dot-case: 3.0.4
+      tslib: 2.8.1
+
+  parent-module@1.0.1:
+    dependencies:
+      callsites: 3.1.0
+
+  parse-json@5.2.0:
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      error-ex: 1.3.4
+      json-parse-even-better-errors: 2.3.1
+      lines-and-columns: 1.2.4
+
+  parse5-htmlparser2-tree-adapter@7.1.0:
+    dependencies:
+      domhandler: 5.0.3
+      parse5: 7.3.0
+
+  parse5-parser-stream@7.1.2:
+    dependencies:
+      parse5: 7.3.0
+
+  parse5@7.3.0:
+    dependencies:
+      entities: 6.0.1
+
+  parse5@8.0.1:
+    dependencies:
+      entities: 8.0.0
+
+  parsel-js@1.2.2: {}
+
+  pascal-case@3.1.2:
+    dependencies:
+      no-case: 3.0.4
+      tslib: 2.8.1
+
+  path-case@3.0.4:
+    dependencies:
+      dot-case: 3.0.4
+      tslib: 2.8.1
+
+  path-exists@3.0.0: {}
+
+  path-key@3.1.1: {}
+
+  path-key@4.0.0: {}
+
+  path-parse@1.0.7: {}
+
+  path-to-regexp@6.3.0: {}
+
+  path-type@4.0.0: {}
+
+  pathe@1.1.2: {}
+
+  pathval@2.0.1: {}
+
+  picocolors@1.1.1: {}
+
+  picomatch@2.3.2: {}
+
+  picomatch@4.0.4: {}
+
+  pirates@4.0.7: {}
+
+  postcss-load-config@4.0.2(postcss@8.5.15):
+    dependencies:
+      lilconfig: 3.1.3
+      yaml: 2.9.0
+    optionalDependencies:
+      postcss: 8.5.15
+
+  postcss-prefix-selector@1.16.1(postcss@8.5.15):
+    dependencies:
+      postcss: 8.5.15
+
+  postcss-urlrebase@1.4.0(postcss@8.5.15):
+    dependencies:
+      postcss: 8.5.15
+      postcss-value-parser: 4.2.0
+
+  postcss-value-parser@4.2.0: {}
+
+  postcss@8.5.15:
+    dependencies:
+      nanoid: 3.3.15
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
+  preact@10.29.2: {}
+
+  pretty-format@29.7.0:
+    dependencies:
+      '@jest/schemas': 29.6.3
+      ansi-styles: 5.2.0
+      react-is: 18.3.1
+
+  prop-types@15.8.1:
+    dependencies:
+      loose-envify: 1.4.0
+      object-assign: 4.1.1
+      react-is: 16.13.1
+
+  punycode@2.3.1: {}
+
+  queue-microtask@1.2.3: {}
+
+  re-resizable@6.11.2(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
+  react-autosize-textarea@7.1.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+    dependencies:
+      autosize: 4.0.4
+      line-height: 0.3.1
+      prop-types: 15.8.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
+  react-colorful@5.7.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
+  react-day-picker@9.14.0(react@18.3.1):
+    dependencies:
+      '@date-fns/tz': 1.5.0
+      '@tabby_ai/hijri-converter': 1.0.5
+      date-fns: 4.4.0
+      date-fns-jalali: 4.1.0-0
+      react: 18.3.1
+
+  react-dom@18.3.1(react@18.3.1):
+    dependencies:
+      loose-envify: 1.4.0
+      react: 18.3.1
+      scheduler: 0.23.2
+
+  react-easy-crop@5.5.7(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+    dependencies:
+      normalize-wheel: 1.0.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      tslib: 2.8.1
+
+  react-is@16.13.1: {}
+
+  react-is@18.3.1: {}
+
+  react-property@2.0.2: {}
+
+  react-remove-scroll-bar@2.3.8(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      react-style-singleton: 2.2.3(@types/react@18.3.31)(react@18.3.1)
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  react-remove-scroll@2.7.2(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      react-remove-scroll-bar: 2.3.8(@types/react@18.3.31)(react@18.3.1)
+      react-style-singleton: 2.2.3(@types/react@18.3.31)(react@18.3.1)
+      tslib: 2.8.1
+      use-callback-ref: 1.3.3(@types/react@18.3.31)(react@18.3.1)
+      use-sidecar: 1.1.3(@types/react@18.3.31)(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  react-style-singleton@2.2.3(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      get-nonce: 1.0.1
+      react: 18.3.1
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  react@18.3.1:
+    dependencies:
+      loose-envify: 1.4.0
+
+  readdirp@3.6.0:
+    dependencies:
+      picomatch: 2.3.2
+
+  redux@5.0.1: {}
+
+  rememo@4.0.2: {}
+
+  remove-accents@0.5.0: {}
+
+  requestidlecallback@0.3.0: {}
+
+  require-directory@2.1.1: {}
+
+  require-from-string@2.0.2: {}
+
+  require-main-filename@2.0.0: {}
+
+  reselect@5.2.0: {}
+
+  resolve-from@4.0.0: {}
+
+  resolve-from@5.0.0: {}
+
+  resolve@1.22.12:
+    dependencies:
+      es-errors: 1.3.0
+      is-core-module: 2.16.2
+      path-parse: 1.0.7
+      supports-preserve-symlinks-flag: 1.0.0
+
+  reusify@1.1.0: {}
+
+  rollup@4.62.2:
+    dependencies:
+      '@types/estree': 1.0.9
+    optionalDependencies:
+      '@rollup/rollup-android-arm-eabi': 4.62.2
+      '@rollup/rollup-android-arm64': 4.62.2
+      '@rollup/rollup-darwin-arm64': 4.62.2
+      '@rollup/rollup-darwin-x64': 4.62.2
+      '@rollup/rollup-freebsd-arm64': 4.62.2
+      '@rollup/rollup-freebsd-x64': 4.62.2
+      '@rollup/rollup-linux-arm-gnueabihf': 4.62.2
+      '@rollup/rollup-linux-arm-musleabihf': 4.62.2
+      '@rollup/rollup-linux-arm64-gnu': 4.62.2
+      '@rollup/rollup-linux-arm64-musl': 4.62.2
+      '@rollup/rollup-linux-loong64-gnu': 4.62.2
+      '@rollup/rollup-linux-loong64-musl': 4.62.2
+      '@rollup/rollup-linux-ppc64-gnu': 4.62.2
+      '@rollup/rollup-linux-ppc64-musl': 4.62.2
+      '@rollup/rollup-linux-riscv64-gnu': 4.62.2
+      '@rollup/rollup-linux-riscv64-musl': 4.62.2
+      '@rollup/rollup-linux-s390x-gnu': 4.62.2
+      '@rollup/rollup-linux-x64-gnu': 4.62.2
+      '@rollup/rollup-linux-x64-musl': 4.62.2
+      '@rollup/rollup-openbsd-x64': 4.62.2
+      '@rollup/rollup-openharmony-arm64': 4.62.2
+      '@rollup/rollup-win32-arm64-msvc': 4.62.2
+      '@rollup/rollup-win32-ia32-msvc': 4.62.2
+      '@rollup/rollup-win32-x64-gnu': 4.62.2
+      '@rollup/rollup-win32-x64-msvc': 4.62.2
+      fsevents: 2.3.3
+
+  run-parallel@1.2.0:
+    dependencies:
+      queue-microtask: 1.2.3
+
+  rungen@0.3.2: {}
+
+  safe-buffer@5.2.1: {}
+
+  safer-buffer@2.1.2: {}
+
+  saxes@6.0.0:
+    dependencies:
+      xmlchars: 2.2.0
+
+  scheduler@0.23.2:
+    dependencies:
+      loose-envify: 1.4.0
+
+  sentence-case@3.0.4:
+    dependencies:
+      no-case: 3.0.4
+      tslib: 2.8.1
+      upper-case-first: 2.0.2
+
+  set-blocking@2.0.0: {}
+
+  shebang-command@2.0.0:
+    dependencies:
+      shebang-regex: 3.0.0
+
+  shebang-regex@3.0.0: {}
+
+  showdown@1.9.1:
+    dependencies:
+      yargs: 14.2.3
+
+  siginfo@2.0.0: {}
+
+  signal-exit@3.0.7: {}
+
+  signal-exit@4.1.0: {}
+
+  simple-html-tokenizer@0.5.11: {}
+
+  slash@3.0.0: {}
+
+  snake-case@3.0.4:
+    dependencies:
+      dot-case: 3.0.4
+      tslib: 2.8.1
+
+  source-map-js@1.2.1: {}
+
+  source-map@0.5.7: {}
+
+  source-map@0.8.0-beta.0:
+    dependencies:
+      whatwg-url: 7.1.0
+
+  stackback@0.0.2: {}
+
+  std-env@3.10.0: {}
+
+  string-width@3.1.0:
+    dependencies:
+      emoji-regex: 7.0.3
+      is-fullwidth-code-point: 2.0.0
+      strip-ansi: 5.2.0
+
+  strip-ansi@5.2.0:
+    dependencies:
+      ansi-regex: 4.1.1
+
+  strip-final-newline@2.0.0: {}
+
+  strip-final-newline@3.0.0: {}
+
+  style-to-js@1.1.21:
+    dependencies:
+      style-to-object: 1.0.14
+
+  style-to-object@1.0.14:
+    dependencies:
+      inline-style-parser: 0.2.7
+
+  stylis@4.2.0: {}
+
+  sucrase@3.35.1:
+    dependencies:
+      '@jridgewell/gen-mapping': 0.3.13
+      commander: 4.1.1
+      lines-and-columns: 1.2.4
+      mz: 2.7.0
+      pirates: 4.0.7
+      tinyglobby: 0.2.17
+      ts-interface-checker: 0.1.13
+
+  supports-preserve-symlinks-flag@1.0.0: {}
+
+  symbol-tree@3.2.4: {}
+
+  tabbable@6.5.0: {}
+
+  tannin@1.2.0:
+    dependencies:
+      '@tannin/plural-forms': 1.1.0
+
+  temml@0.10.34: {}
+
+  thenify-all@1.6.0:
+    dependencies:
+      thenify: 3.3.1
+
+  thenify@3.3.1:
+    dependencies:
+      any-promise: 1.3.0
+
+  tinybench@2.9.0: {}
+
+  tinyglobby@0.2.17:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
+
+  tinypool@1.1.1: {}
+
+  tinyspy@3.0.2: {}
+
+  tldts-core@7.4.3: {}
+
+  tldts@7.4.3:
+    dependencies:
+      tldts-core: 7.4.3
+
+  to-regex-range@5.0.1:
+    dependencies:
+      is-number: 7.0.0
+
+  tough-cookie@6.0.1:
+    dependencies:
+      tldts: 7.4.3
+
+  tr46@1.0.1:
+    dependencies:
+      punycode: 2.3.1
+
+  tr46@6.0.0:
+    dependencies:
+      punycode: 2.3.1
+
+  tree-kill@1.2.2: {}
+
+  ts-interface-checker@0.1.13: {}
+
+  tslib@2.8.1: {}
+
+  tsup@8.0.0(postcss@8.5.15)(typescript@5.7.3):
+    dependencies:
+      bundle-require: 4.2.1(esbuild@0.19.12)
+      cac: 6.7.14
+      chokidar: 3.6.0
+      debug: 4.4.3
+      esbuild: 0.19.12
+      execa: 5.1.1
+      globby: 11.1.0
+      joycon: 3.1.1
+      postcss-load-config: 4.0.2(postcss@8.5.15)
+      resolve-from: 5.0.0
+      rollup: 4.62.2
+      source-map: 0.8.0-beta.0
+      sucrase: 3.35.1
+      tree-kill: 1.2.2
+    optionalDependencies:
+      postcss: 8.5.15
+      typescript: 5.7.3
+    transitivePeerDependencies:
+      - supports-color
+      - ts-node
+
+  typescript@5.7.3: {}
+
+  undici@7.28.0: {}
+
+  upper-case-first@2.0.2:
+    dependencies:
+      tslib: 2.8.1
+
+  upper-case@2.0.2:
+    dependencies:
+      tslib: 2.8.1
+
+  use-callback-ref@1.3.3(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  use-memo-one@1.1.3(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+
+  use-sidecar@1.1.3(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      detect-node-es: 1.1.0
+      react: 18.3.1
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  use-sync-external-store@1.6.0(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+
+  uuid@14.0.1: {}
+
+  uuid@9.0.1: {}
+
+  vite-node@2.0.0:
+    dependencies:
+      cac: 6.7.14
+      debug: 4.4.3
+      pathe: 1.1.2
+      picocolors: 1.1.1
+      vite: 5.4.21
+    transitivePeerDependencies:
+      - '@types/node'
+      - less
+      - lightningcss
+      - sass
+      - sass-embedded
+      - stylus
+      - sugarss
+      - supports-color
+      - terser
+
+  vite@5.4.21:
+    dependencies:
+      esbuild: 0.21.5
+      postcss: 8.5.15
+      rollup: 4.62.2
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  vitest@2.0.0(jsdom@29.0.1):
+    dependencies:
+      '@ampproject/remapping': 2.3.0
+      '@vitest/expect': 2.0.0
+      '@vitest/runner': 2.0.0
+      '@vitest/snapshot': 2.0.0
+      '@vitest/spy': 2.0.0
+      '@vitest/utils': 2.0.0
+      chai: 5.3.3
+      debug: 4.4.3
+      execa: 8.0.1
+      magic-string: 0.30.21
+      pathe: 1.1.2
+      picocolors: 1.1.1
+      std-env: 3.10.0
+      tinybench: 2.9.0
+      tinypool: 1.1.1
+      vite: 5.4.21
+      vite-node: 2.0.0
+      why-is-node-running: 2.3.0
+    optionalDependencies:
+      jsdom: 29.0.1
+    transitivePeerDependencies:
+      - less
+      - lightningcss
+      - sass
+      - sass-embedded
+      - stylus
+      - sugarss
+      - supports-color
+      - terser
+
+  w3c-xmlserializer@5.0.0:
+    dependencies:
+      xml-name-validator: 5.0.0
+
+  wasm-vips@0.0.16: {}
+
+  wasm-vips@0.0.17: {}
+
+  webidl-conversions@4.0.2: {}
+
+  webidl-conversions@8.0.1: {}
+
+  whatwg-encoding@3.1.1:
+    dependencies:
+      iconv-lite: 0.6.3
+
+  whatwg-mimetype@4.0.0: {}
+
+  whatwg-mimetype@5.0.0: {}
+
+  whatwg-url@16.0.1:
+    dependencies:
+      '@exodus/bytes': 1.15.1
+      tr46: 6.0.0
+      webidl-conversions: 8.0.1
+    transitivePeerDependencies:
+      - '@noble/hashes'
+
+  whatwg-url@7.1.0:
+    dependencies:
+      lodash.sortby: 4.7.0
+      tr46: 1.0.1
+      webidl-conversions: 4.0.2
+
+  which-module@2.0.1: {}
+
+  which@2.0.2:
+    dependencies:
+      isexe: 2.0.0
+
+  why-is-node-running@2.3.0:
+    dependencies:
+      siginfo: 2.0.0
+      stackback: 0.0.2
+
+  wrap-ansi@5.1.0:
+    dependencies:
+      ansi-styles: 3.2.1
+      string-width: 3.1.0
+      strip-ansi: 5.2.0
+
+  xml-name-validator@5.0.0: {}
+
+  xmlchars@2.2.0: {}
+
+  y-protocols@1.0.7(yjs@13.6.31):
+    dependencies:
+      lib0: 0.2.117
+      yjs: 13.6.31
+
+  y18n@4.0.3: {}
+
+  yaml@1.10.3: {}
+
+  yaml@2.9.0: {}
+
+  yargs-parser@15.0.3:
+    dependencies:
+      camelcase: 5.3.1
+      decamelize: 1.2.0
+
+  yargs@14.2.3:
+    dependencies:
+      cliui: 5.0.0
+      decamelize: 1.2.0
+      find-up: 3.0.0
+      get-caller-file: 2.0.5
+      require-directory: 2.1.1
+      require-main-filename: 2.0.0
+      set-blocking: 2.0.0
+      string-width: 3.1.0
+      which-module: 2.0.1
+      y18n: 4.0.3
+      yargs-parser: 15.0.3
+
+  yjs@13.6.31:
+    dependencies:
+      lib0: 0.2.117
diff --git a/packages/blocks-engine/src/__tests__/version-lock.test.ts b/packages/blocks-engine/src/__tests__/version-lock.test.ts
new file mode 100644
index 00000000..683bdd22
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/version-lock.test.ts
@@ -0,0 +1,10 @@
+import { describe, it, expect } from 'vitest';
+import wpBlocksPkg from '@wordpress/blocks/package.json' with { type: 'json' };
+import jsdomPkg from 'jsdom/package.json' with { type: 'json' };
+
+describe('dependency version lock (fidelity guard)', () => {
+  it('resolves the exact pinned @wordpress/blocks + jsdom', () => {
+    expect(wpBlocksPkg.version).toBe('15.15.0');
+    expect(jsdomPkg.version).toBe('29.0.1');
+  });
+});
diff --git a/packages/blocks-engine/src/index.ts b/packages/blocks-engine/src/index.ts
new file mode 100644
index 00000000..a530279e
--- /dev/null
+++ b/packages/blocks-engine/src/index.ts
@@ -0,0 +1,3 @@
+// @automattic/blocks-engine
+// Engine entry point — implementation added by subsequent tasks (D phase).
+export {};
diff --git a/packages/blocks-engine/tsconfig.json b/packages/blocks-engine/tsconfig.json
new file mode 100644
index 00000000..ee46c990
--- /dev/null
+++ b/packages/blocks-engine/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/blocks-engine/tsup.config.ts b/packages/blocks-engine/tsup.config.ts
new file mode 100644
index 00000000..79f123ba
--- /dev/null
+++ b/packages/blocks-engine/tsup.config.ts
@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  // Note: src/wp/index.ts + src/wp/worker-child.ts entries are added by later tasks (B/C phases)
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+});
diff --git a/packages/blocks-engine/vitest.config.ts b/packages/blocks-engine/vitest.config.ts
new file mode 100644
index 00000000..2dcea8c5
--- /dev/null
+++ b/packages/blocks-engine/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: false,
+    environment: 'node',
+  },
+});

From a8819d81eb3becc991ec4eeacb15fca197453c83 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 15:58:39 -0400
Subject: [PATCH 002/113] test(blocks-engine): freeze DLA golden fixture
 contract

---
 .../blocks-engine/src/__fixtures__/cases.json | 168 ++++++++++++++++++
 1 file changed, 168 insertions(+)
 create mode 100644 packages/blocks-engine/src/__fixtures__/cases.json

diff --git a/packages/blocks-engine/src/__fixtures__/cases.json b/packages/blocks-engine/src/__fixtures__/cases.json
new file mode 100644
index 00000000..bab4edac
--- /dev/null
+++ b/packages/blocks-engine/src/__fixtures__/cases.json
@@ -0,0 +1,168 @@
+[
+  {
+    "id": "raw.smoke-heading-paragraph-table",
+    "op": "rawConvert",
+    "input": "<main><div class=\"wp-block-group\"><h2 class=\"wp-block-heading\">Widget Catalog</h2><p>Three fictional widgets for testing.</p><figure class=\"wp-block-table\"><table><thead><tr><th>Name</th><th>Use</th></tr></thead><tbody><tr><td>Sprocket</td><td>spins</td></tr></tbody></table></figure></div></main>",
+    "expected": {
+      "html": "<!-- wp:heading {\"className\":\"wp-block-heading\"} -->\n<h2 class=\"wp-block-heading\">Widget Catalog</h2>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph -->\n<p>Three fictional widgets for testing.</p>\n<!-- /wp:paragraph -->\n\n<!-- wp:table -->\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th>Name</th><th>Use</th></tr></thead><tbody><tr><td>Sprocket</td><td>spins</td></tr></tbody></table></figure>\n<!-- /wp:table -->",
+      "wpHtmlResidue": 0
+    }
+  },
+  {
+    "id": "raw.smoke-spacer-height",
+    "op": "rawConvert",
+    "input": "<div class=\"wp-block-spacer\" style=\"height:48px\"></div><p>After.</p>",
+    "expected": {
+      "html": "<!-- wp:spacer {\"height\":\"48px\"} -->\n<div style=\"height:48px\" aria-hidden=\"true\" class=\"wp-block-spacer\"></div>\n<!-- /wp:spacer -->\n\n<!-- wp:paragraph -->\n<p>After.</p>\n<!-- /wp:paragraph -->",
+      "wpHtmlResidue": 0
+    }
+  },
+  {
+    "id": "raw.smoke-post-meta-strip",
+    "op": "rawConvert",
+    "input": "<main><h1 class=\"wp-block-post-title\">A Quiet Honor</h1><div class=\"wp-block-template-part\"><div class=\"wp-block-post-date\"><time datetime=\"2024-11-11\">Nov 11, 2024</time></div></div><div class=\"wp-block-post-author-name\"><a class=\"wp-block-post-author-name__link\" href=\"/author/poet\">Poet</a></div><p>They leave without fanfare, packing pieces of themselves.</p><div class=\"wp-block-post-terms\"><span class=\"wp-block-post-terms__prefix\">Tags: </span><a href=\"/tag/x\" rel=\"tag\">Sentimental</a></div><a class=\"wp-block-post-navigation-link\" href=\"/prev\"><span class=\"wp-block-post-navigation-link__arrow-previous\">Previous</span>Previous</a></main>",
+    "expected": {
+      "html": "<!-- wp:paragraph -->\n<p>They leave without fanfare, packing pieces of themselves.</p>\n<!-- /wp:paragraph -->",
+      "wpHtmlResidue": 0
+    }
+  },
+  {
+    "id": "raw.sample-wix-div-soup",
+    "op": "rawConvert",
+    "input": "<div id=\"SITE_PAGES\"><div data-mesh-id=\"comp-heroinlineContent\" class=\"wixui-section\"><div data-testid=\"richTextElement\"><h2>Handmade planters</h2><p>Small-batch ceramics for bright windows.</p></div><div class=\"wixui-button\"><a href=\"/shop\">Shop the drop</a></div></div></div>",
+    "expected": {
+      "html": "<!-- wp:html -->\n<div id=\"SITE_PAGES\"><div data-mesh-id=\"comp-heroinlineContent\" class=\"wixui-section\"><div data-testid=\"richTextElement\"><h2>Handmade planters</h2><p>Small-batch ceramics for bright windows.</p></div><div class=\"wixui-button\"><a href=\"/shop\">Shop the drop</a></div></div></div>\n<!-- /wp:html -->",
+      "wpHtmlResidue": 1
+    }
+  },
+  {
+    "id": "raw.sample-squarespace-sqs-block",
+    "op": "rawConvert",
+    "input": "<section class=\"Index-page\"><div class=\"sqs-layout\"><div class=\"sqs-block html-block sqs-block-html\"><div class=\"sqs-block-content\"><h2>Studio notes</h2><p>Glazes are mixed every Friday.</p></div></div></div></section>",
+    "expected": {
+      "html": "<!-- wp:html -->\n<section class=\"Index-page\"><div class=\"sqs-layout\"><div class=\"sqs-block html-block sqs-block-html\"><div class=\"sqs-block-content\"><h2>Studio notes</h2><p>Glazes are mixed every Friday.</p></div></div></div></section>\n<!-- /wp:html -->",
+      "wpHtmlResidue": 1
+    }
+  },
+  {
+    "id": "raw.sample-semantic-section",
+    "op": "rawConvert",
+    "input": "<section><h2>Our process</h2><p>We sketch, throw, glaze, and fire each piece in-house.</p></section>",
+    "expected": {
+      "html": "<!-- wp:html -->\n<section><h2>Our process</h2><p>We sketch, throw, glaze, and fire each piece in-house.</p></section>\n<!-- /wp:html -->",
+      "wpHtmlResidue": 1
+    }
+  },
+  {
+    "id": "canonicalize.smoke-simple-paragraph",
+    "op": "canonicalize",
+    "input": "<!-- wp:paragraph --><p>Hello world</p><!-- /wp:paragraph -->",
+    "expected": {
+      "html": "<!-- wp:paragraph -->\n<p>Hello world</p>\n<!-- /wp:paragraph -->",
+      "changed": true,
+      "fixedIssues": []
+    }
+  },
+  {
+    "id": "canonicalize.smoke-nested-paragraph",
+    "op": "canonicalize",
+    "input": "<!-- wp:paragraph --><p class=\"outer\"><p class=\"inner\">Nested</p></p><!-- /wp:paragraph -->",
+    "expected": {
+      "html": "<!-- wp:paragraph {\"className\":\"outer inner\"} -->\n<p class=\"outer inner\">Nested</p>\n<!-- /wp:paragraph -->",
+      "changed": true,
+      "fixedIssues": [
+        "core/paragraph: Nested paragraph tags detected and removed"
+      ]
+    }
+  },
+  {
+    "id": "canonicalize.smoke-heading-paragraph-composition",
+    "op": "canonicalize",
+    "input": "<!-- wp:heading {\"level\":1} --><h1>Title</h1><!-- /wp:heading -->\n<!-- wp:paragraph --><p>Body text.</p><!-- /wp:paragraph -->",
+    "expected": {
+      "html": "<!-- wp:heading {\"level\":1} -->\n<h1 class=\"wp-block-heading\">Title</h1>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph -->\n<p>Body text.</p>\n<!-- /wp:paragraph -->",
+      "changed": true,
+      "fixedIssues": []
+    }
+  },
+  {
+    "id": "canonicalize.unknown-jetpack-contact-form-minimal",
+    "op": "canonicalize",
+    "input": "<!-- wp:jetpack/contact-form -->x<!-- /wp:jetpack/contact-form -->",
+    "expected": {
+      "html": "<!-- wp:jetpack/contact-form -->\nx\n<!-- /wp:jetpack/contact-form -->",
+      "changed": true,
+      "fixedIssues": []
+    }
+  },
+  {
+    "id": "canonicalize.unknown-jetpack-contact-form-full",
+    "op": "canonicalize",
+    "input": "<!-- wp:jetpack/contact-form {\"style\":{\"spacing\":{\"padding\":{\"top\":\"16px\",\"right\":\"16px\",\"bottom\":\"16px\",\"left\":\"16px\"}}}} -->\n<div class=\"wp-block-jetpack-contact-form\">\n<!-- wp:jetpack/field-name {\"label\":\"Full name\",\"required\":true,\"width\":50} /-->\n<!-- wp:jetpack/field-email {\"label\":\"Email address\",\"required\":true,\"width\":50} /-->\n<!-- wp:button {\"tagName\":\"button\",\"type\":\"submit\",\"lock\":{\"remove\":true},\"className\":\"form-button-submit is-submit\",\"metadata\":{\"name\":\"Submit button\"}} -->\n<div class=\"wp-block-button form-button-submit is-submit\"><button type=\"submit\" class=\"wp-block-button__link wp-element-button\">Send Message</button></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:jetpack/contact-form -->",
+    "expected": {
+      "html": "<!-- wp:jetpack/contact-form {\"style\":{\"spacing\":{\"padding\":{\"top\":\"16px\",\"right\":\"16px\",\"bottom\":\"16px\",\"left\":\"16px\"}}}} -->\n<div class=\"wp-block-jetpack-contact-form\">\n<!-- wp:jetpack/field-name {\"label\":\"Full name\",\"required\":true,\"width\":50} /-->\n<!-- wp:jetpack/field-email {\"label\":\"Email address\",\"required\":true,\"width\":50} /-->\n<!-- wp:button {\"tagName\":\"button\",\"type\":\"submit\",\"lock\":{\"remove\":true},\"className\":\"form-button-submit is-submit\",\"metadata\":{\"name\":\"Submit button\"}} -->\n<div class=\"wp-block-button form-button-submit is-submit\"><button type=\"submit\" class=\"wp-block-button__link wp-element-button\">Send Message</button></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:jetpack/contact-form -->",
+      "changed": false,
+      "fixedIssues": []
+    }
+  },
+  {
+    "id": "compose.generic-details",
+    "op": "compose",
+    "input": "<details><summary>Q</summary><p>A</p></details>",
+    "expected": "<!-- wp:details -->\n<details class=\"wp-block-details\"><summary>Q</summary><p>A</p></details>\n<!-- /wp:details -->"
+  },
+  {
+    "id": "compose.generic-callout",
+    "op": "compose",
+    "input": "<div class=\"callout\"><h3>Note</h3><p>body</p></div>",
+    "expected": "<!-- wp:group {\"className\":\"wp-block-group is-style-callout\",\"layout\":{\"type\":\"constrained\"}} -->\n<div class=\"wp-block-group is-style-callout\"><h3>Note</h3><p>body</p></div>\n<!-- /wp:group -->"
+  },
+  {
+    "id": "compose.generic-pullquote",
+    "op": "compose",
+    "input": "<blockquote class=\"pullquote\"><p>Big idea</p><cite>Me</cite></blockquote>",
+    "expected": "<!-- wp:pullquote -->\n<figure class=\"wp-block-pullquote\"><blockquote><p>Big idea</p><cite>Me</cite></blockquote></figure>\n<!-- /wp:pullquote -->"
+  },
+  {
+    "id": "compose.generic-buttons",
+    "op": "compose",
+    "input": "<div class=\"btn-group\"><a class=\"button\" href=\"/x\">Go</a><a class=\"btn\" href=\"/y\">More</a></div>",
+    "expected": "<!-- wp:buttons -->\n<div class=\"wp-block-buttons\">\n<!-- wp:button -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link wp-element-button\" href=\"/x\">Go</a></div>\n<!-- /wp:button -->\n<!-- wp:button -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link wp-element-button\" href=\"/y\">More</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->"
+  },
+  {
+    "id": "compose.generic-media-text",
+    "op": "compose",
+    "input": "<div class=\"media-text\"><figure><img src=\"https://cdn.test/a.jpg\" alt=\"A\"/></figure><div><h3>Title</h3><p>copy</p></div></div>",
+    "expected": "<!-- wp:media-text {\"mediaType\":\"image\"} -->\n<div class=\"wp-block-media-text is-stacked-on-mobile\"><figure class=\"wp-block-media-text__media\"><img src=\"https://cdn.test/a.jpg\" alt=\"A\"/></figure><div class=\"wp-block-media-text__content\"><h3>Title</h3><p>copy</p></div></div>\n<!-- /wp:media-text -->"
+  },
+  {
+    "id": "compose.sample-youtube-iframe",
+    "op": "compose",
+    "input": "<figure class=\"video\"><iframe src=\"https://www.youtube.com/embed/abc123\"></iframe></figure>",
+    "expected": "<!-- wp:embed {\"url\":\"https://www.youtube.com/embed/abc123\",\"type\":\"video\",\"providerNameSlug\":\"youtube\",\"responsive\":true} -->\n<figure class=\"wp-block-embed is-provider-youtube wp-block-embed-youtube wp-embed-aspect-16-9 wp-has-aspect-ratio\"><div class=\"wp-block-embed__wrapper\">\nhttps://www.youtube.com/embed/abc123\n</div></figure>\n<!-- /wp:embed -->"
+  },
+  {
+    "id": "compose.sample-callout-div",
+    "op": "compose",
+    "input": "<div class=\"notice callout\"><h3>Shipping pause</h3><p>Orders resume Monday.</p></div>",
+    "expected": "<!-- wp:group {\"className\":\"wp-block-group is-style-notice\",\"layout\":{\"type\":\"constrained\"}} -->\n<div class=\"wp-block-group is-style-notice\"><h3>Shipping pause</h3><p>Orders resume Monday.</p></div>\n<!-- /wp:group -->"
+  },
+  {
+    "id": "compose.sample-semantic-section-fallback",
+    "op": "compose",
+    "input": "<section><h2>Our process</h2><p>We sketch, throw, glaze, and fire each piece in-house.</p></section>",
+    "expected": "<!-- wp:html {\"metadata\":{\"name\":\"lib-coverage-island\"}} -->\n<section><h2>Our process</h2><p>We sketch, throw, glaze, and fire each piece in-house.</p></section>\n<!-- /wp:html -->"
+  },
+  {
+    "id": "compose.sample-wix-div-soup-fallback",
+    "op": "compose",
+    "input": "<div id=\"SITE_PAGES\"><div data-mesh-id=\"comp-heroinlineContent\" class=\"wixui-section\"><div data-testid=\"richTextElement\"><h2>Handmade planters</h2><p>Small-batch ceramics for bright windows.</p></div><div class=\"wixui-button\"><a href=\"/shop\">Shop the drop</a></div></div></div>",
+    "expected": "<!-- wp:html {\"metadata\":{\"name\":\"lib-coverage-island\"}} -->\n<div id=\"SITE_PAGES\"><div data-mesh-id=\"comp-heroinlineContent\" class=\"wixui-section\"><div data-testid=\"richTextElement\"><h2>Handmade planters</h2><p>Small-batch ceramics for bright windows.</p></div><div class=\"wixui-button\"><a href=\"/shop\">Shop the drop</a></div></div></div>\n<!-- /wp:html -->"
+  },
+  {
+    "id": "compose.sample-squarespace-sqs-block-fallback",
+    "op": "compose",
+    "input": "<section class=\"Index-page\"><div class=\"sqs-layout\"><div class=\"sqs-block html-block sqs-block-html\"><div class=\"sqs-block-content\"><h2>Studio notes</h2><p>Glazes are mixed every Friday.</p></div></div></div></section>",
+    "expected": "<!-- wp:html {\"metadata\":{\"name\":\"lib-coverage-island\"}} -->\n<section class=\"Index-page\"><div class=\"sqs-layout\"><div class=\"sqs-block html-block sqs-block-html\"><div class=\"sqs-block-content\"><h2>Studio notes</h2><p>Glazes are mixed every Friday.</p></div></div></div></section>\n<!-- /wp:html -->"
+  }
+]

From 628baf916b49710206cc775e41682c6ba7dac104 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 16:01:58 -0400
Subject: [PATCH 003/113] test(blocks-engine): capture golden fixtures from
 current DLA output

---
 .../scripts/capture-fixtures.mjs              | 317 ++++++++++++++++++
 .../src/__tests__/fixtures-present.test.ts    |  23 ++
 2 files changed, 340 insertions(+)
 create mode 100644 packages/blocks-engine/scripts/capture-fixtures.mjs
 create mode 100644 packages/blocks-engine/src/__tests__/fixtures-present.test.ts

diff --git a/packages/blocks-engine/scripts/capture-fixtures.mjs b/packages/blocks-engine/scripts/capture-fixtures.mjs
new file mode 100644
index 00000000..d0c69189
--- /dev/null
+++ b/packages/blocks-engine/scripts/capture-fixtures.mjs
@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const DLA_ROOT = process.env.DLA_ROOT ?? '/Users/matt/projects/a8c/data-liberation-agent';
+const BLOCK_FIXER_DIR = path.join(DLA_ROOT, 'scripts/block-fixer');
+const THIS_DIR = path.dirname(fileURLToPath(import.meta.url));
+const CASES_PATH = path.resolve(THIS_DIR, '../src/__fixtures__/cases.json');
+
+const RAW_CASES = [
+  {
+    id: 'raw.smoke-heading-paragraph-table',
+    input:
+      '<main><div class="wp-block-group"><h2 class="wp-block-heading">Widget Catalog</h2>' +
+      '<p>Three fictional widgets for testing.</p>' +
+      '<figure class="wp-block-table"><table><thead><tr><th>Name</th><th>Use</th></tr></thead>' +
+      '<tbody><tr><td>Sprocket</td><td>spins</td></tr></tbody></table></figure></div></main>',
+  },
+  {
+    id: 'raw.smoke-spacer-height',
+    input: '<div class="wp-block-spacer" style="height:48px"></div><p>After.</p>',
+  },
+  {
+    id: 'raw.smoke-post-meta-strip',
+    input:
+      '<main><h1 class="wp-block-post-title">A Quiet Honor</h1>' +
+      '<div class="wp-block-template-part"><div class="wp-block-post-date"><time datetime="2024-11-11">Nov 11, 2024</time></div></div>' +
+      '<div class="wp-block-post-author-name"><a class="wp-block-post-author-name__link" href="/author/poet">Poet</a></div>' +
+      '<p>They leave without fanfare, packing pieces of themselves.</p>' +
+      '<div class="wp-block-post-terms"><span class="wp-block-post-terms__prefix">Tags: </span><a href="/tag/x" rel="tag">Sentimental</a></div>' +
+      '<a class="wp-block-post-navigation-link" href="/prev"><span class="wp-block-post-navigation-link__arrow-previous">Previous</span>Previous</a></main>',
+  },
+  {
+    id: 'raw.sample-wix-div-soup',
+    input:
+      '<div id="SITE_PAGES"><div data-mesh-id="comp-heroinlineContent" class="wixui-section">' +
+      '<div data-testid="richTextElement"><h2>Handmade planters</h2><p>Small-batch ceramics for bright windows.</p></div>' +
+      '<div class="wixui-button"><a href="/shop">Shop the drop</a></div></div></div>',
+  },
+  {
+    id: 'raw.sample-squarespace-sqs-block',
+    input:
+      '<section class="Index-page"><div class="sqs-layout"><div class="sqs-block html-block sqs-block-html">' +
+      '<div class="sqs-block-content"><h2>Studio notes</h2><p>Glazes are mixed every Friday.</p></div></div></div></section>',
+  },
+  {
+    id: 'raw.sample-semantic-section',
+    input: '<section><h2>Our process</h2><p>We sketch, throw, glaze, and fire each piece in-house.</p></section>',
+  },
+];
+
+const CANONICALIZE_CASES = [
+  {
+    id: 'canonicalize.smoke-simple-paragraph',
+    input: '<!-- wp:paragraph --><p>Hello world</p><!-- /wp:paragraph -->',
+  },
+  {
+    id: 'canonicalize.smoke-nested-paragraph',
+    input: '<!-- wp:paragraph --><p class="outer"><p class="inner">Nested</p></p><!-- /wp:paragraph -->',
+  },
+  {
+    id: 'canonicalize.smoke-heading-paragraph-composition',
+    input:
+      '<!-- wp:heading {"level":1} --><h1>Title</h1><!-- /wp:heading -->\n' +
+      '<!-- wp:paragraph --><p>Body text.</p><!-- /wp:paragraph -->',
+  },
+  {
+    id: 'canonicalize.unknown-jetpack-contact-form-minimal',
+    input: '<!-- wp:jetpack/contact-form -->x<!-- /wp:jetpack/contact-form -->',
+  },
+  {
+    id: 'canonicalize.unknown-jetpack-contact-form-full',
+    input:
+      '<!-- wp:jetpack/contact-form {"style":{"spacing":{"padding":{"top":"16px","right":"16px","bottom":"16px","left":"16px"}}}} -->\n' +
+      '<div class="wp-block-jetpack-contact-form">\n' +
+      '<!-- wp:jetpack/field-name {"label":"Full name","required":true,"width":50} /-->\n' +
+      '<!-- wp:jetpack/field-email {"label":"Email address","required":true,"width":50} /-->\n' +
+      '<!-- wp:button {"tagName":"button","type":"submit","lock":{"remove":true},"className":"form-button-submit is-submit","metadata":{"name":"Submit button"}} -->\n' +
+      '<div class="wp-block-button form-button-submit is-submit"><button type="submit" class="wp-block-button__link wp-element-button">Send Message</button></div>\n' +
+      '<!-- /wp:button -->\n' +
+      '</div>\n' +
+      '<!-- /wp:jetpack/contact-form -->',
+  },
+];
+
+const COMPOSE_CASES = [
+  {
+    id: 'compose.generic-details',
+    input: '<details><summary>Q</summary><p>A</p></details>',
+  },
+  {
+    id: 'compose.generic-callout',
+    input: '<div class="callout"><h3>Note</h3><p>body</p></div>',
+  },
+  {
+    id: 'compose.generic-pullquote',
+    input: '<blockquote class="pullquote"><p>Big idea</p><cite>Me</cite></blockquote>',
+  },
+  {
+    id: 'compose.generic-buttons',
+    input: '<div class="btn-group"><a class="button" href="/x">Go</a><a class="btn" href="/y">More</a></div>',
+  },
+  {
+    id: 'compose.generic-media-text',
+    input:
+      '<div class="media-text"><figure><img src="https://cdn.test/a.jpg" alt="A"/></figure>' +
+      '<div><h3>Title</h3><p>copy</p></div></div>',
+  },
+  {
+    id: 'compose.sample-youtube-iframe',
+    input: '<figure class="video"><iframe src="https://www.youtube.com/embed/abc123"></iframe></figure>',
+  },
+  {
+    id: 'compose.sample-callout-div',
+    input: '<div class="notice callout"><h3>Shipping pause</h3><p>Orders resume Monday.</p></div>',
+  },
+  {
+    id: 'compose.sample-semantic-section-fallback',
+    input: '<section><h2>Our process</h2><p>We sketch, throw, glaze, and fire each piece in-house.</p></section>',
+  },
+  {
+    id: 'compose.sample-wix-div-soup-fallback',
+    input:
+      '<div id="SITE_PAGES"><div data-mesh-id="comp-heroinlineContent" class="wixui-section">' +
+      '<div data-testid="richTextElement"><h2>Handmade planters</h2><p>Small-batch ceramics for bright windows.</p></div>' +
+      '<div class="wixui-button"><a href="/shop">Shop the drop</a></div></div></div>',
+  },
+  {
+    id: 'compose.sample-squarespace-sqs-block-fallback',
+    input:
+      '<section class="Index-page"><div class="sqs-layout"><div class="sqs-block html-block sqs-block-html">' +
+      '<div class="sqs-block-content"><h2>Studio notes</h2><p>Glazes are mixed every Friday.</p></div></div></div></section>',
+  },
+];
+
+function setupWordPressGlobals() {
+  const requireFromHere = createRequire(import.meta.url);
+  const { JSDOM } = requireFromHere(path.join(BLOCK_FIXER_DIR, 'node_modules/jsdom'));
+  const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', {
+    url: 'http://localhost',
+    pretendToBeVisual: true,
+  });
+  for (const key of [
+    'window',
+    'document',
+    'DOMParser',
+    'XMLSerializer',
+    'Node',
+    'Element',
+    'HTMLElement',
+    'getComputedStyle',
+    'MutationObserver',
+  ]) {
+    globalThis[key] = dom.window[key];
+  }
+  globalThis.requestAnimationFrame = (callback) => setTimeout(callback, 16);
+  globalThis.cancelAnimationFrame = (id) => clearTimeout(id);
+  globalThis.matchMedia = () => ({
+    matches: false,
+    addListener() {},
+    removeListener() {},
+    addEventListener() {},
+    removeEventListener() {},
+  });
+  globalThis.ResizeObserver = class ResizeObserver {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  };
+  Object.defineProperty(globalThis, 'navigator', {
+    value: dom.window.navigator,
+    writable: true,
+    configurable: true,
+  });
+}
+
+function withQuietConsole(fn) {
+  const originalError = console.error;
+  const originalWarn = console.warn;
+  const originalLog = console.log;
+  const originalStderrWrite = process.stderr.write;
+  const originalStdoutWrite = process.stdout.write;
+  console.error = () => {};
+  console.warn = () => {};
+  console.log = () => {};
+  process.stderr.write = () => true;
+  process.stdout.write = () => true;
+  try {
+    return fn();
+  } finally {
+    console.error = originalError;
+    console.warn = originalWarn;
+    console.log = originalLog;
+    process.stderr.write = originalStderrWrite;
+    process.stdout.write = originalStdoutWrite;
+  }
+}
+
+async function loadDlaFunctions() {
+  setupWordPressGlobals();
+  const requireFromHere = createRequire(import.meta.url);
+  const { convertHtmlToBlocks, fixBlocksInTemplate } = withQuietConsole(() => ({
+    ...requireFromHere(path.join(BLOCK_FIXER_DIR, 'lib/rawConvert.js')),
+    ...requireFromHere(path.join(BLOCK_FIXER_DIR, 'lib/blockFixer.js')),
+  }));
+  try {
+    const { applyBlockRecipe } = await import(
+      pathToFileURL(path.join(DLA_ROOT, 'src/lib/replicate/apply-block-recipe.ts')).href
+    );
+    const { buildHtmlFallbackBlock } = await import(
+      pathToFileURL(path.join(DLA_ROOT, 'src/lib/replicate/html-fallback.ts')).href
+    );
+    return { convertHtmlToBlocks, fixBlocksInTemplate, applyBlockRecipe, buildHtmlFallbackBlock };
+  } catch (error) {
+    throw new Error(
+      `Unable to import DLA TypeScript modules. Run with DLA tsx, for example: cd ${DLA_ROOT} && ./node_modules/.bin/tsx ${fileURLToPath(import.meta.url)} --check\n${error.message}`,
+    );
+  }
+}
+
+function normalizeRawResult(result) {
+  assert.equal(typeof result, 'object');
+  assert.equal(typeof result.html, 'string');
+  assert.equal(typeof result.wpHtmlResidue, 'number');
+  assert.equal(Number.isFinite(result.wpHtmlResidue), true);
+  return {
+    html: result.html,
+    wpHtmlResidue: result.wpHtmlResidue,
+  };
+}
+
+function normalizeFixResult(result) {
+  assert.equal(typeof result, 'object');
+  assert.equal(typeof result.html, 'string');
+  assert.equal(typeof result.changed, 'boolean');
+  assert.equal(Array.isArray(result.fixedIssues), true);
+  assert.equal(result.fixedIssues.every((issue) => typeof issue === 'string'), true);
+  return {
+    html: result.html,
+    changed: result.changed,
+    fixedIssues: result.fixedIssues,
+  };
+}
+
+function composeWithFallback(input, applyBlockRecipe, buildHtmlFallbackBlock) {
+  const ctx = { url: 'https://fixtures.example/source' };
+  return applyBlockRecipe(input, undefined, ctx) ?? buildHtmlFallbackBlock(input, {});
+}
+
+async function captureCases() {
+  const { convertHtmlToBlocks, fixBlocksInTemplate, applyBlockRecipe, buildHtmlFallbackBlock } = await loadDlaFunctions();
+  const cases = [];
+
+  for (const { id, input } of RAW_CASES) {
+    cases.push({
+      id,
+      op: 'rawConvert',
+      input,
+      expected: withQuietConsole(() => normalizeRawResult(convertHtmlToBlocks(input))),
+    });
+  }
+
+  for (const { id, input } of CANONICALIZE_CASES) {
+    cases.push({
+      id,
+      op: 'canonicalize',
+      input,
+      expected: withQuietConsole(() => normalizeFixResult(fixBlocksInTemplate(input))),
+    });
+  }
+
+  for (const { id, input } of COMPOSE_CASES) {
+    cases.push({
+      id,
+      op: 'compose',
+      input,
+      expected: withQuietConsole(() => composeWithFallback(input, applyBlockRecipe, buildHtmlFallbackBlock)),
+    });
+  }
+
+  return cases;
+}
+
+function serializeCases(cases) {
+  return `${JSON.stringify(cases, null, 2)}\n`;
+}
+
+async function main() {
+  const mode = process.argv[2] ?? '--write';
+  const cases = await captureCases();
+  const serialized = serializeCases(cases);
+
+  if (mode === '--write') {
+    await writeFile(CASES_PATH, serialized);
+    console.log(`WROTE ${path.relative(process.cwd(), CASES_PATH)} (${cases.length} cases)`);
+    return;
+  }
+
+  if (mode === '--check') {
+    const existing = await readFile(CASES_PATH, 'utf8');
+    assert.equal(serialized, existing);
+    console.log(`PASS capture deterministic (${cases.length} cases)`);
+    return;
+  }
+
+  if (mode === '--stdout') {
+    process.stdout.write(serialized);
+    return;
+  }
+
+  throw new Error(`Unknown mode ${mode}. Use --write, --check, or --stdout.`);
+}
+
+await main();
diff --git a/packages/blocks-engine/src/__tests__/fixtures-present.test.ts b/packages/blocks-engine/src/__tests__/fixtures-present.test.ts
new file mode 100644
index 00000000..ae2508ab
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/fixtures-present.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import cases from '../__fixtures__/cases.json' with { type: 'json' };
+
+const OPS = ['rawConvert', 'canonicalize', 'compose'] as const;
+
+describe('golden fixtures', () => {
+  it('includes at least one populated case for each pinned operation', () => {
+    expect(Array.isArray(cases)).toBe(true);
+
+    for (const op of OPS) {
+      expect(cases.some((fixture) => fixture.op === op)).toBe(true);
+    }
+
+    for (const fixture of cases) {
+      expect(typeof fixture.id).toBe('string');
+      expect(fixture.id.length).toBeGreaterThan(0);
+      expect(OPS).toContain(fixture.op);
+      expect(typeof fixture.input).toBe('string');
+      expect(fixture.input.length).toBeGreaterThan(0);
+      expect(fixture.expected).toBeDefined();
+    }
+  });
+});

From 87ad8590dd88b87141496c479b375e30f305f0cb Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 17:38:54 -0400
Subject: [PATCH 004/113] test(blocks-engine): freeze /wp public contract

---
 .../src/__tests__/bootstrap.test.ts           | 15 ++++++++
 .../__tests__/canonicalize.fixture.test.ts    | 22 +++++++++++
 .../canonicalize.unknown-block.test.ts        | 12 ++++++
 .../src/__tests__/raw-convert.fixture.test.ts | 22 +++++++++++
 .../src/__tests__/wp-entry.test.ts            | 37 +++++++++++++++++++
 5 files changed, 108 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/bootstrap.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/canonicalize.fixture.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/canonicalize.unknown-block.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/raw-convert.fixture.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/wp-entry.test.ts

diff --git a/packages/blocks-engine/src/__tests__/bootstrap.test.ts b/packages/blocks-engine/src/__tests__/bootstrap.test.ts
new file mode 100644
index 00000000..de8ca49e
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/bootstrap.test.ts
@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { __resetBootstrapForTest, bootstrap } from '../wp/bootstrap';
+
+describe('bootstrap', () => {
+  it('is idempotent and installs DOM globals', () => {
+    __resetBootstrapForTest();
+
+    expect(() => {
+      bootstrap();
+      bootstrap();
+      bootstrap();
+    }).not.toThrow();
+    expect(globalThis.document).toBeDefined();
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/canonicalize.fixture.test.ts b/packages/blocks-engine/src/__tests__/canonicalize.fixture.test.ts
new file mode 100644
index 00000000..a5b4ff74
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/canonicalize.fixture.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import cases from '../__fixtures__/cases.json' with { type: 'json' };
+import { canonicalize } from '../wp/canonicalize';
+
+type CanonicalizeFixture = {
+  id: string;
+  op: 'canonicalize';
+  input: string;
+  expected: { html: string; changed: boolean; fixedIssues: string[] };
+};
+
+const canonicalizeCases = (cases as CanonicalizeFixture[]).filter(
+  (fixture) => fixture.op === 'canonicalize',
+);
+
+describe('canonicalize golden fixtures', () => {
+  for (const fixture of canonicalizeCases) {
+    it(`${fixture.id} is byte-identical to the DLA golden`, () => {
+      expect(canonicalize(fixture.input)).toEqual(fixture.expected);
+    });
+  }
+});
diff --git a/packages/blocks-engine/src/__tests__/canonicalize.unknown-block.test.ts b/packages/blocks-engine/src/__tests__/canonicalize.unknown-block.test.ts
new file mode 100644
index 00000000..80815126
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/canonicalize.unknown-block.test.ts
@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { canonicalize } from '../wp/canonicalize';
+
+describe('canonicalize unknown blocks', () => {
+  it('preserves unknown jetpack block delimiters', () => {
+    const result = canonicalize(
+      '<!-- wp:jetpack/contact-form -->x<!-- /wp:jetpack/contact-form -->',
+    );
+
+    expect(result.html).toContain('wp:jetpack/contact-form');
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/raw-convert.fixture.test.ts b/packages/blocks-engine/src/__tests__/raw-convert.fixture.test.ts
new file mode 100644
index 00000000..5ba9c61f
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/raw-convert.fixture.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import cases from '../__fixtures__/cases.json' with { type: 'json' };
+import { rawConvert } from '../wp/raw-convert';
+
+type RawConvertFixture = {
+  id: string;
+  op: 'rawConvert';
+  input: string;
+  expected: { html: string | null; wpHtmlResidue: number };
+};
+
+const rawConvertCases = (cases as RawConvertFixture[]).filter(
+  (fixture) => fixture.op === 'rawConvert',
+);
+
+describe('rawConvert golden fixtures', () => {
+  for (const fixture of rawConvertCases) {
+    it(`${fixture.id} is byte-identical to the DLA golden`, () => {
+      expect(rawConvert(fixture.input)).toEqual(fixture.expected);
+    });
+  }
+});
diff --git a/packages/blocks-engine/src/__tests__/wp-entry.test.ts b/packages/blocks-engine/src/__tests__/wp-entry.test.ts
new file mode 100644
index 00000000..0e4a58f6
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/wp-entry.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import cases from '../__fixtures__/cases.json' with { type: 'json' };
+import { bootstrap, canonicalize, convert, rawConvert } from '../wp';
+
+type Fixture = {
+  id: string;
+  op: 'rawConvert' | 'canonicalize' | 'compose';
+  input: string;
+  expected: unknown;
+};
+
+const fixtures = cases as Fixture[];
+
+function fixtureFor(op: 'rawConvert' | 'canonicalize'): Fixture {
+  const fixture = fixtures.find((candidate) => candidate.op === op);
+  if (!fixture) {
+    throw new Error(`Missing ${op} fixture`);
+  }
+  return fixture;
+}
+
+describe('/wp entry', () => {
+  it('exports the frozen public surface', () => {
+    expect(typeof rawConvert).toBe('function');
+    expect(typeof canonicalize).toBe('function');
+    expect(typeof bootstrap).toBe('function');
+    expect(typeof convert).toBe('function');
+  });
+
+  it('resolves rawConvert and canonicalize in-process', () => {
+    const rawFixture = fixtureFor('rawConvert');
+    const canonicalizeFixture = fixtureFor('canonicalize');
+
+    expect(rawConvert(rawFixture.input)).toEqual(rawFixture.expected);
+    expect(canonicalize(canonicalizeFixture.input)).toEqual(canonicalizeFixture.expected);
+  });
+});

From 32cb41e1f3bcbbdb01f58074e603cb7f28d83f0e Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 17:58:24 -0400
Subject: [PATCH 005/113] feat(blocks-engine): port WP-backed /wp operations

---
 packages/blocks-engine/src/node-module.d.ts   |   9 +
 packages/blocks-engine/src/wp/bootstrap.ts    | 119 +++++
 packages/blocks-engine/src/wp/canonicalize.ts | 436 ++++++++++++++++++
 packages/blocks-engine/src/wp/index.ts        |  15 +
 packages/blocks-engine/src/wp/raw-convert.ts  | 152 ++++++
 packages/blocks-engine/tsconfig.json          |   4 +-
 packages/blocks-engine/tsup.config.ts         |   4 +-
 7 files changed, 735 insertions(+), 4 deletions(-)
 create mode 100644 packages/blocks-engine/src/node-module.d.ts
 create mode 100644 packages/blocks-engine/src/wp/bootstrap.ts
 create mode 100644 packages/blocks-engine/src/wp/canonicalize.ts
 create mode 100644 packages/blocks-engine/src/wp/index.ts
 create mode 100644 packages/blocks-engine/src/wp/raw-convert.ts

diff --git a/packages/blocks-engine/src/node-module.d.ts b/packages/blocks-engine/src/node-module.d.ts
new file mode 100644
index 00000000..c19ab469
--- /dev/null
+++ b/packages/blocks-engine/src/node-module.d.ts
@@ -0,0 +1,9 @@
+declare module 'node:module' {
+  export interface NodeRequire {
+    (id: string): unknown;
+  }
+
+  export function createRequire(filename: string): NodeRequire;
+}
+
+declare const __filename: string | undefined;
diff --git a/packages/blocks-engine/src/wp/bootstrap.ts b/packages/blocks-engine/src/wp/bootstrap.ts
new file mode 100644
index 00000000..575c64fe
--- /dev/null
+++ b/packages/blocks-engine/src/wp/bootstrap.ts
@@ -0,0 +1,119 @@
+import { createRequire } from 'node:module';
+
+type JSDOMConstructor = new (
+  html?: string,
+  options?: { pretendToBeVisual?: boolean; url?: string },
+) => BootstrapDom;
+
+type JSDOMModule = {
+  JSDOM: JSDOMConstructor;
+};
+
+type BlockLibraryModule = {
+  registerCoreBlocks: () => void;
+};
+
+type BootstrapWindow = Window &
+  typeof globalThis & {
+    close: () => void;
+  };
+
+type BootstrapDom = {
+  window: BootstrapWindow;
+};
+
+type DomGlobalTarget = typeof globalThis & {
+  window: Window & typeof globalThis;
+  document: Document;
+  DOMParser: typeof DOMParser;
+  XMLSerializer: typeof XMLSerializer;
+  Node: typeof Node;
+  Element: typeof Element;
+  HTMLElement: typeof HTMLElement;
+  getComputedStyle: typeof getComputedStyle;
+  MutationObserver: typeof MutationObserver;
+  requestAnimationFrame: typeof requestAnimationFrame;
+  cancelAnimationFrame: typeof cancelAnimationFrame;
+  matchMedia: typeof matchMedia;
+  ResizeObserver: typeof ResizeObserver;
+  navigator: Navigator;
+};
+
+const requireFromHere = createRequire(
+  typeof __filename === 'string' ? __filename : import.meta.url,
+);
+
+let dom: BootstrapDom | undefined;
+let ready = false;
+
+function installDomGlobals(nextDom: BootstrapDom): void {
+  const { window } = nextDom;
+  const target = globalThis as DomGlobalTarget;
+
+  target.window = window;
+  target.document = window.document;
+  target.DOMParser = window.DOMParser;
+  target.XMLSerializer = window.XMLSerializer;
+  target.Node = window.Node;
+  target.Element = window.Element;
+  target.HTMLElement = window.HTMLElement;
+  target.getComputedStyle = window.getComputedStyle;
+  target.MutationObserver = window.MutationObserver;
+  target.requestAnimationFrame = ((callback) =>
+    setTimeout(() => {
+      callback(Date.now());
+    }, 16) as unknown as number) as typeof requestAnimationFrame;
+  target.cancelAnimationFrame = ((id) => {
+    clearTimeout(id as unknown as ReturnType<typeof setTimeout>);
+  }) as typeof cancelAnimationFrame;
+  target.matchMedia = (() => ({
+    matches: false,
+    addListener() {},
+    removeListener() {},
+    addEventListener() {},
+    removeEventListener() {},
+  })) as unknown as typeof matchMedia;
+  target.ResizeObserver = class ResizeObserver {
+    observe(): void {}
+    unobserve(): void {}
+    disconnect(): void {}
+  } as typeof ResizeObserver;
+
+  Object.defineProperty(target, 'navigator', {
+    value: window.navigator,
+    writable: true,
+    configurable: true,
+  });
+}
+
+export function bootstrap(): void {
+  if (ready) {
+    return;
+  }
+
+  const { JSDOM } = requireFromHere('jsdom') as JSDOMModule;
+  dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', {
+    url: 'http://localhost',
+    pretendToBeVisual: true,
+  });
+
+  installDomGlobals(dom);
+
+  try {
+    const { registerCoreBlocks } = requireFromHere(
+      '@wordpress/block-library',
+    ) as BlockLibraryModule;
+    registerCoreBlocks();
+    ready = true;
+  } catch (error) {
+    dom.window.close();
+    dom = undefined;
+    throw error;
+  }
+}
+
+export function __resetBootstrapForTest(): void {
+  ready = false;
+  dom?.window.close();
+  dom = undefined;
+}
diff --git a/packages/blocks-engine/src/wp/canonicalize.ts b/packages/blocks-engine/src/wp/canonicalize.ts
new file mode 100644
index 00000000..97e2d152
--- /dev/null
+++ b/packages/blocks-engine/src/wp/canonicalize.ts
@@ -0,0 +1,436 @@
+import { createRequire } from 'node:module';
+
+import { bootstrap } from './bootstrap';
+
+export type CanonicalizeResult = {
+  html: string;
+  changed: boolean;
+  fixedIssues: string[];
+};
+
+type BlockAttributes = Record<string, unknown>;
+
+type ValidationIssue =
+  | string
+  | {
+      message?: unknown;
+      args?: unknown[];
+    };
+
+type ParsedBlock = {
+  name?: string | null;
+  attributes: BlockAttributes;
+  innerBlocks?: ParsedBlock[];
+  isValid?: boolean;
+  validationIssues?: ValidationIssue[];
+  originalContent?: string;
+  __unstableBlockSource?: {
+    attrs?: BlockAttributes;
+  };
+};
+
+type RawBlock = {
+  blockName?: string | null;
+  attrs?: BlockAttributes | null;
+  innerBlocks?: RawBlock[];
+  innerHTML?: string;
+};
+
+type WordpressBlocks = {
+  parse: (html: string) => ParsedBlock[];
+  serialize: (blocks: ParsedBlock[]) => string;
+  createBlock: (
+    name: string,
+    attributes?: BlockAttributes,
+    innerBlocks?: ParsedBlock[],
+  ) => ParsedBlock;
+  getBlockAttributes: (
+    name: string,
+    sourceHtml: string,
+    rawAttrs: BlockAttributes,
+  ) => BlockAttributes;
+};
+
+type BlockSerializationParser = {
+  parse: (html: string) => RawBlock[];
+};
+
+type WordpressRuntime = WordpressBlocks & {
+  parseBlockGrammar: (html: string) => RawBlock[];
+};
+
+const requireWordPress = createRequire(
+  typeof __filename === 'string' ? __filename : import.meta.url,
+);
+let wordpressRuntime: WordpressRuntime | undefined;
+
+function loadWordPress(): WordpressRuntime {
+  bootstrap();
+
+  if (wordpressRuntime) {
+    return wordpressRuntime;
+  }
+
+  const {
+    parse,
+    serialize,
+    createBlock,
+    getBlockAttributes,
+  } = requireWordPress('@wordpress/blocks') as WordpressBlocks;
+  const { parse: parseBlockGrammar } = requireWordPress(
+    '@wordpress/block-serialization-default-parser',
+  ) as BlockSerializationParser;
+
+  wordpressRuntime = {
+    parse,
+    serialize,
+    createBlock,
+    getBlockAttributes,
+    parseBlockGrammar,
+  };
+
+  return wordpressRuntime;
+}
+
+function parseAttributes(attrString: string | undefined): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  if (!attrString) return attrs;
+
+  const doubleQuotePattern = /(\S+)="([^"]*)"/g;
+  let match;
+  while ((match = doubleQuotePattern.exec(attrString)) !== null) {
+    attrs[match[1]] = match[2];
+  }
+
+  const singleQuotePattern = /(\S+)='([^']*)'/g;
+  while ((match = singleQuotePattern.exec(attrString)) !== null) {
+    if (!(match[1] in attrs)) {
+      attrs[match[1]] = match[2];
+    }
+  }
+
+  return attrs;
+}
+
+function mergeAttributes(
+  outerAttrs: string | undefined,
+  innerAttrs: string | undefined,
+): Record<string, string> {
+  const outer = parseAttributes(outerAttrs);
+  const inner = parseAttributes(innerAttrs);
+  const merged = { ...outer };
+
+  for (const [key, value] of Object.entries(inner)) {
+    if (key === 'class') {
+      const outerClasses = (outer.class || '').split(/\s+/).filter(Boolean);
+      const innerClasses = value.split(/\s+/).filter(Boolean);
+      const allClasses = [...new Set([...outerClasses, ...innerClasses])];
+      merged.class = allClasses.join(' ');
+    } else if (key === 'style') {
+      const outerStyles = (outer.style || '').split(';').filter(Boolean);
+      const innerStyles = value.split(';').filter(Boolean);
+
+      const styleMap: Record<string, string> = {};
+      for (const style of [...outerStyles, ...innerStyles]) {
+        const colonIdx = style.indexOf(':');
+        if (colonIdx > 0) {
+          const prop = style.substring(0, colonIdx).trim();
+          const val = style.substring(colonIdx + 1).trim();
+          styleMap[prop] = val;
+        }
+      }
+
+      merged.style = Object.entries(styleMap)
+        .map(([prop, val]) => `${prop}:${val}`)
+        .join(';');
+    } else if (!(key in outer)) {
+      merged[key] = value;
+    }
+  }
+
+  return merged;
+}
+
+function serializeAttributes(attrs: Record<string, string>): string {
+  const parts = [];
+  for (const [key, value] of Object.entries(attrs)) {
+    parts.push(`${key}="${value}"`);
+  }
+  return parts.length > 0 ? ' ' + parts.join(' ') : '';
+}
+
+function fixNestedParagraphs(htmlContent: string): string {
+  if (!htmlContent.includes('<!-- wp:paragraph')) {
+    return htmlContent;
+  }
+
+  const wpParagraphBlockPattern =
+    /(<!-- wp:paragraph[^>]*-->)([\s\S]*?)(<!-- \/wp:paragraph -->)/g;
+  const nestedPPattern =
+    /<p(\s[^>]*)?>(\s*)<p(\s[^>]*)?>([^]*?)<\/p>(\s*)<\/p>/gi;
+
+  let result = htmlContent;
+  let totalFixCount = 0;
+
+  result = result.replace(
+    wpParagraphBlockPattern,
+    (
+      _fullMatch: string,
+      openComment: string,
+      blockContent: string,
+      closeComment: string,
+    ) => {
+      let fixedContent = blockContent;
+      let prevContent;
+      let blockFixCount = 0;
+
+      do {
+        prevContent = fixedContent;
+        fixedContent = fixedContent.replace(
+          nestedPPattern,
+          (
+            _match: string,
+            outerAttrs: string | undefined,
+            _ws1: string,
+            innerAttrs: string | undefined,
+            innerContent: string,
+            _ws2: string,
+          ) => {
+            blockFixCount++;
+            const mergedAttrs = mergeAttributes(outerAttrs, innerAttrs);
+            const attrString = serializeAttributes(mergedAttrs);
+            return `<p${attrString}>${innerContent}</p>`;
+          },
+        );
+      } while (fixedContent !== prevContent);
+
+      totalFixCount += blockFixCount;
+      return `${openComment}${fixedContent}${closeComment}`;
+    },
+  );
+
+  if (totalFixCount > 0) {
+    console.error(
+      `[ParagraphFixer] Fixed ${totalFixCount} nested <p> tag(s) in WordPress paragraph blocks`,
+    );
+  }
+
+  return result;
+}
+
+// Did parse() alter or drop any attribute the document's comment delimiter
+// declared? Comment attrs are plain JSON, so stringify equality is exact.
+function commentAttrsAltered(
+  parsedAttrs: BlockAttributes,
+  rawAttrs: BlockAttributes,
+): boolean {
+  return Object.keys(rawAttrs).some(
+    (key) => JSON.stringify(parsedAttrs[key]) !== JSON.stringify(rawAttrs[key]),
+  );
+}
+
+//
+// Comment-delimiter attrs are authoritative (this mirrors what WordPress
+// persists for the block). parse() can silently lose them on two paths:
+//
+//   1. Invalid blocks: built-in "validation fixes" (fixCustomClassname /
+//      ariaLabel / anchor) re-derive those attrs from the STALE inner HTML -
+//      deleting author-intent values that only exist in the comment attrs
+//      (e.g. a hoisted "is-style-lib-*" className whose inner HTML still
+//      carries the pre-hoist inline styles).
+//   2. Deprecation hijack: an eligible deprecated version (core/paragraph)
+//      can "successfully migrate" the block - marking it VALID while eating
+//      comment attrs absent from the deprecated schema (className,
+//      fontFamily) and swallowing the whole outer markup into `content`.
+//
+// `rawBlock` is this block's counterpart from the grammar-level parser
+// (verbatim comment attrs, untouched by either path). When parse() altered
+// any declared attr, re-derive the attribute set from the original inner
+// HTML + raw comment attrs via getBlockAttributes() - the same call
+// parse() itself makes BEFORE validation fixes / deprecations run. Sourced
+// attributes (content etc.) never appear in comment attrs, so author intent
+// can't clobber them; createBlock() drops keys unknown to the current schema.
+//
+function fixBlockRecursively(
+  block: ParsedBlock,
+  rawBlock: RawBlock | undefined,
+  getBlockAttributes: WordpressBlocks['getBlockAttributes'],
+  createBlock: WordpressBlocks['createBlock'],
+): { block: ParsedBlock; wasFixed: boolean } {
+  const fixedInnerBlocks = [];
+
+  if (block.innerBlocks && block.innerBlocks.length > 0) {
+    const rawInner = (rawBlock && rawBlock.innerBlocks) || [];
+    let rawIndex = 0;
+    for (const innerBlock of block.innerBlocks) {
+      // Align the raw pointer: parse() drops raw nodes that produce no block
+      // (whitespace-only freeform, unregistered types), so pair strictly by
+      // block name and skip raw nodes that have no parsed counterpart. If
+      // alignment is lost we simply stop pairing - same behavior as before.
+      while (
+        rawIndex < rawInner.length &&
+        rawInner[rawIndex].blockName !== innerBlock.name
+      ) {
+        rawIndex++;
+      }
+      const rawInnerBlock =
+        rawIndex < rawInner.length ? rawInner[rawIndex++] : undefined;
+      const result = fixBlockRecursively(
+        innerBlock,
+        rawInnerBlock,
+        getBlockAttributes,
+        createBlock,
+      );
+      fixedInnerBlocks.push(result.block);
+    }
+  }
+
+  if (!block.name) {
+    return { block, wasFixed: false };
+  }
+
+  let attributes = block.attributes;
+  const rawCommentAttrs =
+    (rawBlock && rawBlock.blockName === block.name && rawBlock.attrs) ||
+    (block.__unstableBlockSource && block.__unstableBlockSource.attrs) ||
+    null;
+  if (rawCommentAttrs && commentAttrsAltered(block.attributes, rawCommentAttrs)) {
+    const sourceHtml =
+      typeof block.originalContent === 'string'
+        ? block.originalContent
+        : (rawBlock && rawBlock.innerHTML) || '';
+    attributes = getBlockAttributes(block.name, sourceHtml, rawCommentAttrs);
+  }
+
+  const fixedBlock = createBlock(
+    block.name,
+    attributes,
+    fixedInnerBlocks.length > 0 ? fixedInnerBlocks : undefined,
+  );
+
+  return { block: fixedBlock, wasFixed: true };
+}
+
+function formatValidationIssue(issue: ValidationIssue): string {
+  if (typeof issue === 'string') {
+    return issue;
+  }
+
+  if (typeof issue.message === 'string') {
+    return issue.message;
+  }
+
+  if (Array.isArray(issue.args) && typeof issue.args[0] === 'string') {
+    const template = issue.args[0];
+    const values = issue.args.slice(1).map((value) => {
+      if (typeof value === 'string') return value;
+      if (Array.isArray(value) && value.every(Array.isArray)) {
+        return '[' + value.map((attr) => attr[0]).join(', ') + ']';
+      }
+      if (typeof value === 'object' && value !== null) return '{...}';
+      return String(value);
+    });
+    let msg = template;
+    values.forEach((value) => {
+      msg = msg.replace(/%[os]/, value);
+    });
+    return msg;
+  }
+
+  return JSON.stringify(issue);
+}
+
+function collectIssues(blockList: ParsedBlock[], fixedIssues: string[]): void {
+  for (const block of blockList) {
+    if (!block.isValid) {
+      const blockName = block.name || 'unknown';
+      const blockIssues = block.validationIssues || [];
+      if (blockIssues.length > 0) {
+        for (const issue of blockIssues) {
+          const msg = formatValidationIssue(issue);
+          fixedIssues.push(`${blockName}: ${msg}`);
+        }
+      } else {
+        fixedIssues.push(`${blockName}: Block marked as invalid`);
+      }
+    }
+    if (block.innerBlocks && block.innerBlocks.length > 0) {
+      collectIssues(block.innerBlocks, fixedIssues);
+    }
+  }
+}
+
+export function canonicalize(markup: string): CanonicalizeResult {
+  const {
+    parse,
+    serialize,
+    createBlock,
+    getBlockAttributes,
+    parseBlockGrammar,
+  } = loadWordPress();
+
+  try {
+    const preFixedContent = fixNestedParagraphs(markup);
+    const blocks = parse(preFixedContent);
+    // Grammar-level parse of the same content: verbatim comment attrs,
+    // untouched by validation fixes or deprecation migrations.
+    const rawBlocks = parseBlockGrammar(preFixedContent);
+
+    const fixedIssues: string[] = [];
+    collectIssues(blocks, fixedIssues);
+
+    let rawIndex = 0;
+    const fixedBlocks = blocks.map((block) => {
+      while (
+        rawIndex < rawBlocks.length &&
+        rawBlocks[rawIndex].blockName !== block.name
+      ) {
+        rawIndex++;
+      }
+      const rawBlock =
+        rawIndex < rawBlocks.length ? rawBlocks[rawIndex++] : undefined;
+      return fixBlockRecursively(
+        block,
+        rawBlock,
+        getBlockAttributes,
+        createBlock,
+      ).block;
+    });
+
+    let fixedHtml = serialize(fixedBlocks);
+
+    const beforeParaFix = fixedHtml;
+    fixedHtml = fixNestedParagraphs(fixedHtml);
+    if (preFixedContent !== markup || fixedHtml !== beforeParaFix) {
+      fixedIssues.push('core/paragraph: Nested paragraph tags detected and removed');
+    }
+
+    const wasChanged = fixedHtml !== preFixedContent;
+
+    if (fixedIssues.length > 0) {
+      console.error(`[BlockFixer] Found ${fixedIssues.length} invalid block(s)`);
+      for (const issue of fixedIssues) {
+        console.error(`  - ${issue}`);
+      }
+    }
+
+    if (wasChanged) {
+      console.error(
+        `[BlockFixer] HTML normalized (re-serialized ${blocks.length} block(s))`,
+      );
+    }
+
+    return {
+      html: fixedHtml,
+      changed: wasChanged,
+      fixedIssues,
+    };
+  } catch (error) {
+    console.error('[BlockFixer] Error fixing blocks:', error);
+    return {
+      html: markup,
+      changed: false,
+      fixedIssues: [],
+    };
+  }
+}
diff --git a/packages/blocks-engine/src/wp/index.ts b/packages/blocks-engine/src/wp/index.ts
new file mode 100644
index 00000000..603bdca8
--- /dev/null
+++ b/packages/blocks-engine/src/wp/index.ts
@@ -0,0 +1,15 @@
+import { canonicalize } from './canonicalize';
+import { rawConvert } from './raw-convert';
+
+export { bootstrap } from './bootstrap';
+export { canonicalize } from './canonicalize';
+export { rawConvert } from './raw-convert';
+
+export type ConvertContext = { url?: string };
+
+export function convert(html: string, ctx?: ConvertContext): string {
+  void ctx;
+  const raw = rawConvert(html);
+  // D6: insert compose() between rawConvert and canonicalize
+  return canonicalize(raw.html ?? '').html;
+}
diff --git a/packages/blocks-engine/src/wp/raw-convert.ts b/packages/blocks-engine/src/wp/raw-convert.ts
new file mode 100644
index 00000000..02dcd005
--- /dev/null
+++ b/packages/blocks-engine/src/wp/raw-convert.ts
@@ -0,0 +1,152 @@
+import { createRequire } from 'node:module';
+import { bootstrap } from './bootstrap';
+
+type JSDOMConstructor = new (html: string) => { window: { document: Document } };
+type RawHandler = (options: { HTML: string }) => unknown[];
+type Serialize = (blocks: unknown[]) => string;
+
+type Runtime = {
+  JSDOM: JSDOMConstructor;
+  rawHandler: RawHandler;
+  serialize: Serialize;
+};
+
+const require = createRequire(
+  typeof __filename === 'string' ? __filename : import.meta.url,
+);
+
+let runtime: Runtime | undefined;
+function loadRuntime(): Runtime {
+  if (!runtime) {
+    const { JSDOM } = require('jsdom') as { JSDOM: JSDOMConstructor };
+    const { rawHandler, serialize } = require('@wordpress/blocks') as {
+      rawHandler: RawHandler;
+      serialize: Serialize;
+    };
+    runtime = { JSDOM, rawHandler, serialize };
+  }
+  return runtime;
+}
+
+//
+// General HTML -> native blocks (rawHandler)
+// =========================================
+// WordPress's paste parser (`@wordpress/blocks` rawHandler) is the general,
+// semantic-tag-driven HTML->blocks engine -- it reads <h2>/<table>/<blockquote>
+// and emits core blocks regardless of source platform. It runs HERE (not in the
+// main process) only because @wordpress/blocks needs React 18 while the CLI
+// hoists React 19 from Ink -- they can't share a process (see block-fixer-client.ts).
+//
+// Three render-save normalizations precede the parse -- they fix HTML that any
+// RENDERED page carries, and do NOT read wp-block-* to decide block identity
+// (that's rawHandler's tag-driven job):
+//   1. Unwrap non-semantic layout/template wrappers -- else the whole section
+//      collapses into one wp:html.
+//   2. Unwrap figure.wp-block-table -> bare <table> -- the table transform's
+//      selector is 'table', so the figure wrapper matches nothing -> wp:html;
+//      the bare table -> clean wp:table.
+//   3. Native-emit spacers -- core/spacer has no raw transform, so a spacer div
+//      -> wp:html; we splice a real wp:spacer (source height) after serialize.
+//
+
+// TODO(D5): import shared UNWRAP_SELECTOR from ../raw-convertible
+const UNWRAP_SELECTOR =
+  'main, div.wp-block-group, div.wp-block-post-content, div.entry-content, div.wp-block-group__inner-container';
+
+function spacerBlock(height: string): string {
+  const h = height || '50px';
+  return `<!-- wp:spacer {"height":"${h}"} -->\n<div style="height:${h}" aria-hidden="true" class="wp-block-spacer"></div>\n<!-- /wp:spacer -->`;
+}
+
+// WordPress post-meta DYNAMIC blocks that rawHandler can't convert from rendered
+// HTML (they'd become wp:html residue) and that belong in the post TEMPLATE, not
+// post_content. A capture that bundled them into the content section (e.g. a poem
+// post carrying its title/date/author/tags/prev-next nav) is stripped here so the
+// real content converts native; the replica single.html renders this meta instead.
+// Keep in sync with the meta blocks emitted by buildSingleTemplate() in
+// src/lib/replicate/theme-scaffold.ts.
+const POST_META_CHROME =
+  '.wp-block-post-date, .wp-block-post-author, .wp-block-post-author-name, ' +
+  '.wp-block-post-author-biography, .wp-block-post-terms, .wp-block-post-navigation-link, ' +
+  '.wp-block-post-navigation, .wp-block-template-part, .wp-block-post-comments, .wp-block-comments, ' +
+  '.wp-block-post-excerpt, .wp-block-read-more';
+// Indicators that a section is a single-POST body (vs a page/home hero): the full
+// post-meta set. Used to gate the post-title strip -- post-title is duplicated meta
+// on a post (single.html renders it) but the load-bearing HERO HEADING on the home
+// front page (front-page.html renders no title), so it must only be stripped on posts.
+const POST_BODY_SIGNAL =
+  '.wp-block-post-date, .wp-block-post-author-name, .wp-block-post-terms, .wp-block-post-navigation-link';
+
+function preprocess(html: string): { html: string; spacers: string[] } {
+  const { JSDOM } = loadRuntime();
+  const d = new JSDOM(`<body>${html}</body>`).window.document.body;
+  // 0. Strip post-meta dynamic-block chrome -- it's template-level meta, not content,
+  //    and rawHandler can't convert it (-> wp:html residue). The replica single.html
+  //    renders this meta instead.
+  // 0a. Detect a single-post body BEFORE removing anything (the signal blocks get
+  //     stripped below, so the check must come first).
+  const isPostBody = !!d.querySelector(POST_BODY_SIGNAL);
+  // 0b. The prev/next post-navigation wrapper is a <nav> holding post-navigation-link
+  //     blocks. Target it precisely (a content <nav> -- should it ever appear -- survives).
+  for (const nav of [...d.querySelectorAll('nav')]) {
+    if (nav.querySelector('.wp-block-post-navigation-link')) nav.remove();
+  }
+  // 0c. post-title only on a post body (see POST_BODY_SIGNAL) -- never on the home hero.
+  if (isPostBody) for (const el of [...d.querySelectorAll('.wp-block-post-title')]) el.remove();
+  // 0d. The rest of the post-meta chrome (unambiguous on any context).
+  for (const el of [...d.querySelectorAll(POST_META_CHROME)]) el.remove();
+  // 1. Unwrap non-semantic wrappers, repeatedly, until stable (NOT spacers).
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const el of [...d.querySelectorAll(UNWRAP_SELECTOR)]) {
+      if (el.classList.contains('wp-block-spacer')) continue;
+      while (el.firstChild) el.parentNode!.insertBefore(el.firstChild, el);
+      el.remove();
+      changed = true;
+    }
+  }
+  // 2. Unwrap figure.wp-block-table -> bare <table>.
+  for (const fig of [...d.querySelectorAll('figure.wp-block-table')]) {
+    const table = fig.querySelector('table');
+    if (table) fig.parentNode!.replaceChild(table, fig);
+  }
+  // 3. Replace spacers with sentinel paragraphs spliced back post-serialize.
+  const spacers: string[] = [];
+  for (const sp of [...d.querySelectorAll('.wp-block-spacer')]) {
+    const m = (sp.getAttribute('style') || '').match(/height:\s*([0-9.]+px)/);
+    spacers.push(m ? m[1] : '50px');
+    const marker = d.ownerDocument.createElement('p');
+    marker.textContent = `@@SPACER_${spacers.length - 1}@@`;
+    sp.parentNode!.replaceChild(marker, sp);
+  }
+  return { html: d.innerHTML, spacers };
+}
+
+/**
+ * Convert one section's (already-sanitized) HTML into native block markup.
+ * Returns { html, wpHtmlResidue }. Never throws -- on parser error returns
+ * { html: '', wpHtmlResidue: Infinity } so the caller falls back.
+ */
+export function rawConvert(html: string): { html: string | null; wpHtmlResidue: number } {
+  bootstrap();
+  if (!html || !html.trim()) return { html: '', wpHtmlResidue: 0 };
+  try {
+    const { rawHandler, serialize } = loadRuntime();
+    const { html: preprocessedHtml, spacers } = preprocess(html);
+    let markup = serialize(rawHandler({ HTML: preprocessedHtml }));
+    markup = markup.replace(
+      /<!-- wp:paragraph -->\s*<p>@@SPACER_(\d+)@@<\/p>\s*<!-- \/wp:paragraph -->/g,
+      (_: string, i: string) => spacerBlock(spacers[+i]),
+    );
+    if (markup.includes('@@SPACER_')) {
+      console.error('[rawConvert] spacer sentinel survived serialization -- forcing fallback');
+      return { html: '', wpHtmlResidue: Infinity };
+    }
+    const wpHtmlResidue = (markup.match(/<!-- wp:html/g) || []).length;
+    return { html: markup, wpHtmlResidue };
+  } catch (e) {
+    console.error('[rawConvert] convert failed:', e && (e as { message?: unknown }).message);
+    return { html: '', wpHtmlResidue: Infinity };
+  }
+}
diff --git a/packages/blocks-engine/tsconfig.json b/packages/blocks-engine/tsconfig.json
index ee46c990..8ee6c0b7 100644
--- a/packages/blocks-engine/tsconfig.json
+++ b/packages/blocks-engine/tsconfig.json
@@ -1,8 +1,8 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
     "strict": true,
     "declaration": true,
     "declarationMap": true,
diff --git a/packages/blocks-engine/tsup.config.ts b/packages/blocks-engine/tsup.config.ts
index 79f123ba..b9aa4d17 100644
--- a/packages/blocks-engine/tsup.config.ts
+++ b/packages/blocks-engine/tsup.config.ts
@@ -1,8 +1,8 @@
 import { defineConfig } from 'tsup';
 
 export default defineConfig({
-  // Note: src/wp/index.ts + src/wp/worker-child.ts entries are added by later tasks (B/C phases)
-  entry: ['src/index.ts'],
+  // Note: src/wp/worker-child.ts entry is added by a later task (C phase)
+  entry: ['src/index.ts', 'src/wp/index.ts'],
   format: ['esm', 'cjs'],
   dts: true,
   clean: true,

From f6a6a5fe3012a0f7dbc55aeff030d1045ebfab69 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 20:17:42 -0400
Subject: [PATCH 006/113] test(blocks-engine): freeze worker pool contract

---
 .../src/__tests__/pool.contract.test.ts       | 83 +++++++++++++++++++
 packages/blocks-engine/src/pool/events.ts     | 11 +++
 packages/blocks-engine/src/pool/pool.ts       | 23 +++++
 packages/blocks-engine/src/pool/protocol.ts   | 25 ++++++
 packages/blocks-engine/src/pool/types.ts      | 28 +++++++
 5 files changed, 170 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/pool.contract.test.ts
 create mode 100644 packages/blocks-engine/src/pool/events.ts
 create mode 100644 packages/blocks-engine/src/pool/pool.ts
 create mode 100644 packages/blocks-engine/src/pool/protocol.ts
 create mode 100644 packages/blocks-engine/src/pool/types.ts

diff --git a/packages/blocks-engine/src/__tests__/pool.contract.test.ts b/packages/blocks-engine/src/__tests__/pool.contract.test.ts
new file mode 100644
index 00000000..f4b7a066
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/pool.contract.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import {
+  createWorker,
+  type FixResult,
+  type RawConvertResult,
+  type WorkerPool,
+} from '../pool/pool';
+import type { PoolEvent } from '../pool/events';
+import type { ChildToParentMessage, ParentToChildMessage } from '../pool/protocol';
+
+describe('worker pool contract', () => {
+  it('exports the createWorker public surface', () => {
+    const pool = createWorker({
+      size: 1,
+      recycleAfter: 3,
+      maxReroutes: 2,
+      itemTimeoutMs: 50,
+      onEvent: (event) => {
+        expect(typeof event.type).toBe('string');
+      },
+    });
+
+    expect(typeof pool.rawConvert).toBe('function');
+    expect(typeof pool.canonicalize).toBe('function');
+    expect(typeof pool.stop).toBe('function');
+  });
+
+  it('keeps the public and IPC types frozen', () => {
+    expectTypeOf(createWorker).toEqualTypeOf<
+      (opts?: {
+        size?: number;
+        recycleAfter?: number;
+        maxReroutes?: number;
+        itemTimeoutMs?: number;
+        onEvent?: (e: PoolEvent) => void;
+      }) => WorkerPool
+    >();
+
+    expectTypeOf<RawConvertResult>().toEqualTypeOf<{
+      html: string | null;
+      wpHtmlResidue: number;
+    }>();
+
+    expectTypeOf<FixResult>().toEqualTypeOf<{
+      html: string;
+      changed: boolean;
+      fixedIssues: string[];
+    }>();
+
+    expectTypeOf<PoolEvent>().toEqualTypeOf<{
+      type:
+        | 'child-spawn'
+        | 'child-crash'
+        | 're-route'
+        | 'recycle'
+        | 'sentinel'
+        | 'pool-degraded';
+      childId?: number;
+      count?: number;
+    }>();
+
+    expectTypeOf<ParentToChildMessage>().toEqualTypeOf<{
+      id: number;
+      op: 'rawConvert' | 'canonicalize';
+      payload: string;
+    }>();
+
+    expectTypeOf<ChildToParentMessage>().toEqualTypeOf<
+      | {
+          id: number;
+          result: RawConvertResult | FixResult;
+        }
+      | {
+          id: number;
+          error: {
+            message: string;
+            name?: string;
+            stack?: string;
+          };
+        }
+    >();
+  });
+});
diff --git a/packages/blocks-engine/src/pool/events.ts b/packages/blocks-engine/src/pool/events.ts
new file mode 100644
index 00000000..36470650
--- /dev/null
+++ b/packages/blocks-engine/src/pool/events.ts
@@ -0,0 +1,11 @@
+export type PoolEvent = {
+  type:
+    | 'child-spawn'
+    | 'child-crash'
+    | 're-route'
+    | 'recycle'
+    | 'sentinel'
+    | 'pool-degraded';
+  childId?: number;
+  count?: number;
+};
diff --git a/packages/blocks-engine/src/pool/pool.ts b/packages/blocks-engine/src/pool/pool.ts
new file mode 100644
index 00000000..1ab9d254
--- /dev/null
+++ b/packages/blocks-engine/src/pool/pool.ts
@@ -0,0 +1,23 @@
+import type { CreateWorker, WorkerPoolOptions } from './types';
+
+export type {
+  FixResult,
+  RawConvertResult,
+  WorkerPool,
+  WorkerPoolOptions,
+} from './types';
+export type { PoolEvent } from './events';
+
+export const createWorker: CreateWorker = (opts?: WorkerPoolOptions) => {
+  void opts;
+
+  const notImplemented = async (): Promise<never> => {
+    throw new Error('createWorker implementation is added by Phase C');
+  };
+
+  return {
+    rawConvert: notImplemented,
+    canonicalize: notImplemented,
+    stop: async () => {},
+  };
+};
diff --git a/packages/blocks-engine/src/pool/protocol.ts b/packages/blocks-engine/src/pool/protocol.ts
new file mode 100644
index 00000000..c75ee705
--- /dev/null
+++ b/packages/blocks-engine/src/pool/protocol.ts
@@ -0,0 +1,25 @@
+import type { FixResult, RawConvertResult } from './types';
+
+export type WorkerOp = 'rawConvert' | 'canonicalize';
+
+export type ParentToChildMessage = {
+  id: number;
+  op: WorkerOp;
+  payload: string;
+};
+
+export type WorkerError = {
+  message: string;
+  name?: string;
+  stack?: string;
+};
+
+export type ChildToParentMessage =
+  | {
+      id: number;
+      result: RawConvertResult | FixResult;
+    }
+  | {
+      id: number;
+      error: WorkerError;
+    };
diff --git a/packages/blocks-engine/src/pool/types.ts b/packages/blocks-engine/src/pool/types.ts
new file mode 100644
index 00000000..f5b31cfb
--- /dev/null
+++ b/packages/blocks-engine/src/pool/types.ts
@@ -0,0 +1,28 @@
+import type { PoolEvent } from './events';
+
+export interface RawConvertResult {
+  html: string | null;
+  wpHtmlResidue: number;
+}
+
+export interface FixResult {
+  html: string;
+  changed: boolean;
+  fixedIssues: string[];
+}
+
+export interface WorkerPoolOptions {
+  size?: number;
+  recycleAfter?: number;
+  maxReroutes?: number;
+  itemTimeoutMs?: number;
+  onEvent?: (e: PoolEvent) => void;
+}
+
+export interface WorkerPool {
+  rawConvert(items: string[]): Promise<RawConvertResult[]>;
+  canonicalize(items: string[]): Promise<FixResult[]>;
+  stop(): Promise<void>;
+}
+
+export type CreateWorker = (opts?: WorkerPoolOptions) => WorkerPool;

From e706b2b2d8a47d70b6a50f3e57d6fbeba64f65ef Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 20:38:43 -0400
Subject: [PATCH 007/113] feat(blocks-engine): add forked worker pool

---
 packages/blocks-engine/package.json           |   4 +-
 packages/blocks-engine/pnpm-lock.yaml         | 313 +++++++++-
 .../src/__tests__/oneshot.test.ts             |  25 +
 .../src/__tests__/pool-test-helpers.ts        | 144 +++++
 .../src/__tests__/pool.chaos.test.ts          | 169 ++++++
 .../src/__tests__/pool.events.test.ts         |  39 ++
 .../src/__tests__/pool.order.test.ts          |  89 +++
 .../src/__tests__/pool.purity.test.ts         |  37 ++
 .../src/__tests__/pool.recycle.test.ts        |  38 ++
 .../src/__tests__/worker-child.test.ts        |  36 ++
 packages/blocks-engine/src/pool/pool.ts       | 542 +++++++++++++++++-
 packages/blocks-engine/src/wp/worker-child.ts | 129 +++++
 packages/blocks-engine/tsup.config.ts         |   3 +-
 13 files changed, 1547 insertions(+), 21 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/oneshot.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/pool-test-helpers.ts
 create mode 100644 packages/blocks-engine/src/__tests__/pool.chaos.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/pool.events.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/pool.order.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/pool.purity.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/pool.recycle.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/worker-child.test.ts
 create mode 100644 packages/blocks-engine/src/wp/worker-child.ts

diff --git a/packages/blocks-engine/package.json b/packages/blocks-engine/package.json
index 3ec1e05f..df360939 100644
--- a/packages/blocks-engine/package.json
+++ b/packages/blocks-engine/package.json
@@ -30,8 +30,10 @@
     "jsdom": "29.0.1"
   },
   "devDependencies": {
+    "@types/node": "^26.0.0",
     "tsup": "8.0.0",
     "vitest": "2.0.0",
-    "typescript": "5.7.3"
+    "typescript": "5.7.3",
+    "tsx": "^4.22.4"
   }
 }
diff --git a/packages/blocks-engine/pnpm-lock.yaml b/packages/blocks-engine/pnpm-lock.yaml
index 62b3cfd2..e76ef977 100644
--- a/packages/blocks-engine/pnpm-lock.yaml
+++ b/packages/blocks-engine/pnpm-lock.yaml
@@ -33,15 +33,21 @@ importers:
         specifier: 29.0.1
         version: 29.0.1
     devDependencies:
+      '@types/node':
+        specifier: ^26.0.0
+        version: 26.0.0
       tsup:
         specifier: 8.0.0
         version: 8.0.0(postcss@8.5.15)(typescript@5.7.3)
+      tsx:
+        specifier: ^4.22.4
+        version: 4.22.4
       typescript:
         specifier: 5.7.3
         version: 5.7.3
       vitest:
         specifier: 2.0.0
-        version: 2.0.0(jsdom@29.0.1)
+        version: 2.0.0(@types/node@26.0.0)(jsdom@29.0.1)
 
 packages:
 
@@ -286,6 +292,12 @@ packages:
     cpu: [ppc64]
     os: [aix]
 
+  '@esbuild/aix-ppc64@0.28.1':
+    resolution: {integrity: sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==, tarball: https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
   '@esbuild/android-arm64@0.19.12':
     resolution: {integrity: sha512-P0UVNGIienjZv3f5zq0DP3Nt2IE/3plFzuaS96vihvD0Hd6H/q4WXUGpCxD/E8YrSXfNyRPbpTq+T8ZQioSuPA==, tarball: https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -298,6 +310,12 @@ packages:
     cpu: [arm64]
     os: [android]
 
+  '@esbuild/android-arm64@0.28.1':
+    resolution: {integrity: sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==, tarball: https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
   '@esbuild/android-arm@0.19.12':
     resolution: {integrity: sha512-qg/Lj1mu3CdQlDEEiWrlC4eaPZ1KztwGJ9B6J+/6G+/4ewxJg7gqj8eVYWvao1bXrqGiW2rsBZFSX3q2lcW05w==, tarball: https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -310,6 +328,12 @@ packages:
     cpu: [arm]
     os: [android]
 
+  '@esbuild/android-arm@0.28.1':
+    resolution: {integrity: sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==, tarball: https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
   '@esbuild/android-x64@0.19.12':
     resolution: {integrity: sha512-3k7ZoUW6Q6YqhdhIaq/WZ7HwBpnFBlW905Fa4s4qWJyiNOgT1dOqDiVAQFwBH7gBRZr17gLrlFCRzF6jFh7Kew==, tarball: https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -322,6 +346,12 @@ packages:
     cpu: [x64]
     os: [android]
 
+  '@esbuild/android-x64@0.28.1':
+    resolution: {integrity: sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==, tarball: https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
   '@esbuild/darwin-arm64@0.19.12':
     resolution: {integrity: sha512-B6IeSgZgtEzGC42jsI+YYu9Z3HKRxp8ZT3cqhvliEHovq8HSX2YX8lNocDn79gCKJXOSaEot9MVYky7AKjCs8g==, tarball: https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -334,6 +364,12 @@ packages:
     cpu: [arm64]
     os: [darwin]
 
+  '@esbuild/darwin-arm64@0.28.1':
+    resolution: {integrity: sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==, tarball: https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
   '@esbuild/darwin-x64@0.19.12':
     resolution: {integrity: sha512-hKoVkKzFiToTgn+41qGhsUJXFlIjxI/jSYeZf3ugemDYZldIXIxhvwN6erJGlX4t5h417iFuheZ7l+YVn05N3A==, tarball: https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -346,6 +382,12 @@ packages:
     cpu: [x64]
     os: [darwin]
 
+  '@esbuild/darwin-x64@0.28.1':
+    resolution: {integrity: sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==, tarball: https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
   '@esbuild/freebsd-arm64@0.19.12':
     resolution: {integrity: sha512-4aRvFIXmwAcDBw9AueDQ2YnGmz5L6obe5kmPT8Vd+/+x/JMVKCgdcRwH6APrbpNXsPz+K653Qg8HB/oXvXVukA==, tarball: https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -358,6 +400,12 @@ packages:
     cpu: [arm64]
     os: [freebsd]
 
+  '@esbuild/freebsd-arm64@0.28.1':
+    resolution: {integrity: sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==, tarball: https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
   '@esbuild/freebsd-x64@0.19.12':
     resolution: {integrity: sha512-EYoXZ4d8xtBoVN7CEwWY2IN4ho76xjYXqSXMNccFSx2lgqOG/1TBPW0yPx1bJZk94qu3tX0fycJeeQsKovA8gg==, tarball: https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -370,6 +418,12 @@ packages:
     cpu: [x64]
     os: [freebsd]
 
+  '@esbuild/freebsd-x64@0.28.1':
+    resolution: {integrity: sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==, tarball: https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
   '@esbuild/linux-arm64@0.19.12':
     resolution: {integrity: sha512-EoTjyYyLuVPfdPLsGVVVC8a0p1BFFvtpQDB/YLEhaXyf/5bczaGeN15QkR+O4S5LeJ92Tqotve7i1jn35qwvdA==, tarball: https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -382,6 +436,12 @@ packages:
     cpu: [arm64]
     os: [linux]
 
+  '@esbuild/linux-arm64@0.28.1':
+    resolution: {integrity: sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==, tarball: https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
   '@esbuild/linux-arm@0.19.12':
     resolution: {integrity: sha512-J5jPms//KhSNv+LO1S1TX1UWp1ucM6N6XuL6ITdKWElCu8wXP72l9MM0zDTzzeikVyqFE6U8YAV9/tFyj0ti+w==, tarball: https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -394,6 +454,12 @@ packages:
     cpu: [arm]
     os: [linux]
 
+  '@esbuild/linux-arm@0.28.1':
+    resolution: {integrity: sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==, tarball: https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
   '@esbuild/linux-ia32@0.19.12':
     resolution: {integrity: sha512-Thsa42rrP1+UIGaWz47uydHSBOgTUnwBwNq59khgIwktK6x60Hivfbux9iNR0eHCHzOLjLMLfUMLCypBkZXMHA==, tarball: https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -406,6 +472,12 @@ packages:
     cpu: [ia32]
     os: [linux]
 
+  '@esbuild/linux-ia32@0.28.1':
+    resolution: {integrity: sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==, tarball: https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
   '@esbuild/linux-loong64@0.19.12':
     resolution: {integrity: sha512-LiXdXA0s3IqRRjm6rV6XaWATScKAXjI4R4LoDlvO7+yQqFdlr1Bax62sRwkVvRIrwXxvtYEHHI4dm50jAXkuAA==, tarball: https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -418,6 +490,12 @@ packages:
     cpu: [loong64]
     os: [linux]
 
+  '@esbuild/linux-loong64@0.28.1':
+    resolution: {integrity: sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==, tarball: https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
   '@esbuild/linux-mips64el@0.19.12':
     resolution: {integrity: sha512-fEnAuj5VGTanfJ07ff0gOA6IPsvrVHLVb6Lyd1g2/ed67oU1eFzL0r9WL7ZzscD+/N6i3dWumGE1Un4f7Amf+w==, tarball: https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -430,6 +508,12 @@ packages:
     cpu: [mips64el]
     os: [linux]
 
+  '@esbuild/linux-mips64el@0.28.1':
+    resolution: {integrity: sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==, tarball: https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
   '@esbuild/linux-ppc64@0.19.12':
     resolution: {integrity: sha512-nYJA2/QPimDQOh1rKWedNOe3Gfc8PabU7HT3iXWtNUbRzXS9+vgB0Fjaqr//XNbd82mCxHzik2qotuI89cfixg==, tarball: https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -442,6 +526,12 @@ packages:
     cpu: [ppc64]
     os: [linux]
 
+  '@esbuild/linux-ppc64@0.28.1':
+    resolution: {integrity: sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==, tarball: https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
   '@esbuild/linux-riscv64@0.19.12':
     resolution: {integrity: sha512-2MueBrlPQCw5dVJJpQdUYgeqIzDQgw3QtiAHUC4RBz9FXPrskyyU3VI1hw7C0BSKB9OduwSJ79FTCqtGMWqJHg==, tarball: https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -454,6 +544,12 @@ packages:
     cpu: [riscv64]
     os: [linux]
 
+  '@esbuild/linux-riscv64@0.28.1':
+    resolution: {integrity: sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==, tarball: https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
   '@esbuild/linux-s390x@0.19.12':
     resolution: {integrity: sha512-+Pil1Nv3Umes4m3AZKqA2anfhJiVmNCYkPchwFJNEJN5QxmTs1uzyy4TvmDrCRNT2ApwSari7ZIgrPeUx4UZDg==, tarball: https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -466,6 +562,12 @@ packages:
     cpu: [s390x]
     os: [linux]
 
+  '@esbuild/linux-s390x@0.28.1':
+    resolution: {integrity: sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==, tarball: https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
   '@esbuild/linux-x64@0.19.12':
     resolution: {integrity: sha512-B71g1QpxfwBvNrfyJdVDexenDIt1CiDN1TIXLbhOw0KhJzE78KIFGX6OJ9MrtC0oOqMWf+0xop4qEU8JrJTwCg==, tarball: https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -478,6 +580,18 @@ packages:
     cpu: [x64]
     os: [linux]
 
+  '@esbuild/linux-x64@0.28.1':
+    resolution: {integrity: sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==, tarball: https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.28.1':
+    resolution: {integrity: sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==, tarball: https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
   '@esbuild/netbsd-x64@0.19.12':
     resolution: {integrity: sha512-3ltjQ7n1owJgFbuC61Oj++XhtzmymoCihNFgT84UAmJnxJfm4sYCiSLTXZtE00VWYpPMYc+ZQmB6xbSdVh0JWA==, tarball: https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -490,6 +604,18 @@ packages:
     cpu: [x64]
     os: [netbsd]
 
+  '@esbuild/netbsd-x64@0.28.1':
+    resolution: {integrity: sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==, tarball: https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.28.1':
+    resolution: {integrity: sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==, tarball: https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
   '@esbuild/openbsd-x64@0.19.12':
     resolution: {integrity: sha512-RbrfTB9SWsr0kWmb9srfF+L933uMDdu9BIzdA7os2t0TXhCRjrQyCeOt6wVxr79CKD4c+p+YhCj31HBkYcXebw==, tarball: https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -502,6 +628,18 @@ packages:
     cpu: [x64]
     os: [openbsd]
 
+  '@esbuild/openbsd-x64@0.28.1':
+    resolution: {integrity: sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==, tarball: https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.28.1':
+    resolution: {integrity: sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==, tarball: https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
   '@esbuild/sunos-x64@0.19.12':
     resolution: {integrity: sha512-HKjJwRrW8uWtCQnQOz9qcU3mUZhTUQvi56Q8DPTLLB+DawoiQdjsYq+j+D3s9I8VFtDr+F9CjgXKKC4ss89IeA==, tarball: https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -514,6 +652,12 @@ packages:
     cpu: [x64]
     os: [sunos]
 
+  '@esbuild/sunos-x64@0.28.1':
+    resolution: {integrity: sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==, tarball: https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
   '@esbuild/win32-arm64@0.19.12':
     resolution: {integrity: sha512-URgtR1dJnmGvX864pn1B2YUYNzjmXkuJOIqG2HdU62MVS4EHpU2946OZoTMnRUHklGtJdJZ33QfzdjGACXhn1A==, tarball: https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -526,6 +670,12 @@ packages:
     cpu: [arm64]
     os: [win32]
 
+  '@esbuild/win32-arm64@0.28.1':
+    resolution: {integrity: sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==, tarball: https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
   '@esbuild/win32-ia32@0.19.12':
     resolution: {integrity: sha512-+ZOE6pUkMOJfmxmBZElNOx72NKpIa/HFOMGzu8fqzQJ5kgf6aTGrcJaFsNiVMH4JKpMipyK+7k0n2UXN7a8YKQ==, tarball: https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -538,6 +688,12 @@ packages:
     cpu: [ia32]
     os: [win32]
 
+  '@esbuild/win32-ia32@0.28.1':
+    resolution: {integrity: sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==, tarball: https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
   '@esbuild/win32-x64@0.19.12':
     resolution: {integrity: sha512-T1QyPSDCyMXaO3pzBkF96E8xMkiRYbUEZADd29SyPGabqxMViNoii+NcK7eWJAEoU6RZyEm5lVSIjTmcdoB9HA==, tarball: https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.19.12.tgz}
     engines: {node: '>=12'}
@@ -550,6 +706,12 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@esbuild/win32-x64@0.28.1':
+    resolution: {integrity: sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==, tarball: https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.1.tgz}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
   '@exodus/bytes@1.15.1':
     resolution: {integrity: sha512-S6mL0yNB/Abt9Ei4tq8gDhcczc4S3+vQ4ra7vxnAf+YHC02srtqxKKZghx2Dq6p0e66THKwR6r8N6P95wEty7Q==, tarball: https://registry.npmjs.org/@exodus/bytes/-/bytes-1.15.1.tgz}
     engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
@@ -977,6 +1139,9 @@ packages:
   '@types/mousetrap@1.6.15':
     resolution: {integrity: sha512-qL0hyIMNPow317QWW/63RvL1x5MVMV+Ru3NaY9f/CuEpCqrmb7WeuK2071ZY5hczOnm38qExWM2i2WtkXLSqFw==, tarball: https://registry.npmjs.org/@types/mousetrap/-/mousetrap-1.6.15.tgz}
 
+  '@types/node@26.0.0':
+    resolution: {integrity: sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA==, tarball: https://registry.npmjs.org/@types/node/-/node-26.0.0.tgz}
+
   '@types/parse-json@4.0.2':
     resolution: {integrity: sha512-dISoDXWWQwUquiKsyZ4Ng+HX2KsPL7LyHKHQwgGFEA3IaKac4Obd+h2a/a6waisAoepJlBcx9paWqjA8/HVjCw==, tarball: https://registry.npmjs.org/@types/parse-json/-/parse-json-4.0.2.tgz}
 
@@ -1688,6 +1853,11 @@ packages:
     engines: {node: '>=12'}
     hasBin: true
 
+  esbuild@0.28.1:
+    resolution: {integrity: sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==, tarball: https://registry.npmjs.org/esbuild/-/esbuild-0.28.1.tgz}
+    engines: {node: '>=18'}
+    hasBin: true
+
   escape-string-regexp@4.0.0:
     resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==, tarball: https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz}
     engines: {node: '>=10'}
@@ -2518,11 +2688,19 @@ packages:
       typescript:
         optional: true
 
+  tsx@4.22.4:
+    resolution: {integrity: sha512-X8EX+XV4QR5xCsrgxaED954zTDfY8KqlDtskKEL0cHhyS/P8b4IFOvGDQpsC9Q1XnLq915wEfwwY/zzskCtmhg==, tarball: https://registry.npmjs.org/tsx/-/tsx-4.22.4.tgz}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
   typescript@5.7.3:
     resolution: {integrity: sha512-84MVSjMEHP+FQRPy3pX9sTVV/INIex71s9TL2Gm5FG/WG1SqXeKyZ0k7/blY/4FdOzI12CBy1vGc4og/eus0fw==, tarball: https://registry.npmjs.org/typescript/-/typescript-5.7.3.tgz}
     engines: {node: '>=14.17'}
     hasBin: true
 
+  undici-types@8.3.0:
+    resolution: {integrity: sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==, tarball: https://registry.npmjs.org/undici-types/-/undici-types-8.3.0.tgz}
+
   undici@7.28.0:
     resolution: {integrity: sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA==, tarball: https://registry.npmjs.org/undici/-/undici-7.28.0.tgz}
     engines: {node: '>=20.18.1'}
@@ -3007,138 +3185,216 @@ snapshots:
   '@esbuild/aix-ppc64@0.21.5':
     optional: true
 
+  '@esbuild/aix-ppc64@0.28.1':
+    optional: true
+
   '@esbuild/android-arm64@0.19.12':
     optional: true
 
   '@esbuild/android-arm64@0.21.5':
     optional: true
 
+  '@esbuild/android-arm64@0.28.1':
+    optional: true
+
   '@esbuild/android-arm@0.19.12':
     optional: true
 
   '@esbuild/android-arm@0.21.5':
     optional: true
 
+  '@esbuild/android-arm@0.28.1':
+    optional: true
+
   '@esbuild/android-x64@0.19.12':
     optional: true
 
   '@esbuild/android-x64@0.21.5':
     optional: true
 
+  '@esbuild/android-x64@0.28.1':
+    optional: true
+
   '@esbuild/darwin-arm64@0.19.12':
     optional: true
 
   '@esbuild/darwin-arm64@0.21.5':
     optional: true
 
+  '@esbuild/darwin-arm64@0.28.1':
+    optional: true
+
   '@esbuild/darwin-x64@0.19.12':
     optional: true
 
   '@esbuild/darwin-x64@0.21.5':
     optional: true
 
+  '@esbuild/darwin-x64@0.28.1':
+    optional: true
+
   '@esbuild/freebsd-arm64@0.19.12':
     optional: true
 
   '@esbuild/freebsd-arm64@0.21.5':
     optional: true
 
+  '@esbuild/freebsd-arm64@0.28.1':
+    optional: true
+
   '@esbuild/freebsd-x64@0.19.12':
     optional: true
 
   '@esbuild/freebsd-x64@0.21.5':
     optional: true
 
+  '@esbuild/freebsd-x64@0.28.1':
+    optional: true
+
   '@esbuild/linux-arm64@0.19.12':
     optional: true
 
   '@esbuild/linux-arm64@0.21.5':
     optional: true
 
+  '@esbuild/linux-arm64@0.28.1':
+    optional: true
+
   '@esbuild/linux-arm@0.19.12':
     optional: true
 
   '@esbuild/linux-arm@0.21.5':
     optional: true
 
+  '@esbuild/linux-arm@0.28.1':
+    optional: true
+
   '@esbuild/linux-ia32@0.19.12':
     optional: true
 
   '@esbuild/linux-ia32@0.21.5':
     optional: true
 
+  '@esbuild/linux-ia32@0.28.1':
+    optional: true
+
   '@esbuild/linux-loong64@0.19.12':
     optional: true
 
   '@esbuild/linux-loong64@0.21.5':
     optional: true
 
+  '@esbuild/linux-loong64@0.28.1':
+    optional: true
+
   '@esbuild/linux-mips64el@0.19.12':
     optional: true
 
   '@esbuild/linux-mips64el@0.21.5':
     optional: true
 
+  '@esbuild/linux-mips64el@0.28.1':
+    optional: true
+
   '@esbuild/linux-ppc64@0.19.12':
     optional: true
 
   '@esbuild/linux-ppc64@0.21.5':
     optional: true
 
+  '@esbuild/linux-ppc64@0.28.1':
+    optional: true
+
   '@esbuild/linux-riscv64@0.19.12':
     optional: true
 
   '@esbuild/linux-riscv64@0.21.5':
     optional: true
 
+  '@esbuild/linux-riscv64@0.28.1':
+    optional: true
+
   '@esbuild/linux-s390x@0.19.12':
     optional: true
 
   '@esbuild/linux-s390x@0.21.5':
     optional: true
 
+  '@esbuild/linux-s390x@0.28.1':
+    optional: true
+
   '@esbuild/linux-x64@0.19.12':
     optional: true
 
   '@esbuild/linux-x64@0.21.5':
     optional: true
 
+  '@esbuild/linux-x64@0.28.1':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.28.1':
+    optional: true
+
   '@esbuild/netbsd-x64@0.19.12':
     optional: true
 
   '@esbuild/netbsd-x64@0.21.5':
     optional: true
 
+  '@esbuild/netbsd-x64@0.28.1':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.28.1':
+    optional: true
+
   '@esbuild/openbsd-x64@0.19.12':
     optional: true
 
   '@esbuild/openbsd-x64@0.21.5':
     optional: true
 
+  '@esbuild/openbsd-x64@0.28.1':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.28.1':
+    optional: true
+
   '@esbuild/sunos-x64@0.19.12':
     optional: true
 
   '@esbuild/sunos-x64@0.21.5':
     optional: true
 
+  '@esbuild/sunos-x64@0.28.1':
+    optional: true
+
   '@esbuild/win32-arm64@0.19.12':
     optional: true
 
   '@esbuild/win32-arm64@0.21.5':
     optional: true
 
+  '@esbuild/win32-arm64@0.28.1':
+    optional: true
+
   '@esbuild/win32-ia32@0.19.12':
     optional: true
 
   '@esbuild/win32-ia32@0.21.5':
     optional: true
 
+  '@esbuild/win32-ia32@0.28.1':
+    optional: true
+
   '@esbuild/win32-x64@0.19.12':
     optional: true
 
   '@esbuild/win32-x64@0.21.5':
     optional: true
 
+  '@esbuild/win32-x64@0.28.1':
+    optional: true
+
   '@exodus/bytes@1.15.1': {}
 
   '@floating-ui/core@1.7.5':
@@ -3479,6 +3735,10 @@ snapshots:
 
   '@types/mousetrap@1.6.15': {}
 
+  '@types/node@26.0.0':
+    dependencies:
+      undici-types: 8.3.0
+
   '@types/parse-json@4.0.2': {}
 
   '@types/prop-types@15.7.15': {}
@@ -4889,6 +5149,35 @@ snapshots:
       '@esbuild/win32-ia32': 0.21.5
       '@esbuild/win32-x64': 0.21.5
 
+  esbuild@0.28.1:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.28.1
+      '@esbuild/android-arm': 0.28.1
+      '@esbuild/android-arm64': 0.28.1
+      '@esbuild/android-x64': 0.28.1
+      '@esbuild/darwin-arm64': 0.28.1
+      '@esbuild/darwin-x64': 0.28.1
+      '@esbuild/freebsd-arm64': 0.28.1
+      '@esbuild/freebsd-x64': 0.28.1
+      '@esbuild/linux-arm': 0.28.1
+      '@esbuild/linux-arm64': 0.28.1
+      '@esbuild/linux-ia32': 0.28.1
+      '@esbuild/linux-loong64': 0.28.1
+      '@esbuild/linux-mips64el': 0.28.1
+      '@esbuild/linux-ppc64': 0.28.1
+      '@esbuild/linux-riscv64': 0.28.1
+      '@esbuild/linux-s390x': 0.28.1
+      '@esbuild/linux-x64': 0.28.1
+      '@esbuild/netbsd-arm64': 0.28.1
+      '@esbuild/netbsd-x64': 0.28.1
+      '@esbuild/openbsd-arm64': 0.28.1
+      '@esbuild/openbsd-x64': 0.28.1
+      '@esbuild/openharmony-arm64': 0.28.1
+      '@esbuild/sunos-x64': 0.28.1
+      '@esbuild/win32-arm64': 0.28.1
+      '@esbuild/win32-ia32': 0.28.1
+      '@esbuild/win32-x64': 0.28.1
+
   escape-string-regexp@4.0.0: {}
 
   estree-walker@3.0.3:
@@ -5680,8 +5969,16 @@ snapshots:
       - supports-color
       - ts-node
 
+  tsx@4.22.4:
+    dependencies:
+      esbuild: 0.28.1
+    optionalDependencies:
+      fsevents: 2.3.3
+
   typescript@5.7.3: {}
 
+  undici-types@8.3.0: {}
+
   undici@7.28.0: {}
 
   upper-case-first@2.0.2:
@@ -5719,13 +6016,13 @@ snapshots:
 
   uuid@9.0.1: {}
 
-  vite-node@2.0.0:
+  vite-node@2.0.0(@types/node@26.0.0):
     dependencies:
       cac: 6.7.14
       debug: 4.4.3
       pathe: 1.1.2
       picocolors: 1.1.1
-      vite: 5.4.21
+      vite: 5.4.21(@types/node@26.0.0)
     transitivePeerDependencies:
       - '@types/node'
       - less
@@ -5737,15 +6034,16 @@ snapshots:
       - supports-color
       - terser
 
-  vite@5.4.21:
+  vite@5.4.21(@types/node@26.0.0):
     dependencies:
       esbuild: 0.21.5
       postcss: 8.5.15
       rollup: 4.62.2
     optionalDependencies:
+      '@types/node': 26.0.0
       fsevents: 2.3.3
 
-  vitest@2.0.0(jsdom@29.0.1):
+  vitest@2.0.0(@types/node@26.0.0)(jsdom@29.0.1):
     dependencies:
       '@ampproject/remapping': 2.3.0
       '@vitest/expect': 2.0.0
@@ -5762,10 +6060,11 @@ snapshots:
       std-env: 3.10.0
       tinybench: 2.9.0
       tinypool: 1.1.1
-      vite: 5.4.21
-      vite-node: 2.0.0
+      vite: 5.4.21(@types/node@26.0.0)
+      vite-node: 2.0.0(@types/node@26.0.0)
       why-is-node-running: 2.3.0
     optionalDependencies:
+      '@types/node': 26.0.0
       jsdom: 29.0.1
     transitivePeerDependencies:
       - less
diff --git a/packages/blocks-engine/src/__tests__/oneshot.test.ts b/packages/blocks-engine/src/__tests__/oneshot.test.ts
new file mode 100644
index 00000000..97a78d5a
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/oneshot.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('node:child_process', async () => {
+  const actual = await vi.importActual<typeof import('node:child_process')>(
+    'node:child_process',
+  );
+  return {
+    ...actual,
+    fork: vi.fn(actual.fork),
+  };
+});
+
+import { fork } from 'node:child_process';
+
+import { rawConvert } from '../wp';
+import { fixtureFor } from './pool-test-helpers';
+
+describe('one-shot /wp fast path', () => {
+  it('runs in-process without forking', () => {
+    const fixture = fixtureFor('rawConvert');
+
+    expect(rawConvert(fixture.input)).toEqual(fixture.expected);
+    expect(fork).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/pool-test-helpers.ts b/packages/blocks-engine/src/__tests__/pool-test-helpers.ts
new file mode 100644
index 00000000..1f39271e
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/pool-test-helpers.ts
@@ -0,0 +1,144 @@
+import { fork, type ChildProcess } from 'node:child_process';
+import { once } from 'node:events';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import cases from '../__fixtures__/cases.json' with { type: 'json' };
+import type { ChildToParentMessage, ParentToChildMessage } from '../pool/protocol';
+
+type RawConvertFixture = {
+  id: string;
+  op: 'rawConvert';
+  input: string;
+  expected: { html: string | null; wpHtmlResidue: number };
+};
+
+type CanonicalizeFixture = {
+  id: string;
+  op: 'canonicalize';
+  input: string;
+  expected: { html: string; changed: boolean; fixedIssues: string[] };
+};
+
+export type Fixture = RawConvertFixture | CanonicalizeFixture;
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(here, '..', '..');
+const workerChildPath = resolve(here, '..', 'wp', 'worker-child.ts');
+
+const TEST_TIMEOUT_MS = 15_000;
+
+export function fixturesFor(op: 'rawConvert'): RawConvertFixture[];
+export function fixturesFor(op: 'canonicalize'): CanonicalizeFixture[];
+export function fixturesFor(op: Fixture['op']): Fixture[] {
+  return (cases as Fixture[]).filter((fixture) => fixture.op === op);
+}
+
+export function fixtureFor(op: 'rawConvert', index?: number): RawConvertFixture;
+export function fixtureFor(op: 'canonicalize', index?: number): CanonicalizeFixture;
+export function fixtureFor(op: Fixture['op'], index = 0): Fixture {
+  const matches = (cases as Fixture[]).filter((fixture) => fixture.op === op);
+  const fixture = matches[index];
+  if (!fixture) {
+    throw new Error(`Missing fixture ${op}[${index}]`);
+  }
+  return fixture;
+}
+
+export function delayedInput(input: string, delayMs = 150): string {
+  return `<!-- BLOCKS_ENGINE_TEST_DELAY:${delayMs} -->${input}`;
+}
+
+export function crashOnceInput(input: string): string {
+  return `<!-- BLOCKS_ENGINE_TEST_CRASH_ONCE -->${input}`;
+}
+
+export function crashAlwaysInput(input: string): string {
+  return `<!-- BLOCKS_ENGINE_TEST_CRASH_ALWAYS -->${input}`;
+}
+
+export function hangInput(input: string): string {
+  return `<!-- BLOCKS_ENGINE_TEST_HANG -->${input}`;
+}
+
+export function testWorkerEnv(env: NodeJS.ProcessEnv = {}): NodeJS.ProcessEnv {
+  return {
+    ...env,
+    BLOCKS_ENGINE_WORKER_TEST_MODE: '1',
+  };
+}
+
+export function forkTestWorker(env: NodeJS.ProcessEnv = {}): ChildProcess {
+  return fork(workerChildPath, [], {
+    cwd: packageRoot,
+    env: {
+      ...process.env,
+      ...env,
+    },
+    execArgv: ['--import', 'tsx'],
+    stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+  });
+}
+
+export async function sendWorkerMessage(
+  child: ChildProcess,
+  message: ParentToChildMessage,
+): Promise<ChildToParentMessage> {
+  child.send(message);
+
+  return withTimeout(
+    Promise.race([
+      once(child, 'message').then(([response]) => response as ChildToParentMessage),
+      once(child, 'exit').then(([code, signal]) => {
+        throw new Error(`Worker exited before response code=${code} signal=${signal}`);
+      }),
+    ]),
+  );
+}
+
+export async function cleanupChild(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return;
+  }
+
+  const exited = once(child, 'exit').then(() => undefined);
+  child.kill('SIGTERM');
+
+  try {
+    await withTimeout(exited, 2_000);
+  } catch {
+    child.kill('SIGKILL');
+    await withTimeout(exited, 2_000).catch(() => undefined);
+  }
+}
+
+export function pidIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs = TEST_TIMEOUT_MS,
+): Promise<T> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<T>((_resolve, reject) => {
+        timeout = setTimeout(
+          () => reject(new Error(`Timed out after ${timeoutMs}ms`)),
+          timeoutMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  }
+}
diff --git a/packages/blocks-engine/src/__tests__/pool.chaos.test.ts b/packages/blocks-engine/src/__tests__/pool.chaos.test.ts
new file mode 100644
index 00000000..ca10f910
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/pool.chaos.test.ts
@@ -0,0 +1,169 @@
+import { describe, expect, it } from 'vitest';
+
+import { createWorker, type PoolEvent } from '../pool/pool';
+import {
+  crashAlwaysInput,
+  crashOnceInput,
+  fixtureFor,
+  hangInput,
+  withTimeout,
+} from './pool-test-helpers';
+
+function withTestMode<T>(fn: () => Promise<T>): Promise<T> {
+  const previousMode = process.env.BLOCKS_ENGINE_WORKER_TEST_MODE;
+  process.env.BLOCKS_ENGINE_WORKER_TEST_MODE = '1';
+
+  return fn().finally(() => {
+    if (previousMode === undefined) {
+      delete process.env.BLOCKS_ENGINE_WORKER_TEST_MODE;
+    } else {
+      process.env.BLOCKS_ENGINE_WORKER_TEST_MODE = previousMode;
+    }
+  });
+}
+
+describe('worker pool chaos recovery', () => {
+  it('re-routes an item after a child crashes and still returns the golden result', async () =>
+    withTestMode(async () => {
+      const fixture = fixtureFor('rawConvert');
+      const events: PoolEvent[] = [];
+      const pool = createWorker({
+        size: 2,
+        maxReroutes: 2,
+        onEvent: (event) => events.push(event),
+      });
+
+      try {
+        await expect(pool.rawConvert([crashOnceInput(fixture.input)])).resolves.toEqual([
+          fixture.expected,
+        ]);
+      } finally {
+        await pool.stop();
+      }
+
+      expect(events.some((event) => event.type === 'child-crash')).toBe(true);
+      expect(events.some((event) => event.type === 're-route')).toBe(true);
+      expect(events.some((event) => event.type === 'sentinel')).toBe(false);
+    }), 20_000);
+
+  it('returns the rawConvert sentinel after a poison item exhausts re-routes', async () =>
+    withTestMode(async () => {
+      const fixture = fixtureFor('rawConvert');
+      const events: PoolEvent[] = [];
+      const pool = createWorker({
+        size: 2,
+        maxReroutes: 2,
+        onEvent: (event) => events.push(event),
+      });
+
+      try {
+        await expect(pool.rawConvert([crashAlwaysInput(fixture.input)])).resolves.toEqual([
+          { html: null, wpHtmlResidue: Infinity },
+        ]);
+      } finally {
+        await pool.stop();
+      }
+
+      expect(events.some((event) => event.type === 'child-crash')).toBe(true);
+      expect(events.some((event) => event.type === 're-route')).toBe(true);
+      expect(events.filter((event) => event.type === 'sentinel')).toHaveLength(1);
+    }), 20_000);
+
+  it('uses itemTimeoutMs to sentinel a hung canonicalize item without waiting 10 seconds', async () =>
+    withTestMode(async () => {
+      const fixture = fixtureFor('canonicalize');
+      const events: PoolEvent[] = [];
+      const input = hangInput(fixture.input);
+      const pool = createWorker({
+        size: 1,
+        maxReroutes: 1,
+        itemTimeoutMs: 50,
+        onEvent: (event) => events.push(event),
+      });
+
+      try {
+        await expect(pool.canonicalize([input])).resolves.toEqual([
+          { html: input, changed: false, fixedIssues: [] },
+        ]);
+      } finally {
+        await pool.stop();
+      }
+
+      expect(events.some((event) => event.type === 're-route')).toBe(true);
+      expect(events.filter((event) => event.type === 'sentinel')).toHaveLength(1);
+    }), 20_000);
+
+  it('degrades the whole batch when every child fails bootstrap', async () => {
+    const previousMode = process.env.BLOCKS_ENGINE_WORKER_TEST_MODE;
+    const previousBootstrapFail = process.env.BLOCKS_ENGINE_FORCE_BOOTSTRAP_FAIL;
+    process.env.BLOCKS_ENGINE_WORKER_TEST_MODE = '1';
+    process.env.BLOCKS_ENGINE_FORCE_BOOTSTRAP_FAIL = '1';
+
+    const first = fixtureFor('rawConvert', 0);
+    const second = fixtureFor('rawConvert', 1);
+    const events: PoolEvent[] = [];
+    const pool = createWorker({
+      size: 2,
+      maxReroutes: 2,
+      onEvent: (event) => events.push(event),
+    });
+
+    try {
+      await expect(pool.rawConvert([first.input, second.input])).resolves.toEqual([
+        { html: null, wpHtmlResidue: Infinity },
+        { html: null, wpHtmlResidue: Infinity },
+      ]);
+    } finally {
+      await pool.stop();
+      if (previousMode === undefined) {
+        delete process.env.BLOCKS_ENGINE_WORKER_TEST_MODE;
+      } else {
+        process.env.BLOCKS_ENGINE_WORKER_TEST_MODE = previousMode;
+      }
+      if (previousBootstrapFail === undefined) {
+        delete process.env.BLOCKS_ENGINE_FORCE_BOOTSTRAP_FAIL;
+      } else {
+        process.env.BLOCKS_ENGINE_FORCE_BOOTSTRAP_FAIL = previousBootstrapFail;
+      }
+    }
+
+    expect(events.some((event) => event.type === 'pool-degraded')).toBe(true);
+    expect(events.filter((event) => event.type === 'sentinel')).toHaveLength(2);
+  }, 20_000);
+
+  it('degrades a one-item batch when every child fails bootstrap', async () => {
+    const previousMode = process.env.BLOCKS_ENGINE_WORKER_TEST_MODE;
+    const previousBootstrapFail = process.env.BLOCKS_ENGINE_FORCE_BOOTSTRAP_FAIL;
+    process.env.BLOCKS_ENGINE_WORKER_TEST_MODE = '1';
+    process.env.BLOCKS_ENGINE_FORCE_BOOTSTRAP_FAIL = '1';
+
+    const fixture = fixtureFor('rawConvert');
+    const events: PoolEvent[] = [];
+    const pool = createWorker({
+      size: 2,
+      maxReroutes: 2,
+      onEvent: (event) => events.push(event),
+    });
+
+    try {
+      await expect(withTimeout(pool.rawConvert([fixture.input]), 3_000)).resolves.toEqual([
+        { html: null, wpHtmlResidue: Infinity },
+      ]);
+    } finally {
+      await pool.stop();
+      if (previousMode === undefined) {
+        delete process.env.BLOCKS_ENGINE_WORKER_TEST_MODE;
+      } else {
+        process.env.BLOCKS_ENGINE_WORKER_TEST_MODE = previousMode;
+      }
+      if (previousBootstrapFail === undefined) {
+        delete process.env.BLOCKS_ENGINE_FORCE_BOOTSTRAP_FAIL;
+      } else {
+        process.env.BLOCKS_ENGINE_FORCE_BOOTSTRAP_FAIL = previousBootstrapFail;
+      }
+    }
+
+    expect(events.some((event) => event.type === 'pool-degraded')).toBe(true);
+    expect(events.filter((event) => event.type === 'sentinel')).toHaveLength(1);
+  }, 10_000);
+});
diff --git a/packages/blocks-engine/src/__tests__/pool.events.test.ts b/packages/blocks-engine/src/__tests__/pool.events.test.ts
new file mode 100644
index 00000000..5b8d7bf0
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/pool.events.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+
+import { createWorker, type PoolEvent } from '../pool/pool';
+import { crashAlwaysInput, fixtureFor } from './pool-test-helpers';
+
+describe('worker pool telemetry events', () => {
+  it('emits one sentinel event per passthrough item and puts count on every event', async () => {
+    const previousMode = process.env.BLOCKS_ENGINE_WORKER_TEST_MODE;
+    process.env.BLOCKS_ENGINE_WORKER_TEST_MODE = '1';
+
+    const fixture = fixtureFor('rawConvert');
+    const events: PoolEvent[] = [];
+    const pool = createWorker({
+      size: 2,
+      maxReroutes: 1,
+      onEvent: (event) => events.push(event),
+    });
+
+    try {
+      await expect(
+        pool.rawConvert([crashAlwaysInput(fixture.input), crashAlwaysInput(fixture.input)]),
+      ).resolves.toEqual([
+        { html: null, wpHtmlResidue: Infinity },
+        { html: null, wpHtmlResidue: Infinity },
+      ]);
+    } finally {
+      await pool.stop();
+      if (previousMode === undefined) {
+        delete process.env.BLOCKS_ENGINE_WORKER_TEST_MODE;
+      } else {
+        process.env.BLOCKS_ENGINE_WORKER_TEST_MODE = previousMode;
+      }
+    }
+
+    expect(events.length).toBeGreaterThan(0);
+    expect(events.every((event) => typeof event.count === 'number')).toBe(true);
+    expect(events.filter((event) => event.type === 'sentinel')).toHaveLength(2);
+  }, 20_000);
+});
diff --git a/packages/blocks-engine/src/__tests__/pool.order.test.ts b/packages/blocks-engine/src/__tests__/pool.order.test.ts
new file mode 100644
index 00000000..b5c1c189
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/pool.order.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+
+import { createWorker, type PoolEvent } from '../pool/pool';
+import {
+  delayedInput,
+  fixtureFor,
+  fixturesFor,
+  pidIsAlive,
+  testWorkerEnv,
+} from './pool-test-helpers';
+
+describe('worker pool ordered batches', () => {
+  it('returns rawConvert results 1:1 in input order when the first item completes later', async () => {
+    const [first, second] = fixturesFor('rawConvert');
+    const pool = createWorker({
+      size: 2,
+      onEvent: () => {},
+    });
+
+    const previousMode = process.env.BLOCKS_ENGINE_WORKER_TEST_MODE;
+    process.env.BLOCKS_ENGINE_WORKER_TEST_MODE = '1';
+    try {
+      await expect(pool.rawConvert([delayedInput(first.input), second.input])).resolves.toEqual([
+        first.expected,
+        second.expected,
+      ]);
+    } finally {
+      await pool.stop();
+      if (previousMode === undefined) {
+        delete process.env.BLOCKS_ENGINE_WORKER_TEST_MODE;
+      } else {
+        process.env.BLOCKS_ENGINE_WORKER_TEST_MODE = previousMode;
+      }
+    }
+  }, 20_000);
+
+  it('returns canonicalize results 1:1 in input order when the first item completes later', async () => {
+    const [first, second] = fixturesFor('canonicalize');
+    const pool = createWorker({ size: 2 });
+
+    const previousMode = process.env.BLOCKS_ENGINE_WORKER_TEST_MODE;
+    process.env.BLOCKS_ENGINE_WORKER_TEST_MODE = '1';
+    try {
+      await expect(pool.canonicalize([delayedInput(first.input), second.input])).resolves.toEqual([
+        first.expected,
+        second.expected,
+      ]);
+    } finally {
+      await pool.stop();
+      if (previousMode === undefined) {
+        delete process.env.BLOCKS_ENGINE_WORKER_TEST_MODE;
+      } else {
+        process.env.BLOCKS_ENGINE_WORKER_TEST_MODE = previousMode;
+      }
+    }
+  }, 20_000);
+
+  it('returns empty batches without starting children', async () => {
+    const events: PoolEvent[] = [];
+    const pool = createWorker({ size: 2, onEvent: (event) => events.push(event) });
+
+    await expect(pool.rawConvert([])).resolves.toEqual([]);
+    await expect(pool.canonicalize([])).resolves.toEqual([]);
+    await pool.stop();
+    await pool.stop();
+
+    expect(events).toEqual([]);
+  });
+
+  it('stop resolves after terminating spawned children', async () => {
+    const pids: number[] = [];
+    const fixture = fixtureFor('rawConvert');
+    const pool = createWorker({
+      size: 2,
+      onEvent: (event) => {
+        if (event.type === 'child-spawn' && event.childId !== undefined) {
+          pids.push(event.childId);
+        }
+      },
+    });
+
+    await expect(pool.rawConvert([fixture.input])).resolves.toEqual([fixture.expected]);
+    await pool.stop();
+    await pool.stop();
+
+    expect(pids.length).toBeGreaterThan(0);
+    expect(pids.every((pid) => !pidIsAlive(pid))).toBe(true);
+  }, 20_000);
+});
diff --git a/packages/blocks-engine/src/__tests__/pool.purity.test.ts b/packages/blocks-engine/src/__tests__/pool.purity.test.ts
new file mode 100644
index 00000000..202b7ba3
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/pool.purity.test.ts
@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+const forbiddenImports = [
+  '@wordpress/blocks',
+  'react',
+  '../wp',
+  '../wp/raw-convert',
+  '../wp/canonicalize',
+  '../wp/bootstrap',
+];
+
+function runtimeImports(source: string): string[] {
+  return source
+    .split('\n')
+    .filter((line) => /^\s*import(?!\s+type)\b/.test(line))
+    .map((line) => line.trim());
+}
+
+describe('worker pool parent purity', () => {
+  it('keeps pool.ts and events.ts free of React and /wp runtime imports', () => {
+    const poolSource = readFileSync(resolve('src/pool/pool.ts'), 'utf8');
+    const eventsSource = readFileSync(resolve('src/pool/events.ts'), 'utf8');
+    const imports = [...runtimeImports(poolSource), ...runtimeImports(eventsSource)];
+
+    for (const source of forbiddenImports) {
+      expect(imports, `runtime import of ${source}`).not.toEqual(
+        expect.arrayContaining([expect.stringContaining(`'${source}'`)]),
+      );
+      expect(imports, `runtime import of ${source}`).not.toEqual(
+        expect.arrayContaining([expect.stringContaining(`"${source}"`)]),
+      );
+    }
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/pool.recycle.test.ts b/packages/blocks-engine/src/__tests__/pool.recycle.test.ts
new file mode 100644
index 00000000..9f417d89
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/pool.recycle.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+
+import { createWorker, type PoolEvent } from '../pool/pool';
+import { fixturesFor } from './pool-test-helpers';
+
+describe('worker pool recycle', () => {
+  it('recycles a child after the configured processed count boundary', async () => {
+    const rawFixtures = fixturesFor('rawConvert');
+    const batch = Array.from({ length: 7 }, (_value, index) => {
+      return rawFixtures[index % rawFixtures.length];
+    });
+    const events: PoolEvent[] = [];
+    const pool = createWorker({
+      size: 1,
+      recycleAfter: 3,
+      onEvent: (event) => events.push(event),
+    });
+
+    try {
+      await expect(pool.rawConvert(batch.map((fixture) => fixture.input))).resolves.toEqual(
+        batch.map((fixture) => fixture.expected),
+      );
+    } finally {
+      await pool.stop();
+    }
+
+    const spawnedPids = events
+      .filter((event) => event.type === 'child-spawn')
+      .map((event) => event.childId)
+      .filter((pid): pid is number => pid !== undefined);
+    const recycleCounts = events
+      .filter((event) => event.type === 'recycle')
+      .map((event) => event.count);
+
+    expect(new Set(spawnedPids).size).toBeGreaterThanOrEqual(3);
+    expect(recycleCounts).toEqual([3, 6]);
+  }, 30_000);
+});
diff --git a/packages/blocks-engine/src/__tests__/worker-child.test.ts b/packages/blocks-engine/src/__tests__/worker-child.test.ts
new file mode 100644
index 00000000..8d5e068f
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/worker-child.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  cleanupChild,
+  fixtureFor,
+  forkTestWorker,
+  sendWorkerMessage,
+} from './pool-test-helpers';
+
+describe('worker child IPC', () => {
+  it('runs rawConvert and canonicalize through a real forked child', async () => {
+    const child = forkTestWorker();
+    const rawFixture = fixtureFor('rawConvert');
+    const canonicalizeFixture = fixtureFor('canonicalize');
+
+    try {
+      await expect(
+        sendWorkerMessage(child, {
+          id: 1,
+          op: 'rawConvert',
+          payload: rawFixture.input,
+        }),
+      ).resolves.toEqual({ id: 1, result: rawFixture.expected });
+
+      await expect(
+        sendWorkerMessage(child, {
+          id: 2,
+          op: 'canonicalize',
+          payload: canonicalizeFixture.input,
+        }),
+      ).resolves.toEqual({ id: 2, result: canonicalizeFixture.expected });
+    } finally {
+      await cleanupChild(child);
+    }
+  }, 20_000);
+});
diff --git a/packages/blocks-engine/src/pool/pool.ts b/packages/blocks-engine/src/pool/pool.ts
index 1ab9d254..26327fcb 100644
--- a/packages/blocks-engine/src/pool/pool.ts
+++ b/packages/blocks-engine/src/pool/pool.ts
@@ -1,4 +1,17 @@
-import type { CreateWorker, WorkerPoolOptions } from './types';
+import { fork, type ChildProcess } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { cpus } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { ChildToParentMessage, WorkerOp } from './protocol';
+import type {
+  CreateWorker,
+  FixResult,
+  RawConvertResult,
+  WorkerPool,
+  WorkerPoolOptions,
+} from './types';
 
 export type {
   FixResult,
@@ -8,16 +21,523 @@ export type {
 } from './types';
 export type { PoolEvent } from './events';
 
-export const createWorker: CreateWorker = (opts?: WorkerPoolOptions) => {
-  void opts;
+const DEFAULT_MAX_REROUTES = 2;
+const DEFAULT_ITEM_TIMEOUT_MS = 10_000;
+const STOP_GRACE_MS = 10_000;
+const BOOTSTRAP_FAIL_EXIT_CODE = 87;
+
+type PoolEventType =
+  | 'child-spawn'
+  | 'child-crash'
+  | 're-route'
+  | 'recycle'
+  | 'sentinel'
+  | 'pool-degraded';
+
+type BatchResultByOp = {
+  rawConvert: RawConvertResult;
+  canonicalize: FixResult;
+};
+
+type BatchItem = {
+  index: number;
+  input: string;
+  payload: string;
+  reroutes: number;
+};
+
+type BatchState = {
+  op: WorkerOp;
+  items: string[];
+  queue: BatchItem[];
+  results: Array<RawConvertResult | FixResult | undefined>;
+  remaining: number;
+  bootstrapFailedSlots: Set<WorkerSlot>;
+  degraded: boolean;
+  done: boolean;
+  resolve: (results: Array<RawConvertResult | FixResult>) => void;
+};
+
+type InFlight = {
+  id: number;
+  batch: BatchState;
+  item: BatchItem;
+  timer: ReturnType<typeof setTimeout>;
+};
+
+type WorkerSlot = {
+  child: ChildProcess | null;
+  inFlight: InFlight | null;
+  processed: number;
+  recycling: boolean;
+  stopping: boolean;
+};
+
+function defaultSize(): number {
+  return Math.max(1, Math.min(cpus().length, 4));
+}
+
+function normalizeSize(size: number | undefined): number {
+  if (size === undefined) {
+    return defaultSize();
+  }
+  return Math.max(1, Math.floor(size));
+}
+
+function workerChildPath(): string {
+  const here = fileURLToPath(import.meta.url);
+  const poolDir = dirname(here);
+  const sourcePath = resolve(poolDir, '..', 'wp', 'worker-child.ts');
+  if (existsSync(sourcePath)) {
+    return sourcePath;
+  }
+  return resolve(poolDir, '..', 'wp', 'worker-child.js');
+}
+
+function forkExecArgv(path: string): string[] {
+  if (!path.endsWith('.ts')) {
+    return process.execArgv;
+  }
+  if (process.execArgv.includes('tsx')) {
+    return process.execArgv;
+  }
+  return [...process.execArgv, '--import', 'tsx'];
+}
+
+function rawSentinel(): RawConvertResult {
+  return { html: null, wpHtmlResidue: Infinity };
+}
+
+function canonicalizeSentinel(html: string): FixResult {
+  return { html, changed: false, fixedIssues: [] };
+}
+
+function sentinelFor<Op extends WorkerOp>(
+  op: Op,
+  input: string,
+): BatchResultByOp[Op] {
+  return (op === 'rawConvert' ? rawSentinel() : canonicalizeSentinel(input)) as BatchResultByOp[Op];
+}
+
+function isTestMode(): boolean {
+  return process.env.BLOCKS_ENGINE_WORKER_TEST_MODE === '1';
+}
+
+function stripCrashOnceMarker(payload: string): string {
+  if (!isTestMode()) {
+    return payload;
+  }
+  return payload.replace(/^<!-- BLOCKS_ENGINE_TEST_CRASH_ONCE -->/, '');
+}
+
+function stopChild(child: ChildProcess, graceMs = STOP_GRACE_MS): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve) => {
+    let killTimer: ReturnType<typeof setTimeout> | undefined;
+    const onExit = (): void => {
+      if (killTimer) {
+        clearTimeout(killTimer);
+      }
+      resolve();
+    };
+    child.once('exit', onExit);
+
+    try {
+      child.kill('SIGTERM');
+    } catch {
+      onExit();
+      return;
+    }
+
+    killTimer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        // already dead
+      }
+    }, graceMs);
+    killTimer.unref();
+  });
+}
+
+class WorkerPoolImpl implements WorkerPool {
+  private readonly size: number;
+  private readonly recycleAfter: number;
+  private readonly maxReroutes: number;
+  private readonly itemTimeoutMs: number;
+  private readonly onEvent: WorkerPoolOptions['onEvent'];
+  private readonly slots: WorkerSlot[] = [];
+  private readonly path = workerChildPath();
+  private eventCount = 0;
+  private sentinelCount = 0;
+  private nextMessageId = 1;
+  private stopped = false;
+  private chain: Promise<unknown> = Promise.resolve();
+
+  constructor(opts: WorkerPoolOptions = {}) {
+    this.size = normalizeSize(opts.size);
+    this.recycleAfter = opts.recycleAfter ?? 0;
+    this.maxReroutes = opts.maxReroutes ?? DEFAULT_MAX_REROUTES;
+    this.itemTimeoutMs = opts.itemTimeoutMs ?? DEFAULT_ITEM_TIMEOUT_MS;
+    this.onEvent = opts.onEvent;
+  }
+
+  rawConvert(items: string[]): Promise<RawConvertResult[]> {
+    return this.enqueue(() => this.runBatch('rawConvert', items));
+  }
+
+  canonicalize(items: string[]): Promise<FixResult[]> {
+    return this.enqueue(() => this.runBatch('canonicalize', items));
+  }
+
+  async stop(): Promise<void> {
+    this.stopped = true;
+    const children = this.slots
+      .map((slot) => slot.child)
+      .filter((child): child is ChildProcess => child !== null);
+
+    for (const slot of this.slots) {
+      slot.stopping = true;
+      if (slot.inFlight) {
+        clearTimeout(slot.inFlight.timer);
+        slot.inFlight = null;
+      }
+    }
+
+    await Promise.all(children.map((child) => stopChild(child)));
+    this.slots.length = 0;
+  }
+
+  private enqueue<T>(work: () => Promise<T>): Promise<T> {
+    const next = this.chain.then(work, work);
+    this.chain = next.catch(() => undefined);
+    return next;
+  }
+
+  private async runBatch<Op extends WorkerOp>(
+    op: Op,
+    items: string[],
+  ): Promise<BatchResultByOp[Op][]> {
+    if (items.length === 0) {
+      return [];
+    }
+
+    this.stopped = false;
+    this.ensureStarted();
+
+    return new Promise((resolve) => {
+      const batch: BatchState = {
+        op,
+        items,
+        queue: items.map((input, index) => ({
+          index,
+          input,
+          payload: input,
+          reroutes: 0,
+        })),
+        results: Array.from({ length: items.length }),
+        remaining: items.length,
+        bootstrapFailedSlots: new Set(),
+        degraded: false,
+        done: false,
+        resolve: (results) => resolve(results as BatchResultByOp[Op][]),
+      };
 
-  const notImplemented = async (): Promise<never> => {
-    throw new Error('createWorker implementation is added by Phase C');
-  };
+      this.dispatch(batch);
+    });
+  }
 
-  return {
-    rawConvert: notImplemented,
-    canonicalize: notImplemented,
-    stop: async () => {},
-  };
+  private ensureStarted(): void {
+    while (this.slots.length < this.size) {
+      this.slots.push({
+        child: null,
+        inFlight: null,
+        processed: 0,
+        recycling: false,
+        stopping: false,
+      });
+    }
+
+    for (const slot of this.slots) {
+      if (!slot.child) {
+        this.spawn(slot);
+      }
+    }
+  }
+
+  private spawn(slot: WorkerSlot): void {
+    slot.stopping = false;
+    slot.recycling = false;
+    slot.inFlight = null;
+
+    const child = fork(this.path, [], {
+      env: process.env,
+      execArgv: forkExecArgv(this.path),
+      stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+    });
+    slot.child = child;
+
+    this.emit({ type: 'child-spawn', childId: child.pid });
+
+    child.on('message', (message) => this.handleMessage(slot, message as ChildToParentMessage));
+    child.on('exit', (code, signal) => this.handleExit(slot, code, signal));
+    child.on('error', () => {
+      this.emit({ type: 'child-crash', childId: child.pid });
+    });
+  }
+
+  private dispatch(batch: BatchState): void {
+    if (batch.done || batch.degraded || this.stopped) {
+      return;
+    }
+
+    for (const slot of this.slots) {
+      if (batch.queue.length === 0) {
+        return;
+      }
+      if (!slot.child || slot.inFlight || slot.recycling || slot.stopping) {
+        continue;
+      }
+      if (batch.bootstrapFailedSlots.has(slot)) {
+        continue;
+      }
+      if (this.recycleAfter > 0 && slot.processed >= this.recycleAfter) {
+        void this.recycle(slot, batch);
+        continue;
+      }
+
+      const item = batch.queue.shift();
+      if (!item) {
+        return;
+      }
+      this.assign(slot, batch, item);
+    }
+  }
+
+  private assign(
+    slot: WorkerSlot,
+    batch: BatchState,
+    item: BatchItem,
+  ): void {
+    const child = slot.child;
+    if (!child || !child.connected) {
+      batch.queue.unshift(item);
+      return;
+    }
+
+    const id = this.nextMessageId++;
+    const timer = setTimeout(() => this.handleTimeout(slot), this.itemTimeoutMs);
+    timer.unref();
+
+    slot.inFlight = { id, batch, item, timer };
+    child.send(
+      {
+        id,
+        op: batch.op,
+        payload: item.payload,
+      },
+      (error) => {
+        if (error) {
+          this.handleFailure(slot, slot.inFlight, 'send-error');
+        }
+      },
+    );
+  }
+
+  private handleMessage(slot: WorkerSlot, message: ChildToParentMessage): void {
+    const inFlight = slot.inFlight;
+    if (!inFlight || inFlight.id !== message.id) {
+      return;
+    }
+
+    clearTimeout(inFlight.timer);
+    slot.inFlight = null;
+
+    if ('error' in message) {
+      this.handleFailure(slot, inFlight, 'worker-error');
+      return;
+    }
+
+    this.completeItem(inFlight.batch, inFlight.item.index, message.result);
+    slot.processed += 1;
+    this.dispatch(inFlight.batch);
+  }
+
+  private handleTimeout(slot: WorkerSlot): void {
+    const inFlight = slot.inFlight;
+    if (!inFlight) {
+      return;
+    }
+
+    slot.inFlight = null;
+    this.handleFailure(slot, inFlight, 'timeout');
+
+    try {
+      slot.child?.kill('SIGKILL');
+    } catch {
+      // already dead
+    }
+  }
+
+  private handleExit(
+    slot: WorkerSlot,
+    code: number | null,
+    signal: NodeJS.Signals | null,
+  ): void {
+    const childId = slot.child?.pid;
+    const inFlight = slot.inFlight;
+    slot.child = null;
+    slot.inFlight = null;
+
+    if (inFlight) {
+      clearTimeout(inFlight.timer);
+    }
+
+    const intentional = slot.stopping || slot.recycling || this.stopped;
+    if (!intentional) {
+      this.emit({ type: 'child-crash', childId });
+      if (inFlight && code === BOOTSTRAP_FAIL_EXIT_CODE) {
+        this.handleBootstrapFailure(slot, inFlight);
+      } else if (inFlight) {
+        this.handleFailure(slot, inFlight, `exit:${code ?? signal ?? 'unknown'}`);
+      }
+      if (!inFlight?.batch.degraded) {
+        slot.processed = 0;
+        this.spawn(slot);
+        if (inFlight) {
+          this.dispatch(inFlight.batch);
+        }
+      }
+    }
+  }
+
+  private handleBootstrapFailure(slot: WorkerSlot, inFlight: InFlight): void {
+    const batch = inFlight.batch;
+    if (batch.done || batch.degraded) {
+      return;
+    }
+
+    batch.bootstrapFailedSlots.add(slot);
+    if (batch.bootstrapFailedSlots.size < this.size) {
+      batch.queue.unshift(inFlight.item);
+      return;
+    }
+
+    batch.degraded = true;
+    this.emit({ type: 'pool-degraded' });
+
+    for (const slot of this.slots) {
+      if (slot.inFlight?.batch === batch) {
+        clearTimeout(slot.inFlight.timer);
+        slot.inFlight = null;
+      }
+    }
+    batch.queue.length = 0;
+
+    for (let index = 0; index < batch.items.length; index++) {
+      if (batch.results[index] === undefined) {
+        this.emitSentinel();
+        batch.results[index] = sentinelFor(batch.op, batch.items[index]);
+      }
+    }
+
+    batch.remaining = 0;
+    this.finish(batch);
+  }
+
+  private handleFailure(
+    slot: WorkerSlot,
+    inFlight: InFlight | null,
+    _reason: string,
+  ): void {
+    if (!inFlight || inFlight.batch.done || inFlight.batch.degraded) {
+      return;
+    }
+
+    clearTimeout(inFlight.timer);
+    const { batch, item } = inFlight;
+    if (item.reroutes >= this.maxReroutes) {
+      this.emitSentinel();
+      this.completeItem(batch, item.index, sentinelFor(batch.op, item.input));
+      this.dispatch(batch);
+      return;
+    }
+
+    item.reroutes += 1;
+    item.payload = stripCrashOnceMarker(item.payload);
+    this.emit({ type: 're-route', childId: slot.child?.pid, count: item.reroutes });
+    batch.queue.unshift(item);
+    this.dispatch(batch);
+  }
+
+  private completeItem(
+    batch: BatchState,
+    index: number,
+    result: RawConvertResult | FixResult,
+  ): void {
+    if (batch.done || batch.results[index] !== undefined) {
+      return;
+    }
+
+    batch.results[index] = result;
+    batch.remaining -= 1;
+    this.finish(batch);
+  }
+
+  private finish(batch: BatchState): void {
+    if (batch.done || batch.remaining > 0) {
+      return;
+    }
+
+    batch.done = true;
+    batch.resolve(batch.results as Array<RawConvertResult | FixResult>);
+  }
+
+  private async recycle(slot: WorkerSlot, batch: BatchState): Promise<void> {
+    const child = slot.child;
+    if (!child || slot.recycling) {
+      return;
+    }
+
+    slot.recycling = true;
+    this.emit({
+      type: 'recycle',
+      childId: child.pid,
+      count: batch.items.length - batch.remaining,
+    });
+    await stopChild(child);
+
+    slot.child = null;
+    slot.processed = 0;
+    slot.recycling = false;
+
+    if (!this.stopped && !batch.done) {
+      this.spawn(slot);
+      this.dispatch(batch);
+    }
+  }
+
+  private emitSentinel(): void {
+    this.sentinelCount += 1;
+    this.emit({ type: 'sentinel', count: this.sentinelCount });
+  }
+
+  private emit(event: {
+    type: PoolEventType;
+    childId?: number;
+    count?: number;
+  }): void {
+    this.eventCount += 1;
+    this.onEvent?.({
+      ...event,
+      count: event.count ?? this.eventCount,
+    });
+  }
+}
+
+export const createWorker: CreateWorker = (opts?: WorkerPoolOptions) => {
+  return new WorkerPoolImpl(opts);
 };
diff --git a/packages/blocks-engine/src/wp/worker-child.ts b/packages/blocks-engine/src/wp/worker-child.ts
new file mode 100644
index 00000000..236ab7f0
--- /dev/null
+++ b/packages/blocks-engine/src/wp/worker-child.ts
@@ -0,0 +1,129 @@
+import { bootstrap } from './bootstrap';
+import { canonicalize } from './canonicalize';
+import { rawConvert } from './raw-convert';
+import type {
+  ChildToParentMessage,
+  ParentToChildMessage,
+  WorkerError,
+} from '../pool/protocol';
+
+const POISON_EXIT_CODE = 86;
+const BOOTSTRAP_FAIL_EXIT_CODE = 87;
+
+let bootstrapped = false;
+let hangRef: ReturnType<typeof setInterval> | undefined;
+
+function testMode(): boolean {
+  return process.env.BLOCKS_ENGINE_WORKER_TEST_MODE === '1';
+}
+
+function serializeError(error: unknown): WorkerError {
+  if (error instanceof Error) {
+    return {
+      message: error.message,
+      name: error.name,
+      stack: error.stack,
+    };
+  }
+  return { message: String(error) };
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
+
+function preparePayload(payload: string): {
+  payload: string;
+  delayMs: number;
+  crash: boolean;
+  hang: boolean;
+} {
+  if (!testMode()) {
+    return { payload, delayMs: 0, crash: false, hang: false };
+  }
+
+  let nextPayload = payload;
+  let delayMs = 0;
+  let crash = false;
+  let hang = false;
+  let changed = true;
+
+  while (changed) {
+    changed = false;
+
+    const delayMatch = nextPayload.match(/^<!-- BLOCKS_ENGINE_TEST_DELAY:(\d+) -->/);
+    if (delayMatch) {
+      delayMs = Number(delayMatch[1]);
+      nextPayload = nextPayload.slice(delayMatch[0].length);
+      changed = true;
+      continue;
+    }
+
+    if (nextPayload.startsWith('<!-- BLOCKS_ENGINE_TEST_CRASH_ONCE -->')) {
+      crash = true;
+      nextPayload = nextPayload.slice('<!-- BLOCKS_ENGINE_TEST_CRASH_ONCE -->'.length);
+      changed = true;
+      continue;
+    }
+
+    if (nextPayload.startsWith('<!-- BLOCKS_ENGINE_TEST_CRASH_ALWAYS -->')) {
+      crash = true;
+      nextPayload = nextPayload.slice('<!-- BLOCKS_ENGINE_TEST_CRASH_ALWAYS -->'.length);
+      changed = true;
+      continue;
+    }
+
+    if (nextPayload.startsWith('<!-- BLOCKS_ENGINE_TEST_HANG -->')) {
+      hang = true;
+      nextPayload = nextPayload.slice('<!-- BLOCKS_ENGINE_TEST_HANG -->'.length);
+      changed = true;
+    }
+  }
+
+  return { payload: nextPayload, delayMs, crash, hang };
+}
+
+function send(message: ChildToParentMessage): void {
+  process.send?.(message);
+}
+
+process.on('message', async (message: ParentToChildMessage) => {
+  const { id, op } = message;
+
+  try {
+    if (testMode() && process.env.BLOCKS_ENGINE_FORCE_BOOTSTRAP_FAIL === '1') {
+      process.exit(BOOTSTRAP_FAIL_EXIT_CODE);
+    }
+
+    const prepared = preparePayload(message.payload);
+    if (prepared.crash) {
+      process.exit(POISON_EXIT_CODE);
+    }
+    if (prepared.hang) {
+      hangRef ??= setInterval(() => {}, 1_000);
+      return;
+    }
+    if (prepared.delayMs > 0) {
+      await delay(prepared.delayMs);
+    }
+
+    if (!bootstrapped) {
+      bootstrap();
+      bootstrapped = true;
+    }
+
+    if (op === 'rawConvert') {
+      send({ id, result: rawConvert(prepared.payload) });
+      return;
+    }
+
+    if (op === 'canonicalize') {
+      send({ id, result: canonicalize(prepared.payload) });
+      return;
+    }
+
+    send({ id, error: { message: `Unknown worker op: ${String(op)}` } });
+  } catch (error) {
+    send({ id, error: serializeError(error) });
+  }
+});
diff --git a/packages/blocks-engine/tsup.config.ts b/packages/blocks-engine/tsup.config.ts
index b9aa4d17..900e3231 100644
--- a/packages/blocks-engine/tsup.config.ts
+++ b/packages/blocks-engine/tsup.config.ts
@@ -1,8 +1,7 @@
 import { defineConfig } from 'tsup';
 
 export default defineConfig({
-  // Note: src/wp/worker-child.ts entry is added by a later task (C phase)
-  entry: ['src/index.ts', 'src/wp/index.ts'],
+  entry: ['src/index.ts', 'src/wp/index.ts', 'src/wp/worker-child.ts'],
   format: ['esm', 'cjs'],
   dts: true,
   clean: true,

From 817a3421bc344b7c70e8c0c673b58c44c53b1f16 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 21:36:37 -0400
Subject: [PATCH 008/113] fix(blocks-engine): resolve in-flight batches to
 sentinels on stop()

---
 .../src/__tests__/pool.stop.test.ts           | 316 ++++++++++++++++++
 packages/blocks-engine/src/pool/pool.ts       | 136 ++++++--
 2 files changed, 428 insertions(+), 24 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/pool.stop.test.ts

diff --git a/packages/blocks-engine/src/__tests__/pool.stop.test.ts b/packages/blocks-engine/src/__tests__/pool.stop.test.ts
new file mode 100644
index 00000000..110cc6ff
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/pool.stop.test.ts
@@ -0,0 +1,316 @@
+import type { ChildProcess } from 'node:child_process';
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createWorker } from '../pool/pool';
+import { crashAlwaysInput, fixtureFor, hangInput, withTimeout } from './pool-test-helpers';
+
+const childActivity = vi.hoisted(() => {
+  type Waiter = { target: number; resolve: () => void };
+
+  const state = {
+    sends: 0,
+    responses: 0,
+    exits: 0,
+    sendWaiters: [] as Waiter[],
+    responseWaiters: [] as Waiter[],
+    exitWaiters: [] as Waiter[],
+  };
+
+  function resolveReady(waiters: Waiter[], count: number): Waiter[] {
+    const pending: Waiter[] = [];
+    for (const waiter of waiters) {
+      if (count >= waiter.target) {
+        waiter.resolve();
+      } else {
+        pending.push(waiter);
+      }
+    }
+    return pending;
+  }
+
+  return {
+    reset(): void {
+      state.sends = 0;
+      state.responses = 0;
+      state.exits = 0;
+      state.sendWaiters = [];
+      state.responseWaiters = [];
+      state.exitWaiters = [];
+    },
+    noteSend(): void {
+      state.sends += 1;
+      state.sendWaiters = resolveReady(state.sendWaiters, state.sends);
+    },
+    noteResponse(): void {
+      state.responses += 1;
+      state.responseWaiters = resolveReady(state.responseWaiters, state.responses);
+    },
+    noteExit(): void {
+      state.exits += 1;
+      state.exitWaiters = resolveReady(state.exitWaiters, state.exits);
+    },
+    exitCount(): number {
+      return state.exits;
+    },
+    waitForSends(target: number): Promise<void> {
+      if (state.sends >= target) {
+        return Promise.resolve();
+      }
+      return new Promise((resolve) => state.sendWaiters.push({ target, resolve }));
+    },
+    waitForResponses(target: number): Promise<void> {
+      if (state.responses >= target) {
+        return Promise.resolve();
+      }
+      return new Promise((resolve) => state.responseWaiters.push({ target, resolve }));
+    },
+    waitForExits(target: number): Promise<void> {
+      if (state.exits >= target) {
+        return Promise.resolve();
+      }
+      return new Promise((resolve) => state.exitWaiters.push({ target, resolve }));
+    },
+  };
+});
+
+vi.mock('node:child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:child_process')>();
+  const fork = ((...args: unknown[]) => {
+    const child = Reflect.apply(actual.fork, actual, args) as ChildProcess;
+    const originalSend = child.send.bind(child) as (
+      ...sendArgs: Parameters<ChildProcess['send']>
+    ) => boolean;
+
+    child.send = ((...sendArgs: Parameters<ChildProcess['send']>) => {
+      childActivity.noteSend();
+      return originalSend(...sendArgs);
+    }) as ChildProcess['send'];
+
+    child.on('message', () => childActivity.noteResponse());
+    child.once('exit', () => childActivity.noteExit());
+    return child;
+  }) as typeof actual.fork;
+
+  return { ...actual, fork };
+});
+
+function withTestMode<T>(fn: () => Promise<T>): Promise<T> {
+  const previousMode = process.env.BLOCKS_ENGINE_WORKER_TEST_MODE;
+  process.env.BLOCKS_ENGINE_WORKER_TEST_MODE = '1';
+
+  return fn().finally(() => {
+    if (previousMode === undefined) {
+      delete process.env.BLOCKS_ENGINE_WORKER_TEST_MODE;
+    } else {
+      process.env.BLOCKS_ENGINE_WORKER_TEST_MODE = previousMode;
+    }
+  });
+}
+
+async function waitForSecondItemInFlight(): Promise<void> {
+  await withLabel('first worker response', childActivity.waitForResponses(1), 15_000);
+  await withLabel('second worker send', childActivity.waitForSends(2), 15_000);
+}
+
+async function withLabel<T>(
+  label: string,
+  promise: Promise<T>,
+  timeoutMs = 3_000,
+): Promise<T> {
+  try {
+    return await withTimeout(promise, timeoutMs);
+  } catch (error) {
+    throw new Error(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+describe('worker pool stop during in-flight batches', () => {
+  beforeEach(() => {
+    childActivity.reset();
+  });
+
+  it('resolves a stopped rawConvert batch to the oracle sentinel shape', async () =>
+    withTestMode(async () => {
+      const fixture = fixtureFor('rawConvert', 1);
+      const pool = createWorker({ size: 1 });
+
+      try {
+        const batch = pool.rawConvert([hangInput(fixture.input)]);
+        await withLabel('rawConvert worker send', childActivity.waitForSends(1));
+
+        const stopped = pool.stop();
+        await expect(withLabel('stopped rawConvert batch', batch)).resolves.toEqual([
+          { html: null, wpHtmlResidue: Infinity },
+        ]);
+        await withLabel('stop after rawConvert batch', stopped);
+      } finally {
+        await pool.stop();
+      }
+    }), 20_000);
+
+  it('keeps completed canonicalize results and does not wedge later batches', async () =>
+    withTestMode(async () => {
+      const first = fixtureFor('canonicalize', 0);
+      const second = fixtureFor('canonicalize', 1);
+      const hungInput = hangInput(second.input);
+      const pool = createWorker({ size: 1 });
+
+      try {
+        const batch = pool.canonicalize([first.input, hungInput]);
+        await waitForSecondItemInFlight();
+
+        const stopped = pool.stop();
+        await expect(withLabel('stopped canonicalize batch', batch)).resolves.toEqual([
+          first.expected,
+          { html: hungInput, changed: false, fixedIssues: [] },
+        ]);
+        await withLabel('stop after canonicalize batch', stopped);
+
+        await expect(withLabel('empty batch after stop', pool.canonicalize([]))).resolves.toEqual([]);
+      } finally {
+        await pool.stop();
+      }
+    }), 20_000);
+
+  it('does not wedge a non-empty batch queued before stop settles the in-flight batch', async () =>
+    withTestMode(async () => {
+      const first = fixtureFor('canonicalize', 0);
+      const second = fixtureFor('canonicalize', 1);
+      const third = fixtureFor('canonicalize', 2);
+      const stoppedInput = hangInput(second.input);
+      const queuedInput = crashAlwaysInput(third.input);
+      const pool = createWorker({
+        size: 1,
+        maxReroutes: 0,
+      });
+
+      try {
+        const inFlightBatch = pool.canonicalize([first.input, stoppedInput]);
+        const queuedBatch = pool.canonicalize([queuedInput]);
+        await waitForSecondItemInFlight();
+
+        const stopped = pool.stop();
+        await expect(withLabel('stopped canonicalize batch', inFlightBatch)).resolves.toEqual([
+          first.expected,
+          { html: stoppedInput, changed: false, fixedIssues: [] },
+        ]);
+        await withLabel('stop after canonicalize batch', stopped);
+
+        await expect(withLabel('queued canonicalize batch', queuedBatch)).resolves.toEqual([
+          { html: queuedInput, changed: false, fixedIssues: [] },
+        ]);
+      } finally {
+        await pool.stop();
+      }
+    }), 20_000);
+
+  it('resolves a batch stopped while recycling between items', async () =>
+    withTestMode(async () => {
+      const first = fixtureFor('canonicalize', 0);
+      const second = fixtureFor('canonicalize', 1);
+      let stopDuringRecycle: Promise<void> | undefined;
+      let sawRecycle: () => void = () => {};
+      const recycleSeen = new Promise<void>((resolve) => {
+        sawRecycle = resolve;
+      });
+      const pool = createWorker({
+        size: 1,
+        recycleAfter: 1,
+        onEvent: (event) => {
+          if (event.type === 'recycle' && !stopDuringRecycle) {
+            stopDuringRecycle = pool.stop();
+            sawRecycle();
+          }
+        },
+      });
+
+      try {
+        const batch = pool.canonicalize([first.input, second.input]);
+        await withLabel('recycle event', recycleSeen, 15_000);
+
+        await expect(withLabel('batch stopped during recycle', batch)).resolves.toEqual([
+          first.expected,
+          { html: second.input, changed: false, fixedIssues: [] },
+        ]);
+        await withLabel(
+          'stop during recycle',
+          stopDuringRecycle ?? Promise.reject(new Error('Missing stop during recycle')),
+        );
+      } finally {
+        await pool.stop();
+      }
+    }), 20_000);
+
+  it('resolves a batch stopped from a child-crash event before reroute', async () =>
+    withTestMode(async () => {
+      const fixture = fixtureFor('canonicalize', 0);
+      const input = crashAlwaysInput(fixture.input);
+      let stopDuringCrash: Promise<void> | undefined;
+      let sawCrash: () => void = () => {};
+      const crashSeen = new Promise<void>((resolve) => {
+        sawCrash = resolve;
+      });
+      const pool = createWorker({
+        size: 1,
+        maxReroutes: 2,
+        onEvent: (event) => {
+          if (event.type === 'child-crash' && !stopDuringCrash) {
+            stopDuringCrash = pool.stop();
+            sawCrash();
+          }
+        },
+      });
+
+      try {
+        const batch = pool.canonicalize([input]);
+        await withLabel('child-crash event', crashSeen, 15_000);
+
+        await expect(withLabel('batch stopped during child crash', batch)).resolves.toEqual([
+          { html: input, changed: false, fixedIssues: [] },
+        ]);
+        await withLabel(
+          'stop during child crash',
+          stopDuringCrash ?? Promise.reject(new Error('Missing stop during child crash')),
+        );
+      } finally {
+        await pool.stop();
+      }
+    }), 20_000);
+
+  it('returns the active teardown promise for stop re-entered from sentinel callbacks', async () =>
+    withTestMode(async () => {
+      const fixture = fixtureFor('rawConvert', 1);
+      let nestedStop: Promise<void> | undefined;
+      let nestedResolvedBeforeExit = false;
+      const pool = createWorker({
+        size: 1,
+        onEvent: (event) => {
+          if (event.type === 'sentinel' && !nestedStop) {
+            nestedStop = pool.stop().then(() => {
+              nestedResolvedBeforeExit = childActivity.exitCount() === 0;
+            });
+          }
+        },
+      });
+
+      try {
+        const batch = pool.rawConvert([hangInput(fixture.input)]);
+        await withLabel('rawConvert worker send', childActivity.waitForSends(1));
+
+        const stopped = pool.stop();
+        await expect(withLabel('stopped rawConvert batch', batch)).resolves.toEqual([
+          { html: null, wpHtmlResidue: Infinity },
+        ]);
+        await withLabel(
+          'nested stop from sentinel',
+          nestedStop ?? Promise.reject(new Error('Missing nested stop from sentinel')),
+        );
+        await withLabel('outer stop from sentinel test', stopped);
+        await withLabel('worker exit after sentinel stop', childActivity.waitForExits(1));
+        expect(nestedResolvedBeforeExit).toBe(false);
+      } finally {
+        await pool.stop();
+      }
+    }), 20_000);
+});
diff --git a/packages/blocks-engine/src/pool/pool.ts b/packages/blocks-engine/src/pool/pool.ts
index 26327fcb..e8056277 100644
--- a/packages/blocks-engine/src/pool/pool.ts
+++ b/packages/blocks-engine/src/pool/pool.ts
@@ -68,6 +68,8 @@ type InFlight = {
 type WorkerSlot = {
   child: ChildProcess | null;
   inFlight: InFlight | null;
+  failureInFlight: InFlight | null;
+  recyclingBatch: BatchState | null;
   processed: number;
   recycling: boolean;
   stopping: boolean;
@@ -175,6 +177,8 @@ class WorkerPoolImpl implements WorkerPool {
   private sentinelCount = 0;
   private nextMessageId = 1;
   private stopped = false;
+  private stopping = false;
+  private stopPromise: Promise<void> = Promise.resolve();
   private chain: Promise<unknown> = Promise.resolve();
 
   constructor(opts: WorkerPoolOptions = {}) {
@@ -194,7 +198,54 @@ class WorkerPoolImpl implements WorkerPool {
   }
 
   async stop(): Promise<void> {
+    if (this.stopping) {
+      return this.stopPromise;
+    }
+
     this.stopped = true;
+    this.stopping = true;
+    let resolveStop!: () => void;
+    let rejectStop!: (error: unknown) => void;
+    const stopPromise = new Promise<void>((resolve, reject) => {
+      resolveStop = resolve;
+      rejectStop = reject;
+    });
+    this.stopPromise = stopPromise;
+
+    const finishStop = (): void => {
+      this.stopping = false;
+      this.stopPromise = Promise.resolve();
+    };
+    void this.stopSlots().then(
+      () => {
+        finishStop();
+        resolveStop();
+      },
+      (error: unknown) => {
+        finishStop();
+        rejectStop(error);
+      },
+    );
+    return stopPromise;
+  }
+
+  private async stopSlots(): Promise<void> {
+    const inFlightBatches = new Set<BatchState>();
+    for (const slot of this.slots) {
+      if (slot.inFlight) {
+        inFlightBatches.add(slot.inFlight.batch);
+      }
+      if (slot.failureInFlight) {
+        inFlightBatches.add(slot.failureInFlight.batch);
+      }
+      if (slot.recyclingBatch) {
+        inFlightBatches.add(slot.recyclingBatch);
+      }
+    }
+    for (const batch of inFlightBatches) {
+      this.settleBatchWithSentinels(batch);
+    }
+
     const children = this.slots
       .map((slot) => slot.child)
       .filter((child): child is ChildProcess => child !== null);
@@ -224,6 +275,9 @@ class WorkerPoolImpl implements WorkerPool {
     if (items.length === 0) {
       return [];
     }
+    if (this.stopping) {
+      await this.stopPromise;
+    }
 
     this.stopped = false;
     this.ensureStarted();
@@ -255,6 +309,8 @@ class WorkerPoolImpl implements WorkerPool {
       this.slots.push({
         child: null,
         inFlight: null,
+        failureInFlight: null,
+        recyclingBatch: null,
         processed: 0,
         recycling: false,
         stopping: false,
@@ -271,6 +327,8 @@ class WorkerPoolImpl implements WorkerPool {
   private spawn(slot: WorkerSlot): void {
     slot.stopping = false;
     slot.recycling = false;
+    slot.failureInFlight = null;
+    slot.recyclingBatch = null;
     slot.inFlight = null;
 
     const child = fork(this.path, [], {
@@ -394,23 +452,30 @@ class WorkerPoolImpl implements WorkerPool {
 
     if (inFlight) {
       clearTimeout(inFlight.timer);
+      slot.failureInFlight = inFlight;
     }
 
     const intentional = slot.stopping || slot.recycling || this.stopped;
-    if (!intentional) {
-      this.emit({ type: 'child-crash', childId });
-      if (inFlight && code === BOOTSTRAP_FAIL_EXIT_CODE) {
-        this.handleBootstrapFailure(slot, inFlight);
-      } else if (inFlight) {
-        this.handleFailure(slot, inFlight, `exit:${code ?? signal ?? 'unknown'}`);
-      }
-      if (!inFlight?.batch.degraded) {
-        slot.processed = 0;
-        this.spawn(slot);
-        if (inFlight) {
-          this.dispatch(inFlight.batch);
+    try {
+      if (!intentional) {
+        this.emit({ type: 'child-crash', childId });
+        if (inFlight && code === BOOTSTRAP_FAIL_EXIT_CODE) {
+          this.handleBootstrapFailure(slot, inFlight);
+        } else if (inFlight) {
+          this.handleFailure(slot, inFlight, `exit:${code ?? signal ?? 'unknown'}`);
+        }
+        if (!this.stopped && !inFlight?.batch.degraded) {
+          slot.processed = 0;
+          this.spawn(slot);
+          if (inFlight) {
+            this.dispatch(inFlight.batch);
+          }
         }
       }
+    } finally {
+      if (slot.failureInFlight === inFlight) {
+        slot.failureInFlight = null;
+      }
     }
   }
 
@@ -448,6 +513,20 @@ class WorkerPoolImpl implements WorkerPool {
     this.finish(batch);
   }
 
+  private settleBatchWithSentinels(batch: BatchState): void {
+    if (batch.done) {
+      return;
+    }
+
+    batch.queue.length = 0;
+    for (let index = 0; index < batch.items.length; index++) {
+      if (batch.results[index] === undefined) {
+        this.emitSentinel();
+        this.completeItem(batch, index, sentinelFor(batch.op, batch.items[index]));
+      }
+    }
+  }
+
   private handleFailure(
     slot: WorkerSlot,
     inFlight: InFlight | null,
@@ -457,20 +536,27 @@ class WorkerPoolImpl implements WorkerPool {
       return;
     }
 
-    clearTimeout(inFlight.timer);
-    const { batch, item } = inFlight;
-    if (item.reroutes >= this.maxReroutes) {
-      this.emitSentinel();
-      this.completeItem(batch, item.index, sentinelFor(batch.op, item.input));
+    slot.failureInFlight = inFlight;
+    try {
+      clearTimeout(inFlight.timer);
+      const { batch, item } = inFlight;
+      if (item.reroutes >= this.maxReroutes) {
+        this.emitSentinel();
+        this.completeItem(batch, item.index, sentinelFor(batch.op, item.input));
+        this.dispatch(batch);
+        return;
+      }
+
+      item.reroutes += 1;
+      item.payload = stripCrashOnceMarker(item.payload);
+      this.emit({ type: 're-route', childId: slot.child?.pid, count: item.reroutes });
+      batch.queue.unshift(item);
       this.dispatch(batch);
-      return;
+    } finally {
+      if (slot.failureInFlight === inFlight) {
+        slot.failureInFlight = null;
+      }
     }
-
-    item.reroutes += 1;
-    item.payload = stripCrashOnceMarker(item.payload);
-    this.emit({ type: 're-route', childId: slot.child?.pid, count: item.reroutes });
-    batch.queue.unshift(item);
-    this.dispatch(batch);
   }
 
   private completeItem(
@@ -503,6 +589,7 @@ class WorkerPoolImpl implements WorkerPool {
     }
 
     slot.recycling = true;
+    slot.recyclingBatch = batch;
     this.emit({
       type: 'recycle',
       childId: child.pid,
@@ -513,6 +600,7 @@ class WorkerPoolImpl implements WorkerPool {
     slot.child = null;
     slot.processed = 0;
     slot.recycling = false;
+    slot.recyclingBatch = null;
 
     if (!this.stopped && !batch.done) {
       this.spawn(slot);

From fa9a305863aac2fdcf9c9d4cc66a9edda2de4fe1 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 22:01:53 -0400
Subject: [PATCH 009/113] test(blocks-engine): freeze compose contract

---
 .../src/__tests__/compose.contract.test.ts    | 32 +++++++++++++++++++
 packages/blocks-engine/src/compose.ts         | 11 +++++++
 packages/blocks-engine/src/types.ts           | 18 +++++++++++
 3 files changed, 61 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/compose.contract.test.ts
 create mode 100644 packages/blocks-engine/src/compose.ts
 create mode 100644 packages/blocks-engine/src/types.ts

diff --git a/packages/blocks-engine/src/__tests__/compose.contract.test.ts b/packages/blocks-engine/src/__tests__/compose.contract.test.ts
new file mode 100644
index 00000000..b4b2950f
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/compose.contract.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+
+import { compose } from '../compose';
+import type { ConversionContext, Converter, HtmlFallback, RecipeRule } from '../types';
+
+describe('compose public contract', () => {
+  it('freezes the shared Phase D type surface and compose signature', () => {
+    const ctx: ConversionContext = {
+      url: 'https://example.test/',
+      mediaMap: {
+        'https://cdn.example.test/a.jpg': '/wp-content/uploads/a.jpg',
+      },
+    };
+    const converter: Converter = (html, conversionCtx) => {
+      expect(conversionCtx).toBe(ctx);
+      expect(html).toBe('<p>source</p>');
+      return null;
+    };
+    const recipe: RecipeRule = {
+      match: '.card',
+      block: 'core/group',
+      attrs: { layout: { type: 'constrained' } },
+      inner: 'innerHtml',
+    };
+    const fallback: HtmlFallback = (html) => html.toUpperCase();
+
+    expect(typeof compose).toBe('function');
+    expect(converter('<p>source</p>', ctx)).toBeNull();
+    expect(recipe.inner).toBe('innerHtml');
+    expect(typeof fallback).toBe('function');
+  });
+});
diff --git a/packages/blocks-engine/src/compose.ts b/packages/blocks-engine/src/compose.ts
new file mode 100644
index 00000000..34c2029a
--- /dev/null
+++ b/packages/blocks-engine/src/compose.ts
@@ -0,0 +1,11 @@
+import type { ConversionContext, Converter, HtmlFallback } from './types';
+
+export function compose(
+  html: string,
+  ctx: ConversionContext,
+  opts?: { converters?: Converter[]; htmlFallback?: HtmlFallback },
+): string {
+  void ctx;
+  void opts;
+  return html;
+}
diff --git a/packages/blocks-engine/src/types.ts b/packages/blocks-engine/src/types.ts
new file mode 100644
index 00000000..0e9f436e
--- /dev/null
+++ b/packages/blocks-engine/src/types.ts
@@ -0,0 +1,18 @@
+export interface ConversionContext {
+  url: string;
+  mediaMap?: Record<string, string>;
+}
+
+export type Converter = (
+  html: string,
+  ctx: ConversionContext,
+) => string | null;
+
+export interface RecipeRule {
+  match: string;
+  block: string;
+  attrs?: Record<string, unknown>;
+  inner?: 'innerHtml' | 'text' | 'images' | 'drop';
+}
+
+export type HtmlFallback = string | ((html: string) => string);

From 215c38c4fb2cec7f490f626d4705d2115219afd2 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 22:06:17 -0400
Subject: [PATCH 010/113] feat(blocks-engine): port pure helper modules

---
 .../blocks-engine/src/__tests__/embed.test.ts |  65 ++++++++
 .../src/__tests__/escape.test.ts              |  17 ++
 .../src/__tests__/heuristics.test.ts          |  49 ++++++
 .../src/__tests__/output-verify.test.ts       |  50 ++++++
 .../src/__tests__/validate.test.ts            |  28 ++++
 packages/blocks-engine/src/embed.ts           |  52 ++++++
 packages/blocks-engine/src/escape.ts          |  19 +++
 packages/blocks-engine/src/heuristics.ts      | 153 ++++++++++++++++++
 packages/blocks-engine/src/output-verify.ts   |  63 ++++++++
 packages/blocks-engine/src/validate.ts        |  32 ++++
 10 files changed, 528 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/embed.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/escape.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/heuristics.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/output-verify.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/validate.test.ts
 create mode 100644 packages/blocks-engine/src/embed.ts
 create mode 100644 packages/blocks-engine/src/escape.ts
 create mode 100644 packages/blocks-engine/src/heuristics.ts
 create mode 100644 packages/blocks-engine/src/output-verify.ts
 create mode 100644 packages/blocks-engine/src/validate.ts

diff --git a/packages/blocks-engine/src/__tests__/embed.test.ts b/packages/blocks-engine/src/__tests__/embed.test.ts
new file mode 100644
index 00000000..d7710840
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/embed.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildEmbedBlock, guessEmbedProvider } from '../embed';
+
+describe('guessEmbedProvider', () => {
+  it('maps known video providers to their slug', () => {
+    expect(guessEmbedProvider('https://www.youtube.com/watch?v=abc')).toBe('youtube');
+    expect(guessEmbedProvider('https://youtu.be/abc')).toBe('youtube');
+    expect(guessEmbedProvider('https://player.vimeo.com/video/123')).toBe('vimeo');
+    expect(guessEmbedProvider('https://www.dailymotion.com/video/x1')).toBe('dailymotion');
+  });
+
+  it('maps known rich providers to their slug', () => {
+    expect(guessEmbedProvider('https://twitter.com/a/status/1')).toBe('twitter');
+    expect(guessEmbedProvider('https://www.instagram.com/p/abc/')).toBe('instagram');
+    expect(guessEmbedProvider('https://www.facebook.com/x/posts/1')).toBe('facebook');
+    expect(guessEmbedProvider('https://www.tiktok.com/@a/video/1')).toBe('tiktok');
+    expect(guessEmbedProvider('https://soundcloud.com/a/b')).toBe('soundcloud');
+    expect(guessEmbedProvider('https://open.spotify.com/track/1')).toBe('spotify');
+  });
+
+  it('treats x.com as twitter', () => {
+    expect(guessEmbedProvider('https://x.com/a/status/1')).toBe('twitter');
+  });
+
+  it('returns null for an unknown provider', () => {
+    expect(guessEmbedProvider('https://maps.example.com/embed?pb=1')).toBeNull();
+  });
+});
+
+describe('buildEmbedBlock', () => {
+  it('emits a video embed with 16:9 aspect classes for youtube', () => {
+    const out = buildEmbedBlock('https://www.youtube.com/embed/abc');
+    expect(out).toContain('<!-- wp:embed');
+    expect(out).toContain('"type":"video"');
+    expect(out).toContain('"providerNameSlug":"youtube"');
+    expect(out).toContain('"responsive":true');
+    expect(out).toContain('is-provider-youtube');
+    expect(out).toContain('wp-block-embed-youtube');
+    expect(out).toContain('wp-embed-aspect-16-9');
+    expect(out).toContain('wp-has-aspect-ratio');
+    expect(out).toContain('https://www.youtube.com/embed/abc');
+    expect(out).toContain('<!-- /wp:embed -->');
+  });
+
+  it('emits a rich embed without aspect-ratio classes for twitter', () => {
+    const out = buildEmbedBlock('https://twitter.com/a/status/1');
+    expect(out).toContain('"type":"rich"');
+    expect(out).toContain('"providerNameSlug":"twitter"');
+    expect(out).not.toContain('wp-embed-aspect');
+    expect(out).not.toContain('wp-has-aspect-ratio');
+  });
+
+  it('emits a lossless generic embed for an unknown provider', () => {
+    const url = 'https://widgets.example.com/embed/xyz';
+    const out = buildEmbedBlock(url);
+    expect(out).toContain('<!-- wp:embed');
+    expect(out).toContain(`"url":"${url}"`);
+    expect(out).toContain('"responsive":true');
+    expect(out).not.toContain('"type"');
+    expect(out).not.toContain('providerNameSlug');
+    expect(out).not.toContain('wp-embed-aspect');
+    expect(out).toContain(url);
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/escape.test.ts b/packages/blocks-engine/src/__tests__/escape.test.ts
new file mode 100644
index 00000000..f0e94ef0
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/escape.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+
+import { escapeHtml, escapeHtmlAttr, escapeHtmlText } from '../escape';
+
+describe('html escaping helpers', () => {
+  it('escapes text-node entities', () => {
+    expect(escapeHtmlText('A & <B>')).toBe('A &amp; &lt;B&gt;');
+  });
+
+  it('escapes double quotes for attributes', () => {
+    expect(escapeHtmlAttr('A "quote" & <B>')).toBe('A &quot;quote&quot; &amp; &lt;B&gt;');
+  });
+
+  it('escapes apostrophes in the full helper', () => {
+    expect(escapeHtml(`A 'quote'`)).toBe('A &#039;quote&#039;');
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/heuristics.test.ts b/packages/blocks-engine/src/__tests__/heuristics.test.ts
new file mode 100644
index 00000000..208cdfe8
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/heuristics.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import { heuristicBlocks } from '../heuristics';
+
+describe('heuristicBlocks', () => {
+  it('handles pure paragraphs and headings', () => {
+    const result = heuristicBlocks('<h2>Section</h2><p>Some prose.</p><h3>Subsection</h3><p>More prose.</p>');
+    expect(result.handled).toBe(true);
+    expect(result.blocks).toContain('<!-- wp:heading -->');
+    expect(result.blocks).toContain('<!-- wp:heading {"level":3} -->');
+    expect(result.blocks).toContain('Section');
+    expect(result.blocks).toContain('Subsection');
+  });
+
+  it('handles a leading image followed by paragraphs', () => {
+    const result = heuristicBlocks('<img src="https://example.com/hero.jpg" alt="Hero"><p>Caption-like text.</p><p>More body.</p>');
+    expect(result.handled).toBe(true);
+    expect(result.blocks).toContain('<!-- wp:image -->');
+    expect(result.blocks).toContain('src="https://example.com/hero.jpg"');
+    expect(result.blocks).toContain('alt="Hero"');
+    expect(result.blocks).toContain('<!-- wp:paragraph -->');
+  });
+
+  it('handles a single section with heading and paragraphs as a group', () => {
+    const result = heuristicBlocks('<section><h2>About</h2><p>We make things.</p></section>');
+    expect(result.handled).toBe(true);
+    expect(result.blocks).toContain('<!-- wp:group -->');
+    expect(result.blocks).toContain('<!-- wp:heading -->');
+    expect(result.blocks).toContain('About');
+  });
+
+  it('refuses unsupported shapes', () => {
+    expect(heuristicBlocks('<section><h2>One</h2></section><section><h2>Two</h2></section>').handled).toBe(false);
+    expect(heuristicBlocks('<ul><li>a</li><li>b</li></ul>').handled).toBe(false);
+    expect(heuristicBlocks('<table><tr><td>x</td></tr></table>').handled).toBe(false);
+    expect(heuristicBlocks('<div class="hero">stuff</div>').handled).toBe(false);
+    expect(heuristicBlocks('').handled).toBe(false);
+    expect(heuristicBlocks('   \n  ').handled).toBe(false);
+    expect(heuristicBlocks('<h1>Title</h1><p>Body.</p>').handled).toBe(false);
+    expect(heuristicBlocks('stray text<p>then a paragraph</p>').handled).toBe(false);
+  });
+
+  it('preserves inline markup inside paragraphs', () => {
+    const result = heuristicBlocks('<p>Click <a href="/x"><strong>here</strong></a> now.</p>');
+    expect(result.handled).toBe(true);
+    expect(result.blocks).toContain('<a href="/x">');
+    expect(result.blocks).toContain('<strong>here</strong>');
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/output-verify.test.ts b/packages/blocks-engine/src/__tests__/output-verify.test.ts
new file mode 100644
index 00000000..1682db7c
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/output-verify.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+
+import { verifyComposedOutput } from '../output-verify';
+
+describe('verifyComposedOutput', () => {
+  it('passes when every text node appears in source plain text', () => {
+    const source = '<article><h1>Welcome to Foo Industries</h1><p>We make widgets for the modern era.</p></article>';
+    const blocks = `<!-- wp:heading -->
+<h2 class="wp-block-heading">Welcome to Foo Industries</h2>
+<!-- /wp:heading -->
+
+<!-- wp:paragraph -->
+<p>We make widgets for the modern era.</p>
+<!-- /wp:paragraph -->`;
+    const result = verifyComposedOutput(blocks, source);
+    expect(result.valid).toBe(true);
+    expect(result.hallucinated).toEqual([]);
+  });
+
+  it('fails when output substitutes a different brand name', () => {
+    const source = '<article><h1>Foo Industries</h1><p>About us.</p></article>';
+    const blocks = `<!-- wp:heading --><h2>Bar Inc</h2><!-- /wp:heading --><!-- wp:paragraph --><p>About us.</p><!-- /wp:paragraph -->`;
+    const result = verifyComposedOutput(blocks, source);
+    expect(result.valid).toBe(false);
+    expect(result.hallucinated).toContain('Bar Inc');
+  });
+
+  it('treats wp block comments as metadata, not text', () => {
+    const source = '<article><p>Hello</p></article>';
+    const blocks = `<!-- wp:cover {"className":"is-style-accent-primary"} --><div><!-- wp:paragraph --><p>Hello</p><!-- /wp:paragraph --></div><!-- /wp:cover -->`;
+    const result = verifyComposedOutput(blocks, source);
+    expect(result.valid).toBe(true);
+  });
+
+  it('normalizes case, whitespace, and HTML entities before comparison', () => {
+    expect(verifyComposedOutput(`<!-- wp:paragraph --><p>Welcome to Foo Industries</p><!-- /wp:paragraph -->`, '<p>welcome to foo industries</p>').valid).toBe(true);
+    expect(verifyComposedOutput(`<!-- wp:paragraph --><p>We make widgets.</p><!-- /wp:paragraph -->`, '<p>We   make\n\nwidgets.</p>').valid).toBe(true);
+    expect(verifyComposedOutput(`<!-- wp:paragraph --><p>Tom &amp; Jerry</p><!-- /wp:paragraph -->`, '<p>Tom &amp; Jerry</p>').valid).toBe(true);
+  });
+
+  it('reports hallucinations and handles empty markup', () => {
+    const source = '<article><p>The original text only.</p></article>';
+    const blocks = `<!-- wp:heading --><h2>Hallucinated heading</h2><!-- /wp:heading -->
+<!-- wp:paragraph --><p>Made-up paragraph copy.</p><!-- /wp:paragraph -->`;
+    const result = verifyComposedOutput(blocks, source);
+    expect(result.valid).toBe(false);
+    expect(result.hallucinated.length).toBeGreaterThanOrEqual(2);
+    expect(verifyComposedOutput('', '<p>anything</p>')).toEqual({ valid: true, hallucinated: [] });
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/validate.test.ts b/packages/blocks-engine/src/__tests__/validate.test.ts
new file mode 100644
index 00000000..3d06d662
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/validate.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+
+import { blockMarkupRoundtrips } from '../validate';
+
+describe('blockMarkupRoundtrips', () => {
+  it('accepts balanced block markup', () => {
+    expect(blockMarkupRoundtrips('<!-- wp:paragraph -->\n<p>x</p>\n<!-- /wp:paragraph -->')).toEqual({ ok: true });
+  });
+
+  it('accepts self-closing block markup', () => {
+    expect(blockMarkupRoundtrips('<!-- wp:jetpack/field-name /-->')).toEqual({ ok: true });
+  });
+
+  it('rejects empty markup', () => {
+    expect(blockMarkupRoundtrips('')).toEqual({ ok: false, reason: 'empty markup' });
+  });
+
+  it('rejects mismatched closes and unclosed opens', () => {
+    expect(blockMarkupRoundtrips('<!-- wp:group --><!-- /wp:paragraph -->')).toEqual({
+      ok: false,
+      reason: 'mismatched block close: expected /wp:group, got /wp:paragraph',
+    });
+    expect(blockMarkupRoundtrips('<!-- wp:group -->')).toEqual({
+      ok: false,
+      reason: 'unclosed blocks: group',
+    });
+  });
+});
diff --git a/packages/blocks-engine/src/embed.ts b/packages/blocks-engine/src/embed.ts
new file mode 100644
index 00000000..25ba775e
--- /dev/null
+++ b/packages/blocks-engine/src/embed.ts
@@ -0,0 +1,52 @@
+type EmbedType = 'video' | 'rich';
+
+interface ProviderDef {
+  slug: string;
+  type: EmbedType;
+  match: RegExp;
+}
+
+const PROVIDERS: ProviderDef[] = [
+  { slug: 'youtube', type: 'video', match: /youtube\.com|youtu\.be/i },
+  { slug: 'vimeo', type: 'video', match: /vimeo\.com/i },
+  { slug: 'dailymotion', type: 'video', match: /dailymotion\.com|dai\.ly/i },
+  { slug: 'twitter', type: 'rich', match: /twitter\.com|x\.com/i },
+  { slug: 'instagram', type: 'rich', match: /instagram\.com/i },
+  { slug: 'facebook', type: 'rich', match: /facebook\.com|fb\.watch/i },
+  { slug: 'tiktok', type: 'rich', match: /tiktok\.com/i },
+  { slug: 'soundcloud', type: 'rich', match: /soundcloud\.com/i },
+  { slug: 'spotify', type: 'rich', match: /spotify\.com/i },
+];
+
+function providerDef(url: string): ProviderDef | null {
+  for (const provider of PROVIDERS) {
+    if (provider.match.test(url)) return provider;
+  }
+  return null;
+}
+
+/** Identify the oEmbed provider slug for a URL, or null when unrecognised. */
+export function guessEmbedProvider(url: string): string | null {
+  return providerDef(url)?.slug ?? null;
+}
+
+export function buildEmbedBlock(url: string): string {
+  const def = providerDef(url);
+  const isVideo = def?.type === 'video';
+
+  const attrParts = [`"url":${JSON.stringify(url)}`];
+  if (def) attrParts.push(`"type":"${def.type}"`);
+  if (def) attrParts.push(`"providerNameSlug":"${def.slug}"`);
+  attrParts.push('"responsive":true');
+  const attrs = `{${attrParts.join(',')}}`;
+
+  const providerClasses = def ? ` is-provider-${def.slug} wp-block-embed-${def.slug}` : '';
+  const aspectClasses = isVideo ? ' wp-embed-aspect-16-9 wp-has-aspect-ratio' : '';
+
+  return (
+    `<!-- wp:embed ${attrs} -->\n` +
+    `<figure class="wp-block-embed${providerClasses}${aspectClasses}">` +
+    `<div class="wp-block-embed__wrapper">\n${url}\n</div></figure>\n` +
+    `<!-- /wp:embed -->`
+  );
+}
diff --git a/packages/blocks-engine/src/escape.ts b/packages/blocks-engine/src/escape.ts
new file mode 100644
index 00000000..c6688161
--- /dev/null
+++ b/packages/blocks-engine/src/escape.ts
@@ -0,0 +1,19 @@
+// src/lib/html-escape.ts
+//
+// The single home for HTML entity escaping. Three escalating variants: pick by
+// context, not convenience.
+
+/** Escape &, <, >: the minimal set for HTML text-node content. */
+export function escapeHtmlText(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+/** Escape &, <, >, ": text plus double-quoted attribute values. */
+export function escapeHtmlAttr(s: string): string {
+  return escapeHtmlText(s).replace(/"/g, '&quot;');
+}
+
+/** Escape &, <, >, ", ': the full set, safe in any HTML context. */
+export function escapeHtml(s: string): string {
+  return escapeHtmlAttr(s).replace(/'/g, '&#039;');
+}
diff --git a/packages/blocks-engine/src/heuristics.ts b/packages/blocks-engine/src/heuristics.ts
new file mode 100644
index 00000000..00289342
--- /dev/null
+++ b/packages/blocks-engine/src/heuristics.ts
@@ -0,0 +1,153 @@
+import * as cheerio from 'cheerio';
+
+import { escapeHtmlText as escapeHtml } from './escape';
+
+export interface HeuristicResult {
+  handled: boolean;
+  blocks?: string;
+  reason?: string;
+}
+
+const ALLOWED_TEXTISH = new Set(['p', 'h2', 'h3']);
+
+function paragraphBlock(html: string): string {
+  return `<!-- wp:paragraph -->\n<p>${html}</p>\n<!-- /wp:paragraph -->`;
+}
+
+function headingBlock(level: 2 | 3, html: string): string {
+  const attrs = level === 2 ? '' : ` {"level":${level}}`;
+  return `<!-- wp:heading${attrs} -->\n<h${level} class="wp-block-heading">${html}</h${level}>\n<!-- /wp:heading -->`;
+}
+
+function imageBlock(src: string, alt: string): string {
+  const escapedSrc = escapeHtml(src);
+  const escapedAlt = escapeHtml(alt);
+  return `<!-- wp:image -->\n<figure class="wp-block-image"><img src="${escapedSrc}" alt="${escapedAlt}"/></figure>\n<!-- /wp:image -->`;
+}
+
+function groupBlock(inner: string): string {
+  return `<!-- wp:group -->\n<div class="wp-block-group">\n${inner}\n</div>\n<!-- /wp:group -->`;
+}
+
+interface SimpleEl {
+  tag: string;
+  innerHtml: string;
+  attrs: Record<string, string>;
+  childTags: string[];
+}
+
+function topLevelChildren(html: string): SimpleEl[] {
+  const $ = cheerio.load(`<body>${html}</body>`);
+  const body = $('body').first();
+  const elements: SimpleEl[] = [];
+  body.contents().each((_, node) => {
+    if (node.type === 'tag') {
+      const $node = $(node);
+      const attrs: Record<string, string> = {};
+      const tagAttrs = (node as { attribs?: Record<string, string> }).attribs ?? {};
+      for (const [key, value] of Object.entries(tagAttrs)) attrs[key] = value;
+      const childTags: string[] = [];
+      $node.children().each((__, child) => {
+        if (child.type === 'tag') childTags.push((child as { tagName: string }).tagName.toLowerCase());
+      });
+      elements.push({
+        tag: (node as { tagName: string }).tagName.toLowerCase(),
+        innerHtml: $node.html() ?? '',
+        attrs,
+        childTags,
+      });
+    } else if (node.type === 'text') {
+      const text = (node as { data: string }).data ?? '';
+      if (text.trim()) elements.push({ tag: '#textnode', innerHtml: text, attrs: {}, childTags: [] });
+    }
+  });
+  return elements;
+}
+
+interface ImageInfo {
+  src: string;
+  alt: string;
+}
+
+function pickFigureImage(figureInnerHtml: string): ImageInfo | null {
+  const $ = cheerio.load(`<body>${figureInnerHtml}</body>`);
+  const body = $('body').first();
+  const childEls: Array<{ tag: string; src: string; alt: string }> = [];
+  body.contents().each((_, node) => {
+    if (node.type === 'tag') {
+      const tagName = (node as { tagName: string }).tagName.toLowerCase();
+      if (tagName === 'img' || tagName === 'figcaption') {
+        const $node = $(node);
+        childEls.push({
+          tag: tagName,
+          src: $node.attr('src') ?? '',
+          alt: $node.attr('alt') ?? '',
+        });
+      } else {
+        childEls.push({ tag: tagName, src: '', alt: '' });
+      }
+    }
+  });
+  const hasOnlyAllowed = childEls.every((child) => child.tag === 'img' || child.tag === 'figcaption');
+  const img = childEls.find((child) => child.tag === 'img');
+  if (!hasOnlyAllowed || !img) return null;
+  return { src: img.src, alt: img.alt };
+}
+
+function pickLeadingImage(el: SimpleEl): ImageInfo | null {
+  if (el.tag === 'img') return { src: el.attrs.src ?? '', alt: el.attrs.alt ?? '' };
+  if (el.tag === 'figure') return pickFigureImage(el.innerHtml);
+  return null;
+}
+
+function textishToBlock(el: SimpleEl): string {
+  const inner = el.innerHtml.trim();
+  if (el.tag === 'p') return paragraphBlock(inner);
+  if (el.tag === 'h2') return headingBlock(2, inner);
+  if (el.tag === 'h3') return headingBlock(3, inner);
+  return paragraphBlock(escapeHtml(inner));
+}
+
+export function heuristicBlocks(html: string): HeuristicResult {
+  if (!html || !html.trim()) return { handled: false, reason: 'empty input' };
+
+  const children = topLevelChildren(html);
+  if (children.length === 0) return { handled: false, reason: 'no structured children' };
+  if (children.some((child) => child.tag === '#textnode')) {
+    return { handled: false, reason: 'top-level stray text' };
+  }
+
+  if (children.length === 1 && children[0].tag === 'section') {
+    const inner = topLevelChildren(children[0].innerHtml);
+    const allTextish = inner.every((child) => ALLOWED_TEXTISH.has(child.tag));
+    const hasHeading = inner.some((child) => child.tag === 'h2' || child.tag === 'h3');
+    if (allTextish && hasHeading && inner.length > 0) {
+      const innerBlocks = inner.map((child) => textishToBlock(child)).join('\n\n');
+      return { handled: true, blocks: groupBlock(innerBlocks), reason: 'section-with-heading' };
+    }
+    return { handled: false, reason: 'section is not pure heading+paragraphs' };
+  }
+
+  const leadingImage = pickLeadingImage(children[0]);
+  if (leadingImage) {
+    const rest = children.slice(1);
+    const restAllParagraphs = rest.every((child) => child.tag === 'p');
+    if (restAllParagraphs && rest.length > 0) {
+      const blocks = [imageBlock(leadingImage.src, leadingImage.alt)];
+      for (const paragraph of rest) blocks.push(paragraphBlock(paragraph.innerHtml.trim()));
+      return { handled: true, blocks: blocks.join('\n\n'), reason: 'image+paragraphs' };
+    }
+    return { handled: false, reason: 'leading image not followed by paragraphs only' };
+  }
+
+  const allTextish = children.every((child) => ALLOWED_TEXTISH.has(child.tag));
+  if (allTextish) {
+    return {
+      handled: true,
+      blocks: children.map((child) => textishToBlock(child)).join('\n\n'),
+      reason: 'paragraphs+headings',
+    };
+  }
+
+  return { handled: false, reason: 'mixed structure outside heuristic shapes' };
+}
diff --git a/packages/blocks-engine/src/output-verify.ts b/packages/blocks-engine/src/output-verify.ts
new file mode 100644
index 00000000..abe54117
--- /dev/null
+++ b/packages/blocks-engine/src/output-verify.ts
@@ -0,0 +1,63 @@
+export interface VerifyResult {
+  valid: boolean;
+  hallucinated: string[];
+}
+
+function stripBlockComments(markup: string): string {
+  return markup
+    .replace(/<!--\s*\/?wp:[^>]*-->/g, ' ')
+    .replace(/<!--[\s\S]*?-->/g, ' ');
+}
+
+function htmlToPlainText(html: string): string {
+  if (!html) return '';
+  return html
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&apos;/g, "'")
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function extractTextNodes(markup: string): string[] {
+  const stripped = stripBlockComments(markup);
+  const nodes: string[] = [];
+  const parts = stripped.split(/<[^>]+>/);
+  for (const raw of parts) {
+    const text = htmlToPlainText(raw);
+    if (!text) continue;
+    const alnum = text.replace(/[^a-zA-Z0-9]/g, '');
+    if (alnum.length < 3) continue;
+    nodes.push(text);
+  }
+  return nodes;
+}
+
+function normalize(text: string): string {
+  return text.toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+export function verifyComposedOutput(
+  blocksMarkup: string,
+  sourceHtmlPlainText: string,
+): VerifyResult {
+  const sourceText = normalize(htmlToPlainText(sourceHtmlPlainText));
+  const nodes = extractTextNodes(blocksMarkup);
+  const hallucinated: string[] = [];
+
+  for (const node of nodes) {
+    const needle = normalize(node);
+    if (!needle) continue;
+    if (!sourceText.includes(needle)) hallucinated.push(node);
+  }
+
+  return {
+    valid: hallucinated.length === 0,
+    hallucinated,
+  };
+}
diff --git a/packages/blocks-engine/src/validate.ts b/packages/blocks-engine/src/validate.ts
new file mode 100644
index 00000000..900eddcc
--- /dev/null
+++ b/packages/blocks-engine/src/validate.ts
@@ -0,0 +1,32 @@
+export function blockMarkupRoundtrips(
+  markup: string,
+): { ok: true } | { ok: false; reason: string } {
+  if (!markup || !markup.trim()) {
+    return { ok: false, reason: 'empty markup' };
+  }
+
+  const stack: string[] = [];
+  const re = /<!--\s*(\/?)wp:([a-zA-Z0-9/_-]+)([^]*?)(\/)?\s*-->/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(markup)) !== null) {
+    const isClose = match[1] === '/';
+    const name = match[2];
+    const isSelfClose = match[4] === '/';
+    if (isSelfClose) continue;
+    if (isClose) {
+      const top = stack.pop();
+      if (top !== name) {
+        return {
+          ok: false,
+          reason: `mismatched block close: expected /wp:${top ?? '(empty)'}, got /wp:${name}`,
+        };
+      }
+    } else {
+      stack.push(name);
+    }
+  }
+  if (stack.length > 0) {
+    return { ok: false, reason: `unclosed blocks: ${stack.join(', ')}` };
+  }
+  return { ok: true };
+}

From 3744d10e0bd7b5353cd011a7e8cce091b49918b4 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 22:06:22 -0400
Subject: [PATCH 011/113] feat(blocks-engine): extract sanitize helper

---
 .../src/__tests__/sanitize.test.ts            | 31 +++++++++++++++++++
 packages/blocks-engine/src/sanitize.ts        | 16 ++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/sanitize.test.ts
 create mode 100644 packages/blocks-engine/src/sanitize.ts

diff --git a/packages/blocks-engine/src/__tests__/sanitize.test.ts b/packages/blocks-engine/src/__tests__/sanitize.test.ts
new file mode 100644
index 00000000..0bf25b89
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/sanitize.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+
+import { sanitize } from '../sanitize';
+
+describe('sanitize', () => {
+  it('strips active content and inline event handlers while preserving real content', () => {
+    const dirty =
+      '<section onload="track()">' +
+      '<script>evil()</script>' +
+      '<style>.x{color:red}</style>' +
+      '<img src="/u/a.jpg" onerror="steal()"/>' +
+      '<?php echo "x"; ?>' +
+      '<!-- wp:html -->noise<!-- /wp:html -->' +
+      '<p>Real copy</p>' +
+      '</section>';
+    const out = sanitize(dirty);
+
+    expect(out).not.toMatch(/<script/i);
+    expect(out).not.toMatch(/<style/i);
+    expect(out).not.toMatch(/on\w+\s*=/i);
+    expect(out).not.toContain('<?php');
+    expect(out).not.toContain('<!--');
+    expect(out).toContain('<p>Real copy</p>');
+    expect(out).toContain('<img src="/u/a.jpg"');
+  });
+
+  it('removes residual script/style and php open tags', () => {
+    expect(sanitize('<script>oops<p>copy</p><style>x')).toBe('oops<p>copy</p>x');
+    expect(sanitize('<?php echo "x"; ?><p>copy</p><?')).toBe('<p>copy</p>');
+  });
+});
diff --git a/packages/blocks-engine/src/sanitize.ts b/packages/blocks-engine/src/sanitize.ts
new file mode 100644
index 00000000..50636fe7
--- /dev/null
+++ b/packages/blocks-engine/src/sanitize.ts
@@ -0,0 +1,16 @@
+/** Remove script/style/comment blocks, inline event handlers, and PHP tags. */
+export function sanitize(html: string): string {
+  return html
+    // Paired script/style including their contents.
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script\s*>/gi, '')
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style\s*>/gi, '')
+    // Any residual/unclosed script/style tags.
+    .replace(/<\/?(?:script|style)\b[^>]*>/gi, '')
+    // PHP (incl. short tags).
+    .replace(/<\?[\s\S]*?\?>/g, '')
+    .replace(/<\?/g, '')
+    // HTML comments, including literal block-comment lookalikes.
+    .replace(/<!--[\s\S]*?-->/g, '')
+    // Inline event handlers.
+    .replace(/\son[a-z]+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, '');
+}

From fb848b92e53a485a0f447c284946c5934960e870 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 22:08:47 -0400
Subject: [PATCH 012/113] feat(blocks-engine): port catalog recipe table seam

---
 .../src/__tests__/recipe-table.test.ts        |  37 +++
 packages/blocks-engine/src/block-policy.ts    |   4 +
 packages/blocks-engine/src/catalog.ts         | 310 ++++++++++++++++++
 packages/blocks-engine/src/recipe-table.ts    |  65 ++++
 4 files changed, 416 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/recipe-table.test.ts
 create mode 100644 packages/blocks-engine/src/block-policy.ts
 create mode 100644 packages/blocks-engine/src/catalog.ts
 create mode 100644 packages/blocks-engine/src/recipe-table.ts

diff --git a/packages/blocks-engine/src/__tests__/recipe-table.test.ts b/packages/blocks-engine/src/__tests__/recipe-table.test.ts
new file mode 100644
index 00000000..84c8d03e
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/recipe-table.test.ts
@@ -0,0 +1,37 @@
+import * as cheerio from 'cheerio';
+import type { Element } from 'domhandler';
+import { describe, expect, it } from 'vitest';
+
+import { composeFromRecipes, emitRecipeBlock } from '../recipe-table';
+import type { RecipeRule } from '../types';
+
+const ctx = { url: 'https://x.test/p' };
+const marker = (html: string) =>
+  `<!-- wp:html {"metadata":{"name":"X"}} -->${html}<!-- /wp:html -->`;
+
+describe('recipe-table', () => {
+  it('converts matched elements and islands unmatched siblings', () => {
+    const recipes: RecipeRule[] = [{ match: 'h2', block: 'core/heading', inner: 'text' }];
+    const out = composeFromRecipes('<h2>Title</h2><weird-el>z</weird-el>', recipes, ctx, marker);
+
+    expect(out).toContain('<!-- wp:heading -->');
+    expect(out).toContain('Title');
+    expect(out).toContain('<!-- wp:html {"metadata":{"name":"X"}} --><weird-el>z</weird-el><!-- /wp:html -->');
+  });
+
+  it('escapes comment closers in attribute JSON', () => {
+    const $ = cheerio.load('<div class="card">Body</div>', null, false);
+    const el = $.root().children().first().get(0) as Element;
+    const rule: RecipeRule = {
+      match: '.card',
+      block: 'core/group',
+      attrs: { label: 'a-->b' },
+      inner: 'text',
+    };
+
+    const out = emitRecipeBlock($, el, rule, ctx, marker);
+
+    expect(out).toContain('a--\\u003eb');
+    expect(out).not.toContain('a-->b');
+  });
+});
diff --git a/packages/blocks-engine/src/block-policy.ts b/packages/blocks-engine/src/block-policy.ts
new file mode 100644
index 00000000..b7d3e24d
--- /dev/null
+++ b/packages/blocks-engine/src/block-policy.ts
@@ -0,0 +1,4 @@
+export const PIPELINE_ISLAND_NAME = 'lib-coverage-island';
+
+export const PIPELINE_ISLAND_OPENER =
+  `<!-- wp:html {"metadata":{"name":"${PIPELINE_ISLAND_NAME}"}} -->`;
diff --git a/packages/blocks-engine/src/catalog.ts b/packages/blocks-engine/src/catalog.ts
new file mode 100644
index 00000000..b8a2b6fd
--- /dev/null
+++ b/packages/blocks-engine/src/catalog.ts
@@ -0,0 +1,310 @@
+import * as cheerio from 'cheerio';
+import type { Cheerio, CheerioAPI } from 'cheerio';
+import type { Element } from 'domhandler';
+
+import { PIPELINE_ISLAND_OPENER } from './block-policy';
+import { buildEmbedBlock, guessEmbedProvider } from './embed';
+import { escapeHtmlAttr as escapeAttr, escapeHtmlText as escapeHtml } from './escape';
+import { sanitize } from './sanitize';
+import type { ConversionContext } from './types';
+
+type HtmlFallbackEmitter = (html: string) => string;
+
+interface Converted {
+  matched: boolean;
+  markup: string;
+}
+
+function defaultHtmlFallback(html: string): string {
+  return `${PIPELINE_ISLAND_OPENER}\n${sanitize(html)}\n<!-- /wp:html -->`;
+}
+
+export function genericHtmlToBlocks(
+  html: string,
+  ctx: ConversionContext,
+  htmlFallback: HtmlFallbackEmitter = defaultHtmlFallback,
+): string | null {
+  if (!html || !html.trim()) return null;
+  if (/<!--\s*wp:/.test(html)) return null;
+
+  const $ = cheerio.load(html, null, false);
+  const out: string[] = [];
+  let matchedAny = false;
+
+  $.root().children().each((_, node) => {
+    if ((node as Element).type !== 'tag') return;
+    const el = node as Element;
+    const converted = convertElement($, el, ctx, htmlFallback);
+    if (converted.matched) matchedAny = true;
+    if (converted.markup.trim()) out.push(converted.markup);
+  });
+
+  if (!matchedAny) return null;
+  return out.length ? out.join('\n\n') : null;
+}
+
+function convertElement(
+  $: CheerioAPI,
+  el: Element,
+  ctx: ConversionContext,
+  htmlFallback: HtmlFallbackEmitter,
+): Converted {
+  const embed = tryEmbed($, el);
+  if (embed) return { matched: true, markup: embed };
+  const details = tryDetails($, el, ctx, htmlFallback);
+  if (details) return { matched: true, markup: details };
+  const detailsPairs = tryDetailsPairs($, el, ctx, htmlFallback);
+  if (detailsPairs) return { matched: true, markup: detailsPairs };
+  const callout = tryCallout($, el, ctx, htmlFallback);
+  if (callout) return { matched: true, markup: callout };
+  const pull = tryPullquote($, el);
+  if (pull) return { matched: true, markup: pull };
+  const buttons = tryButtons($, el);
+  if (buttons) return { matched: true, markup: buttons };
+  const mediaText = tryMediaText($, el, ctx, htmlFallback);
+  if (mediaText) return { matched: true, markup: mediaText };
+  return { matched: false, markup: htmlFallback($.html(el)) };
+}
+
+const EMBED_WRAPPER_TAGS = new Set(['figure', 'div', 'p', 'span']);
+
+function tryEmbed($: CheerioAPI, el: Element): string | null {
+  const $el = $(el);
+  let src: string | undefined;
+
+  if (el.tagName === 'iframe') {
+    src = $el.attr('src');
+  } else if (EMBED_WRAPPER_TAGS.has(el.tagName)) {
+    const iframes = $el.find('iframe');
+    if (iframes.length !== 1) return null;
+    const clone = $el.clone();
+    clone.find('iframe').remove();
+    if (clone.text().trim()) return null;
+    src = iframes.first().attr('src');
+  } else {
+    return null;
+  }
+
+  if (!src || !/^https?:\/\//i.test(src)) return null;
+  if (!guessEmbedProvider(src)) return null;
+  return buildEmbedBlock(src);
+}
+
+function tryDetails(
+  $: CheerioAPI,
+  el: Element,
+  ctx: ConversionContext,
+  htmlFallback: HtmlFallbackEmitter,
+): string | null {
+  const $el = $(el);
+  const isDetails = el.tagName === 'details';
+  const isAccordionClass = /\b(accordion|faq-item)\b/.test($el.attr('class') || '');
+  if (!isDetails && !isAccordionClass) return null;
+
+  const summary =
+    $el.find('summary').first().text().trim() ||
+    $el.children('h1,h2,h3,h4,h5,h6,.accordion-title,.faq-question').first().text().trim();
+  if (!summary) return null;
+
+  const bodyHtml = bodyExcludingSummary($, $el);
+  const inner = recurseInner(bodyHtml, ctx, htmlFallback);
+  return (
+    `<!-- wp:details -->\n` +
+    `<details class="wp-block-details"><summary>${escapeHtml(summary)}</summary>${inner}</details>\n` +
+    `<!-- /wp:details -->`
+  );
+}
+
+function bodyExcludingSummary($: CheerioAPI, $el: Cheerio<Element>): string {
+  const clone = $el.clone();
+  clone.find('summary').first().remove();
+  clone.children('h1,h2,h3,h4,h5,h6,.accordion-title,.faq-question').first().remove();
+  return clone.html() ?? '';
+}
+
+function recurseInner(
+  html: string,
+  ctx: ConversionContext,
+  htmlFallback: HtmlFallbackEmitter,
+): string {
+  const nested = genericHtmlToBlocks(html, ctx, htmlFallback);
+  if (nested && nested.trim()) return `\n${nested}\n`;
+  const clean = sanitize(html).trim();
+  return clean ? clean : '';
+}
+
+const HEADING_TAGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']);
+
+function isHiddenContent($: CheerioAPI, el: Element): boolean {
+  const $el = $(el);
+  return (
+    $el.attr('hidden') !== undefined ||
+    $el.attr('aria-hidden') === 'true' ||
+    /display\s*:\s*none/.test($el.attr('style') ?? '')
+  );
+}
+
+function tryDetailsPairs(
+  $: CheerioAPI,
+  el: Element,
+  ctx: ConversionContext,
+  htmlFallback: HtmlFallbackEmitter,
+): string | null {
+  const kids = $(el).children().toArray();
+  if (kids.length < 2 || kids.length % 2 !== 0) return null;
+  const pairs: Array<{ summary: string; bodyHtml: string }> = [];
+  for (let i = 0; i < kids.length; i += 2) {
+    const head = kids[i];
+    const body = kids[i + 1];
+    if (!HEADING_TAGS.has(head.tagName)) return null;
+    if (HEADING_TAGS.has(body.tagName) || !isHiddenContent($, body)) return null;
+    const summary = $(head).text().trim();
+    if (!summary) return null;
+    pairs.push({ summary, bodyHtml: $(body).html() ?? '' });
+  }
+  if (pairs.length === 0) return null;
+  return pairs
+    .map(
+      (pair) =>
+        `<!-- wp:details -->\n` +
+        `<details class="wp-block-details"><summary>${escapeHtml(pair.summary)}</summary>${recurseInner(pair.bodyHtml, ctx, htmlFallback)}</details>\n` +
+        `<!-- /wp:details -->`,
+    )
+    .join('\n\n');
+}
+
+const CALLOUT_RE = /\b(callout|notice|alert|card)\b/;
+
+function tryCallout(
+  $: CheerioAPI,
+  el: Element,
+  ctx: ConversionContext,
+  htmlFallback: HtmlFallbackEmitter,
+): string | null {
+  const $el = $(el);
+  const cls = $el.attr('class') || '';
+  if (!CALLOUT_RE.test(cls)) return null;
+  const inner = recurseInner($el.html() ?? '', ctx, htmlFallback);
+  if (!inner.trim()) return null;
+  const matchedClass = (cls.match(CALLOUT_RE) || [])[0] ?? 'callout';
+  const className = `wp-block-group is-style-${matchedClass}`;
+  return (
+    `<!-- wp:group {"className":${JSON.stringify(className)},"layout":{"type":"constrained"}} -->\n` +
+    `<div class="${escapeAttr(className)}">${inner}</div>\n` +
+    `<!-- /wp:group -->`
+  );
+}
+
+function tryPullquote($: CheerioAPI, el: Element): string | null {
+  const $el = $(el);
+  const cls = $el.attr('class') || '';
+  const isPull =
+    (el.tagName === 'blockquote' && /\bpull/.test(cls)) ||
+    (el.tagName === 'aside' && $el.find('blockquote').length > 0);
+  if (!isPull) return null;
+  const $quote = $el.is('blockquote') ? $el : $el.find('blockquote').first();
+  const text = $quote.find('p').first().text().trim() || $quote.text().trim();
+  if (!text) return null;
+  const cite = $el.find('cite').first().text().trim();
+  const citeHtml = cite ? `<cite>${escapeHtml(cite)}</cite>` : '';
+  return (
+    `<!-- wp:pullquote -->\n` +
+    `<figure class="wp-block-pullquote"><blockquote><p>${escapeHtml(text)}</p>${citeHtml}</blockquote></figure>\n` +
+    `<!-- /wp:pullquote -->`
+  );
+}
+
+const BTN_RE = /\b(button|btn)\b/;
+
+function isButtonLink($: CheerioAPI, el: Element): boolean {
+  return el.tagName === 'a' && BTN_RE.test($(el).attr('class') || '') && Boolean($(el).attr('href'));
+}
+
+function tryButtons($: CheerioAPI, el: Element): string | null {
+  const $el = $(el);
+  let links: Element[];
+  if (isButtonLink($, el)) {
+    links = [el];
+  } else {
+    links = $el.children('a').toArray().filter((anchor) => isButtonLink($, anchor));
+    if (links.length === 0) return null;
+  }
+  const buttonBlocks = links.map((anchor) => {
+    const $anchor = $(anchor);
+    const href = $anchor.attr('href') || '';
+    const label = $anchor.text().trim();
+    return (
+      `<!-- wp:button -->\n` +
+      `<div class="wp-block-button"><a class="wp-block-button__link wp-element-button" href="${escapeAttr(href)}">${escapeHtml(label)}</a></div>\n` +
+      `<!-- /wp:button -->`
+    );
+  });
+  return (
+    `<!-- wp:buttons -->\n` +
+    `<div class="wp-block-buttons">\n${buttonBlocks.join('\n')}\n</div>\n` +
+    `<!-- /wp:buttons -->`
+  );
+}
+
+const MEDIA_TEXT_RE = /\b(media-text|media-object|image-text|text-image)\b/;
+const LAYOUT_HINT_CLASS_RE = /\b(split(?:-\w+)?|two-col(?:umn)?s?|cols?-2|grid|row|flex)\b/;
+const LAYOUT_HINT_STYLE_RE = /display\s*:\s*(flex|grid)\b/;
+
+function isMediaChild($: CheerioAPI, el: Element): boolean {
+  if (el.tagName === 'img' || el.tagName === 'picture' || el.tagName === 'figure') {
+    return $(el).find('img').length > 0 || el.tagName === 'img';
+  }
+  return $(el).find('img').length === 1 && !$(el).text().trim();
+}
+
+function tryMediaText(
+  $: CheerioAPI,
+  el: Element,
+  ctx: ConversionContext,
+  htmlFallback: HtmlFallbackEmitter,
+): string | null {
+  const $el = $(el);
+  const classNamed = MEDIA_TEXT_RE.test($el.attr('class') || '');
+
+  let mediaOnRight = false;
+  if (!classNamed) {
+    const kids = $el.children().toArray();
+    if (kids.length !== 2) return null;
+    const hasLayoutHint =
+      LAYOUT_HINT_CLASS_RE.test($el.attr('class') || '') ||
+      LAYOUT_HINT_STYLE_RE.test($el.attr('style') || '');
+    if (!hasLayoutHint) return null;
+    const [first, second] = kids;
+    const firstIsMedia = isMediaChild($, first);
+    const secondIsMedia = isMediaChild($, second);
+    if (firstIsMedia === secondIsMedia) return null;
+    const textChild = firstIsMedia ? second : first;
+    if ($(textChild).find('img').length > 0) return null;
+    mediaOnRight = secondIsMedia;
+  }
+
+  const img = $el.find('img').first();
+  if (img.length === 0) return null;
+  const rawSrc = img.attr('src') || '';
+  if (!rawSrc) return null;
+  const src = ctx.mediaMap?.[rawSrc] ?? rawSrc;
+  const alt = img.attr('alt') || '';
+  const textNode = $el.children().toArray().find((child) => {
+    const tag = child.tagName;
+    return tag && tag !== 'figure' && tag !== 'img' && tag !== 'picture' && $(child).find('img').length === 0;
+  });
+  const textHtml = textNode ? ($(textNode).html() ?? '') : '';
+  const innerText =
+    recurseInner(textHtml, ctx, htmlFallback).trim() ||
+    `<!-- wp:paragraph -->\n<p>${escapeHtml($el.text().trim())}</p>\n<!-- /wp:paragraph -->`;
+  const attrs = mediaOnRight ? `{"mediaType":"image","mediaPosition":"right"}` : `{"mediaType":"image"}`;
+  const cls = `wp-block-media-text is-stacked-on-mobile${mediaOnRight ? ' has-media-on-the-right' : ''}`;
+  return (
+    `<!-- wp:media-text ${attrs} -->\n` +
+    `<div class="${cls}">` +
+    `<figure class="wp-block-media-text__media"><img src="${escapeAttr(src)}" alt="${escapeAttr(alt)}"/></figure>` +
+    `<div class="wp-block-media-text__content">${innerText}</div>` +
+    `</div>\n` +
+    `<!-- /wp:media-text -->`
+  );
+}
diff --git a/packages/blocks-engine/src/recipe-table.ts b/packages/blocks-engine/src/recipe-table.ts
new file mode 100644
index 00000000..ce74b612
--- /dev/null
+++ b/packages/blocks-engine/src/recipe-table.ts
@@ -0,0 +1,65 @@
+import * as cheerio from 'cheerio';
+import type { CheerioAPI } from 'cheerio';
+import type { Element } from 'domhandler';
+
+import { PIPELINE_ISLAND_OPENER } from './block-policy';
+import { escapeHtmlAttr as escapeAttr, escapeHtmlText as escapeHtml } from './escape';
+import { sanitize } from './sanitize';
+import type { ConversionContext, RecipeRule } from './types';
+
+type HtmlFallbackEmitter = (html: string) => string;
+
+function defaultHtmlFallback(html: string): string {
+  return `${PIPELINE_ISLAND_OPENER}\n${sanitize(html)}\n<!-- /wp:html -->`;
+}
+
+export function composeFromRecipes(
+  html: string,
+  recipes: RecipeRule[],
+  ctx: ConversionContext,
+  htmlFallback: HtmlFallbackEmitter = defaultHtmlFallback,
+): string | null {
+  if (/<!--\s*wp:/.test(html)) return null;
+  const $ = cheerio.load(html, null, false);
+  const out: string[] = [];
+  $.root().children().each((_, node) => {
+    if ((node as Element).type !== 'tag') return;
+    const el = node as Element;
+    const recipe = recipes.find((candidate) => $(el).is(candidate.match));
+    out.push(recipe ? emitRecipeBlock($, el, recipe, ctx, htmlFallback) : htmlFallback($.html(el)));
+  });
+  const result = out.filter((block) => block && block.trim());
+  return result.length ? result.join('\n\n') : null;
+}
+
+export function blockTag(block: string): string {
+  return block.startsWith('core/') ? block.slice('core/'.length) : block;
+}
+
+export function emitRecipeBlock(
+  $: CheerioAPI,
+  el: Element,
+  recipe: RecipeRule,
+  ctx: ConversionContext,
+  htmlFallback: HtmlFallbackEmitter = defaultHtmlFallback,
+): string {
+  const tag = blockTag(recipe.block);
+  const attrs =
+    recipe.attrs && Object.keys(recipe.attrs).length
+      ? ` ${JSON.stringify(recipe.attrs).replace(/-->/g, '--\\u003e')}`
+      : '';
+  const open = `<!-- wp:${tag}${attrs} -->`;
+  const close = `<!-- /wp:${tag} -->`;
+  const mode = recipe.inner ?? 'innerHtml';
+  const $el = $(el);
+  if (recipe.block === 'core/image' || mode === 'images') {
+    const img = $el.is('img') ? $el : $el.find('img').first();
+    const rawSrc = img.attr('src') || '';
+    if (!rawSrc) return htmlFallback($.html(el));
+    const src = ctx.mediaMap?.[rawSrc] ?? rawSrc;
+    return `${open}\n<figure class="wp-block-image"><img src="${escapeAttr(src)}" alt="${escapeAttr(img.attr('alt') || '')}"/></figure>\n${close}`;
+  }
+  if (mode === 'drop') return `${open}\n${close}`;
+  const inner = mode === 'text' ? escapeHtml($el.text().trim()) : ($el.html() ?? '');
+  return `${open}\n${inner}\n${close}`;
+}

From 9bf16bd6240f55501051ed83456bb52715c61e02 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 22:08:53 -0400
Subject: [PATCH 013/113] feat(blocks-engine): add compose precedence

---
 .../src/__tests__/compose.fixture.test.ts     | 21 +++++++++++++++
 .../__tests__/html-fallback-recursion.test.ts | 22 ++++++++++++++++
 packages/blocks-engine/src/compose.ts         | 26 ++++++++++++++++---
 3 files changed, 66 insertions(+), 3 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/compose.fixture.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/html-fallback-recursion.test.ts

diff --git a/packages/blocks-engine/src/__tests__/compose.fixture.test.ts b/packages/blocks-engine/src/__tests__/compose.fixture.test.ts
new file mode 100644
index 00000000..f1d24a08
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/compose.fixture.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import cases from '../__fixtures__/cases.json' with { type: 'json' };
+import { compose } from '../compose';
+
+type ComposeFixture = {
+  id: string;
+  op: 'compose';
+  input: string;
+  expected: string;
+};
+
+const composeCases = (cases as ComposeFixture[]).filter((fixture) => fixture.op === 'compose');
+
+describe('compose golden fixtures', () => {
+  for (const fixture of composeCases) {
+    it(`${fixture.id} is byte-identical to the DLA golden`, () => {
+      expect(compose(fixture.input, { url: 'https://x.test/' }, {})).toBe(fixture.expected);
+    });
+  }
+});
diff --git a/packages/blocks-engine/src/__tests__/html-fallback-recursion.test.ts b/packages/blocks-engine/src/__tests__/html-fallback-recursion.test.ts
new file mode 100644
index 00000000..a1bd3e57
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/html-fallback-recursion.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+
+import { compose } from '../compose';
+
+const ctx = { url: 'https://x.test/' };
+
+describe('compose htmlFallback seam', () => {
+  it('threads a custom fallback into unmatched siblings after a matched wrapper', () => {
+    const marker = (html: string) =>
+      `<!-- wp:html {"metadata":{"name":"X"}} -->${html}<!-- /wp:html -->`;
+
+    const out = compose(
+      '<div class="callout"><p>hi</p></div><weird-el>z</weird-el>',
+      ctx,
+      { htmlFallback: marker },
+    );
+
+    expect(out).toContain('<!-- wp:group');
+    expect(out).toContain('<!-- wp:html {"metadata":{"name":"X"}} --><weird-el>z</weird-el><!-- /wp:html -->');
+    expect(out).not.toContain('lib-coverage-island');
+  });
+});
diff --git a/packages/blocks-engine/src/compose.ts b/packages/blocks-engine/src/compose.ts
index 34c2029a..129c7d39 100644
--- a/packages/blocks-engine/src/compose.ts
+++ b/packages/blocks-engine/src/compose.ts
@@ -1,11 +1,31 @@
+import { PIPELINE_ISLAND_OPENER } from './block-policy';
+import { genericHtmlToBlocks } from './catalog';
+import { sanitize } from './sanitize';
 import type { ConversionContext, Converter, HtmlFallback } from './types';
 
+type HtmlFallbackEmitter = (html: string) => string;
+
+function defaultHtmlFallback(html: string): string {
+  return `${PIPELINE_ISLAND_OPENER}\n${sanitize(html).trim()}\n<!-- /wp:html -->`;
+}
+
+function normalizeHtmlFallback(htmlFallback: HtmlFallback | undefined): HtmlFallbackEmitter {
+  return typeof htmlFallback === 'function' ? htmlFallback : defaultHtmlFallback;
+}
+
 export function compose(
   html: string,
   ctx: ConversionContext,
   opts?: { converters?: Converter[]; htmlFallback?: HtmlFallback },
 ): string {
-  void ctx;
-  void opts;
-  return html;
+  for (const converter of opts?.converters ?? []) {
+    const out = converter(html, ctx);
+    if (out != null && out.trim()) return out;
+  }
+
+  const htmlFallback = normalizeHtmlFallback(opts?.htmlFallback);
+  const catalog = genericHtmlToBlocks(html, ctx, htmlFallback);
+  if (catalog != null && catalog.trim()) return catalog;
+
+  return htmlFallback(html);
 }

From 9435e2f557bb1171d47b767ada3cc9861d110976 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 22:09:23 -0400
Subject: [PATCH 014/113] feat(blocks-engine): share raw convertible unwrap
 list

---
 .../src/__tests__/raw-convertible.test.ts     | 56 +++++++++++++++++++
 packages/blocks-engine/src/raw-convertible.ts | 44 +++++++++++++++
 packages/blocks-engine/src/wp/raw-convert.ts  |  5 +-
 3 files changed, 101 insertions(+), 4 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/raw-convertible.test.ts
 create mode 100644 packages/blocks-engine/src/raw-convertible.ts

diff --git a/packages/blocks-engine/src/__tests__/raw-convertible.test.ts b/packages/blocks-engine/src/__tests__/raw-convertible.test.ts
new file mode 100644
index 00000000..646a8d27
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/raw-convertible.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+
+import { isRawConvertible, UNWRAP_SELECTOR } from '../raw-convertible';
+
+describe('isRawConvertible', () => {
+  it('is true for a flat list of semantic blocks wrapped in layout containers', () => {
+    const html = '<main><div class="wp-block-group">' +
+      '<div class="wp-block-spacer" style="height:40px"></div>' +
+      '<h1 class="wp-block-post-title">Fictional Title</h1>' +
+      '<p>Body copy about nothing in particular.</p>' +
+      '<figure class="wp-block-table"><table><tr><td>x</td></tr></table></figure>' +
+      '</div></main>';
+    expect(isRawConvertible(html)).toBe(true);
+  });
+
+  it('is true for a heading and figure hero with spacers ignored', () => {
+    const html = '<div class="wp-block-spacer" style="height:30px"></div>' +
+      '<h1>Stacked Hero</h1>' +
+      '<div class="wp-block-spacer" style="height:30px"></div>' +
+      '<figure class="wp-block-image"><img src="hero.jpg"/></figure>';
+    expect(isRawConvertible(html)).toBe(true);
+  });
+
+  it('is false for positioned div-soup with no semantic structure', () => {
+    const html = '<div class="comp-abc"><div class="comp-def"><div class="comp-ghi">' +
+      '<span>Label</span></div></div><div class="comp-jkl"><span>Other</span></div></div>';
+    expect(isRawConvertible(html)).toBe(false);
+  });
+
+  it('is false for empty input', () => {
+    expect(isRawConvertible('')).toBe(false);
+  });
+
+  it('is false at ratio 0.5 and true at ratio 0.6', () => {
+    expect(isRawConvertible(
+      '<p>First paragraph.</p><p>Second paragraph.</p><div class="box"><span>x</span></div><div class="box"><span>y</span></div>',
+    )).toBe(false);
+    expect(isRawConvertible(
+      '<h2>Heading</h2><p>First paragraph.</p><p>Second paragraph.</p><div class="box"><span>x</span></div><div class="box"><span>y</span></div>',
+    )).toBe(true);
+  });
+
+  it('unwraps nested layout wrappers', () => {
+    const html =
+      '<main><div class="wp-block-group"><div class="wp-block-post-content">' +
+      '<h1>Title</h1><p>copy</p>' +
+      '</div></div></main>';
+    expect(isRawConvertible(html)).toBe(true);
+  });
+
+  it('exports the shared unwrap selector used by rawConvert', () => {
+    expect(UNWRAP_SELECTOR).toBe(
+      'main, div.wp-block-group, div.wp-block-post-content, div.entry-content, div.wp-block-group__inner-container',
+    );
+  });
+});
diff --git a/packages/blocks-engine/src/raw-convertible.ts b/packages/blocks-engine/src/raw-convertible.ts
new file mode 100644
index 00000000..31db04d2
--- /dev/null
+++ b/packages/blocks-engine/src/raw-convertible.ts
@@ -0,0 +1,44 @@
+import * as cheerio from 'cheerio';
+import type { Element } from 'domhandler';
+
+export const UNWRAP_SELECTOR =
+  'main, div.wp-block-group, div.wp-block-post-content, div.entry-content, div.wp-block-group__inner-container';
+
+const SEMANTIC_TAGS = new Set([
+  'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'ul', 'ol', 'dl',
+  'blockquote', 'table', 'pre', 'figure', 'hr', 'address',
+]);
+
+const SEMANTIC_FLOOR = 0.6;
+
+export function isRawConvertible(html: string): boolean {
+  if (!html || !html.trim()) return false;
+  const $ = cheerio.load(html, null, false);
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+    $(UNWRAP_SELECTOR).each((_, el) => {
+      const $el = $(el);
+      if (($el.attr('class') || '').includes('wp-block-spacer')) return;
+      $el.replaceWith($el.contents());
+      changed = true;
+    });
+  }
+
+  let semantic = 0;
+  let nonSemantic = 0;
+  $.root()
+    .children()
+    .each((_, el) => {
+      if ((el as Element).type !== 'tag') return;
+      const tag = ((el as Element).tagName || '').toLowerCase();
+      const cls = $(el).attr('class') || '';
+      if (cls.includes('wp-block-spacer')) return;
+      if (SEMANTIC_TAGS.has(tag)) semantic++;
+      else nonSemantic++;
+    });
+
+  const total = semantic + nonSemantic;
+  return total > 0 && semantic >= 1 && semantic / total >= SEMANTIC_FLOOR;
+}
diff --git a/packages/blocks-engine/src/wp/raw-convert.ts b/packages/blocks-engine/src/wp/raw-convert.ts
index 02dcd005..6c1e2032 100644
--- a/packages/blocks-engine/src/wp/raw-convert.ts
+++ b/packages/blocks-engine/src/wp/raw-convert.ts
@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module';
 import { bootstrap } from './bootstrap';
+import { UNWRAP_SELECTOR } from '../raw-convertible';
 
 type JSDOMConstructor = new (html: string) => { window: { document: Document } };
 type RawHandler = (options: { HTML: string }) => unknown[];
@@ -49,10 +50,6 @@ function loadRuntime(): Runtime {
 //      -> wp:html; we splice a real wp:spacer (source height) after serialize.
 //
 
-// TODO(D5): import shared UNWRAP_SELECTOR from ../raw-convertible
-const UNWRAP_SELECTOR =
-  'main, div.wp-block-group, div.wp-block-post-content, div.entry-content, div.wp-block-group__inner-container';
-
 function spacerBlock(height: string): string {
   const h = height || '50px';
   return `<!-- wp:spacer {"height":"${h}"} -->\n<div style="height:${h}" aria-hidden="true" class="wp-block-spacer"></div>\n<!-- /wp:spacer -->`;

From 1a86bc8c89940a39182f211080aab5e2525587e6 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 22:12:19 -0400
Subject: [PATCH 015/113] fix(blocks-engine): avoid domhandler type dependency

---
 .../blocks-engine/src/__tests__/recipe-table.test.ts  |  5 ++---
 packages/blocks-engine/src/catalog.ts                 |  9 ++++++---
 packages/blocks-engine/src/raw-convertible.ts         |  6 +++---
 packages/blocks-engine/src/recipe-table.ts            | 11 +++++++----
 4 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/recipe-table.test.ts b/packages/blocks-engine/src/__tests__/recipe-table.test.ts
index 84c8d03e..aabc27b0 100644
--- a/packages/blocks-engine/src/__tests__/recipe-table.test.ts
+++ b/packages/blocks-engine/src/__tests__/recipe-table.test.ts
@@ -1,8 +1,7 @@
 import * as cheerio from 'cheerio';
-import type { Element } from 'domhandler';
 import { describe, expect, it } from 'vitest';
 
-import { composeFromRecipes, emitRecipeBlock } from '../recipe-table';
+import { composeFromRecipes, emitRecipeBlock, type RecipeElement } from '../recipe-table';
 import type { RecipeRule } from '../types';
 
 const ctx = { url: 'https://x.test/p' };
@@ -21,7 +20,7 @@ describe('recipe-table', () => {
 
   it('escapes comment closers in attribute JSON', () => {
     const $ = cheerio.load('<div class="card">Body</div>', null, false);
-    const el = $.root().children().first().get(0) as Element;
+    const el = $.root().children().first().get(0) as RecipeElement;
     const rule: RecipeRule = {
       match: '.card',
       block: 'core/group',
diff --git a/packages/blocks-engine/src/catalog.ts b/packages/blocks-engine/src/catalog.ts
index b8a2b6fd..7ff8b89e 100644
--- a/packages/blocks-engine/src/catalog.ts
+++ b/packages/blocks-engine/src/catalog.ts
@@ -1,6 +1,5 @@
 import * as cheerio from 'cheerio';
-import type { Cheerio, CheerioAPI } from 'cheerio';
-import type { Element } from 'domhandler';
+import type { CheerioAPI } from 'cheerio';
 
 import { PIPELINE_ISLAND_OPENER } from './block-policy';
 import { buildEmbedBlock, guessEmbedProvider } from './embed';
@@ -9,6 +8,10 @@ import { sanitize } from './sanitize';
 import type { ConversionContext } from './types';
 
 type HtmlFallbackEmitter = (html: string) => string;
+type Element = NonNullable<Parameters<CheerioAPI>[0]> & {
+  type?: string;
+  tagName: string;
+};
 
 interface Converted {
   matched: boolean;
@@ -115,7 +118,7 @@ function tryDetails(
   );
 }
 
-function bodyExcludingSummary($: CheerioAPI, $el: Cheerio<Element>): string {
+function bodyExcludingSummary($: CheerioAPI, $el: ReturnType<CheerioAPI>): string {
   const clone = $el.clone();
   clone.find('summary').first().remove();
   clone.children('h1,h2,h3,h4,h5,h6,.accordion-title,.faq-question').first().remove();
diff --git a/packages/blocks-engine/src/raw-convertible.ts b/packages/blocks-engine/src/raw-convertible.ts
index 31db04d2..6ff8c063 100644
--- a/packages/blocks-engine/src/raw-convertible.ts
+++ b/packages/blocks-engine/src/raw-convertible.ts
@@ -1,5 +1,4 @@
 import * as cheerio from 'cheerio';
-import type { Element } from 'domhandler';
 
 export const UNWRAP_SELECTOR =
   'main, div.wp-block-group, div.wp-block-post-content, div.entry-content, div.wp-block-group__inner-container';
@@ -31,8 +30,9 @@ export function isRawConvertible(html: string): boolean {
   $.root()
     .children()
     .each((_, el) => {
-      if ((el as Element).type !== 'tag') return;
-      const tag = ((el as Element).tagName || '').toLowerCase();
+      const node = el as { type?: string; tagName?: string };
+      if (node.type !== 'tag') return;
+      const tag = (node.tagName || '').toLowerCase();
       const cls = $(el).attr('class') || '';
       if (cls.includes('wp-block-spacer')) return;
       if (SEMANTIC_TAGS.has(tag)) semantic++;
diff --git a/packages/blocks-engine/src/recipe-table.ts b/packages/blocks-engine/src/recipe-table.ts
index ce74b612..ae957699 100644
--- a/packages/blocks-engine/src/recipe-table.ts
+++ b/packages/blocks-engine/src/recipe-table.ts
@@ -1,6 +1,5 @@
 import * as cheerio from 'cheerio';
 import type { CheerioAPI } from 'cheerio';
-import type { Element } from 'domhandler';
 
 import { PIPELINE_ISLAND_OPENER } from './block-policy';
 import { escapeHtmlAttr as escapeAttr, escapeHtmlText as escapeHtml } from './escape';
@@ -8,6 +7,10 @@ import { sanitize } from './sanitize';
 import type { ConversionContext, RecipeRule } from './types';
 
 type HtmlFallbackEmitter = (html: string) => string;
+export type RecipeElement = NonNullable<Parameters<CheerioAPI>[0]> & {
+  type?: string;
+  tagName: string;
+};
 
 function defaultHtmlFallback(html: string): string {
   return `${PIPELINE_ISLAND_OPENER}\n${sanitize(html)}\n<!-- /wp:html -->`;
@@ -23,8 +26,8 @@ export function composeFromRecipes(
   const $ = cheerio.load(html, null, false);
   const out: string[] = [];
   $.root().children().each((_, node) => {
-    if ((node as Element).type !== 'tag') return;
-    const el = node as Element;
+    const el = node as unknown as RecipeElement;
+    if (el.type !== 'tag') return;
     const recipe = recipes.find((candidate) => $(el).is(candidate.match));
     out.push(recipe ? emitRecipeBlock($, el, recipe, ctx, htmlFallback) : htmlFallback($.html(el)));
   });
@@ -38,7 +41,7 @@ export function blockTag(block: string): string {
 
 export function emitRecipeBlock(
   $: CheerioAPI,
-  el: Element,
+  el: RecipeElement,
   recipe: RecipeRule,
   ctx: ConversionContext,
   htmlFallback: HtmlFallbackEmitter = defaultHtmlFallback,

From 8ead5fff654621be78631e498ee39e8b5cd5eb93 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 22:12:25 -0400
Subject: [PATCH 016/113] feat(blocks-engine): wire convert and default entry

---
 .../src/__tests__/convert.test.ts             | 54 +++++++++++++++++++
 packages/blocks-engine/src/index.ts           | 24 +++++++--
 packages/blocks-engine/src/wp/index.ts        | 16 ++++--
 3 files changed, 87 insertions(+), 7 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/convert.test.ts

diff --git a/packages/blocks-engine/src/__tests__/convert.test.ts b/packages/blocks-engine/src/__tests__/convert.test.ts
new file mode 100644
index 00000000..57e1be94
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/convert.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+
+import * as defaultEntry from '../index';
+import cases from '../__fixtures__/cases.json' with { type: 'json' };
+import { canonicalize } from '../wp/canonicalize';
+import { convert } from '../wp';
+
+type Fixture = {
+  id: string;
+  op: 'rawConvert' | 'canonicalize' | 'compose';
+  input: string;
+  expected: unknown;
+};
+
+const fixtures = cases as Fixture[];
+const fixture = (id: string) => {
+  const found = fixtures.find((candidate) => candidate.id === id);
+  if (!found) throw new Error(`Missing fixture ${id}`);
+  return found;
+};
+
+describe('convert', () => {
+  it('composes the original source when rawConvert leaves html residue, then canonicalizes', () => {
+    const composeFixture = fixture('compose.sample-callout-div') as Fixture & { expected: string };
+    expect(convert(composeFixture.input, { url: 'https://x.test/' })).toBe(
+      canonicalize(composeFixture.expected).html,
+    );
+  });
+
+  it('keeps clean rawConvert output before canonicalizing', () => {
+    const rawFixture = fixture('raw.smoke-heading-paragraph-table') as Fixture & {
+      expected: { html: string; wpHtmlResidue: number };
+    };
+    expect(convert(rawFixture.input, { url: 'https://x.test/' })).toBe(
+      canonicalize(rawFixture.expected.html).html,
+    );
+  });
+});
+
+describe('default entry', () => {
+  it('exports the React-free public surface', () => {
+    expect(typeof defaultEntry.compose).toBe('function');
+    expect(typeof defaultEntry.createWorker).toBe('function');
+    expect(typeof defaultEntry.isRawConvertible).toBe('function');
+    expect(typeof defaultEntry.escapeHtmlText).toBe('function');
+    expect(typeof defaultEntry.escapeHtmlAttr).toBe('function');
+    expect(typeof defaultEntry.buildEmbedBlock).toBe('function');
+    expect(typeof defaultEntry.guessEmbedProvider).toBe('function');
+    expect(typeof defaultEntry.sanitize).toBe('function');
+    expect(typeof defaultEntry.blockMarkupRoundtrips).toBe('function');
+    expect(typeof defaultEntry.verifyComposedOutput).toBe('function');
+    expect(typeof defaultEntry.heuristicBlocks).toBe('function');
+  });
+});
diff --git a/packages/blocks-engine/src/index.ts b/packages/blocks-engine/src/index.ts
index a530279e..c02847be 100644
--- a/packages/blocks-engine/src/index.ts
+++ b/packages/blocks-engine/src/index.ts
@@ -1,3 +1,21 @@
-// @automattic/blocks-engine
-// Engine entry point — implementation added by subsequent tasks (D phase).
-export {};
+export { compose } from './compose';
+export { createWorker } from './pool/pool';
+export { isRawConvertible, UNWRAP_SELECTOR } from './raw-convertible';
+export { escapeHtml, escapeHtmlAttr, escapeHtmlText } from './escape';
+export { buildEmbedBlock, guessEmbedProvider } from './embed';
+export { sanitize } from './sanitize';
+export { blockMarkupRoundtrips } from './validate';
+export { verifyComposedOutput } from './output-verify';
+export { heuristicBlocks } from './heuristics';
+
+export type * from './types';
+export type { VerifyResult } from './output-verify';
+export type { HeuristicResult } from './heuristics';
+export type {
+  CreateWorker,
+  FixResult,
+  RawConvertResult,
+  WorkerPool,
+  WorkerPoolOptions,
+} from './pool/types';
+export type { PoolEvent } from './pool/events';
diff --git a/packages/blocks-engine/src/wp/index.ts b/packages/blocks-engine/src/wp/index.ts
index 603bdca8..9cc9a3dc 100644
--- a/packages/blocks-engine/src/wp/index.ts
+++ b/packages/blocks-engine/src/wp/index.ts
@@ -1,3 +1,5 @@
+import { compose } from '../compose';
+import type { ConversionContext } from '../types';
 import { canonicalize } from './canonicalize';
 import { rawConvert } from './raw-convert';
 
@@ -5,11 +7,17 @@ export { bootstrap } from './bootstrap';
 export { canonicalize } from './canonicalize';
 export { rawConvert } from './raw-convert';
 
-export type ConvertContext = { url?: string };
+export type ConvertContext = Partial<ConversionContext>;
 
 export function convert(html: string, ctx?: ConvertContext): string {
-  void ctx;
   const raw = rawConvert(html);
-  // D6: insert compose() between rawConvert and canonicalize
-  return canonicalize(raw.html ?? '').html;
+  const conversionCtx: ConversionContext = {
+    url: ctx?.url ?? '',
+    ...(ctx?.mediaMap ? { mediaMap: ctx.mediaMap } : {}),
+  };
+  const blockMarkup =
+    raw.html !== null && raw.wpHtmlResidue === 0
+      ? raw.html
+      : compose(html, conversionCtx, {});
+  return canonicalize(blockMarkup).html;
 }

From e17dc024d8d865448299a31eb4679d1abbcb32b9 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 22:48:52 -0400
Subject: [PATCH 017/113] fix(blocks-engine): restore injection scan+throw in
 default htmlFallback

---
 .../src/__tests__/compose.injection.test.ts   | 21 +++++++++++++++++++
 packages/blocks-engine/src/compose.ts         |  8 ++++++-
 packages/blocks-engine/src/validate.ts        | 14 +++++++++++++
 3 files changed, 42 insertions(+), 1 deletion(-)
 create mode 100644 packages/blocks-engine/src/__tests__/compose.injection.test.ts

diff --git a/packages/blocks-engine/src/__tests__/compose.injection.test.ts b/packages/blocks-engine/src/__tests__/compose.injection.test.ts
new file mode 100644
index 00000000..cf762676
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/compose.injection.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import { compose } from '../compose';
+
+const ctx = { url: 'https://x.test/' };
+
+describe('compose default htmlFallback injection guard', () => {
+  it('throws when sanitized fallback html still contains a quote-adjacent event handler', () => {
+    expect(() => compose('<img src="x"onerror="alert(1)">', ctx, {})).toThrow(
+      /html-fallback sanitization left injection vectors|inline event handler/,
+    );
+  });
+
+  it('keeps clean unconvertible html in the coverage island', () => {
+    const out = compose('<section><h2>Clean</h2><p>ok</p></section>', ctx, {});
+
+    expect(out).toContain('metadata":{"name":"lib-coverage-island"}');
+    expect(out).toContain('<section><h2>Clean</h2><p>ok</p></section>');
+    expect(out).toContain('<!-- /wp:html -->');
+  });
+});
diff --git a/packages/blocks-engine/src/compose.ts b/packages/blocks-engine/src/compose.ts
index 129c7d39..dd450be3 100644
--- a/packages/blocks-engine/src/compose.ts
+++ b/packages/blocks-engine/src/compose.ts
@@ -1,12 +1,18 @@
 import { PIPELINE_ISLAND_OPENER } from './block-policy';
 import { genericHtmlToBlocks } from './catalog';
 import { sanitize } from './sanitize';
+import { scanForInjection } from './validate';
 import type { ConversionContext, Converter, HtmlFallback } from './types';
 
 type HtmlFallbackEmitter = (html: string) => string;
 
 function defaultHtmlFallback(html: string): string {
-  return `${PIPELINE_ISLAND_OPENER}\n${sanitize(html).trim()}\n<!-- /wp:html -->`;
+  const inner = sanitize(html);
+  const violations = scanForInjection(inner);
+  if (violations.length > 0) {
+    throw new Error(`html-fallback sanitization left injection vectors: ${violations.join('; ')}`);
+  }
+  return `${PIPELINE_ISLAND_OPENER}\n${inner.trim()}\n<!-- /wp:html -->`;
 }
 
 function normalizeHtmlFallback(htmlFallback: HtmlFallback | undefined): HtmlFallbackEmitter {
diff --git a/packages/blocks-engine/src/validate.ts b/packages/blocks-engine/src/validate.ts
index 900eddcc..91d15525 100644
--- a/packages/blocks-engine/src/validate.ts
+++ b/packages/blocks-engine/src/validate.ts
@@ -1,3 +1,17 @@
+export function scanForInjection(markup: string): string[] {
+  const violations: string[] = [];
+  if (/<\?/.test(markup)) {
+    violations.push('raw PHP tag in markup (not allowed)');
+  }
+  if (/<\s*script/i.test(markup)) {
+    violations.push('raw <script> tag in markup (not allowed)');
+  }
+  if (/[\s"'/]on[a-z]+\s*=/i.test(markup)) {
+    violations.push('inline event handler attribute (on*=) in markup (not allowed)');
+  }
+  return violations;
+}
+
 export function blockMarkupRoundtrips(
   markup: string,
 ): { ok: true } | { ok: false; reason: string } {

From e3e8cda51c75821932e56997acdfd2b962a9444c Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 22 Jun 2026 23:24:58 -0400
Subject: [PATCH 018/113] fix(blocks-engine): resolve worker-child path in the
 bundled dist layout

---
 .../scripts/smoke-built-pool.mjs              | 22 +++++++++++++++++++
 packages/blocks-engine/src/pool/pool.ts       | 14 ++++++++----
 2 files changed, 32 insertions(+), 4 deletions(-)
 create mode 100644 packages/blocks-engine/scripts/smoke-built-pool.mjs

diff --git a/packages/blocks-engine/scripts/smoke-built-pool.mjs b/packages/blocks-engine/scripts/smoke-built-pool.mjs
new file mode 100644
index 00000000..f4d347e3
--- /dev/null
+++ b/packages/blocks-engine/scripts/smoke-built-pool.mjs
@@ -0,0 +1,22 @@
+import { createWorker } from '../dist/index.js';
+
+const input = '<section><h2>x</h2><p>y</p></section>';
+const worker = createWorker();
+
+function stringifyResult(result) {
+  return JSON.stringify(result, (_key, value) => (value === Infinity ? 'Infinity' : value));
+}
+
+try {
+  const out = await worker.rawConvert([input]);
+  const first = out[0];
+
+  if (!first || typeof first.html !== 'string' || !first.html.includes('<!-- wp:')) {
+    console.error(`FAIL ${stringifyResult(first)}`);
+    process.exitCode = 1;
+  } else {
+    console.log('OK');
+  }
+} finally {
+  await worker.stop();
+}
diff --git a/packages/blocks-engine/src/pool/pool.ts b/packages/blocks-engine/src/pool/pool.ts
index e8056277..41e76553 100644
--- a/packages/blocks-engine/src/pool/pool.ts
+++ b/packages/blocks-engine/src/pool/pool.ts
@@ -89,11 +89,17 @@ function normalizeSize(size: number | undefined): number {
 function workerChildPath(): string {
   const here = fileURLToPath(import.meta.url);
   const poolDir = dirname(here);
-  const sourcePath = resolve(poolDir, '..', 'wp', 'worker-child.ts');
-  if (existsSync(sourcePath)) {
-    return sourcePath;
+  const candidates = [
+    resolve(poolDir, 'wp', 'worker-child.js'),
+    resolve(poolDir, 'wp', 'worker-child.ts'),
+    resolve(poolDir, '..', 'wp', 'worker-child.ts'),
+    resolve(poolDir, '..', 'wp', 'worker-child.js'),
+  ];
+  const workerPath = candidates.find((candidate) => existsSync(candidate));
+  if (workerPath) {
+    return workerPath;
   }
-  return resolve(poolDir, '..', 'wp', 'worker-child.js');
+  throw new Error(`Unable to resolve worker child path. Tried: ${candidates.join(', ')}`);
 }
 
 function forkExecArgv(path: string): string[] {

From 29d81c65e6850a4ed8657fc3b4a726dd8e7c59d3 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Tue, 23 Jun 2026 07:10:31 -0400
Subject: [PATCH 019/113] chore(blocks-engine): consume as tsx source (keep
 tsup for publish) + export catalog/recipe-table primitives

---
 packages/blocks-engine/package.json           |  12 +-
 packages/blocks-engine/src/index.ts           | 157 +++++++++++++++---
 packages/blocks-engine/src/internal-index.ts  |  23 +++
 packages/blocks-engine/src/wp/index.ts        |  62 ++++---
 .../blocks-engine/src/wp/internal-index.ts    |  23 +++
 packages/blocks-engine/tsup.config.ts         |   6 +-
 6 files changed, 234 insertions(+), 49 deletions(-)
 create mode 100644 packages/blocks-engine/src/internal-index.ts
 create mode 100644 packages/blocks-engine/src/wp/internal-index.ts

diff --git a/packages/blocks-engine/package.json b/packages/blocks-engine/package.json
index df360939..be228cd7 100644
--- a/packages/blocks-engine/package.json
+++ b/packages/blocks-engine/package.json
@@ -5,14 +5,14 @@
   "type": "module",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "require": "./dist/index.cjs"
     },
     "./wp": {
-      "import": "./dist/wp/index.js",
-      "require": "./dist/wp/index.cjs",
-      "types": "./dist/wp/index.d.ts"
+      "types": "./src/wp/index.ts",
+      "import": "./src/wp/index.ts",
+      "require": "./dist/wp/index.cjs"
     }
   },
   "scripts": {
diff --git a/packages/blocks-engine/src/index.ts b/packages/blocks-engine/src/index.ts
index c02847be..ca2934dc 100644
--- a/packages/blocks-engine/src/index.ts
+++ b/packages/blocks-engine/src/index.ts
@@ -1,21 +1,136 @@
-export { compose } from './compose';
-export { createWorker } from './pool/pool';
-export { isRawConvertible, UNWRAP_SELECTOR } from './raw-convertible';
-export { escapeHtml, escapeHtmlAttr, escapeHtmlText } from './escape';
-export { buildEmbedBlock, guessEmbedProvider } from './embed';
-export { sanitize } from './sanitize';
-export { blockMarkupRoundtrips } from './validate';
-export { verifyComposedOutput } from './output-verify';
-export { heuristicBlocks } from './heuristics';
-
-export type * from './types';
-export type { VerifyResult } from './output-verify';
-export type { HeuristicResult } from './heuristics';
-export type {
-  CreateWorker,
-  FixResult,
-  RawConvertResult,
-  WorkerPool,
-  WorkerPoolOptions,
-} from './pool/types';
-export type { PoolEvent } from './pool/events';
+import { createRequire } from 'node:module';
+
+export interface ConversionContext {
+  url: string;
+  mediaMap?: Record<string, string>;
+}
+
+export type Converter = (
+  html: string,
+  ctx: ConversionContext,
+) => string | null;
+
+export interface RecipeRule {
+  match: string;
+  block: string;
+  attrs?: Record<string, unknown>;
+  inner?: 'innerHtml' | 'text' | 'images' | 'drop';
+}
+
+export type HtmlFallback = string | ((html: string) => string);
+
+export interface VerifyResult {
+  valid: boolean;
+  hallucinated: string[];
+}
+
+export interface HeuristicResult {
+  handled: boolean;
+  blocks?: string;
+  reason?: string;
+}
+
+export type RoundtripResult = { ok: true } | { ok: false; reason: string };
+
+export type PoolEvent = {
+  type:
+    | 'child-spawn'
+    | 'child-crash'
+    | 're-route'
+    | 'recycle'
+    | 'sentinel'
+    | 'pool-degraded';
+  childId?: number;
+  count?: number;
+};
+
+export interface RawConvertResult {
+  html: string | null;
+  wpHtmlResidue: number;
+}
+
+export interface FixResult {
+  html: string;
+  changed: boolean;
+  fixedIssues: string[];
+}
+
+export interface WorkerPoolOptions {
+  size?: number;
+  recycleAfter?: number;
+  maxReroutes?: number;
+  itemTimeoutMs?: number;
+  onEvent?: (e: PoolEvent) => void;
+}
+
+export interface WorkerPool {
+  rawConvert(items: string[]): Promise<RawConvertResult[]>;
+  canonicalize(items: string[]): Promise<FixResult[]>;
+  stop(): Promise<void>;
+}
+
+export type CreateWorker = (opts?: WorkerPoolOptions) => WorkerPool;
+
+type RuntimeEntry = {
+  compose: (
+    html: string,
+    ctx: ConversionContext,
+    opts?: { converters?: Converter[]; htmlFallback?: HtmlFallback },
+  ) => string;
+  createWorker: CreateWorker;
+  isRawConvertible: (html: string) => boolean;
+  UNWRAP_SELECTOR: string;
+  escapeHtml: (s: string) => string;
+  escapeHtmlAttr: (s: string) => string;
+  escapeHtmlText: (s: string) => string;
+  buildEmbedBlock: (url: string) => string;
+  guessEmbedProvider: (url: string) => string | null;
+  sanitize: (html: string) => string;
+  blockMarkupRoundtrips: (markup: string) => RoundtripResult;
+  verifyComposedOutput: (
+    blocksMarkup: string,
+    sourceHtmlPlainText: string,
+  ) => VerifyResult;
+  heuristicBlocks: (html: string) => HeuristicResult;
+  genericHtmlToBlocks: (
+    html: string,
+    ctx: ConversionContext,
+    htmlFallback?: (html: string) => string,
+  ) => string | null;
+  composeFromRecipes: (
+    html: string,
+    recipes: RecipeRule[],
+    ctx: ConversionContext,
+    htmlFallback?: (html: string) => string,
+  ) => string | null;
+};
+
+const require = createRequire(import.meta.url);
+
+function loadRuntimeEntry(): RuntimeEntry {
+  const { require: tsxRequire } = require('tsx/cjs/api') as {
+    require: (id: string, parentURL: string) => unknown;
+  };
+  return tsxRequire('./internal-index.ts', import.meta.url) as RuntimeEntry;
+}
+
+const entry =
+  process.env.VITEST_WORKER_ID !== undefined
+    ? ((await import(`./internal-index.${'ts'}`)) as RuntimeEntry)
+    : loadRuntimeEntry();
+
+export const compose = entry.compose;
+export const createWorker = entry.createWorker;
+export const isRawConvertible = entry.isRawConvertible;
+export const UNWRAP_SELECTOR = entry.UNWRAP_SELECTOR;
+export const escapeHtml = entry.escapeHtml;
+export const escapeHtmlAttr = entry.escapeHtmlAttr;
+export const escapeHtmlText = entry.escapeHtmlText;
+export const buildEmbedBlock = entry.buildEmbedBlock;
+export const guessEmbedProvider = entry.guessEmbedProvider;
+export const sanitize = entry.sanitize;
+export const blockMarkupRoundtrips = entry.blockMarkupRoundtrips;
+export const verifyComposedOutput = entry.verifyComposedOutput;
+export const heuristicBlocks = entry.heuristicBlocks;
+export const genericHtmlToBlocks = entry.genericHtmlToBlocks;
+export const composeFromRecipes = entry.composeFromRecipes;
diff --git a/packages/blocks-engine/src/internal-index.ts b/packages/blocks-engine/src/internal-index.ts
new file mode 100644
index 00000000..342cdedc
--- /dev/null
+++ b/packages/blocks-engine/src/internal-index.ts
@@ -0,0 +1,23 @@
+export { compose } from './compose';
+export { createWorker } from './pool/pool';
+export { isRawConvertible, UNWRAP_SELECTOR } from './raw-convertible';
+export { escapeHtml, escapeHtmlAttr, escapeHtmlText } from './escape';
+export { buildEmbedBlock, guessEmbedProvider } from './embed';
+export { sanitize } from './sanitize';
+export { blockMarkupRoundtrips } from './validate';
+export { verifyComposedOutput } from './output-verify';
+export { heuristicBlocks } from './heuristics';
+export { genericHtmlToBlocks } from './catalog';
+export { composeFromRecipes } from './recipe-table';
+
+export type * from './types';
+export type { VerifyResult } from './output-verify';
+export type { HeuristicResult } from './heuristics';
+export type {
+  CreateWorker,
+  FixResult,
+  RawConvertResult,
+  WorkerPool,
+  WorkerPoolOptions,
+} from './pool/types';
+export type { PoolEvent } from './pool/events';
diff --git a/packages/blocks-engine/src/wp/index.ts b/packages/blocks-engine/src/wp/index.ts
index 9cc9a3dc..d6549a3d 100644
--- a/packages/blocks-engine/src/wp/index.ts
+++ b/packages/blocks-engine/src/wp/index.ts
@@ -1,23 +1,43 @@
-import { compose } from '../compose';
-import type { ConversionContext } from '../types';
-import { canonicalize } from './canonicalize';
-import { rawConvert } from './raw-convert';
-
-export { bootstrap } from './bootstrap';
-export { canonicalize } from './canonicalize';
-export { rawConvert } from './raw-convert';
-
-export type ConvertContext = Partial<ConversionContext>;
-
-export function convert(html: string, ctx?: ConvertContext): string {
-  const raw = rawConvert(html);
-  const conversionCtx: ConversionContext = {
-    url: ctx?.url ?? '',
-    ...(ctx?.mediaMap ? { mediaMap: ctx.mediaMap } : {}),
+import { createRequire } from 'node:module';
+
+export type ConvertContext = {
+  url?: string;
+  mediaMap?: Record<string, string>;
+};
+
+export type CanonicalizeResult = {
+  html: string;
+  changed: boolean;
+  fixedIssues: string[];
+};
+
+export type RawConvertResult = {
+  html: string | null;
+  wpHtmlResidue: number;
+};
+
+type RuntimeWpEntry = {
+  bootstrap: () => void;
+  canonicalize: (markup: string) => CanonicalizeResult;
+  rawConvert: (html: string) => RawConvertResult;
+  convert: (html: string, ctx?: ConvertContext) => string;
+};
+
+const require = createRequire(import.meta.url);
+
+function loadRuntimeEntry(): RuntimeWpEntry {
+  const { require: tsxRequire } = require('tsx/cjs/api') as {
+    require: (id: string, parentURL: string) => unknown;
   };
-  const blockMarkup =
-    raw.html !== null && raw.wpHtmlResidue === 0
-      ? raw.html
-      : compose(html, conversionCtx, {});
-  return canonicalize(blockMarkup).html;
+  return tsxRequire('./internal-index.ts', import.meta.url) as RuntimeWpEntry;
 }
+
+const entry =
+  process.env.VITEST_WORKER_ID !== undefined
+    ? ((await import(`./internal-index.${'ts'}`)) as RuntimeWpEntry)
+    : loadRuntimeEntry();
+
+export const bootstrap = entry.bootstrap;
+export const canonicalize = entry.canonicalize;
+export const rawConvert = entry.rawConvert;
+export const convert = entry.convert;
diff --git a/packages/blocks-engine/src/wp/internal-index.ts b/packages/blocks-engine/src/wp/internal-index.ts
new file mode 100644
index 00000000..9cc9a3dc
--- /dev/null
+++ b/packages/blocks-engine/src/wp/internal-index.ts
@@ -0,0 +1,23 @@
+import { compose } from '../compose';
+import type { ConversionContext } from '../types';
+import { canonicalize } from './canonicalize';
+import { rawConvert } from './raw-convert';
+
+export { bootstrap } from './bootstrap';
+export { canonicalize } from './canonicalize';
+export { rawConvert } from './raw-convert';
+
+export type ConvertContext = Partial<ConversionContext>;
+
+export function convert(html: string, ctx?: ConvertContext): string {
+  const raw = rawConvert(html);
+  const conversionCtx: ConversionContext = {
+    url: ctx?.url ?? '',
+    ...(ctx?.mediaMap ? { mediaMap: ctx.mediaMap } : {}),
+  };
+  const blockMarkup =
+    raw.html !== null && raw.wpHtmlResidue === 0
+      ? raw.html
+      : compose(html, conversionCtx, {});
+  return canonicalize(blockMarkup).html;
+}
diff --git a/packages/blocks-engine/tsup.config.ts b/packages/blocks-engine/tsup.config.ts
index 900e3231..4edaa7d2 100644
--- a/packages/blocks-engine/tsup.config.ts
+++ b/packages/blocks-engine/tsup.config.ts
@@ -1,7 +1,11 @@
 import { defineConfig } from 'tsup';
 
 export default defineConfig({
-  entry: ['src/index.ts', 'src/wp/index.ts', 'src/wp/worker-child.ts'],
+  entry: {
+    index: 'src/internal-index.ts',
+    'wp/index': 'src/wp/internal-index.ts',
+    'wp/worker-child': 'src/wp/worker-child.ts',
+  },
   format: ['esm', 'cjs'],
   dts: true,
   clean: true,

From 785d47ab04a525e3bd0ce1bc7b98c004fcb46828 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Tue, 23 Jun 2026 07:31:40 -0400
Subject: [PATCH 020/113] refactor(blocks-engine): plain re-export barrel entry
 (drop runtime tsx shim)

---
 packages/blocks-engine/src/catalog.ts         |  10 +-
 packages/blocks-engine/src/compose.ts         |  10 +-
 packages/blocks-engine/src/heuristics.ts      |   2 +-
 packages/blocks-engine/src/index.ts           | 159 +++---------------
 packages/blocks-engine/src/internal-index.ts  |  23 ---
 packages/blocks-engine/src/pool/pool.ts       |   8 +-
 packages/blocks-engine/src/pool/protocol.ts   |   2 +-
 packages/blocks-engine/src/pool/types.ts      |   2 +-
 packages/blocks-engine/src/recipe-table.ts    |   8 +-
 packages/blocks-engine/src/wp/canonicalize.ts |   2 +-
 packages/blocks-engine/src/wp/index.ts        |  65 +++----
 .../blocks-engine/src/wp/internal-index.ts    |  23 ---
 packages/blocks-engine/src/wp/raw-convert.ts  |   4 +-
 packages/blocks-engine/src/wp/worker-child.ts |   8 +-
 packages/blocks-engine/tsup.config.ts         |   4 +-
 15 files changed, 77 insertions(+), 253 deletions(-)
 delete mode 100644 packages/blocks-engine/src/internal-index.ts
 delete mode 100644 packages/blocks-engine/src/wp/internal-index.ts

diff --git a/packages/blocks-engine/src/catalog.ts b/packages/blocks-engine/src/catalog.ts
index 7ff8b89e..e9120af4 100644
--- a/packages/blocks-engine/src/catalog.ts
+++ b/packages/blocks-engine/src/catalog.ts
@@ -1,11 +1,11 @@
 import * as cheerio from 'cheerio';
 import type { CheerioAPI } from 'cheerio';
 
-import { PIPELINE_ISLAND_OPENER } from './block-policy';
-import { buildEmbedBlock, guessEmbedProvider } from './embed';
-import { escapeHtmlAttr as escapeAttr, escapeHtmlText as escapeHtml } from './escape';
-import { sanitize } from './sanitize';
-import type { ConversionContext } from './types';
+import { PIPELINE_ISLAND_OPENER } from './block-policy.js';
+import { buildEmbedBlock, guessEmbedProvider } from './embed.js';
+import { escapeHtmlAttr as escapeAttr, escapeHtmlText as escapeHtml } from './escape.js';
+import { sanitize } from './sanitize.js';
+import type { ConversionContext } from './types.js';
 
 type HtmlFallbackEmitter = (html: string) => string;
 type Element = NonNullable<Parameters<CheerioAPI>[0]> & {
diff --git a/packages/blocks-engine/src/compose.ts b/packages/blocks-engine/src/compose.ts
index dd450be3..803d4789 100644
--- a/packages/blocks-engine/src/compose.ts
+++ b/packages/blocks-engine/src/compose.ts
@@ -1,8 +1,8 @@
-import { PIPELINE_ISLAND_OPENER } from './block-policy';
-import { genericHtmlToBlocks } from './catalog';
-import { sanitize } from './sanitize';
-import { scanForInjection } from './validate';
-import type { ConversionContext, Converter, HtmlFallback } from './types';
+import { PIPELINE_ISLAND_OPENER } from './block-policy.js';
+import { genericHtmlToBlocks } from './catalog.js';
+import { sanitize } from './sanitize.js';
+import { scanForInjection } from './validate.js';
+import type { ConversionContext, Converter, HtmlFallback } from './types.js';
 
 type HtmlFallbackEmitter = (html: string) => string;
 
diff --git a/packages/blocks-engine/src/heuristics.ts b/packages/blocks-engine/src/heuristics.ts
index 00289342..ce4c1015 100644
--- a/packages/blocks-engine/src/heuristics.ts
+++ b/packages/blocks-engine/src/heuristics.ts
@@ -1,6 +1,6 @@
 import * as cheerio from 'cheerio';
 
-import { escapeHtmlText as escapeHtml } from './escape';
+import { escapeHtmlText as escapeHtml } from './escape.js';
 
 export interface HeuristicResult {
   handled: boolean;
diff --git a/packages/blocks-engine/src/index.ts b/packages/blocks-engine/src/index.ts
index ca2934dc..61308e03 100644
--- a/packages/blocks-engine/src/index.ts
+++ b/packages/blocks-engine/src/index.ts
@@ -1,136 +1,23 @@
-import { createRequire } from 'node:module';
-
-export interface ConversionContext {
-  url: string;
-  mediaMap?: Record<string, string>;
-}
-
-export type Converter = (
-  html: string,
-  ctx: ConversionContext,
-) => string | null;
-
-export interface RecipeRule {
-  match: string;
-  block: string;
-  attrs?: Record<string, unknown>;
-  inner?: 'innerHtml' | 'text' | 'images' | 'drop';
-}
-
-export type HtmlFallback = string | ((html: string) => string);
-
-export interface VerifyResult {
-  valid: boolean;
-  hallucinated: string[];
-}
-
-export interface HeuristicResult {
-  handled: boolean;
-  blocks?: string;
-  reason?: string;
-}
-
-export type RoundtripResult = { ok: true } | { ok: false; reason: string };
-
-export type PoolEvent = {
-  type:
-    | 'child-spawn'
-    | 'child-crash'
-    | 're-route'
-    | 'recycle'
-    | 'sentinel'
-    | 'pool-degraded';
-  childId?: number;
-  count?: number;
-};
-
-export interface RawConvertResult {
-  html: string | null;
-  wpHtmlResidue: number;
-}
-
-export interface FixResult {
-  html: string;
-  changed: boolean;
-  fixedIssues: string[];
-}
-
-export interface WorkerPoolOptions {
-  size?: number;
-  recycleAfter?: number;
-  maxReroutes?: number;
-  itemTimeoutMs?: number;
-  onEvent?: (e: PoolEvent) => void;
-}
-
-export interface WorkerPool {
-  rawConvert(items: string[]): Promise<RawConvertResult[]>;
-  canonicalize(items: string[]): Promise<FixResult[]>;
-  stop(): Promise<void>;
-}
-
-export type CreateWorker = (opts?: WorkerPoolOptions) => WorkerPool;
-
-type RuntimeEntry = {
-  compose: (
-    html: string,
-    ctx: ConversionContext,
-    opts?: { converters?: Converter[]; htmlFallback?: HtmlFallback },
-  ) => string;
-  createWorker: CreateWorker;
-  isRawConvertible: (html: string) => boolean;
-  UNWRAP_SELECTOR: string;
-  escapeHtml: (s: string) => string;
-  escapeHtmlAttr: (s: string) => string;
-  escapeHtmlText: (s: string) => string;
-  buildEmbedBlock: (url: string) => string;
-  guessEmbedProvider: (url: string) => string | null;
-  sanitize: (html: string) => string;
-  blockMarkupRoundtrips: (markup: string) => RoundtripResult;
-  verifyComposedOutput: (
-    blocksMarkup: string,
-    sourceHtmlPlainText: string,
-  ) => VerifyResult;
-  heuristicBlocks: (html: string) => HeuristicResult;
-  genericHtmlToBlocks: (
-    html: string,
-    ctx: ConversionContext,
-    htmlFallback?: (html: string) => string,
-  ) => string | null;
-  composeFromRecipes: (
-    html: string,
-    recipes: RecipeRule[],
-    ctx: ConversionContext,
-    htmlFallback?: (html: string) => string,
-  ) => string | null;
-};
-
-const require = createRequire(import.meta.url);
-
-function loadRuntimeEntry(): RuntimeEntry {
-  const { require: tsxRequire } = require('tsx/cjs/api') as {
-    require: (id: string, parentURL: string) => unknown;
-  };
-  return tsxRequire('./internal-index.ts', import.meta.url) as RuntimeEntry;
-}
-
-const entry =
-  process.env.VITEST_WORKER_ID !== undefined
-    ? ((await import(`./internal-index.${'ts'}`)) as RuntimeEntry)
-    : loadRuntimeEntry();
-
-export const compose = entry.compose;
-export const createWorker = entry.createWorker;
-export const isRawConvertible = entry.isRawConvertible;
-export const UNWRAP_SELECTOR = entry.UNWRAP_SELECTOR;
-export const escapeHtml = entry.escapeHtml;
-export const escapeHtmlAttr = entry.escapeHtmlAttr;
-export const escapeHtmlText = entry.escapeHtmlText;
-export const buildEmbedBlock = entry.buildEmbedBlock;
-export const guessEmbedProvider = entry.guessEmbedProvider;
-export const sanitize = entry.sanitize;
-export const blockMarkupRoundtrips = entry.blockMarkupRoundtrips;
-export const verifyComposedOutput = entry.verifyComposedOutput;
-export const heuristicBlocks = entry.heuristicBlocks;
-export const genericHtmlToBlocks = entry.genericHtmlToBlocks;
-export const composeFromRecipes = entry.composeFromRecipes;
+export { compose } from './compose.js';
+export { createWorker } from './pool/pool.js';
+export { isRawConvertible, UNWRAP_SELECTOR } from './raw-convertible.js';
+export { escapeHtml, escapeHtmlAttr, escapeHtmlText } from './escape.js';
+export { buildEmbedBlock, guessEmbedProvider } from './embed.js';
+export { sanitize } from './sanitize.js';
+export { blockMarkupRoundtrips } from './validate.js';
+export { verifyComposedOutput } from './output-verify.js';
+export { heuristicBlocks } from './heuristics.js';
+export { genericHtmlToBlocks } from './catalog.js';
+export { composeFromRecipes } from './recipe-table.js';
+
+export type * from './types.js';
+export type { VerifyResult } from './output-verify.js';
+export type { HeuristicResult } from './heuristics.js';
+export type {
+  CreateWorker,
+  FixResult,
+  RawConvertResult,
+  WorkerPool,
+  WorkerPoolOptions,
+} from './pool/types.js';
+export type { PoolEvent } from './pool/events.js';
diff --git a/packages/blocks-engine/src/internal-index.ts b/packages/blocks-engine/src/internal-index.ts
deleted file mode 100644
index 342cdedc..00000000
--- a/packages/blocks-engine/src/internal-index.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-export { compose } from './compose';
-export { createWorker } from './pool/pool';
-export { isRawConvertible, UNWRAP_SELECTOR } from './raw-convertible';
-export { escapeHtml, escapeHtmlAttr, escapeHtmlText } from './escape';
-export { buildEmbedBlock, guessEmbedProvider } from './embed';
-export { sanitize } from './sanitize';
-export { blockMarkupRoundtrips } from './validate';
-export { verifyComposedOutput } from './output-verify';
-export { heuristicBlocks } from './heuristics';
-export { genericHtmlToBlocks } from './catalog';
-export { composeFromRecipes } from './recipe-table';
-
-export type * from './types';
-export type { VerifyResult } from './output-verify';
-export type { HeuristicResult } from './heuristics';
-export type {
-  CreateWorker,
-  FixResult,
-  RawConvertResult,
-  WorkerPool,
-  WorkerPoolOptions,
-} from './pool/types';
-export type { PoolEvent } from './pool/events';
diff --git a/packages/blocks-engine/src/pool/pool.ts b/packages/blocks-engine/src/pool/pool.ts
index 41e76553..a8f4e801 100644
--- a/packages/blocks-engine/src/pool/pool.ts
+++ b/packages/blocks-engine/src/pool/pool.ts
@@ -4,22 +4,22 @@ import { cpus } from 'node:os';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import type { ChildToParentMessage, WorkerOp } from './protocol';
+import type { ChildToParentMessage, WorkerOp } from './protocol.js';
 import type {
   CreateWorker,
   FixResult,
   RawConvertResult,
   WorkerPool,
   WorkerPoolOptions,
-} from './types';
+} from './types.js';
 
 export type {
   FixResult,
   RawConvertResult,
   WorkerPool,
   WorkerPoolOptions,
-} from './types';
-export type { PoolEvent } from './events';
+} from './types.js';
+export type { PoolEvent } from './events.js';
 
 const DEFAULT_MAX_REROUTES = 2;
 const DEFAULT_ITEM_TIMEOUT_MS = 10_000;
diff --git a/packages/blocks-engine/src/pool/protocol.ts b/packages/blocks-engine/src/pool/protocol.ts
index c75ee705..746ef3d3 100644
--- a/packages/blocks-engine/src/pool/protocol.ts
+++ b/packages/blocks-engine/src/pool/protocol.ts
@@ -1,4 +1,4 @@
-import type { FixResult, RawConvertResult } from './types';
+import type { FixResult, RawConvertResult } from './types.js';
 
 export type WorkerOp = 'rawConvert' | 'canonicalize';
 
diff --git a/packages/blocks-engine/src/pool/types.ts b/packages/blocks-engine/src/pool/types.ts
index f5b31cfb..9c44c7eb 100644
--- a/packages/blocks-engine/src/pool/types.ts
+++ b/packages/blocks-engine/src/pool/types.ts
@@ -1,4 +1,4 @@
-import type { PoolEvent } from './events';
+import type { PoolEvent } from './events.js';
 
 export interface RawConvertResult {
   html: string | null;
diff --git a/packages/blocks-engine/src/recipe-table.ts b/packages/blocks-engine/src/recipe-table.ts
index ae957699..0aa3ac77 100644
--- a/packages/blocks-engine/src/recipe-table.ts
+++ b/packages/blocks-engine/src/recipe-table.ts
@@ -1,10 +1,10 @@
 import * as cheerio from 'cheerio';
 import type { CheerioAPI } from 'cheerio';
 
-import { PIPELINE_ISLAND_OPENER } from './block-policy';
-import { escapeHtmlAttr as escapeAttr, escapeHtmlText as escapeHtml } from './escape';
-import { sanitize } from './sanitize';
-import type { ConversionContext, RecipeRule } from './types';
+import { PIPELINE_ISLAND_OPENER } from './block-policy.js';
+import { escapeHtmlAttr as escapeAttr, escapeHtmlText as escapeHtml } from './escape.js';
+import { sanitize } from './sanitize.js';
+import type { ConversionContext, RecipeRule } from './types.js';
 
 type HtmlFallbackEmitter = (html: string) => string;
 export type RecipeElement = NonNullable<Parameters<CheerioAPI>[0]> & {
diff --git a/packages/blocks-engine/src/wp/canonicalize.ts b/packages/blocks-engine/src/wp/canonicalize.ts
index 97e2d152..7881a777 100644
--- a/packages/blocks-engine/src/wp/canonicalize.ts
+++ b/packages/blocks-engine/src/wp/canonicalize.ts
@@ -1,6 +1,6 @@
 import { createRequire } from 'node:module';
 
-import { bootstrap } from './bootstrap';
+import { bootstrap } from './bootstrap.js';
 
 export type CanonicalizeResult = {
   html: string;
diff --git a/packages/blocks-engine/src/wp/index.ts b/packages/blocks-engine/src/wp/index.ts
index d6549a3d..fa41dde2 100644
--- a/packages/blocks-engine/src/wp/index.ts
+++ b/packages/blocks-engine/src/wp/index.ts
@@ -1,43 +1,26 @@
-import { createRequire } from 'node:module';
-
-export type ConvertContext = {
-  url?: string;
-  mediaMap?: Record<string, string>;
-};
-
-export type CanonicalizeResult = {
-  html: string;
-  changed: boolean;
-  fixedIssues: string[];
-};
-
-export type RawConvertResult = {
-  html: string | null;
-  wpHtmlResidue: number;
-};
-
-type RuntimeWpEntry = {
-  bootstrap: () => void;
-  canonicalize: (markup: string) => CanonicalizeResult;
-  rawConvert: (html: string) => RawConvertResult;
-  convert: (html: string, ctx?: ConvertContext) => string;
-};
-
-const require = createRequire(import.meta.url);
-
-function loadRuntimeEntry(): RuntimeWpEntry {
-  const { require: tsxRequire } = require('tsx/cjs/api') as {
-    require: (id: string, parentURL: string) => unknown;
+import { compose } from '../compose.js';
+import type { RawConvertResult } from '../pool/types.js';
+import type { ConversionContext } from '../types.js';
+import { canonicalize } from './canonicalize.js';
+import { rawConvert } from './raw-convert.js';
+
+export { bootstrap } from './bootstrap.js';
+export { canonicalize } from './canonicalize.js';
+export type { CanonicalizeResult } from './canonicalize.js';
+export { rawConvert } from './raw-convert.js';
+export type { RawConvertResult } from '../pool/types.js';
+
+export type ConvertContext = Partial<ConversionContext>;
+
+export function convert(html: string, ctx?: ConvertContext): string {
+  const raw: RawConvertResult = rawConvert(html);
+  const conversionCtx: ConversionContext = {
+    url: ctx?.url ?? '',
+    ...(ctx?.mediaMap ? { mediaMap: ctx.mediaMap } : {}),
   };
-  return tsxRequire('./internal-index.ts', import.meta.url) as RuntimeWpEntry;
+  const blockMarkup =
+    raw.html !== null && raw.wpHtmlResidue === 0
+      ? raw.html
+      : compose(html, conversionCtx, {});
+  return canonicalize(blockMarkup).html;
 }
-
-const entry =
-  process.env.VITEST_WORKER_ID !== undefined
-    ? ((await import(`./internal-index.${'ts'}`)) as RuntimeWpEntry)
-    : loadRuntimeEntry();
-
-export const bootstrap = entry.bootstrap;
-export const canonicalize = entry.canonicalize;
-export const rawConvert = entry.rawConvert;
-export const convert = entry.convert;
diff --git a/packages/blocks-engine/src/wp/internal-index.ts b/packages/blocks-engine/src/wp/internal-index.ts
deleted file mode 100644
index 9cc9a3dc..00000000
--- a/packages/blocks-engine/src/wp/internal-index.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-import { compose } from '../compose';
-import type { ConversionContext } from '../types';
-import { canonicalize } from './canonicalize';
-import { rawConvert } from './raw-convert';
-
-export { bootstrap } from './bootstrap';
-export { canonicalize } from './canonicalize';
-export { rawConvert } from './raw-convert';
-
-export type ConvertContext = Partial<ConversionContext>;
-
-export function convert(html: string, ctx?: ConvertContext): string {
-  const raw = rawConvert(html);
-  const conversionCtx: ConversionContext = {
-    url: ctx?.url ?? '',
-    ...(ctx?.mediaMap ? { mediaMap: ctx.mediaMap } : {}),
-  };
-  const blockMarkup =
-    raw.html !== null && raw.wpHtmlResidue === 0
-      ? raw.html
-      : compose(html, conversionCtx, {});
-  return canonicalize(blockMarkup).html;
-}
diff --git a/packages/blocks-engine/src/wp/raw-convert.ts b/packages/blocks-engine/src/wp/raw-convert.ts
index 6c1e2032..1ac46ba6 100644
--- a/packages/blocks-engine/src/wp/raw-convert.ts
+++ b/packages/blocks-engine/src/wp/raw-convert.ts
@@ -1,6 +1,6 @@
 import { createRequire } from 'node:module';
-import { bootstrap } from './bootstrap';
-import { UNWRAP_SELECTOR } from '../raw-convertible';
+import { bootstrap } from './bootstrap.js';
+import { UNWRAP_SELECTOR } from '../raw-convertible.js';
 
 type JSDOMConstructor = new (html: string) => { window: { document: Document } };
 type RawHandler = (options: { HTML: string }) => unknown[];
diff --git a/packages/blocks-engine/src/wp/worker-child.ts b/packages/blocks-engine/src/wp/worker-child.ts
index 236ab7f0..0fde3e2b 100644
--- a/packages/blocks-engine/src/wp/worker-child.ts
+++ b/packages/blocks-engine/src/wp/worker-child.ts
@@ -1,11 +1,11 @@
-import { bootstrap } from './bootstrap';
-import { canonicalize } from './canonicalize';
-import { rawConvert } from './raw-convert';
+import { bootstrap } from './bootstrap.js';
+import { canonicalize } from './canonicalize.js';
+import { rawConvert } from './raw-convert.js';
 import type {
   ChildToParentMessage,
   ParentToChildMessage,
   WorkerError,
-} from '../pool/protocol';
+} from '../pool/protocol.js';
 
 const POISON_EXIT_CODE = 86;
 const BOOTSTRAP_FAIL_EXIT_CODE = 87;
diff --git a/packages/blocks-engine/tsup.config.ts b/packages/blocks-engine/tsup.config.ts
index 4edaa7d2..1d2348a0 100644
--- a/packages/blocks-engine/tsup.config.ts
+++ b/packages/blocks-engine/tsup.config.ts
@@ -2,8 +2,8 @@ import { defineConfig } from 'tsup';
 
 export default defineConfig({
   entry: {
-    index: 'src/internal-index.ts',
-    'wp/index': 'src/wp/internal-index.ts',
+    index: 'src/index.ts',
+    'wp/index': 'src/wp/index.ts',
     'wp/worker-child': 'src/wp/worker-child.ts',
   },
   format: ['esm', 'cjs'],

From 2a55e340a5ecfba91ae7f0560d2a39fc500b198a Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Tue, 23 Jun 2026 13:32:30 -0400
Subject: [PATCH 021/113] feat(blocks-engine): export island constants +
 scanForInjection + serializeBlockAttrs

---
 .../src/__tests__/serialize.test.ts           | 42 +++++++++++++++++++
 packages/blocks-engine/src/index.ts           |  4 +-
 packages/blocks-engine/src/serialize.ts       |  8 ++++
 3 files changed, 53 insertions(+), 1 deletion(-)
 create mode 100644 packages/blocks-engine/src/__tests__/serialize.test.ts
 create mode 100644 packages/blocks-engine/src/serialize.ts

diff --git a/packages/blocks-engine/src/__tests__/serialize.test.ts b/packages/blocks-engine/src/__tests__/serialize.test.ts
new file mode 100644
index 00000000..17b4f737
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/serialize.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+
+import { serializeBlockAttrs } from '../serialize';
+
+function dlaSerializeBlockAttrs(attrs: Record<string, unknown>): string {
+  return JSON.stringify(attrs)
+    .replace(/--/g, '\\u002d\\u002d')
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\\"/g, '\\u0022');
+}
+
+describe('serializeBlockAttrs', () => {
+  it('escapes comment-delimiter and markup-sensitive bytes', () => {
+    expect(serializeBlockAttrs({ name: 'a--b' })).toBe('{"name":"a\\u002d\\u002db"}');
+    expect(serializeBlockAttrs({ html: '<b>x</b> & y' })).toBe(
+      '{"html":"\\u003cb\\u003ex\\u003c/b\\u003e \\u0026 y"}',
+    );
+  });
+
+  it('keeps quoted values parseable after unicode escaping', () => {
+    const serialized = serializeBlockAttrs({ label: 'A "quoted" value' });
+
+    expect(serialized).toBe('{"label":"A \\u0022quoted\\u0022 value"}');
+    expect(JSON.parse(serialized)).toEqual({ label: 'A "quoted" value' });
+  });
+
+  it('matches the DLA form-blocks serializer on a shared corpus', () => {
+    const corpus: Array<Record<string, unknown>> = [
+      {},
+      { name: 'plain' },
+      { name: 'a--b', label: 'A "quoted" value' },
+      { html: '<span data-x="1">A & B</span>' },
+      { nested: { text: 'x --> <script>alert("y")</script>' }, list: ['a&b', 3, true] },
+    ];
+
+    for (const attrs of corpus) {
+      expect(serializeBlockAttrs(attrs)).toBe(dlaSerializeBlockAttrs(attrs));
+    }
+  });
+});
diff --git a/packages/blocks-engine/src/index.ts b/packages/blocks-engine/src/index.ts
index 61308e03..a6e3fc6c 100644
--- a/packages/blocks-engine/src/index.ts
+++ b/packages/blocks-engine/src/index.ts
@@ -2,13 +2,15 @@ export { compose } from './compose.js';
 export { createWorker } from './pool/pool.js';
 export { isRawConvertible, UNWRAP_SELECTOR } from './raw-convertible.js';
 export { escapeHtml, escapeHtmlAttr, escapeHtmlText } from './escape.js';
+export { serializeBlockAttrs } from './serialize.js';
 export { buildEmbedBlock, guessEmbedProvider } from './embed.js';
 export { sanitize } from './sanitize.js';
-export { blockMarkupRoundtrips } from './validate.js';
+export { blockMarkupRoundtrips, scanForInjection } from './validate.js';
 export { verifyComposedOutput } from './output-verify.js';
 export { heuristicBlocks } from './heuristics.js';
 export { genericHtmlToBlocks } from './catalog.js';
 export { composeFromRecipes } from './recipe-table.js';
+export { PIPELINE_ISLAND_OPENER, PIPELINE_ISLAND_NAME } from './block-policy.js';
 
 export type * from './types.js';
 export type { VerifyResult } from './output-verify.js';
diff --git a/packages/blocks-engine/src/serialize.ts b/packages/blocks-engine/src/serialize.ts
new file mode 100644
index 00000000..94fdd0ce
--- /dev/null
+++ b/packages/blocks-engine/src/serialize.ts
@@ -0,0 +1,8 @@
+export function serializeBlockAttrs(attrs: Record<string, unknown>): string {
+  return JSON.stringify(attrs)
+    .replace(/--/g, '\\u002d\\u002d')
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\\"/g, '\\u0022');
+}

From 8784f67d9bdfa5387abcdc2fd12831d55d061a41 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Tue, 23 Jun 2026 16:03:17 -0400
Subject: [PATCH 022/113] feat(blocks-engine): port block-markup validation
 unit (validateBlockMarkup + validateBlockContract + walkBlocks +
 core-block-attrs snapshot)

---
 .../scripts/generate-block-attrs-snapshot.mjs |  104 +
 .../src/__tests__/block-contract.test.ts      |  108 ++
 .../__tests__/validate-block-markup.test.ts   |   70 +
 packages/blocks-engine/src/block-contract.ts  |  116 ++
 packages/blocks-engine/src/block-tree.ts      |   21 +
 .../blocks-engine/src/core-block-attrs.json   | 1703 +++++++++++++++++
 packages/blocks-engine/src/index.ts           |    5 +
 .../src/validate-block-markup.ts              |   93 +
 8 files changed, 2220 insertions(+)
 create mode 100644 packages/blocks-engine/scripts/generate-block-attrs-snapshot.mjs
 create mode 100644 packages/blocks-engine/src/__tests__/block-contract.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/validate-block-markup.test.ts
 create mode 100644 packages/blocks-engine/src/block-contract.ts
 create mode 100644 packages/blocks-engine/src/block-tree.ts
 create mode 100644 packages/blocks-engine/src/core-block-attrs.json
 create mode 100644 packages/blocks-engine/src/validate-block-markup.ts

diff --git a/packages/blocks-engine/scripts/generate-block-attrs-snapshot.mjs b/packages/blocks-engine/scripts/generate-block-attrs-snapshot.mjs
new file mode 100644
index 00000000..5a73678f
--- /dev/null
+++ b/packages/blocks-engine/scripts/generate-block-attrs-snapshot.mjs
@@ -0,0 +1,104 @@
+// scripts/generate-block-attrs-snapshot.mjs
+//
+// Regenerates src/core-block-attrs.json — the registered-metadata snapshot
+// the block-contract check validates emitted markup against (block name →
+// attribute names, plus the core/group tagName allowlist). Snapshot route
+// deliberately chosen over importing @wordpress/block-library in library
+// context: the library is jsdom-bound and React-pinned, while the snapshot is
+// small, deterministic, and test-friendly.
+//
+// Run:
+//   node scripts/generate-block-attrs-snapshot.mjs
+//
+// Re-run on @wordpress/block-library bumps in @automattic/blocks-engine.
+import { createRequire } from 'node:module';
+import { writeFileSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const engineRoot = join(here, '..');
+const engineRequire = createRequire(join(engineRoot, 'package.json'));
+
+// --- JSDOM globals BEFORE @wordpress/blocks -------------------------------
+const { JSDOM } = engineRequire('jsdom');
+const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', {
+  url: 'http://localhost',
+  pretendToBeVisual: true,
+});
+global.window = dom.window;
+global.document = dom.window.document;
+global.DOMParser = dom.window.DOMParser;
+global.XMLSerializer = dom.window.XMLSerializer;
+global.Node = dom.window.Node;
+global.Element = dom.window.Element;
+global.HTMLElement = dom.window.HTMLElement;
+global.getComputedStyle = dom.window.getComputedStyle;
+global.MutationObserver = dom.window.MutationObserver;
+global.requestAnimationFrame = (cb) => setTimeout(cb, 16);
+global.cancelAnimationFrame = (id) => clearTimeout(id);
+global.matchMedia = () => ({
+  matches: false,
+  addListener: () => {},
+  removeListener: () => {},
+  addEventListener: () => {},
+  removeEventListener: () => {},
+});
+global.ResizeObserver = class ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+};
+Object.defineProperty(global, 'navigator', {
+  value: dom.window.navigator,
+  writable: true,
+  configurable: true,
+});
+// Keep @wordpress/* chatter off stdout.
+console.log = (...args) => console.error(...args);
+console.warn = (...args) => console.error(...args);
+
+const { getBlockTypes } = engineRequire('@wordpress/blocks');
+const { registerCoreBlocks } = engineRequire('@wordpress/block-library');
+registerCoreBlocks();
+
+// Block name → sorted attribute names. Sorted keys for byte-stable output.
+const blocks = {};
+for (const bt of getBlockTypes().sort((a, b) => a.name.localeCompare(b.name))) {
+  blocks[bt.name] = Object.keys(bt.attributes ?? {}).sort();
+}
+
+// core/group tagName allowlist: NOT in block.json metadata (the attribute is
+// a free string there) — the canonical list lives in the group edit UI's
+// options. Extract it mechanically from the installed build so the snapshot
+// tracks the pinned version; fall back to the documented list if the build
+// shape ever changes (and say so loudly).
+const DOCUMENTED_GROUP_TAGS = ['div', 'header', 'main', 'section', 'article', 'aside', 'footer'];
+let groupTagNames = DOCUMENTED_GROUP_TAGS;
+try {
+  // Direct path (not require.resolve): the package's `exports` map does not
+  // expose build/* subpaths, but the file is right there on disk.
+  const libRoot = dirname(engineRequire.resolve('@wordpress/block-library/package.json'));
+  const editCjs = readFileSync(join(libRoot, 'build', 'group', 'edit.cjs'), 'utf8');
+  const extracted = [...editCjs.matchAll(/value:\s*"([a-z]+)"/g)].map((m) => m[1]);
+  const known = extracted.filter((t) => /^[a-z]+$/.test(t));
+  if (known.length >= 5 && known.includes('div')) {
+    groupTagNames = [...new Set(known)];
+  } else {
+    console.error('[snapshot] group edit.cjs extraction looked wrong — using the documented list');
+  }
+} catch (e) {
+  console.error(`[snapshot] group edit.cjs unreadable (${e.message}) — using the documented list`);
+}
+
+const enginePkg = JSON.parse(readFileSync(join(engineRoot, 'package.json'), 'utf8'));
+const out = {
+  __generated: 'node scripts/generate-block-attrs-snapshot.mjs (deps: @automattic/blocks-engine)',
+  __wpBlockLibrary: enginePkg.dependencies['@wordpress/block-library'],
+  groupTagNames,
+  blocks,
+};
+
+const target = join(here, '..', 'src', 'core-block-attrs.json');
+writeFileSync(target, JSON.stringify(out, null, 2) + '\n');
+console.error(`[snapshot] wrote ${target}: ${Object.keys(blocks).length} blocks, groupTagNames=[${groupTagNames.join(', ')}]`);
diff --git a/packages/blocks-engine/src/__tests__/block-contract.test.ts b/packages/blocks-engine/src/__tests__/block-contract.test.ts
new file mode 100644
index 00000000..71c60493
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/block-contract.test.ts
@@ -0,0 +1,108 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { validateBlockContract } from '../block-contract.js';
+
+describe('validateBlockContract', () => {
+  it('flags an invented core block as unknown-block', () => {
+    const markup = `<!-- wp:fancy-hero {"glow":true} -->
+<div class="wp-block-fancy-hero">x</div>
+<!-- /wp:fancy-hero -->`;
+    const issues = validateBlockContract(markup);
+    expect(issues).toEqual([
+      { code: 'unknown-block', blockName: 'core/fancy-hero', detail: 'not a registered core block' },
+    ]);
+  });
+
+  it('flags an invented attr on a real block, naming block + attr', () => {
+    const markup = `<!-- wp:paragraph {"glow":true,"content":"hi"} -->
+<p>hi</p>
+<!-- /wp:paragraph -->`;
+    const issues = validateBlockContract(markup);
+    expect(issues).toEqual([
+      { code: 'unknown-attr', blockName: 'core/paragraph', detail: 'attr "glow" not in registered metadata' },
+    ]);
+  });
+
+  it('flags a core/group tagName outside the WP allowlist', () => {
+    const markup = `<!-- wp:group {"tagName":"span"} -->
+<span class="wp-block-group">x</span>
+<!-- /wp:group -->`;
+    const issues = validateBlockContract(markup);
+    expect(issues).toEqual([
+      { code: 'invalid-tagname', blockName: 'core/group', detail: 'tagName "span" not in [div, header, main, section, article, aside, footer]' },
+    ]);
+  });
+
+  it('uses a core-only default allowlist and preserves caller allowlists', () => {
+    const markup = `<!-- wp:dla/foo {"madeUp":1} -->
+<section data-wp-interactive="dla/foo">x</section>
+<!-- /wp:dla/foo -->
+<!-- wp:html -->
+<div onclickish="weird">island</div>
+<!-- /wp:html -->`;
+    expect(validateBlockContract(markup)).toEqual([
+      { code: 'unknown-block', blockName: 'dla/foo', detail: 'not a core block or allowlisted namespace' },
+    ]);
+    expect(validateBlockContract(markup, { allowlist: ['dla/', 'core/html'] })).toEqual([]);
+  });
+
+  it('allowlisted non-core namespaces pass untouched', () => {
+    const markup = `<!-- wp:dla/reveal {"madeUp":1} -->
+<section data-wp-interactive="dla/reveal">x</section>
+<!-- /wp:dla/reveal -->
+<!-- wp:html -->
+<div onclickish="weird">island</div>
+<!-- /wp:html -->`;
+    expect(validateBlockContract(markup, { allowlist: ['dla/', 'core/html'] })).toEqual([]);
+  });
+
+  it('clean markup returns no issues', () => {
+    const markup = `<!-- wp:group {"tagName":"section","anchor":"hero"} -->
+<section id="hero" class="wp-block-group"><!-- wp:heading {"level":3} -->
+<h3 class="wp-block-heading">T</h3>
+<!-- /wp:heading --></section>
+<!-- /wp:group -->`;
+    expect(validateBlockContract(markup)).toEqual([]);
+  });
+
+  it('non-core namespaces are flagged unless allowlisted', () => {
+    const markup = `<!-- wp:acme/widget {"anything":"goes"} -->
+<div class="acme-widget">x</div>
+<!-- /wp:acme/widget -->`;
+    expect(validateBlockContract(markup)).toEqual([
+      { code: 'unknown-block', blockName: 'acme/widget', detail: 'not a core block or allowlisted namespace' },
+    ]);
+  });
+
+  it('walks innerBlocks (nested invented attr still caught)', () => {
+    const markup = `<!-- wp:group {"tagName":"section"} -->
+<section class="wp-block-group"><!-- wp:paragraph {"sparkle":"yes"} -->
+<p>x</p>
+<!-- /wp:paragraph --></section>
+<!-- /wp:group -->`;
+    const issues = validateBlockContract(markup);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]).toMatchObject({ code: 'unknown-attr', blockName: 'core/paragraph' });
+    expect(issues[0].detail).toContain('sparkle');
+  });
+
+  it('never throws on unparseable attr JSON (the roundtrip oracle owns that failure)', () => {
+    const markup = `<!-- wp:paragraph {"broken": -->
+<p>x</p>
+<!-- /wp:paragraph -->`;
+    expect(() => validateBlockContract(markup)).not.toThrow();
+  });
+});
+
+describe('core-block-attrs.json snapshot shape', () => {
+  it('exists, parses, and carries the contract essentials', () => {
+    const snapshot = JSON.parse(
+      readFileSync(new URL('../core-block-attrs.json', import.meta.url), 'utf8'),
+    ) as { __generated: string; groupTagNames: string[]; blocks: Record<string, string[]> };
+    expect(snapshot.__generated).toContain('generate-block-attrs-snapshot');
+    expect(snapshot.groupTagNames).toEqual(['div', 'header', 'main', 'section', 'article', 'aside', 'footer']);
+    expect(Object.keys(snapshot.blocks).length).toBeGreaterThan(50);
+    expect(snapshot.blocks['core/paragraph']).toContain('content');
+    expect(snapshot.blocks['core/group']).toContain('tagName');
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/validate-block-markup.test.ts b/packages/blocks-engine/src/__tests__/validate-block-markup.test.ts
new file mode 100644
index 00000000..f1f9f125
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/validate-block-markup.test.ts
@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import { validateBlockMarkup } from '../validate-block-markup.js';
+
+describe('validateBlockMarkup — delimiter balance (the bug the WP parser silently swallows)', () => {
+  it('flags an unclosed block delimiter', () => {
+    const markup =
+      '<!-- wp:columns --><div class="wp-block-columns">' +
+      '<!-- wp:column --><div class="wp-block-column"><!-- wp:paragraph --><p>a</p><!-- /wp:paragraph --></div><!-- /wp:column -->' +
+      '</div>'; // missing <!-- /wp:columns -->
+    const issues = validateBlockMarkup(markup);
+    expect(issues.join('\n')).toMatch(/unclosed.*wp:columns/i);
+  });
+
+  it('flags a closing delimiter whose name does not match the open block', () => {
+    const markup = '<!-- wp:columns --><div></div><!-- /wp:group -->';
+    const issues = validateBlockMarkup(markup);
+    expect(issues.join('\n')).toMatch(/mismatch|expected .*columns.*found .*group/i);
+  });
+
+  it('flags a closing delimiter with no matching open block', () => {
+    const issues = validateBlockMarkup('<!-- wp:paragraph --><p>a</p><!-- /wp:paragraph --><!-- /wp:group -->');
+    expect(issues.join('\n')).toMatch(/no open block|unmatched clos/i);
+  });
+
+  it('treats a self-closing void block as balanced (not unclosed)', () => {
+    expect(validateBlockMarkup('<!-- wp:spacer {"height":"40px"} /-->')).toEqual([]);
+  });
+});
+
+describe('validateBlockMarkup — official-parser checks', () => {
+  it('passes well-formed, balanced block markup', () => {
+    const markup =
+      '<!-- wp:heading {"level":2} --><h2>Title</h2><!-- /wp:heading -->\n\n' +
+      '<!-- wp:paragraph --><p>Body copy.</p><!-- /wp:paragraph -->';
+    expect(validateBlockMarkup(markup)).toEqual([]);
+  });
+
+  it('flags content sitting outside any block delimiter (freeform leak)', () => {
+    const markup = '<p>orphaned html not wrapped in a block</p>';
+    expect(validateBlockMarkup(markup).join('\n')).toMatch(/outside.*block|freeform/i);
+  });
+
+  it('flags invalid block-attribute JSON', () => {
+    const markup = '<!-- wp:image {bad json} --><figure></figure><!-- /wp:image -->';
+    expect(validateBlockMarkup(markup).join('\n')).toMatch(/attribute|json/i);
+  });
+
+  it('ignores blank-line whitespace between blocks (not a freeform leak)', () => {
+    const markup =
+      '<!-- wp:paragraph --><p>one</p><!-- /wp:paragraph -->\n\n\n' +
+      '<!-- wp:paragraph --><p>two</p><!-- /wp:paragraph -->';
+    expect(validateBlockMarkup(markup)).toEqual([]);
+  });
+});
+
+describe('validateBlockMarkup — pattern-file PHP header', () => {
+  it('passes block markup behind a PHP header', () => {
+    const php = `<?php
+/**
+ * Title: Demo
+ * Slug: demo-replica/page-demo
+ */
+?>
+<!-- wp:heading {"level":2} --><h2 class="wp-block-heading">Welcome</h2><!-- /wp:heading -->
+<!-- wp:paragraph --><p>Some verbatim body copy from the source page.</p><!-- /wp:paragraph -->`;
+    expect(php).toContain('<?php');
+    expect(php).toMatch(/<!-- wp:/);
+    expect(validateBlockMarkup(php)).toEqual([]);
+  });
+});
diff --git a/packages/blocks-engine/src/block-contract.ts b/packages/blocks-engine/src/block-contract.ts
new file mode 100644
index 00000000..3a3f7988
--- /dev/null
+++ b/packages/blocks-engine/src/block-contract.ts
@@ -0,0 +1,116 @@
+// src/block-contract.ts
+//
+// Pre-serialization block contract (BDC survey adoption — measurement only).
+// Validates EMITTED block-markup STRINGS against a checked-in snapshot of
+// WordPress's registered core-block metadata: invented core blocks, invented
+// attrs on real blocks, and core/group tagNames outside WP's allowlist are
+// reported as WARNING-level issues. The gate's value is catching OUR emitter
+// bugs before they ship; it never throws (trust-source posture).
+//
+// Deliberately a STRING validator (parse → attrs vs snapshot), not a
+// tree-first emitter rearchitecture — same catch-rate for invented
+// attrs/blocks at a fraction of the surface.
+//
+// Scope:
+// - Only core/* blocks are accepted by default. Allowlisted prefixes (default
+//   ['core/html']) skip entirely — deliberate verbatim islands. Callers that
+//   intentionally emit non-core blocks can pass their namespace allowlist.
+// - attrs === null (unparseable JSON) is the roundtrip oracle's failure to
+//   report; here it degrades to "no attrs to check".
+//
+// Snapshot: ./core-block-attrs.json — block name → registered attr names +
+// the core/group tagName allowlist. Regenerate when the engine's WordPress
+// block-library dependency changes:
+//   node scripts/generate-block-attrs-snapshot.mjs
+import { parse } from '@wordpress/block-serialization-default-parser';
+import snapshot from './core-block-attrs.json' with { type: 'json' };
+import { walkBlocks, type ParsedBlock } from './block-tree.js';
+
+interface BlockAttrsSnapshot {
+  __generated: string;
+  __wpBlockLibrary: string;
+  groupTagNames: string[];
+  blocks: Record<string, string[]>;
+}
+
+const SNAPSHOT = snapshot as BlockAttrsSnapshot;
+
+// Set-backed lookups, built once at module load.
+const ATTRS_BY_BLOCK = new Map<string, Set<string>>(
+  Object.entries(SNAPSHOT.blocks).map(([name, attrs]) => [name, new Set(attrs)]),
+);
+const GROUP_TAGS = new Set(SNAPSHOT.groupTagNames);
+
+export interface BlockContractIssue {
+  code: 'unknown-block' | 'unknown-attr' | 'invalid-tagname';
+  blockName: string;
+  detail: string;
+}
+
+export interface BlockContractOpts {
+  /** Entries ending '/' are namespace prefixes; others are exact block names. */
+  allowlist?: string[];
+}
+
+const DEFAULT_ALLOWLIST = ['core/html'];
+
+function isAllowlisted(blockName: string, allowlist: string[]): boolean {
+  return allowlist.some((entry) =>
+    entry.endsWith('/') ? blockName.startsWith(entry) : blockName === entry,
+  );
+}
+
+function checkBlock(b: ParsedBlock, allowlist: string[], issues: BlockContractIssue[]): void {
+  const name = b.blockName as string;
+  if (isAllowlisted(name, allowlist)) return;
+  if (!name.startsWith('core/')) {
+    issues.push({ code: 'unknown-block', blockName: name, detail: 'not a core block or allowlisted namespace' });
+    return;
+  }
+
+  const registered = ATTRS_BY_BLOCK.get(name);
+  if (!registered) {
+    issues.push({ code: 'unknown-block', blockName: name, detail: 'not a registered core block' });
+    return;
+  }
+  // attrs === null (bad JSON) → roundtrip oracle reports it; nothing to check.
+  const attrs = (b.attrs ?? {}) as Record<string, unknown>;
+  for (const key of Object.keys(attrs)) {
+    if (!registered.has(key)) {
+      issues.push({
+        code: 'unknown-attr',
+        blockName: name,
+        detail: `attr "${key}" not in registered metadata`,
+      });
+    }
+  }
+  if (name === 'core/group') {
+    const tagName = attrs.tagName;
+    if (typeof tagName === 'string' && !GROUP_TAGS.has(tagName)) {
+      issues.push({
+        code: 'invalid-tagname',
+        blockName: name,
+        detail: `tagName "${tagName}" not in [${SNAPSHOT.groupTagNames.join(', ')}]`,
+      });
+    }
+  }
+}
+
+/**
+ * Pure: validate emitted markup against the registered-metadata snapshot.
+ * Returns WARNING-level issues ([] = clean). Never throws.
+ */
+export function validateBlockContract(
+  markup: string,
+  opts: BlockContractOpts = {},
+): BlockContractIssue[] {
+  const allowlist = opts.allowlist ?? DEFAULT_ALLOWLIST;
+  const issues: BlockContractIssue[] = [];
+  try {
+    walkBlocks(parse(markup), (b) => checkBlock(b, allowlist, issues));
+  } catch {
+    // A parser blowup must not fail the caller — the roundtrip oracle is the
+    // structural gate; the contract check is a best-effort warning layer.
+  }
+  return issues;
+}
diff --git a/packages/blocks-engine/src/block-tree.ts b/packages/blocks-engine/src/block-tree.ts
new file mode 100644
index 00000000..4191a534
--- /dev/null
+++ b/packages/blocks-engine/src/block-tree.ts
@@ -0,0 +1,21 @@
+// src/block-tree.ts
+//
+// Shared traversal for parsed block trees (the registration-free default
+// parser's output). Both the style-usage audit and the block-contract check
+// need the same depth-first walk — visit every NAMED block (skipping
+// null/freeform whitespace between delimiters), descending into innerBlocks —
+// differing only in what they do at each block. Keep the recursion in one place.
+import type { parse } from '@wordpress/block-serialization-default-parser';
+
+export type ParsedBlock = ReturnType<typeof parse>[number];
+
+/**
+ * Depth-first visit of every named block in the tree, innerBlocks included.
+ * Freeform nodes (blockName === null) are skipped but still descended through.
+ */
+export function walkBlocks(blocks: ParsedBlock[], visit: (block: ParsedBlock) => void): void {
+  for (const b of blocks) {
+    if (b.blockName !== null) visit(b);
+    if (b.innerBlocks && b.innerBlocks.length > 0) walkBlocks(b.innerBlocks, visit);
+  }
+}
diff --git a/packages/blocks-engine/src/core-block-attrs.json b/packages/blocks-engine/src/core-block-attrs.json
new file mode 100644
index 00000000..c0b2d5f9
--- /dev/null
+++ b/packages/blocks-engine/src/core-block-attrs.json
@@ -0,0 +1,1703 @@
+{
+  "__generated": "node scripts/generate-block-attrs-snapshot.mjs (deps: @automattic/blocks-engine)",
+  "__wpBlockLibrary": "9.42.0",
+  "groupTagNames": [
+    "div",
+    "header",
+    "main",
+    "section",
+    "article",
+    "aside",
+    "footer"
+  ],
+  "blocks": {
+    "core/accordion": [
+      "align",
+      "anchor",
+      "ariaLabel",
+      "autoclose",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "headingLevel",
+      "iconPosition",
+      "layout",
+      "levelOptions",
+      "lock",
+      "metadata",
+      "showIcon",
+      "style",
+      "textColor"
+    ],
+    "core/accordion-heading": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "iconPosition",
+      "level",
+      "lock",
+      "metadata",
+      "openByDefault",
+      "showIcon",
+      "style",
+      "textColor",
+      "title"
+    ],
+    "core/accordion-item": [
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "layout",
+      "lock",
+      "metadata",
+      "openByDefault",
+      "style",
+      "textColor"
+    ],
+    "core/accordion-panel": [
+      "allowedBlocks",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "layout",
+      "lock",
+      "metadata",
+      "style",
+      "templateLock",
+      "textColor"
+    ],
+    "core/archives": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "displayAsDropdown",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "showLabel",
+      "showPostCounts",
+      "style",
+      "textColor",
+      "type"
+    ],
+    "core/audio": [
+      "align",
+      "anchor",
+      "autoplay",
+      "blob",
+      "caption",
+      "className",
+      "id",
+      "lock",
+      "loop",
+      "metadata",
+      "preload",
+      "src",
+      "style"
+    ],
+    "core/avatar": [
+      "align",
+      "anchor",
+      "borderColor",
+      "className",
+      "isLink",
+      "linkTarget",
+      "lock",
+      "metadata",
+      "size",
+      "style",
+      "userId"
+    ],
+    "core/block": [
+      "content",
+      "lock",
+      "metadata",
+      "ref"
+    ],
+    "core/breadcrumbs": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "prefersTaxonomy",
+      "separator",
+      "showCurrentItem",
+      "showHomeItem",
+      "showOnHomePage",
+      "style",
+      "textColor"
+    ],
+    "core/button": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "linkTarget",
+      "lock",
+      "metadata",
+      "placeholder",
+      "rel",
+      "style",
+      "tagName",
+      "text",
+      "textColor",
+      "title",
+      "type",
+      "url"
+    ],
+    "core/buttons": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "layout",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/calendar": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "lock",
+      "metadata",
+      "month",
+      "style",
+      "textColor",
+      "year"
+    ],
+    "core/categories": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "displayAsDropdown",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "label",
+      "lock",
+      "metadata",
+      "showEmpty",
+      "showHierarchy",
+      "showLabel",
+      "showOnlyTopLevel",
+      "showPostCounts",
+      "style",
+      "taxonomy",
+      "textColor"
+    ],
+    "core/code": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "content",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/column": [
+      "allowedBlocks",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "layout",
+      "lock",
+      "metadata",
+      "style",
+      "templateLock",
+      "textColor",
+      "verticalAlignment",
+      "width"
+    ],
+    "core/columns": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "isStackedOnMobile",
+      "layout",
+      "lock",
+      "metadata",
+      "style",
+      "templateLock",
+      "textColor",
+      "verticalAlignment"
+    ],
+    "core/comment-author-name": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "isLink",
+      "linkTarget",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/comment-content": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/comment-date": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "format",
+      "gradient",
+      "isLink",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/comment-edit-link": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "linkTarget",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/comment-reply-link": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/comment-template": [
+      "align",
+      "anchor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "lock",
+      "metadata",
+      "style"
+    ],
+    "core/comments": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "legacy",
+      "lock",
+      "metadata",
+      "style",
+      "tagName",
+      "textColor"
+    ],
+    "core/comments-pagination": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "layout",
+      "lock",
+      "metadata",
+      "paginationArrow",
+      "style",
+      "textColor"
+    ],
+    "core/comments-pagination-next": [
+      "anchor",
+      "backgroundColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "label",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/comments-pagination-numbers": [
+      "anchor",
+      "backgroundColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/comments-pagination-previous": [
+      "anchor",
+      "backgroundColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "label",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/comments-title": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "level",
+      "levelOptions",
+      "lock",
+      "metadata",
+      "showCommentsCount",
+      "showPostTitle",
+      "style",
+      "textColor"
+    ],
+    "core/cover": [
+      "align",
+      "allowedBlocks",
+      "alt",
+      "anchor",
+      "backgroundColor",
+      "backgroundType",
+      "borderColor",
+      "className",
+      "contentPosition",
+      "customGradient",
+      "customOverlayColor",
+      "dimRatio",
+      "focalPoint",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "hasParallax",
+      "id",
+      "isDark",
+      "isRepeated",
+      "isUserOverlayColor",
+      "layout",
+      "lock",
+      "metadata",
+      "minHeight",
+      "minHeightUnit",
+      "overlayColor",
+      "poster",
+      "sizeSlug",
+      "style",
+      "tagName",
+      "templateLock",
+      "textColor",
+      "url",
+      "useFeaturedImage"
+    ],
+    "core/details": [
+      "align",
+      "allowedBlocks",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "layout",
+      "lock",
+      "metadata",
+      "name",
+      "placeholder",
+      "showContent",
+      "style",
+      "summary",
+      "textColor"
+    ],
+    "core/embed": [
+      "align",
+      "allowResponsive",
+      "anchor",
+      "caption",
+      "className",
+      "lock",
+      "metadata",
+      "previewable",
+      "providerNameSlug",
+      "responsive",
+      "style",
+      "type",
+      "url"
+    ],
+    "core/file": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "blob",
+      "borderColor",
+      "className",
+      "displayPreview",
+      "downloadButtonText",
+      "fileId",
+      "fileName",
+      "gradient",
+      "href",
+      "id",
+      "lock",
+      "metadata",
+      "previewHeight",
+      "showDownloadButton",
+      "style",
+      "textColor",
+      "textLinkHref",
+      "textLinkTarget"
+    ],
+    "core/footnotes": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/gallery": [
+      "align",
+      "allowResize",
+      "anchor",
+      "aspectRatio",
+      "backgroundColor",
+      "borderColor",
+      "caption",
+      "className",
+      "columns",
+      "fixedHeight",
+      "gradient",
+      "ids",
+      "imageCrop",
+      "images",
+      "layout",
+      "linkTarget",
+      "linkTo",
+      "lock",
+      "metadata",
+      "navigationButtonType",
+      "randomOrder",
+      "shortCodeTransforms",
+      "sizeSlug",
+      "style",
+      "textColor"
+    ],
+    "core/group": [
+      "align",
+      "allowedBlocks",
+      "anchor",
+      "ariaLabel",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "layout",
+      "lock",
+      "metadata",
+      "settings",
+      "style",
+      "tagName",
+      "templateLock",
+      "textColor"
+    ],
+    "core/heading": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "content",
+      "fitText",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "level",
+      "levelOptions",
+      "lock",
+      "metadata",
+      "placeholder",
+      "style",
+      "textColor"
+    ],
+    "core/home-link": [
+      "anchor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "label",
+      "lock",
+      "metadata",
+      "style"
+    ],
+    "core/html": [
+      "content",
+      "lock",
+      "metadata"
+    ],
+    "core/icon": [
+      "align",
+      "anchor",
+      "ariaLabel",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "icon",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/image": [
+      "align",
+      "alt",
+      "anchor",
+      "aspectRatio",
+      "blob",
+      "borderColor",
+      "caption",
+      "className",
+      "focalPoint",
+      "height",
+      "href",
+      "id",
+      "lightbox",
+      "linkClass",
+      "linkDestination",
+      "linkTarget",
+      "lock",
+      "metadata",
+      "rel",
+      "scale",
+      "sizeSlug",
+      "style",
+      "title",
+      "url",
+      "width"
+    ],
+    "core/latest-comments": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "className",
+      "commentsToShow",
+      "displayAvatar",
+      "displayContent",
+      "displayDate",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/latest-posts": [
+      "addLinkToFeaturedImage",
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "categories",
+      "className",
+      "columns",
+      "displayAuthor",
+      "displayFeaturedImage",
+      "displayPostContent",
+      "displayPostContentRadio",
+      "displayPostDate",
+      "excerptLength",
+      "featuredImageAlign",
+      "featuredImageSizeHeight",
+      "featuredImageSizeSlug",
+      "featuredImageSizeWidth",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "order",
+      "orderBy",
+      "postLayout",
+      "postsToShow",
+      "selectedAuthor",
+      "style",
+      "textColor"
+    ],
+    "core/list": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "ordered",
+      "placeholder",
+      "reversed",
+      "start",
+      "style",
+      "textColor",
+      "type",
+      "values"
+    ],
+    "core/list-item": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "content",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "placeholder",
+      "style",
+      "textColor"
+    ],
+    "core/loginout": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "displayLoginAsForm",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "redirectToCurrent",
+      "style",
+      "textColor"
+    ],
+    "core/math": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontSize",
+      "gradient",
+      "latex",
+      "lock",
+      "mathML",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/media-text": [
+      "align",
+      "allowedBlocks",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "focalPoint",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "href",
+      "imageFill",
+      "isStackedOnMobile",
+      "linkClass",
+      "linkDestination",
+      "linkTarget",
+      "lock",
+      "mediaAlt",
+      "mediaId",
+      "mediaLink",
+      "mediaPosition",
+      "mediaSizeSlug",
+      "mediaType",
+      "mediaUrl",
+      "mediaWidth",
+      "metadata",
+      "rel",
+      "style",
+      "textColor",
+      "useFeaturedImage",
+      "verticalAlignment"
+    ],
+    "core/missing": [
+      "lock",
+      "metadata",
+      "originalContent",
+      "originalName",
+      "originalUndelimitedContent"
+    ],
+    "core/more": [
+      "customText",
+      "lock",
+      "metadata",
+      "noTeaser"
+    ],
+    "core/navigation": [
+      "__unstableLocation",
+      "align",
+      "anchor",
+      "ariaLabel",
+      "backgroundColor",
+      "className",
+      "customBackgroundColor",
+      "customOverlayBackgroundColor",
+      "customOverlayTextColor",
+      "customTextColor",
+      "fontFamily",
+      "fontSize",
+      "hasIcon",
+      "icon",
+      "layout",
+      "lock",
+      "maxNestingLevel",
+      "metadata",
+      "overlay",
+      "overlayBackgroundColor",
+      "overlayMenu",
+      "overlayTextColor",
+      "ref",
+      "rgbBackgroundColor",
+      "rgbTextColor",
+      "showSubmenuIcon",
+      "style",
+      "submenuVisibility",
+      "templateLock",
+      "textColor"
+    ],
+    "core/navigation-link": [
+      "anchor",
+      "className",
+      "description",
+      "fontFamily",
+      "fontSize",
+      "id",
+      "isTopLevelLink",
+      "kind",
+      "label",
+      "lock",
+      "metadata",
+      "opensInNewTab",
+      "rel",
+      "style",
+      "title",
+      "type",
+      "url"
+    ],
+    "core/navigation-overlay-close": [
+      "backgroundColor",
+      "className",
+      "displayMode",
+      "fontFamily",
+      "fontSize",
+      "lock",
+      "metadata",
+      "style",
+      "text",
+      "textColor"
+    ],
+    "core/navigation-submenu": [
+      "anchor",
+      "className",
+      "description",
+      "fontFamily",
+      "fontSize",
+      "id",
+      "isTopLevelItem",
+      "kind",
+      "label",
+      "lock",
+      "metadata",
+      "opensInNewTab",
+      "rel",
+      "style",
+      "title",
+      "type",
+      "url"
+    ],
+    "core/nextpage": [
+      "lock",
+      "metadata"
+    ],
+    "core/page-list": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "isNested",
+      "lock",
+      "metadata",
+      "parentPageID",
+      "style",
+      "textColor"
+    ],
+    "core/page-list-item": [
+      "anchor",
+      "className",
+      "hasChildren",
+      "id",
+      "label",
+      "link",
+      "lock",
+      "metadata",
+      "style",
+      "title"
+    ],
+    "core/paragraph": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "content",
+      "direction",
+      "dropCap",
+      "fitText",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "placeholder",
+      "style",
+      "textColor"
+    ],
+    "core/pattern": [
+      "className",
+      "lock",
+      "metadata",
+      "slug",
+      "style"
+    ],
+    "core/post-author": [
+      "anchor",
+      "avatarSize",
+      "backgroundColor",
+      "borderColor",
+      "byline",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "isLink",
+      "linkTarget",
+      "lock",
+      "metadata",
+      "showAvatar",
+      "showBio",
+      "style",
+      "textAlign",
+      "textColor"
+    ],
+    "core/post-author-biography": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/post-author-name": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "isLink",
+      "linkTarget",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/post-comments-count": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/post-comments-form": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/post-comments-link": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/post-content": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "layout",
+      "lock",
+      "metadata",
+      "style",
+      "tagName",
+      "textColor"
+    ],
+    "core/post-date": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "datetime",
+      "fontFamily",
+      "fontSize",
+      "format",
+      "gradient",
+      "isLink",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/post-excerpt": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "excerptLength",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "moreText",
+      "showMoreOnNewLine",
+      "style",
+      "textColor"
+    ],
+    "core/post-featured-image": [
+      "align",
+      "anchor",
+      "aspectRatio",
+      "borderColor",
+      "className",
+      "customGradient",
+      "customOverlayColor",
+      "dimRatio",
+      "gradient",
+      "height",
+      "isLink",
+      "linkTarget",
+      "lock",
+      "metadata",
+      "overlayColor",
+      "rel",
+      "scale",
+      "sizeSlug",
+      "style",
+      "useFirstImageFromPost",
+      "width"
+    ],
+    "core/post-navigation-link": [
+      "anchor",
+      "arrow",
+      "backgroundColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "label",
+      "linkLabel",
+      "lock",
+      "metadata",
+      "showTitle",
+      "style",
+      "taxonomy",
+      "textColor",
+      "type"
+    ],
+    "core/post-template": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "layout",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/post-terms": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "prefix",
+      "separator",
+      "style",
+      "suffix",
+      "term",
+      "textColor"
+    ],
+    "core/post-time-to-read": [
+      "anchor",
+      "averageReadingSpeed",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "displayAsRange",
+      "displayMode",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/post-title": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "isLink",
+      "level",
+      "levelOptions",
+      "linkTarget",
+      "lock",
+      "metadata",
+      "placeholder",
+      "rel",
+      "style",
+      "textColor"
+    ],
+    "core/preformatted": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "content",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/pullquote": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "citation",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textAlign",
+      "textColor",
+      "value"
+    ],
+    "core/query": [
+      "align",
+      "anchor",
+      "className",
+      "enhancedPagination",
+      "layout",
+      "lock",
+      "metadata",
+      "namespace",
+      "query",
+      "queryId",
+      "style",
+      "tagName"
+    ],
+    "core/query-no-results": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/query-pagination": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "layout",
+      "lock",
+      "metadata",
+      "paginationArrow",
+      "showLabel",
+      "style",
+      "textColor"
+    ],
+    "core/query-pagination-next": [
+      "anchor",
+      "backgroundColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "label",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/query-pagination-numbers": [
+      "anchor",
+      "backgroundColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "midSize",
+      "style",
+      "textColor"
+    ],
+    "core/query-pagination-previous": [
+      "anchor",
+      "backgroundColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "label",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/query-title": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "level",
+      "levelOptions",
+      "lock",
+      "metadata",
+      "showPrefix",
+      "showSearchTerm",
+      "style",
+      "textColor",
+      "type"
+    ],
+    "core/query-total": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "displayType",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/quote": [
+      "align",
+      "allowedBlocks",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "citation",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "layout",
+      "lock",
+      "metadata",
+      "style",
+      "textAlign",
+      "textColor",
+      "value"
+    ],
+    "core/read-more": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "content",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "linkTarget",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/rss": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "blockLayout",
+      "borderColor",
+      "className",
+      "columns",
+      "displayAuthor",
+      "displayDate",
+      "displayExcerpt",
+      "excerptLength",
+      "feedURL",
+      "gradient",
+      "itemsToShow",
+      "lock",
+      "metadata",
+      "openInNewTab",
+      "rel",
+      "style",
+      "textColor"
+    ],
+    "core/search": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "buttonPosition",
+      "buttonText",
+      "buttonUseIcon",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "isSearchFieldHidden",
+      "label",
+      "lock",
+      "metadata",
+      "placeholder",
+      "query",
+      "showLabel",
+      "style",
+      "textColor",
+      "width",
+      "widthUnit"
+    ],
+    "core/separator": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "className",
+      "gradient",
+      "lock",
+      "metadata",
+      "opacity",
+      "style",
+      "tagName",
+      "textColor"
+    ],
+    "core/shortcode": [
+      "lock",
+      "metadata",
+      "text"
+    ],
+    "core/site-logo": [
+      "align",
+      "anchor",
+      "className",
+      "isLink",
+      "linkTarget",
+      "lock",
+      "metadata",
+      "shouldSyncIcon",
+      "style",
+      "width"
+    ],
+    "core/site-tagline": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "level",
+      "levelOptions",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/site-title": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "isLink",
+      "level",
+      "levelOptions",
+      "linkTarget",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/social-link": [
+      "anchor",
+      "className",
+      "label",
+      "lock",
+      "metadata",
+      "rel",
+      "service",
+      "style",
+      "url"
+    ],
+    "core/social-links": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "customIconBackgroundColor",
+      "customIconColor",
+      "gradient",
+      "iconBackgroundColor",
+      "iconBackgroundColorValue",
+      "iconColor",
+      "iconColorValue",
+      "layout",
+      "lock",
+      "metadata",
+      "openInNewTab",
+      "showLabels",
+      "size",
+      "style",
+      "textColor"
+    ],
+    "core/spacer": [
+      "anchor",
+      "className",
+      "height",
+      "lock",
+      "metadata",
+      "style",
+      "width"
+    ],
+    "core/table": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "body",
+      "borderColor",
+      "caption",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "foot",
+      "gradient",
+      "hasFixedLayout",
+      "head",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/tag-cloud": [
+      "align",
+      "anchor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "largestFontSize",
+      "lock",
+      "metadata",
+      "numberOfTags",
+      "showTagCounts",
+      "smallestFontSize",
+      "style",
+      "taxonomy"
+    ],
+    "core/template-part": [
+      "align",
+      "area",
+      "className",
+      "lock",
+      "metadata",
+      "slug",
+      "style",
+      "tagName",
+      "theme"
+    ],
+    "core/term-count": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "bracketType",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/term-description": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/term-name": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "isLink",
+      "level",
+      "levelOptions",
+      "lock",
+      "metadata",
+      "style",
+      "textAlign",
+      "textColor"
+    ],
+    "core/term-template": [
+      "align",
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "layout",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/terms-query": [
+      "align",
+      "anchor",
+      "className",
+      "layout",
+      "lock",
+      "metadata",
+      "style",
+      "tagName",
+      "termQuery"
+    ],
+    "core/text-columns": [
+      "className",
+      "columns",
+      "content",
+      "lock",
+      "metadata",
+      "style",
+      "width"
+    ],
+    "core/verse": [
+      "anchor",
+      "backgroundColor",
+      "borderColor",
+      "className",
+      "content",
+      "fontFamily",
+      "fontSize",
+      "gradient",
+      "lock",
+      "metadata",
+      "style",
+      "textColor"
+    ],
+    "core/video": [
+      "align",
+      "anchor",
+      "autoplay",
+      "blob",
+      "caption",
+      "className",
+      "controls",
+      "id",
+      "lock",
+      "loop",
+      "metadata",
+      "muted",
+      "playsInline",
+      "poster",
+      "preload",
+      "src",
+      "style",
+      "tracks"
+    ]
+  }
+}
diff --git a/packages/blocks-engine/src/index.ts b/packages/blocks-engine/src/index.ts
index a6e3fc6c..ad2aa47b 100644
--- a/packages/blocks-engine/src/index.ts
+++ b/packages/blocks-engine/src/index.ts
@@ -6,6 +6,9 @@ export { serializeBlockAttrs } from './serialize.js';
 export { buildEmbedBlock, guessEmbedProvider } from './embed.js';
 export { sanitize } from './sanitize.js';
 export { blockMarkupRoundtrips, scanForInjection } from './validate.js';
+export { validateBlockMarkup } from './validate-block-markup.js';
+export { walkBlocks } from './block-tree.js';
+export { validateBlockContract } from './block-contract.js';
 export { verifyComposedOutput } from './output-verify.js';
 export { heuristicBlocks } from './heuristics.js';
 export { genericHtmlToBlocks } from './catalog.js';
@@ -23,3 +26,5 @@ export type {
   WorkerPoolOptions,
 } from './pool/types.js';
 export type { PoolEvent } from './pool/events.js';
+export type { ParsedBlock } from './block-tree.js';
+export type { BlockContractIssue } from './block-contract.js';
diff --git a/packages/blocks-engine/src/validate-block-markup.ts b/packages/blocks-engine/src/validate-block-markup.ts
new file mode 100644
index 00000000..db3e3742
--- /dev/null
+++ b/packages/blocks-engine/src/validate-block-markup.ts
@@ -0,0 +1,93 @@
+// src/validate-block-markup.ts
+//
+// Structural oracle for generated block markup. This runs block markup through
+// the SAME parser WordPress/Gutenberg uses
+// (@wordpress/block-serialization-default-parser — a no-DOM JS port of the PHP
+// WP_Block_Parser) and asserts two things the parser otherwise *silently
+// tolerates*:
+//
+//   1. No content sits outside a block delimiter (freeform leak) and every
+//      block's attribute JSON parses — both surfaced by the official parser
+//      (freeform → blockName === null; bad JSON → attrs === null, no throw).
+//   2. Delimiters are balanced. The default parser does NOT flag a missing or
+//      mismatched closing delimiter — it silently re-parents the next sibling
+//      as a child (verified: `wp:columns` with no `/wp:columns` swallows the
+//      following paragraph). So we add a deterministic stack check that reuses
+//      the parser's own delimiter grammar.
+//
+// Returns a list of human-readable violation messages ([] = clean), matching
+// the `scanForInjection` convention so it folds into `validateArtifacts`.
+
+import { parse } from '@wordpress/block-serialization-default-parser';
+
+// ParsedBlock isn't exported by the package; derive it from parse()'s return type.
+type ParsedBlock = ReturnType<typeof parse>[number];
+
+// The exact delimiter grammar from @wordpress/block-serialization-default-parser.
+// Groups: 1 = leading "/" (closer), 2 = "namespace/", 3 = name, 4 = attrs, 5 = trailing "/" (void).
+const DELIMITER =
+  /<!--\s+(\/)?wp:([a-z][a-z0-9_-]*\/)?([a-z][a-z0-9_-]*)\s+({(?:(?!}\s+\/?-->).)*?}\s+)?(\/)?-->/g;
+
+/** Drop a leading `<?php … ?>` pattern-file header so it isn't seen as a freeform leak. */
+function stripPhpHeader(markup: string): string {
+  return markup.replace(/^?\s*<\?php[\s\S]*?\?>\n?/, '');
+}
+
+/** `core/paragraph` → `paragraph`; leaves an already-short name untouched. */
+function shortName(blockName: string): string {
+  return blockName.startsWith('core/') ? blockName.slice('core/'.length) : blockName;
+}
+
+/** Layer 1: walk the official parse tree for freeform leaks + unparseable attrs. */
+function checkParseTree(blocks: ParsedBlock[], issues: string[]): void {
+  for (const b of blocks) {
+    if (b.blockName === null) {
+      if ((b.innerHTML ?? '').trim() !== '') {
+        const snippet = b.innerHTML.trim().replace(/\s+/g, ' ').slice(0, 60);
+        issues.push(`content outside any block delimiter (freeform leak): "${snippet}"`);
+      }
+    } else if (b.attrs === null) {
+      // The parser sets attrs to null when the comment's JSON fails to parse.
+      issues.push(`invalid block-attribute JSON in wp:${shortName(b.blockName)}`);
+    }
+    if (b.innerBlocks && b.innerBlocks.length > 0) {
+      checkParseTree(b.innerBlocks, issues);
+    }
+  }
+}
+
+/** Layer 2: stack-based delimiter balance the default parser silently tolerates. */
+function checkBalance(markup: string, issues: string[]): void {
+  const stack: string[] = [];
+  for (const m of markup.matchAll(DELIMITER)) {
+    const name = (m[2] ?? '') + m[3];
+    const isCloser = Boolean(m[1]);
+    const isVoid = Boolean(m[5]);
+    if (isCloser) {
+      const open = stack.pop();
+      if (open === undefined) {
+        issues.push(`closing delimiter with no open block: /wp:${name}`);
+      } else if (open !== name) {
+        issues.push(`mismatched closing delimiter: expected /wp:${open}, found /wp:${name}`);
+      }
+    } else if (!isVoid) {
+      stack.push(name);
+    }
+  }
+  for (const unclosed of stack) {
+    issues.push(`unclosed block delimiter: wp:${unclosed}`);
+  }
+}
+
+/**
+ * Validate generated WordPress block markup. Accepts either a raw block-markup
+ * string or a full pattern-file `php` field (a leading `<?php … ?>` header is
+ * stripped before validation). Returns violation messages; [] means clean.
+ */
+export function validateBlockMarkup(markup: string): string[] {
+  const body = stripPhpHeader(markup);
+  const issues: string[] = [];
+  checkParseTree(parse(body), issues);
+  checkBalance(body, issues);
+  return issues;
+}

From c362110d8e251d0bc6844e865863f90fdb640e7a Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Tue, 23 Jun 2026 17:23:17 -0400
Subject: [PATCH 023/113] fix(blocks-engine): restore trust-source posture in
 ported validateBlockContract (faithful to DLA)

---
 .../src/__tests__/block-contract.test.ts      | 30 +++++++------------
 packages/blocks-engine/src/block-contract.ts  | 14 ++++-----
 2 files changed, 18 insertions(+), 26 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/block-contract.test.ts b/packages/blocks-engine/src/__tests__/block-contract.test.ts
index 71c60493..5f58a47c 100644
--- a/packages/blocks-engine/src/__tests__/block-contract.test.ts
+++ b/packages/blocks-engine/src/__tests__/block-contract.test.ts
@@ -33,27 +33,21 @@ describe('validateBlockContract', () => {
     ]);
   });
 
-  it('uses a core-only default allowlist and preserves caller allowlists', () => {
-    const markup = `<!-- wp:dla/foo {"madeUp":1} -->
-<section data-wp-interactive="dla/foo">x</section>
-<!-- /wp:dla/foo -->
-<!-- wp:html -->
-<div onclickish="weird">island</div>
-<!-- /wp:html -->`;
-    expect(validateBlockContract(markup)).toEqual([
-      { code: 'unknown-block', blockName: 'dla/foo', detail: 'not a core block or allowlisted namespace' },
-    ]);
-    expect(validateBlockContract(markup, { allowlist: ['dla/', 'core/html'] })).toEqual([]);
-  });
-
-  it('allowlisted non-core namespaces pass untouched', () => {
+  it('skips deliberate non-core blocks and allowlisted core/html untouched', () => {
     const markup = `<!-- wp:dla/reveal {"madeUp":1} -->
 <section data-wp-interactive="dla/reveal">x</section>
 <!-- /wp:dla/reveal -->
 <!-- wp:html -->
 <div onclickish="weird">island</div>
 <!-- /wp:html -->`;
-    expect(validateBlockContract(markup, { allowlist: ['dla/', 'core/html'] })).toEqual([]);
+    expect(validateBlockContract(markup)).toEqual([]);
+  });
+
+  it('skips jetpack/contact-form blocks by default (trust-source posture)', () => {
+    const markup = `<!-- wp:jetpack/contact-form {"anything":"goes"} -->
+<div class="wp-block-jetpack-contact-form">x</div>
+<!-- /wp:jetpack/contact-form -->`;
+    expect(validateBlockContract(markup)).toEqual([]);
   });
 
   it('clean markup returns no issues', () => {
@@ -65,13 +59,11 @@ describe('validateBlockContract', () => {
     expect(validateBlockContract(markup)).toEqual([]);
   });
 
-  it('non-core namespaces are flagged unless allowlisted', () => {
+  it('skips non-allowlisted non-core namespaces by default (trust-source posture)', () => {
     const markup = `<!-- wp:acme/widget {"anything":"goes"} -->
 <div class="acme-widget">x</div>
 <!-- /wp:acme/widget -->`;
-    expect(validateBlockContract(markup)).toEqual([
-      { code: 'unknown-block', blockName: 'acme/widget', detail: 'not a core block or allowlisted namespace' },
-    ]);
+    expect(validateBlockContract(markup)).toEqual([]);
   });
 
   it('walks innerBlocks (nested invented attr still caught)', () => {
diff --git a/packages/blocks-engine/src/block-contract.ts b/packages/blocks-engine/src/block-contract.ts
index 3a3f7988..40c53fc8 100644
--- a/packages/blocks-engine/src/block-contract.ts
+++ b/packages/blocks-engine/src/block-contract.ts
@@ -12,9 +12,10 @@
 // attrs/blocks at a fraction of the surface.
 //
 // Scope:
-// - Only core/* blocks are accepted by default. Allowlisted prefixes (default
-//   ['core/html']) skip entirely — deliberate verbatim islands. Callers that
-//   intentionally emit non-core blocks can pass their namespace allowlist.
+// - Only core/* blocks are validated. Allowlisted prefixes (default
+//   ['core/html']) skip entirely — deliberate verbatim islands. Any non-core
+//   namespace also skips: we have no metadata for third-party blocks and
+//   inventing judgments about them would be guessing (trust-source posture).
 // - attrs === null (unparseable JSON) is the roundtrip oracle's failure to
 //   report; here it degrades to "no attrs to check".
 //
@@ -63,10 +64,9 @@ function isAllowlisted(blockName: string, allowlist: string[]): boolean {
 function checkBlock(b: ParsedBlock, allowlist: string[], issues: BlockContractIssue[]): void {
   const name = b.blockName as string;
   if (isAllowlisted(name, allowlist)) return;
-  if (!name.startsWith('core/')) {
-    issues.push({ code: 'unknown-block', blockName: name, detail: 'not a core block or allowlisted namespace' });
-    return;
-  }
+  // Only core/* validates against the snapshot; other namespaces skip
+  // (no metadata for third-party blocks — see the header).
+  if (!name.startsWith('core/')) return;
 
   const registered = ATTRS_BY_BLOCK.get(name);
   if (!registered) {

From 5f94c63b5213924a5b02fc1b55b865e4c73c0f4d Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 10:31:35 -0400
Subject: [PATCH 024/113] feat(blocks-engine): freeze async convert contract

---
 packages/blocks-engine/src/convert.ts | 23 +++++++++++++++++++++++
 packages/blocks-engine/src/errors.ts  | 19 +++++++++++++++++++
 packages/blocks-engine/src/index.ts   | 14 ++++++++++++++
 3 files changed, 56 insertions(+)
 create mode 100644 packages/blocks-engine/src/convert.ts
 create mode 100644 packages/blocks-engine/src/errors.ts

diff --git a/packages/blocks-engine/src/convert.ts b/packages/blocks-engine/src/convert.ts
new file mode 100644
index 00000000..50cca006
--- /dev/null
+++ b/packages/blocks-engine/src/convert.ts
@@ -0,0 +1,23 @@
+import { BlocksEngineError } from './errors.js';
+import type { WorkerPool } from './pool/types.js';
+import type { ConversionContext, Converter, HtmlFallback } from './types.js';
+
+export interface ConvertOptions {
+  pool?: WorkerPool;
+  converters?: Converter[];
+  htmlFallback?: HtmlFallback;
+}
+
+export async function convert(
+  html: string,
+  ctx?: Partial<ConversionContext>,
+  opts?: ConvertOptions,
+): Promise<string> {
+  void html;
+  void ctx;
+  void opts;
+  throw new BlocksEngineError('Main-entry convert is not wired yet.', {
+    code: 'CONVERT_NOT_IMPLEMENTED',
+    hint: 'Use the /wp entry until the async main-entry convert implementation is wired.',
+  });
+}
diff --git a/packages/blocks-engine/src/errors.ts b/packages/blocks-engine/src/errors.ts
new file mode 100644
index 00000000..9b783663
--- /dev/null
+++ b/packages/blocks-engine/src/errors.ts
@@ -0,0 +1,19 @@
+export interface BlocksEngineErrorOptions {
+  code: string;
+  hint: string;
+  docsAnchor?: string;
+}
+
+export class BlocksEngineError extends Error {
+  readonly code: string;
+  readonly hint: string;
+  readonly docsAnchor?: string;
+
+  constructor(message: string, options: BlocksEngineErrorOptions) {
+    super(message);
+    this.name = 'BlocksEngineError';
+    this.code = options.code;
+    this.hint = options.hint;
+    this.docsAnchor = options.docsAnchor;
+  }
+}
diff --git a/packages/blocks-engine/src/index.ts b/packages/blocks-engine/src/index.ts
index ad2aa47b..7fde552b 100644
--- a/packages/blocks-engine/src/index.ts
+++ b/packages/blocks-engine/src/index.ts
@@ -1,4 +1,17 @@
+import { convert as convertMainEntry } from './convert.js';
+import type { WorkerPool } from './pool/types.js';
+import type { ConversionContext, Converter, HtmlFallback } from './types.js';
+
+export async function convert(
+  html: string,
+  ctx?: Partial<ConversionContext>,
+  opts?: { pool?: WorkerPool; converters?: Converter[]; htmlFallback?: HtmlFallback },
+): Promise<string> {
+  return convertMainEntry(html, ctx, opts);
+}
+
 export { compose } from './compose.js';
+export { BlocksEngineError } from './errors.js';
 export { createWorker } from './pool/pool.js';
 export { isRawConvertible, UNWRAP_SELECTOR } from './raw-convertible.js';
 export { escapeHtml, escapeHtmlAttr, escapeHtmlText } from './escape.js';
@@ -15,6 +28,7 @@ export { genericHtmlToBlocks } from './catalog.js';
 export { composeFromRecipes } from './recipe-table.js';
 export { PIPELINE_ISLAND_OPENER, PIPELINE_ISLAND_NAME } from './block-policy.js';
 
+export type { BlocksEngineErrorOptions } from './errors.js';
 export type * from './types.js';
 export type { VerifyResult } from './output-verify.js';
 export type { HeuristicResult } from './heuristics.js';

From 7d67d24f81fb5ba4e965e865f063ab3b4daa1826 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 10:41:11 -0400
Subject: [PATCH 025/113] feat(blocks-engine): wire async main convert

---
 .../src/__tests__/compose.injection.test.ts   |  14 +-
 .../src/__tests__/convert.test.ts             | 128 +++++++++++++++++-
 packages/blocks-engine/src/compose.ts         |   9 +-
 packages/blocks-engine/src/convert.ts         |  33 +++--
 packages/blocks-engine/src/pool/pool.ts       |   9 +-
 5 files changed, 173 insertions(+), 20 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/compose.injection.test.ts b/packages/blocks-engine/src/__tests__/compose.injection.test.ts
index cf762676..60024b58 100644
--- a/packages/blocks-engine/src/__tests__/compose.injection.test.ts
+++ b/packages/blocks-engine/src/__tests__/compose.injection.test.ts
@@ -1,14 +1,22 @@
 import { describe, expect, it } from 'vitest';
 
 import { compose } from '../compose';
+import { BlocksEngineError } from '../index';
 
 const ctx = { url: 'https://x.test/' };
 
 describe('compose default htmlFallback injection guard', () => {
   it('throws when sanitized fallback html still contains a quote-adjacent event handler', () => {
-    expect(() => compose('<img src="x"onerror="alert(1)">', ctx, {})).toThrow(
-      /html-fallback sanitization left injection vectors|inline event handler/,
-    );
+    try {
+      compose('<img src="x"onerror="alert(1)">', ctx, {});
+      throw new Error('Expected compose to throw');
+    } catch (error) {
+      expect(error).toBeInstanceOf(BlocksEngineError);
+      expect(error).toMatchObject({
+        code: 'INJECTION_VECTORS_REMAIN',
+        hint: expect.stringContaining('htmlFallback'),
+      });
+    }
   });
 
   it('keeps clean unconvertible html in the coverage island', () => {
diff --git a/packages/blocks-engine/src/__tests__/convert.test.ts b/packages/blocks-engine/src/__tests__/convert.test.ts
index 57e1be94..04168557 100644
--- a/packages/blocks-engine/src/__tests__/convert.test.ts
+++ b/packages/blocks-engine/src/__tests__/convert.test.ts
@@ -1,9 +1,11 @@
-import { describe, expect, it } from 'vitest';
+import { createRequire } from 'node:module';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
 
-import * as defaultEntry from '../index';
 import cases from '../__fixtures__/cases.json' with { type: 'json' };
+import type { WorkerPool } from '../pool/types';
 import { canonicalize } from '../wp/canonicalize';
-import { convert } from '../wp';
+import { convert as wpConvert } from '../wp';
 
 type Fixture = {
   id: string;
@@ -19,10 +21,118 @@ const fixture = (id: string) => {
   return found;
 };
 
-describe('convert', () => {
+const inputHtml = '<h2>Title</h2><p>Body</p>';
+const nativeBlocks = [
+  '<!-- wp:heading -->',
+  '<h2 class="wp-block-heading">Title</h2>',
+  '<!-- /wp:heading -->',
+  '',
+  '<!-- wp:paragraph -->',
+  '<p>Body</p>',
+  '<!-- /wp:paragraph -->',
+].join('\n');
+
+const requireFromHere = createRequire(import.meta.url);
+const requireCache = (requireFromHere as typeof requireFromHere & { cache: Record<string, unknown> })
+  .cache;
+const poolModuleIds = ['../pool/pool.js', '../pool/pool'];
+
+function requireCacheEntriesForWordPressBlocks(): string[] {
+  return Object.keys(requireCache).filter((entry) =>
+    entry.includes('/node_modules/@wordpress/blocks/'),
+  );
+}
+
+function clearWordPressBlocksRequireCache(): void {
+  for (const entry of requireCacheEntriesForWordPressBlocks()) {
+    delete requireCache[entry];
+  }
+}
+
+function mockPoolFor(html = nativeBlocks): WorkerPool {
+  return {
+    rawConvert: vi.fn(async () => [{ html, wpHtmlResidue: 0 }]),
+    canonicalize: vi.fn(async (items: string[]) =>
+      items.map((item) => ({ html: item, changed: false, fixedIssues: [] })),
+    ),
+    stop: vi.fn(async () => undefined),
+  };
+}
+
+function mockCreateWorker(pool: WorkerPool): ReturnType<typeof vi.fn> {
+  const createWorker = vi.fn(() => pool);
+  for (const moduleId of poolModuleIds) {
+    vi.doMock(moduleId, () => ({ createWorker }));
+  }
+  return createWorker;
+}
+
+afterEach(() => {
+  for (const moduleId of poolModuleIds) {
+    vi.doUnmock(moduleId);
+  }
+  vi.resetModules();
+});
+
+describe('main entry convert', () => {
+  it('converts simple heading and paragraph html to native blocks through the real one-shot pool', async () => {
+    const { convert } = await import('../index.js');
+
+    const out = await convert(inputHtml, { url: '' });
+
+    expect(out).toContain('<!-- wp:heading -->');
+    expect(out).toContain('<!-- wp:paragraph -->');
+    expect(out).not.toContain('<!-- wp:html');
+  }, 20_000);
+
+  it('stops a one-shot pool created for the call', async () => {
+    const pool = mockPoolFor();
+    const createWorker = mockCreateWorker(pool);
+    const { convert } = await import('../index.js');
+
+    const out = await convert(inputHtml, { url: '' });
+
+    expect(out).toContain('<!-- wp:heading -->');
+    expect(out).toContain('<!-- wp:paragraph -->');
+    expect(out).not.toContain('<!-- wp:html');
+    expect(createWorker).toHaveBeenCalledTimes(1);
+    expect(pool.rawConvert).toHaveBeenCalledWith([inputHtml]);
+    expect(pool.canonicalize).toHaveBeenCalledWith([nativeBlocks]);
+    expect(pool.stop).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not stop an injected pool', async () => {
+    const injectedPool = mockPoolFor();
+    const createWorker = mockCreateWorker(mockPoolFor());
+    const { convert } = await import('../index.js');
+
+    await expect(convert(inputHtml, { url: '' }, { pool: injectedPool })).resolves.toContain(
+      '<!-- wp:heading -->',
+    );
+
+    expect(createWorker).not.toHaveBeenCalled();
+    expect(injectedPool.rawConvert).toHaveBeenCalledWith([inputHtml]);
+    expect(injectedPool.stop).not.toHaveBeenCalled();
+  });
+
+  it('does not require @wordpress/blocks into the current process', async () => {
+    clearWordPressBlocksRequireCache();
+    const pool = mockPoolFor();
+    mockCreateWorker(pool);
+    const { convert } = await import('../index.js');
+
+    expect(requireCacheEntriesForWordPressBlocks()).toEqual([]);
+
+    await convert(inputHtml, { url: '' });
+
+    expect(requireCacheEntriesForWordPressBlocks()).toEqual([]);
+  });
+});
+
+describe('/wp convert', () => {
   it('composes the original source when rawConvert leaves html residue, then canonicalizes', () => {
     const composeFixture = fixture('compose.sample-callout-div') as Fixture & { expected: string };
-    expect(convert(composeFixture.input, { url: 'https://x.test/' })).toBe(
+    expect(wpConvert(composeFixture.input, { url: 'https://x.test/' })).toBe(
       canonicalize(composeFixture.expected).html,
     );
   });
@@ -31,15 +141,19 @@ describe('convert', () => {
     const rawFixture = fixture('raw.smoke-heading-paragraph-table') as Fixture & {
       expected: { html: string; wpHtmlResidue: number };
     };
-    expect(convert(rawFixture.input, { url: 'https://x.test/' })).toBe(
+    expect(wpConvert(rawFixture.input, { url: 'https://x.test/' })).toBe(
       canonicalize(rawFixture.expected.html).html,
     );
   });
 });
 
 describe('default entry', () => {
-  it('exports the React-free public surface', () => {
+  it('exports the React-free public surface', async () => {
+    const defaultEntry = await import('../index.js');
+
+    expect(typeof defaultEntry.convert).toBe('function');
     expect(typeof defaultEntry.compose).toBe('function');
+    expect(typeof defaultEntry.BlocksEngineError).toBe('function');
     expect(typeof defaultEntry.createWorker).toBe('function');
     expect(typeof defaultEntry.isRawConvertible).toBe('function');
     expect(typeof defaultEntry.escapeHtmlText).toBe('function');
diff --git a/packages/blocks-engine/src/compose.ts b/packages/blocks-engine/src/compose.ts
index 803d4789..b8c7fddd 100644
--- a/packages/blocks-engine/src/compose.ts
+++ b/packages/blocks-engine/src/compose.ts
@@ -1,5 +1,6 @@
 import { PIPELINE_ISLAND_OPENER } from './block-policy.js';
 import { genericHtmlToBlocks } from './catalog.js';
+import { BlocksEngineError } from './errors.js';
 import { sanitize } from './sanitize.js';
 import { scanForInjection } from './validate.js';
 import type { ConversionContext, Converter, HtmlFallback } from './types.js';
@@ -10,7 +11,13 @@ function defaultHtmlFallback(html: string): string {
   const inner = sanitize(html);
   const violations = scanForInjection(inner);
   if (violations.length > 0) {
-    throw new Error(`html-fallback sanitization left injection vectors: ${violations.join('; ')}`);
+    throw new BlocksEngineError(
+      `html-fallback sanitization left injection vectors: ${violations.join('; ')}`,
+      {
+        code: 'INJECTION_VECTORS_REMAIN',
+        hint: 'Pass a function htmlFallback that emits safe markup, or pre-sanitize input before using the default htmlFallback.',
+      },
+    );
   }
   return `${PIPELINE_ISLAND_OPENER}\n${inner.trim()}\n<!-- /wp:html -->`;
 }
diff --git a/packages/blocks-engine/src/convert.ts b/packages/blocks-engine/src/convert.ts
index 50cca006..67725569 100644
--- a/packages/blocks-engine/src/convert.ts
+++ b/packages/blocks-engine/src/convert.ts
@@ -1,4 +1,5 @@
-import { BlocksEngineError } from './errors.js';
+import { compose } from './compose.js';
+import { createWorker } from './pool/pool.js';
 import type { WorkerPool } from './pool/types.js';
 import type { ConversionContext, Converter, HtmlFallback } from './types.js';
 
@@ -13,11 +14,27 @@ export async function convert(
   ctx?: Partial<ConversionContext>,
   opts?: ConvertOptions,
 ): Promise<string> {
-  void html;
-  void ctx;
-  void opts;
-  throw new BlocksEngineError('Main-entry convert is not wired yet.', {
-    code: 'CONVERT_NOT_IMPLEMENTED',
-    hint: 'Use the /wp entry until the async main-entry convert implementation is wired.',
-  });
+  const fullCtx: ConversionContext =
+    ctx?.mediaMap === undefined
+      ? { url: ctx?.url ?? '' }
+      : { url: ctx?.url ?? '', mediaMap: ctx.mediaMap };
+  const ownsPool = opts?.pool === undefined;
+  const pool = opts?.pool ?? createWorker();
+
+  try {
+    const [raw] = await pool.rawConvert([html]);
+    const blockMarkup =
+      raw.html !== null && raw.wpHtmlResidue === 0
+        ? raw.html
+        : compose(html, fullCtx, {
+            converters: opts?.converters,
+            htmlFallback: opts?.htmlFallback,
+          });
+    const [fixed] = await pool.canonicalize([blockMarkup]);
+    return fixed.html;
+  } finally {
+    if (ownsPool) {
+      await pool.stop();
+    }
+  }
 }
diff --git a/packages/blocks-engine/src/pool/pool.ts b/packages/blocks-engine/src/pool/pool.ts
index a8f4e801..66cf51bf 100644
--- a/packages/blocks-engine/src/pool/pool.ts
+++ b/packages/blocks-engine/src/pool/pool.ts
@@ -4,6 +4,7 @@ import { cpus } from 'node:os';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { BlocksEngineError } from '../errors.js';
 import type { ChildToParentMessage, WorkerOp } from './protocol.js';
 import type {
   CreateWorker,
@@ -99,7 +100,13 @@ function workerChildPath(): string {
   if (workerPath) {
     return workerPath;
   }
-  throw new Error(`Unable to resolve worker child path. Tried: ${candidates.join(', ')}`);
+  throw new BlocksEngineError(
+    `Unable to resolve worker child path. Tried: ${candidates.join(', ')}`,
+    {
+      code: 'WORKER_CHILD_UNRESOLVED',
+      hint: 'Run npm run build and confirm the expected dist layout includes the pool/wp worker child file.',
+    },
+  );
 }
 
 function forkExecArgv(path: string): string[] {

From ece767b1ea9c4ace0dce890e1d1d91332847c026 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 10:50:53 -0400
Subject: [PATCH 026/113] feat(blocks-engine): freeze internals export contract

---
 packages/blocks-engine/package.json           | 16 ++++++++++++----
 packages/blocks-engine/src/internals/index.ts | 19 +++++++++++++++++++
 2 files changed, 31 insertions(+), 4 deletions(-)
 create mode 100644 packages/blocks-engine/src/internals/index.ts

diff --git a/packages/blocks-engine/package.json b/packages/blocks-engine/package.json
index be228cd7..7ee99af1 100644
--- a/packages/blocks-engine/package.json
+++ b/packages/blocks-engine/package.json
@@ -5,14 +5,22 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "source": "./src/index.ts",
+      "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
     "./wp": {
-      "types": "./src/wp/index.ts",
-      "import": "./src/wp/index.ts",
+      "types": "./dist/wp/index.d.ts",
+      "source": "./src/wp/index.ts",
+      "import": "./dist/wp/index.js",
       "require": "./dist/wp/index.cjs"
+    },
+    "./internals": {
+      "types": "./dist/internals/index.d.ts",
+      "source": "./src/internals/index.ts",
+      "import": "./dist/internals/index.js",
+      "require": "./dist/internals/index.cjs"
     }
   },
   "scripts": {
diff --git a/packages/blocks-engine/src/internals/index.ts b/packages/blocks-engine/src/internals/index.ts
new file mode 100644
index 00000000..37af5c96
--- /dev/null
+++ b/packages/blocks-engine/src/internals/index.ts
@@ -0,0 +1,19 @@
+export { isRawConvertible, UNWRAP_SELECTOR } from '../raw-convertible.js';
+export { escapeHtml, escapeHtmlAttr, escapeHtmlText } from '../escape.js';
+export { serializeBlockAttrs } from '../serialize.js';
+export { buildEmbedBlock, guessEmbedProvider } from '../embed.js';
+export { sanitize } from '../sanitize.js';
+export { blockMarkupRoundtrips, scanForInjection } from '../validate.js';
+export { validateBlockMarkup } from '../validate-block-markup.js';
+export { walkBlocks } from '../block-tree.js';
+export { validateBlockContract } from '../block-contract.js';
+export { verifyComposedOutput } from '../output-verify.js';
+export { heuristicBlocks } from '../heuristics.js';
+export { genericHtmlToBlocks } from '../catalog.js';
+export { composeFromRecipes } from '../recipe-table.js';
+export { PIPELINE_ISLAND_OPENER, PIPELINE_ISLAND_NAME } from '../block-policy.js';
+
+export type { VerifyResult } from '../output-verify.js';
+export type { HeuristicResult } from '../heuristics.js';
+export type { ParsedBlock } from '../block-tree.js';
+export type { BlockContractIssue } from '../block-contract.js';

From e62a5d60032e1642e6170c117aeee6c59ea9be55 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 10:58:30 -0400
Subject: [PATCH 027/113] feat(blocks-engine): curate public barrel exports

---
 .../src/__tests__/convert.test.ts             | 48 ++++++++++++++----
 .../src/__tests__/exports-shape.test.ts       | 49 +++++++++++++++++++
 packages/blocks-engine/src/index.ts           | 36 ++------------
 packages/blocks-engine/tsup.config.ts         |  1 +
 4 files changed, 92 insertions(+), 42 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/exports-shape.test.ts

diff --git a/packages/blocks-engine/src/__tests__/convert.test.ts b/packages/blocks-engine/src/__tests__/convert.test.ts
index 04168557..feab7326 100644
--- a/packages/blocks-engine/src/__tests__/convert.test.ts
+++ b/packages/blocks-engine/src/__tests__/convert.test.ts
@@ -148,21 +148,49 @@ describe('/wp convert', () => {
 });
 
 describe('default entry', () => {
-  it('exports the React-free public surface', async () => {
+  it('exports only the runtime public surface and keeps demoted symbols under internals', async () => {
     const defaultEntry = await import('../index.js');
+    const internalsEntry = await import('../internals/index.js');
+
+    const publicRuntimeSymbols = [
+      'BlocksEngineError',
+      'compose',
+      'convert',
+      'createWorker',
+    ].sort();
+    const demotedRuntimeSymbols = [
+      'PIPELINE_ISLAND_NAME',
+      'PIPELINE_ISLAND_OPENER',
+      'UNWRAP_SELECTOR',
+      'blockMarkupRoundtrips',
+      'buildEmbedBlock',
+      'composeFromRecipes',
+      'escapeHtml',
+      'escapeHtmlAttr',
+      'escapeHtmlText',
+      'genericHtmlToBlocks',
+      'guessEmbedProvider',
+      'heuristicBlocks',
+      'isRawConvertible',
+      'sanitize',
+      'scanForInjection',
+      'serializeBlockAttrs',
+      'validateBlockContract',
+      'validateBlockMarkup',
+      'verifyComposedOutput',
+      'walkBlocks',
+    ];
+
+    expect(Object.keys(defaultEntry).sort()).toEqual(publicRuntimeSymbols);
 
     expect(typeof defaultEntry.convert).toBe('function');
     expect(typeof defaultEntry.compose).toBe('function');
     expect(typeof defaultEntry.BlocksEngineError).toBe('function');
     expect(typeof defaultEntry.createWorker).toBe('function');
-    expect(typeof defaultEntry.isRawConvertible).toBe('function');
-    expect(typeof defaultEntry.escapeHtmlText).toBe('function');
-    expect(typeof defaultEntry.escapeHtmlAttr).toBe('function');
-    expect(typeof defaultEntry.buildEmbedBlock).toBe('function');
-    expect(typeof defaultEntry.guessEmbedProvider).toBe('function');
-    expect(typeof defaultEntry.sanitize).toBe('function');
-    expect(typeof defaultEntry.blockMarkupRoundtrips).toBe('function');
-    expect(typeof defaultEntry.verifyComposedOutput).toBe('function');
-    expect(typeof defaultEntry.heuristicBlocks).toBe('function');
+
+    for (const symbol of demotedRuntimeSymbols) {
+      expect(defaultEntry).not.toHaveProperty(symbol);
+      expect(internalsEntry).toHaveProperty(symbol);
+    }
   });
 });
diff --git a/packages/blocks-engine/src/__tests__/exports-shape.test.ts b/packages/blocks-engine/src/__tests__/exports-shape.test.ts
new file mode 100644
index 00000000..ef1523c2
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/exports-shape.test.ts
@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs';
+
+import { describe, expect, it } from 'vitest';
+
+type PackageExport = {
+  import?: string;
+  require?: string;
+  source?: string;
+  types?: string;
+};
+
+type PackageJson = {
+  exports: Record<string, PackageExport>;
+};
+
+function readPackageJson(): PackageJson {
+  return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+}
+
+describe('package exports', () => {
+  it('points public entries at built dist files and exposes built internals', () => {
+    const { exports } = readPackageJson();
+
+    expect(exports['.']).toEqual({
+      import: './dist/index.js',
+      require: './dist/index.cjs',
+      source: './src/index.ts',
+      types: './dist/index.d.ts',
+    });
+    expect(exports['.'].import).not.toContain('/src/');
+    expect(exports['.'].types).not.toContain('/src/');
+
+    expect(exports['./wp']).toEqual({
+      import: './dist/wp/index.js',
+      require: './dist/wp/index.cjs',
+      source: './src/wp/index.ts',
+      types: './dist/wp/index.d.ts',
+    });
+    expect(exports['./wp'].import).not.toContain('/src/');
+    expect(exports['./wp'].types).not.toContain('/src/');
+
+    expect(exports['./internals']).toEqual({
+      types: './dist/internals/index.d.ts',
+      source: './src/internals/index.ts',
+      import: './dist/internals/index.js',
+      require: './dist/internals/index.cjs',
+    });
+  });
+});
diff --git a/packages/blocks-engine/src/index.ts b/packages/blocks-engine/src/index.ts
index 7fde552b..3e33ee78 100644
--- a/packages/blocks-engine/src/index.ts
+++ b/packages/blocks-engine/src/index.ts
@@ -1,37 +1,11 @@
-import { convert as convertMainEntry } from './convert.js';
-import type { WorkerPool } from './pool/types.js';
-import type { ConversionContext, Converter, HtmlFallback } from './types.js';
-
-export async function convert(
-  html: string,
-  ctx?: Partial<ConversionContext>,
-  opts?: { pool?: WorkerPool; converters?: Converter[]; htmlFallback?: HtmlFallback },
-): Promise<string> {
-  return convertMainEntry(html, ctx, opts);
-}
-
+export { convert } from './convert.js';
 export { compose } from './compose.js';
-export { BlocksEngineError } from './errors.js';
 export { createWorker } from './pool/pool.js';
-export { isRawConvertible, UNWRAP_SELECTOR } from './raw-convertible.js';
-export { escapeHtml, escapeHtmlAttr, escapeHtmlText } from './escape.js';
-export { serializeBlockAttrs } from './serialize.js';
-export { buildEmbedBlock, guessEmbedProvider } from './embed.js';
-export { sanitize } from './sanitize.js';
-export { blockMarkupRoundtrips, scanForInjection } from './validate.js';
-export { validateBlockMarkup } from './validate-block-markup.js';
-export { walkBlocks } from './block-tree.js';
-export { validateBlockContract } from './block-contract.js';
-export { verifyComposedOutput } from './output-verify.js';
-export { heuristicBlocks } from './heuristics.js';
-export { genericHtmlToBlocks } from './catalog.js';
-export { composeFromRecipes } from './recipe-table.js';
-export { PIPELINE_ISLAND_OPENER, PIPELINE_ISLAND_NAME } from './block-policy.js';
+export { BlocksEngineError } from './errors.js';
 
+export type { ConvertOptions } from './convert.js';
 export type { BlocksEngineErrorOptions } from './errors.js';
-export type * from './types.js';
-export type { VerifyResult } from './output-verify.js';
-export type { HeuristicResult } from './heuristics.js';
+export type { ConversionContext, Converter, HtmlFallback } from './types.js';
 export type {
   CreateWorker,
   FixResult,
@@ -40,5 +14,3 @@ export type {
   WorkerPoolOptions,
 } from './pool/types.js';
 export type { PoolEvent } from './pool/events.js';
-export type { ParsedBlock } from './block-tree.js';
-export type { BlockContractIssue } from './block-contract.js';
diff --git a/packages/blocks-engine/tsup.config.ts b/packages/blocks-engine/tsup.config.ts
index 1d2348a0..0f803d7f 100644
--- a/packages/blocks-engine/tsup.config.ts
+++ b/packages/blocks-engine/tsup.config.ts
@@ -3,6 +3,7 @@ import { defineConfig } from 'tsup';
 export default defineConfig({
   entry: {
     index: 'src/index.ts',
+    'internals/index': 'src/internals/index.ts',
     'wp/index': 'src/wp/index.ts',
     'wp/worker-child': 'src/wp/worker-child.ts',
   },

From 966410c7ee6ef61b7c4ca00784f95e346d04a9d9 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 11:05:46 -0400
Subject: [PATCH 028/113] feat(blocks-engine): freeze cli package contract

---
 packages/blocks-engine/package.json           |  8 +-
 .../blocks-engine/src/__tests__/cli.test.ts   | 91 +++++++++++++++++++
 2 files changed, 98 insertions(+), 1 deletion(-)
 create mode 100644 packages/blocks-engine/src/__tests__/cli.test.ts

diff --git a/packages/blocks-engine/package.json b/packages/blocks-engine/package.json
index 7ee99af1..58a9eea9 100644
--- a/packages/blocks-engine/package.json
+++ b/packages/blocks-engine/package.json
@@ -1,8 +1,14 @@
 {
   "name": "@automattic/blocks-engine",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "license": "GPL-3.0-or-later",
   "type": "module",
+  "bin": {
+    "blocks-engine": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
diff --git a/packages/blocks-engine/src/__tests__/cli.test.ts b/packages/blocks-engine/src/__tests__/cli.test.ts
new file mode 100644
index 00000000..633d2513
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/cli.test.ts
@@ -0,0 +1,91 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+
+import { describe, expect, it } from 'vitest';
+
+import { runCli } from '../cli';
+import { BlocksEngineError } from '../errors';
+
+function writableBuffer() {
+  let output = '';
+
+  return {
+    stream: {
+      write(chunk: string | Uint8Array) {
+        output += typeof chunk === 'string' ? chunk : chunk.toString();
+        return true;
+      },
+    },
+    text: () => output,
+  };
+}
+
+describe('CLI one-shot conversion', () => {
+  it('reads a file arg and writes block markup to stdout', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'blocks-engine-cli-'));
+
+    try {
+      const filePath = join(dir, 'sample.html');
+      await writeFile(filePath, '<h2>Hello CLI</h2><p>Body copy.</p>');
+
+      const stdout = writableBuffer();
+      const stderr = writableBuffer();
+      const exitCode = await runCli([filePath], {
+        stdout: stdout.stream,
+        stderr: stderr.stream,
+      });
+
+      expect(exitCode).toBe(0);
+      expect(stdout.text()).toContain('<!-- wp:');
+      expect(stderr.text()).toBe('');
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('reads stdin when no file arg is provided', async () => {
+    let seenUrl: string | undefined;
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+
+    const exitCode = await runCli([], {
+      stdin: Readable.from(['<p>From stdin.</p>']),
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+      convertHtml: async (_html, ctx) => {
+        seenUrl = ctx?.url;
+        return '<!-- wp:paragraph --><p>From stdin.</p><!-- /wp:paragraph -->';
+      },
+    });
+
+    expect(exitCode).toBe(0);
+    expect(seenUrl).toMatch(/^file:\/\//);
+    expect(seenUrl).toMatch(/stdin$/);
+    expect(stdout.text()).toContain('<!-- wp:paragraph -->');
+    expect(stderr.text()).toBe('');
+  });
+
+  it('prints BlocksEngineError message and hint to stderr', async () => {
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+
+    const exitCode = await runCli([], {
+      stdin: Readable.from(['<p>Unsafe.</p>']),
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+      convertHtml: async () => {
+        throw new BlocksEngineError('Cannot convert HTML.', {
+          code: 'test-error',
+          hint: 'Remove unsupported markup and try again.',
+        });
+      },
+    });
+
+    expect(exitCode).toBe(1);
+    expect(stdout.text()).toBe('');
+    expect(stderr.text()).toContain('Cannot convert HTML.');
+    expect(stderr.text()).toContain('Remove unsupported markup and try again.');
+  });
+});

From 5cb6cce6557d56b9d828b9315a49dad8f41f85a8 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 11:19:20 -0400
Subject: [PATCH 029/113] feat(blocks-engine): add one-shot cli

---
 packages/blocks-engine/CHANGELOG.md     | 22 +++++++
 packages/blocks-engine/src/cli.ts       | 84 +++++++++++++++++++++++++
 packages/blocks-engine/tsup.config.ts   |  1 +
 packages/blocks-engine/vitest.config.ts |  1 +
 4 files changed, 108 insertions(+)
 create mode 100644 packages/blocks-engine/CHANGELOG.md
 create mode 100644 packages/blocks-engine/src/cli.ts

diff --git a/packages/blocks-engine/CHANGELOG.md b/packages/blocks-engine/CHANGELOG.md
new file mode 100644
index 00000000..899764eb
--- /dev/null
+++ b/packages/blocks-engine/CHANGELOG.md
@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to `@automattic/blocks-engine` will be documented in this file.
+
+This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## Versioning
+
+This package uses [Semantic Versioning](https://semver.org/). Deprecations are warned one minor version ahead of removal.
+
+## [0.1.0] - 2026-06-24
+
+### Added
+
+- Async main convert API.
+- `BlocksEngineError` for stable package errors.
+- `/internals` subpath for supported internal consumers.
+- `npx` CLI entrypoint.
+
+### Fixed
+
+- Export map now points to built `dist` artifacts.
diff --git a/packages/blocks-engine/src/cli.ts b/packages/blocks-engine/src/cli.ts
new file mode 100644
index 00000000..83c8af68
--- /dev/null
+++ b/packages/blocks-engine/src/cli.ts
@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+import { realpathSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { Readable } from 'node:stream';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { convert } from './convert.js';
+import { BlocksEngineError } from './errors.js';
+
+interface WritableLike {
+  write(chunk: string | Uint8Array): unknown;
+}
+
+type ConvertHtml = (html: string, ctx: { url: string }) => Promise<string>;
+
+export interface RunCliOptions {
+  stdin?: Readable;
+  stdout?: WritableLike;
+  stderr?: WritableLike;
+  convertHtml?: ConvertHtml;
+}
+
+async function readStdin(stdin: Readable): Promise<string> {
+  let html = '';
+
+  for await (const chunk of stdin) {
+    html += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
+  }
+
+  return html;
+}
+
+export async function runCli(argv: string[], options: RunCliOptions = {}): Promise<number> {
+  const stdin = options.stdin ?? process.stdin;
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const convertHtml = options.convertHtml ?? convert;
+  const fileArg = argv[0];
+
+  try {
+    const input =
+      fileArg === undefined
+        ? {
+            html: await readStdin(stdin),
+            url: pathToFileURL(resolve(process.cwd(), 'stdin')).href,
+          }
+        : {
+            html: await readFile(resolve(fileArg), 'utf8'),
+            url: pathToFileURL(resolve(fileArg)).href,
+          };
+
+    stdout.write(await convertHtml(input.html, { url: input.url }));
+    return 0;
+  } catch (error) {
+    if (error instanceof BlocksEngineError) {
+      stderr.write(`${error.message}\n${error.hint}\n`);
+      return 1;
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    stderr.write(`${message}\n`);
+    return 1;
+  }
+}
+
+function realpathOrResolve(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+function isDirectInvocation(argv1: string | undefined): boolean {
+  return argv1 !== undefined && realpathOrResolve(argv1) === realpathOrResolve(fileURLToPath(import.meta.url));
+}
+
+if (isDirectInvocation(process.argv[1])) {
+  void runCli(process.argv.slice(2)).then((exitCode) => {
+    process.exitCode = exitCode;
+  });
+}
diff --git a/packages/blocks-engine/tsup.config.ts b/packages/blocks-engine/tsup.config.ts
index 0f803d7f..cd983a58 100644
--- a/packages/blocks-engine/tsup.config.ts
+++ b/packages/blocks-engine/tsup.config.ts
@@ -2,6 +2,7 @@ import { defineConfig } from 'tsup';
 
 export default defineConfig({
   entry: {
+    cli: 'src/cli.ts',
     index: 'src/index.ts',
     'internals/index': 'src/internals/index.ts',
     'wp/index': 'src/wp/index.ts',
diff --git a/packages/blocks-engine/vitest.config.ts b/packages/blocks-engine/vitest.config.ts
index 2dcea8c5..c5529dc0 100644
--- a/packages/blocks-engine/vitest.config.ts
+++ b/packages/blocks-engine/vitest.config.ts
@@ -4,5 +4,6 @@ export default defineConfig({
   test: {
     globals: false,
     environment: 'node',
+    testTimeout: 20_000,
   },
 });

From 051842a827aeeaa8b72ec599ff872ff62e03c1cd Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 11:30:46 -0400
Subject: [PATCH 030/113] docs(blocks-engine): freeze example contracts

---
 .../blocks-engine/examples/convert-one-liner.mjs |  6 ++++++
 packages/blocks-engine/examples/manifest.json    | 16 ++++++++++++++++
 2 files changed, 22 insertions(+)
 create mode 100644 packages/blocks-engine/examples/convert-one-liner.mjs
 create mode 100644 packages/blocks-engine/examples/manifest.json

diff --git a/packages/blocks-engine/examples/convert-one-liner.mjs b/packages/blocks-engine/examples/convert-one-liner.mjs
new file mode 100644
index 00000000..fcf8cdba
--- /dev/null
+++ b/packages/blocks-engine/examples/convert-one-liner.mjs
@@ -0,0 +1,6 @@
+import { convert } from '@automattic/blocks-engine';
+
+const html = '<h2>Hi</h2><p>Body</p>';
+const blockMarkup = await convert(html, { url: 'https://example.com/page.html' });
+
+console.log(blockMarkup);
diff --git a/packages/blocks-engine/examples/manifest.json b/packages/blocks-engine/examples/manifest.json
new file mode 100644
index 00000000..d3691b4c
--- /dev/null
+++ b/packages/blocks-engine/examples/manifest.json
@@ -0,0 +1,16 @@
+{
+  "examples": [
+    {
+      "file": "convert-one-liner.mjs",
+      "purpose": "README headline convert example"
+    },
+    {
+      "file": "compose-function-converter.mjs",
+      "purpose": "compose with a function converter"
+    },
+    {
+      "file": "worker-pool-batch.mjs",
+      "purpose": "createWorker batch conversion with events and explicit stop"
+    }
+  ]
+}

From ddafd5f3bbe8ab3da79c147a856f8cfd742c4b56 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 11:40:01 -0400
Subject: [PATCH 031/113] docs(blocks-engine): add package usage guide

---
 README.md                                     |   1 +
 packages/blocks-engine/README.md              | 119 ++++++++++++++++++
 .../examples/compose-function-converter.mjs   |  28 +++++
 .../examples/worker-pool-batch.mjs            |  35 ++++++
 .../src/__tests__/doc-accuracy.test.ts        |  94 ++++++++++++++
 5 files changed, 277 insertions(+)
 create mode 100644 packages/blocks-engine/README.md
 create mode 100644 packages/blocks-engine/examples/compose-function-converter.mjs
 create mode 100644 packages/blocks-engine/examples/worker-pool-batch.mjs
 create mode 100644 packages/blocks-engine/src/__tests__/doc-accuracy.test.ts

diff --git a/README.md b/README.md
index 15ccbc7b..b0782a11 100644
--- a/README.md
+++ b/README.md
@@ -4,4 +4,5 @@ Blocks Engine is a collection of tools for generating, transforming, and materia
 
 ## Packages
 
+- [`@automattic/blocks-engine`](packages/blocks-engine/) - JavaScript primitives for transforming content into WordPress-native block outputs.
 - [`php-transformer`](php-transformer/) - PHP primitives for converting HTML, Markdown, and generated website artifacts into WordPress-native block outputs.
diff --git a/packages/blocks-engine/README.md b/packages/blocks-engine/README.md
new file mode 100644
index 00000000..e12fadb1
--- /dev/null
+++ b/packages/blocks-engine/README.md
@@ -0,0 +1,119 @@
+# @automattic/blocks-engine
+
+Convert HTML into WordPress block markup from JavaScript or the command line.
+
+```js
+import { convert } from '@automattic/blocks-engine';
+
+const html = '<h2>Hi</h2><p>Body</p>';
+const blockMarkup = await convert(html, { url: 'https://example.com/page.html' });
+
+console.log(blockMarkup);
+```
+
+Emits:
+
+```html
+<!-- wp:heading -->
+<h2 class="wp-block-heading">Hi</h2>
+<!-- /wp:heading -->
+
+<!-- wp:paragraph -->
+<p>Body</p>
+<!-- /wp:paragraph -->
+```
+
+## Install Quickstart
+
+Install the package:
+
+```sh
+npm install @automattic/blocks-engine
+```
+
+Run a one-shot file conversion without adding a dependency:
+
+```sh
+npx @automattic/blocks-engine page.html
+```
+
+The CLI reads `page.html` and writes block markup to stdout. With no file argument, it reads HTML from stdin.
+
+## Start Here
+
+The root package export mirrors `src/index.ts`:
+
+- `convert`
+- `compose`
+- `createWorker`
+- `BlocksEngineError`
+- `ConvertOptions`
+- `BlocksEngineErrorOptions`
+- `ConversionContext`
+- `Converter`
+- `HtmlFallback`
+- `CreateWorker`
+- `FixResult`
+- `RawConvertResult`
+- `WorkerPool`
+- `WorkerPoolOptions`
+- `PoolEvent`
+
+Import runtime functions and classes normally, and import TypeScript shapes with `type`:
+
+```ts
+import {
+  BlocksEngineError,
+  compose,
+  convert,
+  createWorker,
+  type Converter,
+  type PoolEvent,
+  type WorkerPool,
+} from '@automattic/blocks-engine';
+```
+
+Advanced utilities that are not part of the headline path live under `@automattic/blocks-engine/internals`.
+
+## Which Do I Use?
+
+Use `convert` for the normal end-to-end path. It accepts HTML plus an optional conversion context, tries worker-backed conversion, falls back through composition when needed, canonicalizes the result, and returns WordPress block markup. If you do not pass a pool, `convert` creates one for the call and stops it before returning.
+
+Use `compose` when you want the pure, synchronous in-process composition layer directly. It is useful for custom `Converter` chains, custom `HtmlFallback` behavior, and tests or tools that already know they only need best-effort local HTML-to-block composition. It does not create, own, or stop a worker pool.
+
+Use `createWorker` when you are converting batches or running a long-lived process. Reuse one `WorkerPool` across calls instead of paying worker startup costs per item, and pass it into `convert` with `ConvertOptions.pool` when you want `convert` to use that shared pool.
+
+Use `BlocksEngineError` when catching package-level failures that include a stable `code` and user-facing `hint`.
+
+## Worker Pool Lifecycle
+
+`createWorker(options?)` returns a `WorkerPool` with `rawConvert(items)`, `canonicalize(items)`, and `stop()`. Treat the pool as an owned process resource.
+
+The default pool size is `min(cores, 4)`, with a minimum of one worker. Passing `WorkerPoolOptions.size` floors the value and still keeps at least one worker. For most request/response code, start with the default. For CI, deterministic tests, or memory-constrained jobs, prefer `size: 1` or another explicit small number.
+
+Workers are child processes connected to the parent over Node IPC. Create the pool in the parent process that will send work, and do not try to pass a live pool across process boundaries. Workers die with the parent process, but parent shutdown is not a deterministic cleanup API. Always call `await pool.stop()` in a `finally` block, test teardown, or service shutdown hook. The one-shot `convert` helper handles this for internally-created pools; shared pools are your responsibility.
+
+Use `recycleAfter` to replace a child after it has processed a configured number of items. The default is `0`, which disables recycling. Recycling is useful for long-running batches, CI isolation, and workloads where periodically refreshing child process state is safer than keeping one process alive indefinitely.
+
+Use `itemTimeoutMs` to bound how long one item can occupy a worker. The default is `10000`. On timeout or worker failure, the pool reroutes work until its reroute limit is reached; unresolved raw conversions return a `RawConvertResult` sentinel and unresolved canonicalization returns the original HTML in a `FixResult`.
+
+Use `onEvent` for operational visibility. The callback receives `PoolEvent` values for `child-spawn`, `child-crash`, `re-route`, `recycle`, `sentinel`, and `pool-degraded`, with `childId` and `count` when available. In CI, log these events when diagnosing flakes, timeouts, fork limits, or degraded worker startup.
+
+Build or run from an environment that can fork Node child processes and use IPC. For packaged or CI usage, run the package from its built distribution so the worker child file is present; source-mode execution depends on the local TypeScript runner setup.
+
+```ts
+const events: PoolEvent[] = [];
+const pool = createWorker({
+  size: 2,
+  recycleAfter: 100,
+  itemTimeoutMs: 15_000,
+  onEvent: (event) => events.push(event),
+});
+
+try {
+  const blockMarkup = await convert('<p>Hello</p>', { url: 'https://example.com/' }, { pool });
+  console.log(blockMarkup);
+} finally {
+  await pool.stop();
+}
+```
diff --git a/packages/blocks-engine/examples/compose-function-converter.mjs b/packages/blocks-engine/examples/compose-function-converter.mjs
new file mode 100644
index 00000000..bb2f11eb
--- /dev/null
+++ b/packages/blocks-engine/examples/compose-function-converter.mjs
@@ -0,0 +1,28 @@
+import { compose } from '@automattic/blocks-engine';
+
+const html = '<aside data-block="source-callout"><p>Ship smaller examples.</p></aside>';
+
+const calloutConverter = (sourceHtml, ctx) => {
+  if (!sourceHtml.includes('data-block="source-callout"')) {
+    return null;
+  }
+
+  const sourceHost = new URL(ctx.url).hostname;
+
+  return [
+    '<!-- wp:quote {"className":"source-callout"} -->',
+    '<blockquote class="wp-block-quote source-callout">',
+    '<p>Ship smaller examples.</p>',
+    `<cite>Imported from ${sourceHost}</cite>`,
+    '</blockquote>',
+    '<!-- /wp:quote -->',
+  ].join('\n');
+};
+
+const blockMarkup = compose(
+  html,
+  { url: 'https://example.com/source.html' },
+  { converters: [calloutConverter] },
+);
+
+console.log(blockMarkup);
diff --git a/packages/blocks-engine/examples/worker-pool-batch.mjs b/packages/blocks-engine/examples/worker-pool-batch.mjs
new file mode 100644
index 00000000..86cd21de
--- /dev/null
+++ b/packages/blocks-engine/examples/worker-pool-batch.mjs
@@ -0,0 +1,35 @@
+import { createWorker } from '@automattic/blocks-engine';
+
+const pages = [
+  '<h2>First page</h2><p>Converted in a worker.</p>',
+  '<h2>Second page</h2><p>Canonicalized as a batch.</p>',
+];
+
+function handlePoolEvent(event) {
+  const child = event.childId === undefined ? '' : ` child=${event.childId}`;
+  console.error(`[pool:${event.type}] count=${event.count}${child}`);
+}
+
+const pool = createWorker({
+  size: 2,
+  recycleAfter: 25,
+  itemTimeoutMs: 5_000,
+  onEvent: handlePoolEvent,
+});
+
+try {
+  const rawResults = await pool.rawConvert(pages);
+  const blockInputs = rawResults.map((result, index) => {
+    if (result.html !== null && result.wpHtmlResidue === 0) {
+      return result.html;
+    }
+
+    return `<!-- wp:html -->\n${pages[index]}\n<!-- /wp:html -->`;
+  });
+
+  const fixedResults = await pool.canonicalize(blockInputs);
+
+  console.log(fixedResults.map((result) => result.html).join('\n\n'));
+} finally {
+  await pool.stop();
+}
diff --git a/packages/blocks-engine/src/__tests__/doc-accuracy.test.ts b/packages/blocks-engine/src/__tests__/doc-accuracy.test.ts
new file mode 100644
index 00000000..824965d4
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/doc-accuracy.test.ts
@@ -0,0 +1,94 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+type ExampleManifest = {
+  examples: Array<{
+    file: string;
+  }>;
+};
+
+const packageDirUrl = new URL('../../', import.meta.url);
+const packageDir = fileURLToPath(packageDirUrl);
+const readmeUrl = new URL('README.md', packageDirUrl);
+const oneLinerUrl = new URL('examples/convert-one-liner.mjs', packageDirUrl);
+const manifestUrl = new URL('examples/manifest.json', packageDirUrl);
+
+function readRequiredFile(url: URL, label: string): string {
+  expect(existsSync(url), `${label} must exist`).toBe(true);
+  return readFileSync(url, 'utf8');
+}
+
+function normalizeLineEndings(value: string): string {
+  return value.replace(/\r\n/g, '\n');
+}
+
+function firstJavaScriptCodeBlock(markdown: string): string {
+  const match = normalizeLineEndings(markdown).match(
+    /```(?:javascript|js)\s*\n([\s\S]*?\n)```/,
+  );
+
+  expect(match, 'README must include a JavaScript code block').not.toBeNull();
+  return match?.[1] ?? '';
+}
+
+function firstHtmlCodeBlock(markdown: string): string {
+  const match = normalizeLineEndings(markdown).match(/```html\s*\n([\s\S]*?\n)```/);
+
+  expect(match, 'README must include an HTML output code block').not.toBeNull();
+  return match?.[1] ?? '';
+}
+
+function runFrozenOneLiner(): string {
+  return execFileSync(
+    process.execPath,
+    [
+      '--conditions=source',
+      '--import',
+      'tsx',
+      fileURLToPath(oneLinerUrl),
+    ],
+    {
+      cwd: packageDir,
+      encoding: 'utf8',
+    },
+  );
+}
+
+describe('documentation accuracy', () => {
+  it('keeps the headline README convert example locked to the frozen one-liner', () => {
+    const readme = readRequiredFile(readmeUrl, 'package README');
+    const frozenExample = normalizeLineEndings(
+      readRequiredFile(oneLinerUrl, 'convert-one-liner example'),
+    );
+
+    expect(firstJavaScriptCodeBlock(readme)).toBe(frozenExample);
+  });
+
+  it('runs the frozen one-liner through source exports and matches the shown output', () => {
+    const readme = readRequiredFile(readmeUrl, 'package README');
+    const stdout = runFrozenOneLiner();
+
+    expect(stdout).toContain('<!-- wp:heading -->');
+    expect(stdout).toContain('<!-- wp:paragraph -->');
+    expect(firstHtmlCodeBlock(readme)).toBe(stdout);
+  });
+
+  it('lists every required example script in the examples manifest', () => {
+    const manifest = JSON.parse(
+      readRequiredFile(manifestUrl, 'examples manifest'),
+    ) as ExampleManifest;
+    const files = manifest.examples.map((example) => example.file);
+
+    expect([...files].sort()).toEqual([
+      'compose-function-converter.mjs',
+      'convert-one-liner.mjs',
+      'worker-pool-batch.mjs',
+    ]);
+    for (const file of files) {
+      expect(existsSync(new URL(`examples/${file}`, packageDirUrl))).toBe(true);
+    }
+  });
+});

From 37fb6473dc97a196baea1f28b5716eb75ce721b8 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 11:52:58 -0400
Subject: [PATCH 032/113] feat(theme): freeze site-to-theme contracts

---
 packages/blocks-engine/package.json           |   6 +
 .../blocks-engine/src/theme/section-spec.ts   | 170 ++++++++++++++++++
 packages/blocks-engine/src/theme/types.ts     |  96 ++++++++++
 packages/blocks-engine/tsup.config.ts         |   1 +
 4 files changed, 273 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/section-spec.ts
 create mode 100644 packages/blocks-engine/src/theme/types.ts

diff --git a/packages/blocks-engine/package.json b/packages/blocks-engine/package.json
index 58a9eea9..fa03025b 100644
--- a/packages/blocks-engine/package.json
+++ b/packages/blocks-engine/package.json
@@ -16,6 +16,12 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./theme": {
+      "types": "./dist/theme/index.d.ts",
+      "source": "./src/theme/index.ts",
+      "import": "./dist/theme/index.js",
+      "require": "./dist/theme/index.cjs"
+    },
     "./wp": {
       "types": "./dist/wp/index.d.ts",
       "source": "./src/wp/index.ts",
diff --git a/packages/blocks-engine/src/theme/section-spec.ts b/packages/blocks-engine/src/theme/section-spec.ts
new file mode 100644
index 00000000..882018b8
--- /dev/null
+++ b/packages/blocks-engine/src/theme/section-spec.ts
@@ -0,0 +1,170 @@
+export type InteractionModel =
+  | 'static'
+  | 'cover-with-headline'
+  | 'animated-cover'
+  | 'media-text'
+  | 'columns'
+  | 'gallery'
+  | 'logo-strip'
+  | 'testimonial'
+  | 'cta'
+  | 'blog-card-grid'
+  | 'project-card-grid'
+  | 'price-list'
+  | 'product-card-row'
+  | 'review-grid'
+  | 'app-download'
+  | 'color-block-grid'
+  | 'marquee-strip'
+  | 'horizontal-showcase'
+  | 'footer'
+  | 'nav';
+
+export interface ExtractedReview {
+  category: string | null;
+  stars: number;
+  quote: string;
+  author: string | null;
+}
+
+export interface ExtractedFaq {
+  question: string;
+  answer: string;
+}
+
+export interface SectionSpecImage {
+  url: string;
+  sourceUrl: string;
+  alt: string;
+  kind: 'img' | 'background';
+  width: number;
+  height: number;
+}
+
+export interface SectionSpecIcon {
+  kind: 'svg' | 'glyph';
+  markup?: string;
+  glyph?: string;
+  fontFamily?: string;
+  width: number;
+  height: number;
+}
+
+export interface SectionSpecButton {
+  label: string;
+  href: string;
+  background?: string | null;
+  color?: string | null;
+  icon?: SectionSpecIcon | null;
+  iconAfter?: boolean;
+}
+
+export interface SectionSpecFormField {
+  kind:
+    | 'text'
+    | 'name'
+    | 'email'
+    | 'tel'
+    | 'url'
+    | 'number'
+    | 'date'
+    | 'checkbox'
+    | 'radio'
+    | 'select'
+    | 'textarea'
+    | 'file'
+    | 'hidden'
+    | 'consent';
+  label: string;
+  required: boolean;
+  placeholder?: string;
+  defaultValue?: string;
+  options?: string[];
+  widthPct?: 25 | 50 | 75 | 100;
+}
+
+export interface SectionSpecForm {
+  fields: SectionSpecFormField[];
+  submitLabel: string;
+}
+
+export interface SectionSpecCell {
+  heading: string | null;
+  body: string[];
+  image: SectionSpecImage | null;
+  icon: SectionSpecIcon | null;
+  button: string | null;
+  background?: string | null;
+  radius?: number;
+  headingSize?: number;
+  headingFamily?: string;
+  headingLineHeight?: number;
+  bodyFamily?: string;
+  bodyLineHeight?: number;
+  padding?: { top: number; right: number; bottom: number; left: number } | null;
+  align?: 'left' | 'center' | 'right';
+  iconAlign?: 'left' | 'center' | 'right';
+}
+
+export interface SectionSpecMotion {
+  motionClass:
+    | 'none'
+    | 'css-transition'
+    | 'css-keyframes'
+    | 'entry-reveal'
+    | 'marquee'
+    | 'carousel'
+    | 'parallax'
+    | 'video'
+    | 'lottie'
+    | 'scroll-triggered';
+  signals: string[];
+  animatedElements: number;
+}
+
+export interface SectionSpecLayout {
+  containerWidth: number;
+  padding: string;
+  childLayout: 'grid' | 'flex-row' | 'flex-column' | 'stack';
+  columnCount: number;
+  gap: string;
+  padTopPx?: number;
+  padBottomPx?: number;
+}
+
+export interface SectionSpec {
+  sectionIndex: number;
+  interactionModel: InteractionModel;
+  top: number;
+  height: number;
+  headings: string[];
+  headingSizes?: number[];
+  headingFamilies?: string[];
+  headingLineHeights?: number[];
+  textAlign?: 'left' | 'center' | 'right';
+  mediaLayout?: 'image-left' | 'image-right' | null;
+  fullBleed?: boolean;
+  selector?: string;
+  bodyText: string[];
+  bodyTextSizes?: number[];
+  bodyFamilies?: string[];
+  bodyLineHeights?: number[];
+  buttonLabels: string[];
+  buttons?: SectionSpecButton[];
+  images: SectionSpecImage[];
+  icons: SectionSpecIcon[];
+  backgroundBrightness: number;
+  backgroundColor: string;
+  gradient: string | null;
+  gradientSource: 'wrapper' | 'ancestor' | 'sibling' | 'pageBackground' | 'inherited' | null;
+  motionProfile: SectionSpecMotion;
+  dividerAbove: { color: string; thickness: number } | null;
+  dividerBelow: { color: string; thickness: number } | null;
+  layout: SectionSpecLayout;
+  reviews?: ExtractedReview[];
+  faqs?: ExtractedFaq[];
+  cells?: SectionSpecCell[];
+  forms?: SectionSpecForm[];
+  sectionHtml?: string;
+  styledHtml?: string;
+}
diff --git a/packages/blocks-engine/src/theme/types.ts b/packages/blocks-engine/src/theme/types.ts
new file mode 100644
index 00000000..a351f7e8
--- /dev/null
+++ b/packages/blocks-engine/src/theme/types.ts
@@ -0,0 +1,96 @@
+import type { WorkerPool } from '../pool/types.js';
+import type { SectionSpec } from './section-spec.js';
+
+export interface SiteModel {
+  root: string;
+  pages: SitePage[];
+}
+
+export interface SitePage {
+  relPath: string;
+  slug: string;
+  html: string;
+  title: string;
+  bodyData?: Record<string, string>;
+}
+
+export interface FoundationTokens {
+  palette: { name: string; color: string }[];
+  typography: { body?: string; display?: string };
+  breakpoints: { md?: string; lg?: string; xl?: string };
+}
+
+export interface FoundationAggregates {
+  palette?: unknown;
+  typography?: unknown;
+  breakpoints?: unknown;
+}
+
+export interface AssetFile {
+  relPath: string;
+  bytes?: Uint8Array;
+  sourcePath?: string;
+}
+
+export interface ThemeModel {
+  styleCss: string;
+  themeJson: Record<string, unknown>;
+  templates: Record<string, string>;
+  parts: Record<string, string>;
+  patterns: Record<string, string>;
+  assets: AssetFile[];
+}
+
+export interface SectionBlocks {
+  spec: SectionSpec;
+  blocks: string;
+  coverage: number;
+}
+
+export interface AssetInventory {
+  assets: AssetFile[];
+}
+
+export interface AssetVerdicts {
+  keep: string[];
+  decoration: string[];
+}
+
+export interface StageCtx {
+  srcDir: string;
+  site: SiteModel;
+  themeMeta: ThemeMeta;
+  warn(msg: string): void;
+}
+
+export interface ThemeMeta {
+  name: string;
+  slug: string;
+  author?: string;
+}
+
+export interface SiteToThemeHooks {
+  onFoundation?(tokens: FoundationTokens, ctx: StageCtx): Promise<FoundationTokens>;
+  onSection?(section: SectionBlocks, ctx: StageCtx): Promise<SectionBlocks>;
+  onAssets?(inventory: AssetInventory, ctx: StageCtx): Promise<AssetVerdicts>;
+  onRefine?(theme: ThemeModel, ctx: StageCtx): Promise<ThemeModel>;
+}
+
+export interface SiteToThemeOptions {
+  outDir?: string;
+  pool?: WorkerPool;
+  sections?: Record<string, SectionSpec[]>;
+  foundationAggregates?: FoundationAggregates;
+  hooks?: SiteToThemeHooks;
+  fetchImpl?: typeof fetch;
+  coverageFloor?: number;
+  themeMeta?: Partial<ThemeMeta>;
+}
+
+export interface ThemeBuildResult {
+  outDir: string;
+  model: ThemeModel;
+  written: string[];
+  tallies: Record<string, number>;
+  warnings: string[];
+}
diff --git a/packages/blocks-engine/tsup.config.ts b/packages/blocks-engine/tsup.config.ts
index cd983a58..d3cba60f 100644
--- a/packages/blocks-engine/tsup.config.ts
+++ b/packages/blocks-engine/tsup.config.ts
@@ -5,6 +5,7 @@ export default defineConfig({
     cli: 'src/cli.ts',
     index: 'src/index.ts',
     'internals/index': 'src/internals/index.ts',
+    'theme/index': 'src/theme/index.ts',
     'wp/index': 'src/wp/index.ts',
     'wp/worker-child': 'src/wp/worker-child.ts',
   },

From bf3db753a3c770bd0176f316e0712c2ca2c1de1a Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 12:03:11 -0400
Subject: [PATCH 033/113] feat(theme): add site-to-theme stub exports

---
 .../src/__tests__/convert.test.ts             |   4 +
 .../src/__tests__/exports-shape.test.ts       |   9 +
 .../src/__tests__/theme-contracts.test.ts     | 316 ++++++++++++++++++
 packages/blocks-engine/src/index.ts           |   2 +
 packages/blocks-engine/src/theme/index.ts     |  12 +
 packages/blocks-engine/src/theme/stages.ts    |  82 +++++
 6 files changed, 425 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-contracts.test.ts
 create mode 100644 packages/blocks-engine/src/theme/index.ts
 create mode 100644 packages/blocks-engine/src/theme/stages.ts

diff --git a/packages/blocks-engine/src/__tests__/convert.test.ts b/packages/blocks-engine/src/__tests__/convert.test.ts
index feab7326..293af069 100644
--- a/packages/blocks-engine/src/__tests__/convert.test.ts
+++ b/packages/blocks-engine/src/__tests__/convert.test.ts
@@ -157,6 +157,8 @@ describe('default entry', () => {
       'compose',
       'convert',
       'createWorker',
+      'siteToTheme',
+      'writeTheme',
     ].sort();
     const demotedRuntimeSymbols = [
       'PIPELINE_ISLAND_NAME',
@@ -187,6 +189,8 @@ describe('default entry', () => {
     expect(typeof defaultEntry.compose).toBe('function');
     expect(typeof defaultEntry.BlocksEngineError).toBe('function');
     expect(typeof defaultEntry.createWorker).toBe('function');
+    expect(typeof defaultEntry.siteToTheme).toBe('function');
+    expect(typeof defaultEntry.writeTheme).toBe('function');
 
     for (const symbol of demotedRuntimeSymbols) {
       expect(defaultEntry).not.toHaveProperty(symbol);
diff --git a/packages/blocks-engine/src/__tests__/exports-shape.test.ts b/packages/blocks-engine/src/__tests__/exports-shape.test.ts
index ef1523c2..84802a89 100644
--- a/packages/blocks-engine/src/__tests__/exports-shape.test.ts
+++ b/packages/blocks-engine/src/__tests__/exports-shape.test.ts
@@ -30,6 +30,15 @@ describe('package exports', () => {
     expect(exports['.'].import).not.toContain('/src/');
     expect(exports['.'].types).not.toContain('/src/');
 
+    expect(exports['./theme']).toEqual({
+      types: './dist/theme/index.d.ts',
+      source: './src/theme/index.ts',
+      import: './dist/theme/index.js',
+      require: './dist/theme/index.cjs',
+    });
+    expect(exports['./theme'].import).not.toContain('/src/');
+    expect(exports['./theme'].types).not.toContain('/src/');
+
     expect(exports['./wp']).toEqual({
       import: './dist/wp/index.js',
       require: './dist/wp/index.cjs',
diff --git a/packages/blocks-engine/src/__tests__/theme-contracts.test.ts b/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
new file mode 100644
index 00000000..517d65f7
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
@@ -0,0 +1,316 @@
+import { describe, expect, it } from 'vitest';
+import type { WorkerPool } from '../pool/types.js';
+import {
+  assemble,
+  foundation,
+  ingest,
+  reconstruct,
+  sectionExtract,
+  siteToTheme,
+  writeTheme,
+  type AssetFile,
+  type AssetInventory,
+  type AssetVerdicts,
+  type FoundationAggregates,
+  type FoundationTokens,
+  type SectionBlocks,
+  type SectionSpec,
+  type SectionSpecButton,
+  type SectionSpecCell,
+  type SectionSpecForm,
+  type SectionSpecFormField,
+  type SectionSpecIcon,
+  type SectionSpecImage,
+  type SectionSpecLayout,
+  type SectionSpecMotion,
+  type SiteModel,
+  type SitePage,
+  type SiteToThemeHooks,
+  type SiteToThemeOptions,
+  type StageCtx,
+  type ThemeBuildResult,
+  type ThemeMeta,
+  type ThemeModel,
+} from '../theme/index.js';
+
+type Satisfies<T, U extends T> = U;
+
+type ThemeStageSignatures = {
+  siteToTheme: (srcDir: string, options?: SiteToThemeOptions) => Promise<ThemeBuildResult>;
+  writeTheme: (model: ThemeModel, outDir: string) => Promise<string[]>;
+  ingest: (srcDir: string) => SiteModel;
+  sectionExtract: (page: SitePage) => SectionSpec[];
+  foundation: (site: SiteModel, aggregates?: FoundationAggregates) => FoundationTokens;
+  reconstruct: (
+    specs: SectionSpec[],
+    ctx: StageCtx,
+    pool: WorkerPool,
+    hooks: SiteToThemeHooks,
+    coverageFloor: number
+  ) => Promise<SectionBlocks[]>;
+  assemble: (parts: {
+    site: SiteModel;
+    tokens: FoundationTokens;
+    pages: Record<string, SectionBlocks[]>;
+    meta: ThemeMeta;
+  }) => ThemeModel;
+};
+
+const themeStageSignatures: ThemeStageSignatures = {
+  siteToTheme,
+  writeTheme,
+  ingest,
+  sectionExtract,
+  foundation,
+  reconstruct,
+  assemble,
+};
+
+void themeStageSignatures;
+
+type CompileOnlyThemeContractAssignments = {
+  siteModel: Satisfies<
+    SiteModel,
+    {
+      root: string;
+      pages: SitePage[];
+    }
+  >;
+  sitePage: Satisfies<
+    SitePage,
+    {
+      relPath: string;
+      slug: string;
+      html: string;
+      title: string;
+      bodyData: Record<string, string>;
+    }
+  >;
+  sectionSpecImage: Satisfies<
+    SectionSpecImage,
+    {
+      url: string;
+      sourceUrl: string;
+      alt: string;
+      kind: 'img';
+      width: number;
+      height: number;
+    }
+  >;
+  sectionSpecIcon: Satisfies<
+    SectionSpecIcon,
+    {
+      kind: 'glyph';
+      glyph: string;
+      width: number;
+      height: number;
+    }
+  >;
+  sectionSpecButton: Satisfies<
+    SectionSpecButton,
+    {
+      label: string;
+      href: string;
+      background: string | null;
+      color: string | null;
+      icon: SectionSpecIcon | null;
+      iconAfter: boolean;
+    }
+  >;
+  sectionSpecFormField: Satisfies<
+    SectionSpecFormField,
+    {
+      kind: 'email';
+      label: string;
+      required: boolean;
+      placeholder: string;
+      defaultValue: string;
+      options: string[];
+      widthPct: 100;
+    }
+  >;
+  sectionSpecForm: Satisfies<
+    SectionSpecForm,
+    {
+      fields: SectionSpecFormField[];
+      submitLabel: string;
+    }
+  >;
+  sectionSpecCell: Satisfies<
+    SectionSpecCell,
+    {
+      heading: string | null;
+      body: string[];
+      image: SectionSpecImage | null;
+      icon: SectionSpecIcon | null;
+      button: string | null;
+    }
+  >;
+  sectionSpecMotion: Satisfies<
+    SectionSpecMotion,
+    {
+      motionClass: 'none';
+      signals: string[];
+      animatedElements: number;
+    }
+  >;
+  sectionSpecLayout: Satisfies<
+    SectionSpecLayout,
+    {
+      containerWidth: number;
+      padding: string;
+      childLayout: 'stack';
+      columnCount: number;
+      gap: string;
+    }
+  >;
+  sectionSpec: Satisfies<
+    SectionSpec,
+    {
+      sectionIndex: number;
+      interactionModel: 'static';
+      top: number;
+      height: number;
+      headings: string[];
+      bodyText: string[];
+      buttonLabels: string[];
+      images: SectionSpecImage[];
+      icons: SectionSpecIcon[];
+      backgroundBrightness: number;
+      backgroundColor: string;
+      gradient: string | null;
+      gradientSource: null;
+      motionProfile: SectionSpecMotion;
+      dividerAbove: { color: string; thickness: number } | null;
+      dividerBelow: { color: string; thickness: number } | null;
+      layout: SectionSpecLayout;
+      cells: SectionSpecCell[];
+      forms: SectionSpecForm[];
+    }
+  >;
+  foundationTokens: Satisfies<
+    FoundationTokens,
+    {
+      palette: { name: string; color: string }[];
+      typography: { body: string; display: string };
+      breakpoints: { md: string; lg: string; xl: string };
+    }
+  >;
+  foundationAggregates: Satisfies<
+    FoundationAggregates,
+    {
+      palette: unknown;
+      typography: unknown;
+      breakpoints: unknown;
+    }
+  >;
+  assetFile: Satisfies<
+    AssetFile,
+    {
+      relPath: string;
+      bytes: Uint8Array;
+      sourcePath: string;
+    }
+  >;
+  themeModel: Satisfies<
+    ThemeModel,
+    {
+      styleCss: string;
+      themeJson: Record<string, unknown>;
+      templates: Record<string, string>;
+      parts: Record<string, string>;
+      patterns: Record<string, string>;
+      assets: AssetFile[];
+    }
+  >;
+  sectionBlocks: Satisfies<
+    SectionBlocks,
+    {
+      spec: SectionSpec;
+      blocks: string;
+      coverage: number;
+    }
+  >;
+  assetInventory: Satisfies<
+    AssetInventory,
+    {
+      assets: AssetFile[];
+    }
+  >;
+  assetVerdicts: Satisfies<
+    AssetVerdicts,
+    {
+      keep: string[];
+      decoration: string[];
+    }
+  >;
+  stageCtx: Satisfies<
+    StageCtx,
+    {
+      srcDir: string;
+      site: SiteModel;
+      themeMeta: ThemeMeta;
+      warn(msg: string): void;
+    }
+  >;
+  themeMeta: Satisfies<
+    ThemeMeta,
+    {
+      name: string;
+      slug: string;
+      author: string;
+    }
+  >;
+  siteToThemeHooks: Satisfies<
+    SiteToThemeHooks,
+    {
+      onFoundation(tokens: FoundationTokens, ctx: StageCtx): Promise<FoundationTokens>;
+      onSection(section: SectionBlocks, ctx: StageCtx): Promise<SectionBlocks>;
+      onAssets(inventory: AssetInventory, ctx: StageCtx): Promise<AssetVerdicts>;
+      onRefine(theme: ThemeModel, ctx: StageCtx): Promise<ThemeModel>;
+    }
+  >;
+  siteToThemeOptions: Satisfies<
+    SiteToThemeOptions,
+    {
+      outDir: string;
+      sections: Record<string, SectionSpec[]>;
+      foundationAggregates: FoundationAggregates;
+      hooks: SiteToThemeHooks;
+      fetchImpl: typeof fetch;
+      coverageFloor: number;
+      themeMeta: Partial<ThemeMeta>;
+    }
+  >;
+  themeBuildResult: Satisfies<
+    ThemeBuildResult,
+    {
+      outDir: string;
+      model: ThemeModel;
+      written: string[];
+      tallies: Record<string, number>;
+      warnings: string[];
+    }
+  >;
+};
+
+void (null as never as CompileOnlyThemeContractAssignments);
+
+describe('theme public contract', () => {
+  it('exports runtime stage functions with fixed arity', () => {
+    const runtimeStages = [
+      [siteToTheme, 2],
+      [writeTheme, 2],
+      [ingest, 1],
+      [sectionExtract, 1],
+      [foundation, 2],
+      [reconstruct, 5],
+      [assemble, 1],
+    ] as const;
+
+    for (const [stage, expectedArity] of runtimeStages) {
+      expect(stage).toBeTypeOf('function');
+      expect(stage).toHaveLength(expectedArity);
+    }
+  });
+});
diff --git a/packages/blocks-engine/src/index.ts b/packages/blocks-engine/src/index.ts
index 3e33ee78..0bd963a9 100644
--- a/packages/blocks-engine/src/index.ts
+++ b/packages/blocks-engine/src/index.ts
@@ -2,9 +2,11 @@ export { convert } from './convert.js';
 export { compose } from './compose.js';
 export { createWorker } from './pool/pool.js';
 export { BlocksEngineError } from './errors.js';
+export { siteToTheme, writeTheme } from './theme/index.js';
 
 export type { ConvertOptions } from './convert.js';
 export type { BlocksEngineErrorOptions } from './errors.js';
+export type { SiteToThemeOptions, ThemeBuildResult } from './theme/index.js';
 export type { ConversionContext, Converter, HtmlFallback } from './types.js';
 export type {
   CreateWorker,
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
new file mode 100644
index 00000000..c7c3363b
--- /dev/null
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -0,0 +1,12 @@
+export {
+  assemble,
+  foundation,
+  ingest,
+  reconstruct,
+  sectionExtract,
+  siteToTheme,
+  writeTheme,
+} from './stages.js';
+
+export type * from './section-spec.js';
+export type * from './types.js';
diff --git a/packages/blocks-engine/src/theme/stages.ts b/packages/blocks-engine/src/theme/stages.ts
new file mode 100644
index 00000000..c594c8aa
--- /dev/null
+++ b/packages/blocks-engine/src/theme/stages.ts
@@ -0,0 +1,82 @@
+import { BlocksEngineError } from '../errors.js';
+import type { WorkerPool } from '../pool/types.js';
+import type { SectionSpec } from './section-spec.js';
+import type {
+  FoundationAggregates,
+  FoundationTokens,
+  SectionBlocks,
+  SiteModel,
+  SitePage,
+  SiteToThemeHooks,
+  SiteToThemeOptions,
+  StageCtx,
+  ThemeBuildResult,
+  ThemeMeta,
+  ThemeModel,
+} from './types.js';
+
+export function siteToTheme(
+  srcDir: string,
+  options?: SiteToThemeOptions
+): Promise<ThemeBuildResult> {
+  throw new BlocksEngineError('not implemented', {
+    code: 'STAGE_STUB',
+    hint: 'Phase 0 skeleton',
+  });
+}
+
+export function writeTheme(model: ThemeModel, outDir: string): Promise<string[]> {
+  throw new BlocksEngineError('not implemented', {
+    code: 'STAGE_STUB',
+    hint: 'Phase 0 skeleton',
+  });
+}
+
+export function ingest(srcDir: string): SiteModel {
+  throw new BlocksEngineError('not implemented', {
+    code: 'STAGE_STUB',
+    hint: 'Phase 0 skeleton',
+  });
+}
+
+export function sectionExtract(page: SitePage): SectionSpec[] {
+  throw new BlocksEngineError('not implemented', {
+    code: 'STAGE_STUB',
+    hint: 'Phase 0 skeleton',
+  });
+}
+
+export function foundation(
+  site: SiteModel,
+  aggregates?: FoundationAggregates
+): FoundationTokens {
+  throw new BlocksEngineError('not implemented', {
+    code: 'STAGE_STUB',
+    hint: 'Phase 0 skeleton',
+  });
+}
+
+export function reconstruct(
+  specs: SectionSpec[],
+  ctx: StageCtx,
+  pool: WorkerPool,
+  hooks: SiteToThemeHooks,
+  coverageFloor: number
+): Promise<SectionBlocks[]> {
+  throw new BlocksEngineError('not implemented', {
+    code: 'STAGE_STUB',
+    hint: 'Phase 0 skeleton',
+  });
+}
+
+export function assemble(parts: {
+  site: SiteModel;
+  tokens: FoundationTokens;
+  pages: Record<string, SectionBlocks[]>;
+  meta: ThemeMeta;
+}): ThemeModel {
+  throw new BlocksEngineError('not implemented', {
+    code: 'STAGE_STUB',
+    hint: 'Phase 0 skeleton',
+  });
+}

From f2c546794f6f4c661ab9c1bd3bdc6ef950ad2767 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 12:09:34 -0400
Subject: [PATCH 034/113] test(theme): freeze P0-2 ingest contracts

---
 .../src/__tests__/fixtures/site/about.html    | 16 ++++++++++
 .../src/__tests__/fixtures/site/index.html    | 31 +++++++++++++++++++
 .../src/__tests__/fixtures/site/style.css     | 12 +++++++
 .../__tests__/theme-p0-2-contracts.test.ts    | 25 +++++++++++++++
 packages/blocks-engine/src/theme/index.ts     |  4 +--
 packages/blocks-engine/src/theme/ingest.ts    | 16 ++++++++++
 .../src/theme/section-extract.ts              | 10 ++++++
 7 files changed, 112 insertions(+), 2 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/fixtures/site/about.html
 create mode 100644 packages/blocks-engine/src/__tests__/fixtures/site/index.html
 create mode 100644 packages/blocks-engine/src/__tests__/fixtures/site/style.css
 create mode 100644 packages/blocks-engine/src/__tests__/theme-p0-2-contracts.test.ts
 create mode 100644 packages/blocks-engine/src/theme/ingest.ts
 create mode 100644 packages/blocks-engine/src/theme/section-extract.ts

diff --git a/packages/blocks-engine/src/__tests__/fixtures/site/about.html b/packages/blocks-engine/src/__tests__/fixtures/site/about.html
new file mode 100644
index 00000000..a16ca932
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/fixtures/site/about.html
@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>About</title>
+    <link rel="stylesheet" href="./style.css" />
+  </head>
+  <body data-page="about">
+    <main>
+      <article>
+        <h1>About the assembler</h1>
+        <p>The first browser-free pass extracts stable page sections.</p>
+      </article>
+    </main>
+  </body>
+</html>
diff --git a/packages/blocks-engine/src/__tests__/fixtures/site/index.html b/packages/blocks-engine/src/__tests__/fixtures/site/index.html
new file mode 100644
index 00000000..df1d7ec0
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/fixtures/site/index.html
@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Home</title>
+    <link rel="stylesheet" href="./style.css" />
+  </head>
+  <body data-page="home" data-template="front">
+    <header>
+      <nav aria-label="Primary">
+        <a href="./index.html">Home</a>
+        <a href="./about.html">About</a>
+      </nav>
+    </header>
+    <main>
+      <section id="hero">
+        <h1>Build calmer block themes</h1>
+        <p>Static source pages become a structured theme pipeline.</p>
+        <a class="button" href="./about.html">Learn more</a>
+      </section>
+      <section id="empty"></section>
+      <section aria-labelledby="features-title">
+        <h2 id="features-title">What carries forward</h2>
+        <p>Headings, body copy, selectors, and simple calls to action.</p>
+      </section>
+    </main>
+    <footer>
+      <p>Blocks Engine</p>
+    </footer>
+  </body>
+</html>
diff --git a/packages/blocks-engine/src/__tests__/fixtures/site/style.css b/packages/blocks-engine/src/__tests__/fixtures/site/style.css
new file mode 100644
index 00000000..6f5bfdf9
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/fixtures/site/style.css
@@ -0,0 +1,12 @@
+body {
+  font-family: system-ui, sans-serif;
+  margin: 0;
+}
+
+main {
+  display: block;
+}
+
+.button {
+  display: inline-block;
+}
diff --git a/packages/blocks-engine/src/__tests__/theme-p0-2-contracts.test.ts b/packages/blocks-engine/src/__tests__/theme-p0-2-contracts.test.ts
new file mode 100644
index 00000000..8f9aebb0
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-p0-2-contracts.test.ts
@@ -0,0 +1,25 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { slugFromRelPath } from '../theme/ingest.js';
+import { sectionExtract } from '../theme/section-extract.js';
+import { ingest } from '../theme/index.js';
+
+const fixtureRoot = join(import.meta.dirname, 'fixtures/site');
+
+describe('theme P0-2 path and fixture contracts', () => {
+  it('freezes the ingest and section extraction module paths', () => {
+    expect(ingest).toBeTypeOf('function');
+    expect(ingest).toHaveLength(1);
+    expect(slugFromRelPath).toBeTypeOf('function');
+    expect(slugFromRelPath).toHaveLength(1);
+    expect(sectionExtract).toBeTypeOf('function');
+    expect(sectionExtract).toHaveLength(1);
+  });
+
+  it('freezes the static site fixture layout', () => {
+    expect(existsSync(join(fixtureRoot, 'index.html'))).toBe(true);
+    expect(existsSync(join(fixtureRoot, 'about.html'))).toBe(true);
+    expect(existsSync(join(fixtureRoot, 'style.css'))).toBe(true);
+  });
+});
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index c7c3363b..89315a11 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -1,12 +1,12 @@
 export {
   assemble,
   foundation,
-  ingest,
   reconstruct,
-  sectionExtract,
   siteToTheme,
   writeTheme,
 } from './stages.js';
+export { ingest } from './ingest.js';
+export { sectionExtract } from './section-extract.js';
 
 export type * from './section-spec.js';
 export type * from './types.js';
diff --git a/packages/blocks-engine/src/theme/ingest.ts b/packages/blocks-engine/src/theme/ingest.ts
new file mode 100644
index 00000000..64db86b8
--- /dev/null
+++ b/packages/blocks-engine/src/theme/ingest.ts
@@ -0,0 +1,16 @@
+import { BlocksEngineError } from '../errors.js';
+import type { SiteModel } from './types.js';
+
+export function slugFromRelPath(relPath: string): string {
+  throw new BlocksEngineError('not implemented', {
+    code: 'STAGE_STUB',
+    hint: 'Phase 0 skeleton',
+  });
+}
+
+export function ingest(srcDir: string): SiteModel {
+  throw new BlocksEngineError('not implemented', {
+    code: 'STAGE_STUB',
+    hint: 'Phase 0 skeleton',
+  });
+}
diff --git a/packages/blocks-engine/src/theme/section-extract.ts b/packages/blocks-engine/src/theme/section-extract.ts
new file mode 100644
index 00000000..de58189e
--- /dev/null
+++ b/packages/blocks-engine/src/theme/section-extract.ts
@@ -0,0 +1,10 @@
+import { BlocksEngineError } from '../errors.js';
+import type { SectionSpec } from './section-spec.js';
+import type { SitePage } from './types.js';
+
+export function sectionExtract(page: SitePage): SectionSpec[] {
+  throw new BlocksEngineError('not implemented', {
+    code: 'STAGE_STUB',
+    hint: 'Phase 0 skeleton',
+  });
+}

From 20992fee0e68eacd9fa14a883d1b4ae790fecf50 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 12:23:08 -0400
Subject: [PATCH 035/113] feat(theme): implement browser-free P0-2 extraction

---
 .../src/__tests__/theme-ingest.test.ts        | 107 +++++
 .../__tests__/theme-section-extract.test.ts   | 160 +++++++
 packages/blocks-engine/src/theme/ingest.ts    |  90 +++-
 .../src/theme/section-extract.ts              | 398 +++++++++++++++++-
 4 files changed, 742 insertions(+), 13 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-ingest.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/theme-section-extract.test.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-ingest.test.ts b/packages/blocks-engine/src/__tests__/theme-ingest.test.ts
new file mode 100644
index 00000000..0c4ef491
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-ingest.test.ts
@@ -0,0 +1,107 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { BlocksEngineError } from '../errors.js';
+import { ingest, slugFromRelPath } from '../theme/ingest.js';
+
+const fixtureRoot = join(import.meta.dirname, 'fixtures/site');
+
+function withTempDir<T>(fn: (dir: string) => T): T {
+  const dir = mkdtempSync(join(tmpdir(), 'blocks-engine-theme-ingest-'));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function writeHtml(path: string, title: string): void {
+  writeFileSync(
+    path,
+    `<!doctype html><html><head><title>${title}</title></head><body data-page="${title.toLowerCase()}"></body></html>`,
+    'utf8'
+  );
+}
+
+describe('theme ingest', () => {
+  it('ingests fixture index and about pages with stable slugs and body data', () => {
+    const site = ingest(fixtureRoot);
+
+    expect(site.root).toBe(fixtureRoot);
+    expect(site.pages.map((page) => page.slug)).toEqual(['about', 'home']);
+
+    const home = site.pages.find((page) => page.slug === 'home');
+    const about = site.pages.find((page) => page.slug === 'about');
+
+    expect(home).toMatchObject({
+      relPath: 'index.html',
+      title: 'Home',
+      bodyData: {
+        page: 'home',
+        template: 'front',
+      },
+    });
+    expect(home?.html).toContain('Build calmer block themes');
+
+    expect(about).toMatchObject({
+      relPath: 'about.html',
+      title: 'About',
+      bodyData: {
+        page: 'about',
+      },
+    });
+  });
+
+  it('maps nested paths to DLA-compatible slugs', () => {
+    expect(slugFromRelPath(join('index.html'))).toBe('home');
+    expect(slugFromRelPath(join('blog', 'index.html'))).toBe('blog');
+    expect(slugFromRelPath(join('blog', 'Launch Notes.html'))).toBe('blog-launch-notes');
+    expect(slugFromRelPath(join('shop', '2026', 'index.htm'))).toBe('shop-2026');
+    expect(slugFromRelPath(join('###.html'))).toBe('home');
+  });
+
+  it('throws BlocksEngineError on duplicate slug collisions', () => {
+    withTempDir((dir) => {
+      mkdirSync(join(dir, 'blog'));
+      writeHtml(join(dir, 'blog', 'p.html'), 'Nested');
+      writeHtml(join(dir, 'blog-p.html'), 'Flat');
+
+      let error: unknown;
+      try {
+        ingest(dir);
+      } catch (caught) {
+        error = caught;
+      }
+
+      expect(error).toBeInstanceOf(BlocksEngineError);
+      expect(error).toMatchObject({
+        code: 'THEME_INGEST_DUPLICATE_SLUG',
+      });
+      expect((error as Error).message).toContain('slug collision: "blog-p"');
+    });
+  });
+
+  it('throws BlocksEngineError when no eligible html pages are found', () => {
+    withTempDir((dir) => {
+      writeFileSync(join(dir, 'readme.txt'), 'not html', 'utf8');
+      mkdirSync(join(dir, '.hidden'));
+      writeHtml(join(dir, '.hidden', 'index.html'), 'Hidden');
+      mkdirSync(join(dir, 'node_modules'));
+      writeHtml(join(dir, 'node_modules', 'index.html'), 'Dependency');
+
+      let error: unknown;
+      try {
+        ingest(dir);
+      } catch (caught) {
+        error = caught;
+      }
+
+      expect(error).toBeInstanceOf(BlocksEngineError);
+      expect(error).toMatchObject({
+        code: 'THEME_INGEST_NO_HTML',
+      });
+      expect((error as Error).message).toContain(`no html pages found under ${dir}`);
+    });
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/theme-section-extract.test.ts b/packages/blocks-engine/src/__tests__/theme-section-extract.test.ts
new file mode 100644
index 00000000..fc1d089a
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-section-extract.test.ts
@@ -0,0 +1,160 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+import { sectionExtract } from '../theme/section-extract.js';
+import type { SitePage } from '../theme/types.js';
+
+const testDir = dirname(fileURLToPath(import.meta.url));
+const fixturesDir = join(testDir, 'fixtures/site');
+
+function pageWithHtml(html: string): SitePage {
+  return {
+    relPath: 'index.html',
+    slug: 'index',
+    title: 'Test',
+    html,
+  };
+}
+
+describe('sectionExtract', () => {
+  it('extracts contentful sections from the fixture page', () => {
+    const sections = sectionExtract(
+      pageWithHtml(readFileSync(join(fixturesDir, 'index.html'), 'utf8'))
+    );
+
+    expect(sections.length).toBeGreaterThanOrEqual(1);
+    expect(sections.every((section) => section.selector)).toBe(true);
+    expect(sections.map((section) => section.selector)).not.toContain('#empty');
+    expect(sections).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          selector: '#hero',
+          headings: ['Build calmer block themes'],
+          bodyText: ['Static source pages become a structured theme pipeline.'],
+          buttonLabels: ['Learn more'],
+          sectionHtml: expect.stringContaining('Build calmer block themes'),
+        }),
+        expect.objectContaining({
+          selector: 'section[aria-labelledby="features-title"]',
+          headings: ['What carries forward'],
+          bodyText: ['Headings, body copy, selectors, and simple calls to action.'],
+        }),
+      ])
+    );
+  });
+
+  it('omits empty candidate sections', () => {
+    const sections = sectionExtract(
+      pageWithHtml(`
+        <main>
+          <section id="empty"></section>
+          <section id="content"><h2>Useful section</h2><p>Recognizable copy.</p></section>
+        </main>
+      `)
+    );
+
+    expect(sections).toHaveLength(1);
+    expect(sections[0]).toMatchObject({
+      selector: '#content',
+      headings: ['Useful section'],
+      bodyText: ['Recognizable copy.'],
+    });
+  });
+
+  it('segments semantic landmarks and heading bands with stable selectors', () => {
+    const sections = sectionExtract(
+      pageWithHtml(`
+        <body>
+          <header><nav aria-label="Primary"><a href="/">Home</a><a href="/about">About</a></nav></header>
+          <main>
+            <h1>Opening band</h1>
+            <p>Introductory body.</p>
+            <h2>Second band</h2>
+            <p>Follow-up body.</p>
+          </main>
+          <aside role="complementary"><h2>Related</h2><a href="/guide">Guide</a></aside>
+          <footer><p>Footer copy</p></footer>
+        </body>
+      `)
+    );
+
+    expect(sections.map((section) => section.selector)).toEqual([
+      'nav[aria-label="Primary"]',
+      'main > h1:nth-of-type(1)',
+      'main > h2:nth-of-type(1)',
+      'aside[role="complementary"]',
+      'footer',
+    ]);
+    expect(sections.map((section) => section.interactionModel)).toEqual([
+      'nav',
+      'static',
+      'static',
+      'static',
+      'footer',
+    ]);
+    expect(sections[1]).toMatchObject({
+      headings: ['Opening band'],
+      bodyText: ['Introductory body.'],
+    });
+    expect(sections[2]).toMatchObject({
+      headings: ['Second band'],
+      bodyText: ['Follow-up body.'],
+    });
+  });
+
+  it('keeps explicit sections that follow heading bands in the same container', () => {
+    const sections = sectionExtract(
+      pageWithHtml(`
+        <main>
+          <h1>Opening band</h1>
+          <p>Introductory body.</p>
+          <section id="later"><h2>Later section</h2><p>Section body.</p></section>
+        </main>
+      `)
+    );
+
+    expect(sections.map((section) => section.selector)).toEqual([
+      'main > h1:nth-of-type(1)',
+      '#later',
+    ]);
+    expect(sections[1]).toMatchObject({
+      headings: ['Later section'],
+      bodyText: ['Section body.'],
+    });
+  });
+
+  it('keeps recognizable text from common div and span containers', () => {
+    const sections = sectionExtract(
+      pageWithHtml(`
+        <main>
+          <section id="div-copy"><div>Plain div copy.</div></section>
+          <section id="span-copy"><span>Plain span copy.</span></section>
+        </main>
+      `)
+    );
+
+    expect(sections).toEqual([
+      expect.objectContaining({
+        selector: '#div-copy',
+        bodyText: ['Plain div copy.'],
+      }),
+      expect.objectContaining({
+        selector: '#span-copy',
+        bodyText: ['Plain span copy.'],
+      }),
+    ]);
+  });
+
+  it('does not import browser runtimes in the P0-2 stage implementations', () => {
+    const source = [
+      readFileSync(join(testDir, '../theme/ingest.ts'), 'utf8'),
+      readFileSync(join(testDir, '../theme/section-extract.ts'), 'utf8'),
+    ].join('\n');
+
+    expect(source).not.toMatch(/from ['"](?:playwright|puppeteer|jsdom)/);
+    expect(source).not.toMatch(/require\(['"](?:playwright|puppeteer|jsdom)['"]\)/);
+  });
+});
diff --git a/packages/blocks-engine/src/theme/ingest.ts b/packages/blocks-engine/src/theme/ingest.ts
index 64db86b8..2e743c80 100644
--- a/packages/blocks-engine/src/theme/ingest.ts
+++ b/packages/blocks-engine/src/theme/ingest.ts
@@ -1,16 +1,90 @@
+import { lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import * as cheerio from 'cheerio';
 import { BlocksEngineError } from '../errors.js';
-import type { SiteModel } from './types.js';
+import type { SiteModel, SitePage } from './types.js';
+
+/** Recursively list *.html / *.htm files under root (skips dotdirs, node_modules, and symlinks). */
+function listHtmlFiles(root: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string): void => {
+    for (const name of readdirSync(dir)) {
+      if (name.startsWith('.') || name === 'node_modules') continue;
+      const full = join(dir, name);
+      const st = lstatSync(full);
+      if (st.isSymbolicLink()) continue;
+      if (st.isDirectory()) walk(full);
+      else if (name.toLowerCase().endsWith('.html') || name.toLowerCase().endsWith('.htm')) out.push(full);
+    }
+  };
+  walk(root);
+  return out;
+}
+
+/** One path segment -> slug-safe: lowercase, [^a-z0-9-] runs -> '-', collapse '--', trim edge dashes. */
+function sanitizeSegment(seg: string): string {
+  return seg
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function joinSlugSegments(parts: string[]): string {
+  return parts.map(sanitizeSegment).filter(Boolean).join('-');
+}
 
 export function slugFromRelPath(relPath: string): string {
-  throw new BlocksEngineError('not implemented', {
-    code: 'STAGE_STUB',
-    hint: 'Phase 0 skeleton',
-  });
+  const noExt = relPath.replace(/\.html?$/i, '');
+  const parts = noExt.split(sep).filter(Boolean);
+  if (parts.length === 0) return 'home';
+  const last = parts[parts.length - 1];
+  if (last.toLowerCase() === 'index') {
+    if (parts.length === 1) return 'home';
+    return joinSlugSegments(parts.slice(0, -1)) || 'home';
+  }
+  return joinSlugSegments(parts) || 'home';
 }
 
 export function ingest(srcDir: string): SiteModel {
-  throw new BlocksEngineError('not implemented', {
-    code: 'STAGE_STUB',
-    hint: 'Phase 0 skeleton',
+  const files = listHtmlFiles(srcDir);
+  if (files.length === 0) {
+    throw new BlocksEngineError(`no html pages found under ${srcDir}`, {
+      code: 'THEME_INGEST_NO_HTML',
+      hint: 'Static site ingest requires at least one .html or .htm page.',
+    });
+  }
+
+  const pages: SitePage[] = files.map((full) => {
+    const html = readFileSync(full, 'utf8');
+    const $ = cheerio.load(html);
+    const relPath = relative(srcDir, full);
+    const bodyData: Record<string, string> = {};
+    const bodyAttrs = $('body').attr() ?? {};
+    for (const [key, value] of Object.entries(bodyAttrs)) {
+      if (key.startsWith('data-')) bodyData[key.slice('data-'.length)] = value;
+    }
+    return {
+      relPath,
+      slug: slugFromRelPath(relPath),
+      html,
+      title: $('title').first().text().trim(),
+      ...(Object.keys(bodyData).length > 0 ? { bodyData } : {}),
+    };
   });
+
+  pages.sort((a, b) => a.slug.localeCompare(b.slug));
+
+  const seen = new Set<string>();
+  for (const page of pages) {
+    if (seen.has(page.slug)) {
+      throw new BlocksEngineError(`slug collision: "${page.slug}" from "${page.relPath}"`, {
+        code: 'THEME_INGEST_DUPLICATE_SLUG',
+        hint: 'Static site ingest requires every html page to map to a unique slug.',
+      });
+    }
+    seen.add(page.slug);
+  }
+
+  return { root: srcDir, pages };
 }
diff --git a/packages/blocks-engine/src/theme/section-extract.ts b/packages/blocks-engine/src/theme/section-extract.ts
index de58189e..95aaa098 100644
--- a/packages/blocks-engine/src/theme/section-extract.ts
+++ b/packages/blocks-engine/src/theme/section-extract.ts
@@ -1,10 +1,398 @@
-import { BlocksEngineError } from '../errors.js';
-import type { SectionSpec } from './section-spec.js';
+import * as cheerio from 'cheerio';
+import type { CheerioAPI } from 'cheerio';
+import type { InteractionModel, SectionSpec, SectionSpecImage } from './section-spec.js';
 import type { SitePage } from './types.js';
 
+type ElementNode = NonNullable<Parameters<CheerioAPI>[0]> & {
+  type?: string;
+  tagName: string;
+  attribs?: Record<string, string>;
+  parent?: ElementNode | null;
+};
+
+type ContentNode = {
+  type?: string;
+  tagName?: string;
+  attribs?: Record<string, string>;
+  parent?: ElementNode | null;
+  data?: string;
+};
+
+interface ExtractedContent {
+  headings: string[];
+  bodyText: string[];
+  buttonLabels: string[];
+  images: SectionSpecImage[];
+}
+
+interface SectionDraft {
+  selector: string;
+  html: string;
+  interactionModel: InteractionModel;
+}
+
+const EXPLICIT_TAGS = new Set(['section', 'article', 'nav', 'aside', 'footer', 'header', 'main']);
+const LANDMARK_ROLES = new Set([
+  'article',
+  'banner',
+  'complementary',
+  'contentinfo',
+  'main',
+  'navigation',
+  'region',
+  'search',
+]);
+const HEADING_SELECTOR = 'h1,h2,h3,h4,h5,h6';
+const BODY_TEXT_SELECTOR = 'p,li,blockquote,figcaption';
+const EXPLICIT_SELECTOR =
+  'section,article,nav,aside,footer,header,main,' +
+  '[role="article"],[role="banner"],[role="complementary"],[role="contentinfo"],' +
+  '[role="main"],[role="navigation"],[role="region"],[role="search"]';
+
 export function sectionExtract(page: SitePage): SectionSpec[] {
-  throw new BlocksEngineError('not implemented', {
-    code: 'STAGE_STUB',
-    hint: 'Phase 0 skeleton',
+  const $ = cheerio.load(page.html);
+  const drafts: SectionDraft[] = [];
+  const body = $('body').first();
+
+  if (body.length) {
+    walkContainer($, body.get(0) as ElementNode, drafts);
+  } else {
+    $.root()
+      .contents()
+      .each((_, node) => {
+        if (isElement(node)) processElement($, node, drafts);
+      });
+  }
+
+  const specs: SectionSpec[] = [];
+  for (const draft of drafts) {
+    const spec = buildSectionSpec(draft, specs.length);
+    if (spec) specs.push(spec);
+  }
+  return specs;
+}
+
+function walkContainer($: CheerioAPI, container: ElementNode, drafts: SectionDraft[]): void {
+  const nodes = $(container).contents().toArray() as ContentNode[];
+
+  for (let index = 0; index < nodes.length; index += 1) {
+    const node = nodes[index];
+    if (isHeading(node)) {
+      index = addHeadingBandFrom($, nodes, index, drafts);
+      continue;
+    }
+    if (isElement(node)) processElement($, node, drafts);
+  }
+}
+
+function processElement($: CheerioAPI, el: ElementNode, drafts: SectionDraft[]): void {
+  if (isExplicitCandidate(el)) {
+    const tag = tagName(el);
+
+    if (tag === 'main' && hasDirectHeadingChildren($, el)) {
+      walkContainer($, el, drafts);
+      return;
+    }
+
+    if (hasExplicitDescendant($, el) && !hasRecognizableContentOutsideDescendants($, el)) {
+      walkContainer($, el, drafts);
+      return;
+    }
+
+    addElementSection($, el, drafts);
+    return;
+  }
+
+  if (hasDirectHeadingChildren($, el)) {
+    walkContainer($, el, drafts);
+    return;
+  }
+
+  walkContainer($, el, drafts);
+}
+
+function addElementSection($: CheerioAPI, el: ElementNode, drafts: SectionDraft[]): void {
+  const html = $.html(el).trim();
+  if (!html) return;
+
+  drafts.push({
+    selector: selectorForElement($, el),
+    html,
+    interactionModel: interactionModelForElement(el),
+  });
+}
+
+function addHeadingBandFrom(
+  $: CheerioAPI,
+  nodes: ContentNode[],
+  index: number,
+  drafts: SectionDraft[]
+): number {
+  const node = nodes[index];
+  if (!isHeading(node)) return index;
+
+  const bandNodes: ContentNode[] = [node];
+  let cursor = index + 1;
+  while (cursor < nodes.length && !isHeading(nodes[cursor])) {
+    const current = nodes[cursor];
+    if (isElement(current) && isExplicitCandidate(current)) break;
+    if (hasRecognizableNodeContent($, current)) bandNodes.push(current);
+    cursor += 1;
+  }
+
+  const html = bandNodes.map((bandNode) => htmlForNode($, bandNode)).join('').trim();
+  if (html) {
+    drafts.push({
+      selector: selectorForElement($, node),
+      html,
+      interactionModel: 'static',
+    });
+  }
+  return cursor - 1;
+}
+
+function buildSectionSpec(draft: SectionDraft, sectionIndex: number): SectionSpec | null {
+  const content = extractContent(draft.html);
+  if (!hasRecognizableContent(content)) return null;
+
+  return {
+    sectionIndex,
+    interactionModel: draft.interactionModel,
+    top: 0,
+    height: 0,
+    headings: content.headings,
+    selector: draft.selector,
+    bodyText: content.bodyText,
+    buttonLabels: content.buttonLabels,
+    images: content.images,
+    icons: [],
+    backgroundBrightness: 1,
+    backgroundColor: 'transparent',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: {
+      motionClass: 'none',
+      signals: [],
+      animatedElements: 0,
+    },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: {
+      containerWidth: 0,
+      padding: '0',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '0',
+    },
+    sectionHtml: draft.html,
+  };
+}
+
+function extractContent(html: string): ExtractedContent {
+  const $ = cheerio.load(html, null, false);
+  const headings = collectText($, HEADING_SELECTOR);
+  const bodyText = collectBodyText($);
+  const buttonLabels = collectButtonLabels($);
+  const images = collectImages($);
+
+  return { headings, bodyText, buttonLabels, images };
+}
+
+function hasRecognizableContent(content: ExtractedContent): boolean {
+  return (
+    content.headings.length > 0 ||
+    content.bodyText.length > 0 ||
+    content.buttonLabels.length > 0 ||
+    content.images.length > 0
+  );
+}
+
+function hasRecognizableNodeContent($: CheerioAPI, node: ContentNode): boolean {
+  if (isElement(node)) {
+    return hasRecognizableContent(extractContent($.html(node)));
+  }
+
+  return node.type === 'text' && cleanText(node.data ?? '').length > 0;
+}
+
+function hasRecognizableContentOutsideDescendants($: CheerioAPI, el: ElementNode): boolean {
+  const clone = $(el).clone();
+  clone.find(EXPLICIT_SELECTOR).remove();
+  return hasRecognizableContent(extractContent(clone.html() ?? ''));
+}
+
+function hasExplicitDescendant($: CheerioAPI, el: ElementNode): boolean {
+  return $(el).find(EXPLICIT_SELECTOR).length > 0;
+}
+
+function hasDirectHeadingChildren($: CheerioAPI, el: ElementNode): boolean {
+  return (
+    $(el)
+      .contents()
+      .toArray()
+      .some((node) => isHeading(node as ContentNode))
+  );
+}
+
+function isExplicitCandidate(el: ElementNode): boolean {
+  return EXPLICIT_TAGS.has(tagName(el)) || roleForElement(el) !== null;
+}
+
+function interactionModelForElement(el: ElementNode): InteractionModel {
+  const tag = tagName(el);
+  const role = roleForElement(el);
+
+  if (tag === 'nav' || role === 'navigation') return 'nav';
+  if (tag === 'footer' || role === 'contentinfo') return 'footer';
+  return 'static';
+}
+
+function collectText($: CheerioAPI, selector: string): string[] {
+  const values: string[] = [];
+  $(selector).each((_, el) => {
+    const text = cleanText($(el).text());
+    pushUnique(values, text);
+  });
+  return values;
+}
+
+function collectBodyText($: CheerioAPI): string[] {
+  const values = collectText($, BODY_TEXT_SELECTOR);
+  $('div,span').each((_, el) => {
+    const $el = $(el);
+    if ($el.closest(`${HEADING_SELECTOR},a,button`).length > 0) return;
+    if (
+      $el.find(
+        `${BODY_TEXT_SELECTOR},${HEADING_SELECTOR},a,button,input,select,textarea`
+      ).length > 0
+    ) {
+      return;
+    }
+    pushUnique(values, cleanText($el.text()));
+  });
+  if (values.length === 0) {
+    const clone = $.root().clone();
+    clone.find(`${HEADING_SELECTOR},a,button,input,select,textarea,script,style`).remove();
+    pushUnique(values, cleanText(clone.text()));
+  }
+  return values;
+}
+
+function collectButtonLabels($: CheerioAPI): string[] {
+  const labels: string[] = [];
+  $('a,button,input[type="button"],input[type="submit"]').each((_, el) => {
+    const $el = $(el);
+    const text =
+      cleanText($el.text()) ||
+      cleanText($el.attr('value') ?? '') ||
+      cleanText($el.attr('aria-label') ?? '') ||
+      cleanText($el.attr('title') ?? '');
+    if (text) labels.push(text);
+  });
+  return labels;
+}
+
+function collectImages($: CheerioAPI): SectionSpecImage[] {
+  const images: SectionSpecImage[] = [];
+
+  $('img').each((_, el) => {
+    const $el = $(el);
+    const url = $el.attr('src') ?? '';
+    if (!url) return;
+
+    images.push({
+      url,
+      sourceUrl: url,
+      alt: $el.attr('alt') ?? '',
+      kind: 'img',
+      width: parseDimension($el.attr('width')),
+      height: parseDimension($el.attr('height')),
+    });
   });
+
+  return images;
+}
+
+function parseDimension(value: string | undefined): number {
+  if (!value) return 0;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function selectorForElement($: CheerioAPI, el: ElementNode): string {
+  const tag = tagName(el);
+  const id = attr(el, 'id');
+  if (id) return simpleIdent(id) ? `#${id}` : `${tag}[id="${escapeAttr(id)}"]`;
+
+  const labelledBy = attr(el, 'aria-labelledby');
+  if (labelledBy) return `${tag}[aria-labelledby="${escapeAttr(labelledBy)}"]`;
+
+  const ariaLabel = attr(el, 'aria-label');
+  if (ariaLabel) return `${tag}[aria-label="${escapeAttr(ariaLabel)}"]`;
+
+  const role = attr(el, 'role');
+  if (role) return `${tag}[role="${escapeAttr(role)}"]`;
+
+  if (!/^h[1-6]$/.test(tag) && $(tag).length === 1) return tag;
+
+  const parent = parentElement(el);
+  if (!parent || tagName(parent) === 'html') return `${tag}:nth-of-type(${nthOfType($, el)})`;
+
+  return `${selectorForElement($, parent)} > ${tag}:nth-of-type(${nthOfType($, el)})`;
+}
+
+function nthOfType($: CheerioAPI, el: ElementNode): number {
+  return $(el).prevAll(tagName(el)).length + 1;
+}
+
+function roleForElement(el: ElementNode): string | null {
+  const role = attr(el, 'role');
+  if (!role) return null;
+
+  return role
+    .toLowerCase()
+    .split(/\s+/)
+    .find((candidate) => LANDMARK_ROLES.has(candidate)) ?? null;
+}
+
+function htmlForNode($: CheerioAPI, node: ContentNode): string {
+  if (isElement(node)) return $.html(node);
+  return node.data ?? '';
+}
+
+function parentElement(el: ElementNode): ElementNode | null {
+  const parent = el.parent;
+  return parent && parent.type === 'tag' ? parent : null;
+}
+
+function isHeading(node: ContentNode): node is ElementNode {
+  return isElement(node) && /^h[1-6]$/.test(tagName(node));
+}
+
+function isElement(node: unknown): node is ElementNode {
+  return (node as ElementNode | null)?.type === 'tag';
+}
+
+function tagName(el: ElementNode): string {
+  return el.tagName.toLowerCase();
+}
+
+function attr(el: ElementNode, name: string): string | undefined {
+  return el.attribs?.[name];
+}
+
+function cleanText(value: string): string {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+function pushUnique(values: string[], text: string): void {
+  if (text && !values.includes(text)) values.push(text);
+}
+
+function simpleIdent(value: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_-]*$/.test(value);
+}
+
+function escapeAttr(value: string): string {
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
 }

From 14711fe8979a78a63fa685090cc3a51a4bcb3712 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 12:33:14 -0400
Subject: [PATCH 036/113] test(theme): freeze P0-3 site-to-theme paths

---
 .../src/__tests__/site-to-theme.e2e.test.ts   | 19 +++++++++++++++++++
 packages/blocks-engine/src/theme/assemble.ts  |  1 +
 .../blocks-engine/src/theme/foundation.ts     |  1 +
 .../blocks-engine/src/theme/reconstruct.ts    |  1 +
 .../blocks-engine/src/theme/site-to-theme.ts  |  1 +
 .../src/theme/theme-json-lint.ts              |  9 +++++++++
 .../blocks-engine/src/theme/write-theme.ts    |  1 +
 7 files changed, 33 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
 create mode 100644 packages/blocks-engine/src/theme/assemble.ts
 create mode 100644 packages/blocks-engine/src/theme/foundation.ts
 create mode 100644 packages/blocks-engine/src/theme/reconstruct.ts
 create mode 100644 packages/blocks-engine/src/theme/site-to-theme.ts
 create mode 100644 packages/blocks-engine/src/theme/theme-json-lint.ts
 create mode 100644 packages/blocks-engine/src/theme/write-theme.ts

diff --git a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
new file mode 100644
index 00000000..edbb4a13
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+
+import { assemble } from '../theme/assemble.js';
+import { foundation } from '../theme/foundation.js';
+import { reconstruct } from '../theme/reconstruct.js';
+import { siteToTheme } from '../theme/site-to-theme.js';
+import { lintThemeJson } from '../theme/theme-json-lint.js';
+import { writeTheme } from '../theme/write-theme.js';
+
+describe('site-to-theme P0-3 path contracts', () => {
+  it('freezes the P0-3 module and e2e test paths', () => {
+    expect(foundation).toBeTypeOf('function');
+    expect(reconstruct).toBeTypeOf('function');
+    expect(assemble).toBeTypeOf('function');
+    expect(writeTheme).toBeTypeOf('function');
+    expect(siteToTheme).toBeTypeOf('function');
+    expect(lintThemeJson).toBeTypeOf('function');
+  });
+});
diff --git a/packages/blocks-engine/src/theme/assemble.ts b/packages/blocks-engine/src/theme/assemble.ts
new file mode 100644
index 00000000..1b099b85
--- /dev/null
+++ b/packages/blocks-engine/src/theme/assemble.ts
@@ -0,0 +1 @@
+export { assemble } from './stages.js';
diff --git a/packages/blocks-engine/src/theme/foundation.ts b/packages/blocks-engine/src/theme/foundation.ts
new file mode 100644
index 00000000..7ebaf267
--- /dev/null
+++ b/packages/blocks-engine/src/theme/foundation.ts
@@ -0,0 +1 @@
+export { foundation } from './stages.js';
diff --git a/packages/blocks-engine/src/theme/reconstruct.ts b/packages/blocks-engine/src/theme/reconstruct.ts
new file mode 100644
index 00000000..34ad84fa
--- /dev/null
+++ b/packages/blocks-engine/src/theme/reconstruct.ts
@@ -0,0 +1 @@
+export { reconstruct } from './stages.js';
diff --git a/packages/blocks-engine/src/theme/site-to-theme.ts b/packages/blocks-engine/src/theme/site-to-theme.ts
new file mode 100644
index 00000000..bcaaa2c1
--- /dev/null
+++ b/packages/blocks-engine/src/theme/site-to-theme.ts
@@ -0,0 +1 @@
+export { siteToTheme } from './stages.js';
diff --git a/packages/blocks-engine/src/theme/theme-json-lint.ts b/packages/blocks-engine/src/theme/theme-json-lint.ts
new file mode 100644
index 00000000..c69275b4
--- /dev/null
+++ b/packages/blocks-engine/src/theme/theme-json-lint.ts
@@ -0,0 +1,9 @@
+export interface ThemeJsonLintResult {
+  ok: boolean;
+  errors: string[];
+}
+
+export function lintThemeJson(theme: Record<string, unknown>): ThemeJsonLintResult {
+  void theme;
+  return { ok: false, errors: ['not implemented'] };
+}
diff --git a/packages/blocks-engine/src/theme/write-theme.ts b/packages/blocks-engine/src/theme/write-theme.ts
new file mode 100644
index 00000000..170bd866
--- /dev/null
+++ b/packages/blocks-engine/src/theme/write-theme.ts
@@ -0,0 +1 @@
+export { writeTheme } from './stages.js';

From 86a8cd6aacf491a2b541b36ea12161238ad4cce4 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 12:47:20 -0400
Subject: [PATCH 037/113] feat(theme): implement P0-3 site-to-theme skeleton

---
 .../src/__tests__/convert.test.ts             |   2 +
 .../src/__tests__/site-to-theme.e2e.test.ts   | 270 +++++++++++++-
 packages/blocks-engine/src/index.ts           |   4 +-
 packages/blocks-engine/src/theme/assemble.ts  | 240 +++++++++++-
 .../blocks-engine/src/theme/foundation.ts     | 349 +++++++++++++++++-
 packages/blocks-engine/src/theme/index.ts     |  14 +-
 .../blocks-engine/src/theme/reconstruct.ts    |  96 ++++-
 .../blocks-engine/src/theme/site-to-theme.ts  | 103 +++++-
 packages/blocks-engine/src/theme/stages.ts    |  87 +----
 .../src/theme/theme-json-lint.ts              |  17 +-
 .../blocks-engine/src/theme/write-theme.ts    |  95 ++++-
 11 files changed, 1162 insertions(+), 115 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/convert.test.ts b/packages/blocks-engine/src/__tests__/convert.test.ts
index 293af069..739c280e 100644
--- a/packages/blocks-engine/src/__tests__/convert.test.ts
+++ b/packages/blocks-engine/src/__tests__/convert.test.ts
@@ -157,6 +157,7 @@ describe('default entry', () => {
       'compose',
       'convert',
       'createWorker',
+      'lintThemeJson',
       'siteToTheme',
       'writeTheme',
     ].sort();
@@ -189,6 +190,7 @@ describe('default entry', () => {
     expect(typeof defaultEntry.compose).toBe('function');
     expect(typeof defaultEntry.BlocksEngineError).toBe('function');
     expect(typeof defaultEntry.createWorker).toBe('function');
+    expect(typeof defaultEntry.lintThemeJson).toBe('function');
     expect(typeof defaultEntry.siteToTheme).toBe('function');
     expect(typeof defaultEntry.writeTheme).toBe('function');
 
diff --git a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
index edbb4a13..266f2a07 100644
--- a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
+++ b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
@@ -1,19 +1,255 @@
-import { describe, expect, it } from 'vitest';
-
-import { assemble } from '../theme/assemble.js';
-import { foundation } from '../theme/foundation.js';
-import { reconstruct } from '../theme/reconstruct.js';
-import { siteToTheme } from '../theme/site-to-theme.js';
-import { lintThemeJson } from '../theme/theme-json-lint.js';
-import { writeTheme } from '../theme/write-theme.js';
-
-describe('site-to-theme P0-3 path contracts', () => {
-  it('freezes the P0-3 module and e2e test paths', () => {
-    expect(foundation).toBeTypeOf('function');
-    expect(reconstruct).toBeTypeOf('function');
-    expect(assemble).toBeTypeOf('function');
-    expect(writeTheme).toBeTypeOf('function');
-    expect(siteToTheme).toBeTypeOf('function');
-    expect(lintThemeJson).toBeTypeOf('function');
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { WorkerPool } from '../pool/types.js';
+import type { SectionBlocks, SectionSpec } from '../theme/index.js';
+
+const fixtureRoot = join(import.meta.dirname, 'fixtures/site');
+const requireFromHere = createRequire(import.meta.url);
+const requireWithCache = requireFromHere as typeof requireFromHere & {
+  resolve(id: string): string;
+  cache: Record<string, unknown>;
+};
+
+function requireCacheEntriesForWordPressBlocks(): string[] {
+  return Object.keys(requireWithCache.cache).filter((entry) =>
+    entry.includes('/node_modules/@wordpress/blocks/'),
+  );
+}
+
+function clearWordPressBlocksRequireCache(): void {
+  for (const entry of requireCacheEntriesForWordPressBlocks()) {
+    delete requireWithCache.cache[entry];
+  }
+}
+
+async function withTempDir<T>(prefix: string, fn: (dir: string) => Promise<T> | T): Promise<T> {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  try {
+    return await fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function copyFixtureSite(dest: string): void {
+  for (const file of ['index.html', 'about.html', 'style.css']) {
+    writeFileSync(join(dest, file), readFileSync(join(fixtureRoot, file), 'utf8'), 'utf8');
+  }
+}
+
+function semanticSpec(sectionIndex = 0): SectionSpec {
+  return {
+    sectionIndex,
+    interactionModel: 'static',
+    top: 0,
+    height: 0,
+    headings: ['Semantic heading'],
+    bodyText: ['Semantic body copy.'],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 1,
+    backgroundColor: 'transparent',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: {
+      motionClass: 'none',
+      signals: [],
+      animatedElements: 0,
+    },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: {
+      containerWidth: 0,
+      padding: '0',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '0',
+    },
+    sectionHtml: '<h1>Semantic heading</h1><p>Semantic body copy.</p>',
+  };
+}
+
+function fakePool(markup: string): WorkerPool & { stopCalls: number } {
+  return {
+    stopCalls: 0,
+    async rawConvert(items: string[]) {
+      return items.map(() => ({ html: markup, wpHtmlResidue: 0 }));
+    },
+    async canonicalize(items: string[]) {
+      return items.map((html) => ({ html, changed: false, fixedIssues: [] }));
+    },
+    async stop() {
+      this.stopCalls += 1;
+    },
+  };
+}
+
+afterEach(() => {
+  vi.doUnmock('../pool/pool.js');
+  vi.resetModules();
+});
+
+describe('site-to-theme P0-3 orchestration', () => {
+  it('writes a lintable block theme with native block markup for semantic input', async () => {
+    const { siteToTheme, lintThemeJson } = await import('../theme/index.js');
+
+    await withTempDir('blocks-engine-site-to-theme-', async (siteDir) => {
+      copyFixtureSite(siteDir);
+      const outDir = join(siteDir, 'theme-out');
+
+      const result = await siteToTheme(siteDir, {
+        outDir,
+        sections: { about: [semanticSpec(0)], home: [semanticSpec(0)] },
+      });
+
+      expect(result.written).toEqual(
+        expect.arrayContaining(['style.css', 'theme.json', 'templates/index.html'])
+      );
+      expect(existsSync(join(outDir, 'style.css'))).toBe(true);
+      expect(existsSync(join(outDir, 'theme.json'))).toBe(true);
+      expect(existsSync(join(outDir, 'templates', 'index.html'))).toBe(true);
+
+      const themeJson = JSON.parse(readFileSync(join(outDir, 'theme.json'), 'utf8'));
+      expect(lintThemeJson(themeJson)).toEqual({ ok: true, errors: [] });
+
+      const template = readFileSync(join(outDir, 'templates', 'index.html'), 'utf8');
+      expect(template).toContain('<!-- wp:heading');
+      expect(template).toContain('<!-- wp:paragraph');
+      expect(template).not.toMatch(/^<!-- wp:html -->[\s\S]*<!-- \/wp:html -->$/);
+    });
+  });
+
+  it('treats absent hooks the same as empty and explicit identity hooks byte-for-byte', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+
+    await withTempDir('blocks-engine-site-to-theme-a-', async (rootDir) => {
+      const siteDir = join(rootDir, 'site');
+      mkdirSync(siteDir);
+      copyFixtureSite(siteDir);
+      const firstOut = join(rootDir, 'theme-no-hooks');
+      const secondOut = join(rootDir, 'theme-empty-hooks');
+      const thirdOut = join(rootDir, 'theme-identity-hooks');
+      const pool = fakePool('<!-- wp:paragraph -->\n<p>Stable.</p>\n<!-- /wp:paragraph -->');
+      const emptyHooksPool = fakePool('<!-- wp:paragraph -->\n<p>Stable.</p>\n<!-- /wp:paragraph -->');
+      const identityHooksPool = fakePool('<!-- wp:paragraph -->\n<p>Stable.</p>\n<!-- /wp:paragraph -->');
+
+      const first = await siteToTheme(siteDir, {
+        outDir: firstOut,
+        pool,
+        sections: { about: [semanticSpec(0)], home: [semanticSpec(0)] },
+      });
+      const second = await siteToTheme(siteDir, {
+        outDir: secondOut,
+        pool: emptyHooksPool,
+        sections: { about: [semanticSpec(0)], home: [semanticSpec(0)] },
+        hooks: {},
+      });
+      const third = await siteToTheme(siteDir, {
+        outDir: thirdOut,
+        pool: identityHooksPool,
+        sections: { about: [semanticSpec(0)], home: [semanticSpec(0)] },
+        hooks: {
+          async onFoundation(tokens) {
+            return tokens;
+          },
+          async onSection(section) {
+            return section;
+          },
+          async onRefine(theme) {
+            return theme;
+          },
+        },
+      });
+
+      expect(second.model).toEqual(first.model);
+      expect(readFileSync(join(secondOut, 'theme.json'), 'utf8')).toBe(
+        readFileSync(join(firstOut, 'theme.json'), 'utf8')
+      );
+      expect(readFileSync(join(secondOut, 'templates', 'index.html'), 'utf8')).toBe(
+        readFileSync(join(firstOut, 'templates', 'index.html'), 'utf8')
+      );
+      expect(third.model).toEqual(first.model);
+      expect(readFileSync(join(thirdOut, 'theme.json'), 'utf8')).toBe(
+        readFileSync(join(firstOut, 'theme.json'), 'utf8')
+      );
+      expect(readFileSync(join(thirdOut, 'templates', 'index.html'), 'utf8')).toBe(
+        readFileSync(join(firstOut, 'templates', 'index.html'), 'utf8')
+      );
+    });
+  });
+
+  it('uses injected pools without stopping them and runs onSection for coverageFloor 1', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+
+    await withTempDir('blocks-engine-site-to-theme-pool-', async (siteDir) => {
+      copyFixtureSite(siteDir);
+      const pool = fakePool('<!-- wp:heading -->\n<h2>From pool</h2>\n<!-- /wp:heading -->');
+      const seenSections: SectionBlocks[] = [];
+
+      await siteToTheme(siteDir, {
+        outDir: join(siteDir, 'theme-out'),
+        pool,
+        coverageFloor: 1,
+        sections: { about: [semanticSpec(0)], home: [semanticSpec(0)] },
+        hooks: {
+          async onSection(section) {
+            seenSections.push(section);
+            return section;
+          },
+        },
+      });
+
+      expect(seenSections).toHaveLength(2);
+      expect(pool.stopCalls).toBe(0);
+    });
+  });
+
+  it('stops the one-shot pool it creates internally', async () => {
+    const pool = fakePool('<!-- wp:paragraph -->\n<p>Owned.</p>\n<!-- /wp:paragraph -->');
+
+    vi.doMock('../pool/pool.js', () => ({
+      createWorker: () => pool,
+    }));
+
+    const { siteToTheme } = await import('../theme/site-to-theme.js');
+
+    await withTempDir('blocks-engine-site-to-theme-owned-', async (siteDir) => {
+      copyFixtureSite(siteDir);
+
+      await siteToTheme(siteDir, {
+        outDir: join(siteDir, 'theme-out'),
+        sections: { about: [semanticSpec(0)], home: [semanticSpec(0)] },
+      });
+
+      expect(pool.stopCalls).toBe(1);
+    });
+  });
+
+  it('exports siteToTheme from the main entry without loading @wordpress/blocks in this process', async () => {
+    clearWordPressBlocksRequireCache();
+
+    const entry = await import('../index.js');
+
+    expect(entry.siteToTheme).toBeTypeOf('function');
+    expect(entry.writeTheme).toBeTypeOf('function');
+    expect(entry.lintThemeJson).toBeTypeOf('function');
+    expect(requireCacheEntriesForWordPressBlocks()).toEqual([]);
+
+    await withTempDir('blocks-engine-site-to-theme-main-entry-', async (siteDir) => {
+      copyFixtureSite(siteDir);
+      await entry.siteToTheme(siteDir, {
+        outDir: join(siteDir, 'theme-out'),
+        pool: fakePool('<!-- wp:paragraph -->\n<p>Main entry.</p>\n<!-- /wp:paragraph -->'),
+        sections: { about: [semanticSpec(0)], home: [semanticSpec(0)] },
+      });
+    });
+
+    expect(requireCacheEntriesForWordPressBlocks()).toEqual([]);
   });
 });
diff --git a/packages/blocks-engine/src/index.ts b/packages/blocks-engine/src/index.ts
index 0bd963a9..d41d5fed 100644
--- a/packages/blocks-engine/src/index.ts
+++ b/packages/blocks-engine/src/index.ts
@@ -2,11 +2,11 @@ export { convert } from './convert.js';
 export { compose } from './compose.js';
 export { createWorker } from './pool/pool.js';
 export { BlocksEngineError } from './errors.js';
-export { siteToTheme, writeTheme } from './theme/index.js';
+export { lintThemeJson, siteToTheme, writeTheme } from './theme/index.js';
 
 export type { ConvertOptions } from './convert.js';
 export type { BlocksEngineErrorOptions } from './errors.js';
-export type { SiteToThemeOptions, ThemeBuildResult } from './theme/index.js';
+export type { SiteToThemeOptions, ThemeBuildResult, ThemeJsonLintResult } from './theme/index.js';
 export type { ConversionContext, Converter, HtmlFallback } from './types.js';
 export type {
   CreateWorker,
diff --git a/packages/blocks-engine/src/theme/assemble.ts b/packages/blocks-engine/src/theme/assemble.ts
index 1b099b85..b00390a5 100644
--- a/packages/blocks-engine/src/theme/assemble.ts
+++ b/packages/blocks-engine/src/theme/assemble.ts
@@ -1 +1,239 @@
-export { assemble } from './stages.js';
+import type {
+  AssetFile,
+  FoundationTokens,
+  SectionBlocks,
+  SiteModel,
+  ThemeMeta,
+  ThemeModel,
+} from './types.js';
+
+type ThemeAssemblyParts = {
+  site: SiteModel;
+  tokens: FoundationTokens;
+  pages: Record<string, SectionBlocks[]>;
+  meta: ThemeMeta;
+};
+
+type PaletteEntry = {
+  name: string;
+  slug: string;
+  color: string;
+};
+
+type FontFamilyEntry = {
+  fontFamily: string;
+  name: string;
+  slug: string;
+};
+
+export function assemble(parts: ThemeAssemblyParts): ThemeModel {
+  const themeSlug = slugify(parts.meta.slug || parts.meta.name) || 'blocks-engine-theme';
+  const palette = buildPalette(parts.tokens);
+  const fontFamilies = buildFontFamilies(parts.tokens);
+
+  return {
+    styleCss: buildStyleCss(parts.meta, themeSlug),
+    themeJson: buildThemeJson(parts.tokens, palette, fontFamilies),
+    templates: {
+      'index.html': buildIndexTemplate(parts.site, parts.pages),
+    },
+    parts: {},
+    patterns: {},
+    assets: collectAssets(parts),
+  };
+}
+
+function buildStyleCss(meta: ThemeMeta, themeSlug: string): string {
+  return buildThemeHeader([
+    ['Theme Name', meta.name],
+    ['Author', meta.author ?? 'Automattic'],
+    ['Description', `${meta.name} block theme assembled by @automattic/blocks-engine.`],
+    ['Version', '0.1.0'],
+    ['Requires at least', '6.5'],
+    ['Requires PHP', '8.0'],
+    ['License', 'GPL-3.0-or-later'],
+    ['Text Domain', themeSlug],
+    ['Tags', 'block-theme, full-site-editing'],
+  ]);
+}
+
+function buildThemeHeader(fields: Array<[string, string]>): string {
+  const body = fields.map(([key, value]) => `${key}: ${value}`).join('\n');
+  return `/*\n${body}\n*/\n`;
+}
+
+function buildThemeJson(
+  tokens: FoundationTokens,
+  palette: PaletteEntry[],
+  fontFamilies: FontFamilyEntry[]
+): Record<string, unknown> {
+  const bodyFontSlug = fontFamilies[0]?.slug;
+
+  return {
+    $schema: 'https://schemas.wp.org/trunk/theme.json',
+    version: 3,
+    settings: {
+      appearanceTools: true,
+      color: {
+        custom: false,
+        defaultPalette: false,
+        palette,
+      },
+      typography: {
+        customFontSize: false,
+        defaultFontSizes: false,
+        fluid: false,
+        fontFamilies,
+      },
+      layout: {
+        contentSize: tokens.breakpoints.lg ?? tokens.breakpoints.md ?? '900px',
+        wideSize: tokens.breakpoints.xl ?? tokens.breakpoints.lg ?? '1280px',
+      },
+      spacing: {
+        units: ['px', 'em', 'rem', '%', 'vh', 'vw'],
+      },
+    },
+    styles: {
+      color: {
+        background: colorValueFor(palette, ['surface-base', 'background', 'white'], '#ffffff'),
+        text: colorValueFor(palette, ['text-default', 'foreground', 'black'], '#111111'),
+      },
+      ...(bodyFontSlug
+        ? { typography: { fontFamily: `var(--wp--preset--font-family--${bodyFontSlug})` } }
+        : {}),
+    },
+  };
+}
+
+function buildPalette(tokens: FoundationTokens): PaletteEntry[] {
+  const used = new Set<string>();
+  const palette: PaletteEntry[] = [];
+
+  for (const token of tokens.palette) {
+    const name = token.name.trim();
+    const color = token.color.trim();
+    if (!name || !color) continue;
+
+    const baseSlug = slugify(name) || 'color';
+    const slug = uniqueSlug(baseSlug, used);
+    palette.push({ name, slug, color });
+  }
+
+  return palette;
+}
+
+function buildFontFamilies(tokens: FoundationTokens): FontFamilyEntry[] {
+  const out: FontFamilyEntry[] = [];
+  const used = new Set<string>();
+  addFontFamily(out, used, 'Body', tokens.typography.body);
+  addFontFamily(out, used, 'Display', tokens.typography.display);
+  return out;
+}
+
+function addFontFamily(
+  out: FontFamilyEntry[],
+  used: Set<string>,
+  name: string,
+  fontFamily: string | undefined
+): void {
+  const family = fontFamily?.trim();
+  if (!family) return;
+
+  const baseSlug = slugify(name) || 'font';
+  const slug = uniqueSlug(baseSlug, used);
+  out.push({ fontFamily: family, name, slug });
+}
+
+function colorValueFor(palette: PaletteEntry[], preferredSlugs: string[], fallback: string): string {
+  for (const slug of preferredSlugs) {
+    const match = palette.find((entry) => entry.slug === slug);
+    if (match) return `var(--wp--preset--color--${match.slug})`;
+  }
+  return fallback;
+}
+
+function buildIndexTemplate(site: SiteModel, pages: Record<string, SectionBlocks[]>): string {
+  const pageBlocks = orderedPageBlocks(site, pages);
+  const blocks = pageBlocks.length > 0
+    ? pageBlocks.join('\n\n')
+    : '<!-- wp:paragraph -->\n<p></p>\n<!-- /wp:paragraph -->';
+
+  return `<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
+<main class="wp-block-group">
+${blocks}
+</main>
+<!-- /wp:group -->
+`;
+}
+
+function orderedPageBlocks(site: SiteModel, pages: Record<string, SectionBlocks[]>): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+
+  for (const page of site.pages) {
+    const blocks = blocksForPage(page.slug, pages);
+    if (!blocks) continue;
+    out.push(blocks);
+    seen.add(page.slug);
+  }
+
+  for (const [slug, sections] of Object.entries(pages).sort(([a], [b]) => a.localeCompare(b))) {
+    if (seen.has(slug)) continue;
+    const blocks = joinSectionBlocks(sections);
+    if (blocks) out.push(blocks);
+  }
+
+  return out;
+}
+
+function blocksForPage(slug: string, pages: Record<string, SectionBlocks[]>): string | null {
+  return joinSectionBlocks(pages[slug] ?? []);
+}
+
+function joinSectionBlocks(sections: SectionBlocks[]): string | null {
+  const blocks = sections.map((section) => section.blocks.trim()).filter(Boolean);
+  return blocks.length > 0 ? blocks.join('\n\n') : null;
+}
+
+function collectAssets(parts: ThemeAssemblyParts): AssetFile[] {
+  return [
+    ...assetFilesFromUnknown(parts.site),
+    ...assetFilesFromUnknown(parts.tokens),
+    ...assetFilesFromUnknown(parts.meta),
+  ];
+}
+
+function assetFilesFromUnknown(value: unknown): AssetFile[] {
+  if (!value || typeof value !== 'object' || !('assets' in value)) return [];
+  const assets = (value as { assets?: unknown }).assets;
+  if (!Array.isArray(assets)) return [];
+
+  return assets.filter(isAssetFile);
+}
+
+function isAssetFile(value: unknown): value is AssetFile {
+  return Boolean(
+    value &&
+      typeof value === 'object' &&
+      typeof (value as AssetFile).relPath === 'string' &&
+      (value as AssetFile).relPath.trim()
+  );
+}
+
+function uniqueSlug(baseSlug: string, used: Set<string>): string {
+  let slug = baseSlug;
+  let suffix = 2;
+  while (used.has(slug)) {
+    slug = `${baseSlug}-${suffix}`;
+    suffix += 1;
+  }
+  used.add(slug);
+  return slug;
+}
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
diff --git a/packages/blocks-engine/src/theme/foundation.ts b/packages/blocks-engine/src/theme/foundation.ts
index 7ebaf267..ccc03219 100644
--- a/packages/blocks-engine/src/theme/foundation.ts
+++ b/packages/blocks-engine/src/theme/foundation.ts
@@ -1 +1,348 @@
-export { foundation } from './stages.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import * as cheerio from 'cheerio';
+import type { FoundationAggregates, FoundationTokens, SiteModel, SitePage } from './types.js';
+
+type CssFragment = {
+  key: string;
+  css: string;
+};
+
+type ColorCandidate = {
+  color: string;
+  count: number;
+  firstIndex: number;
+  name?: string;
+};
+
+type FontCandidate = {
+  family: string;
+  count: number;
+  firstIndex: number;
+  bodyCount: number;
+  displayCount: number;
+};
+
+const MAX_PALETTE_COLORS = 12;
+
+const COLOR_VALUE_RE = /#(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})\b|(?:rgb|hsl)a?\(\s*[^)]*\)/gi;
+const COLOR_DECL_RE =
+  /(?:^|[;{\s])((?:--[-\w]*(?:color|primary|secondary|accent|background|foreground|text|brand)[-\w]*)|color|background(?:-color)?|border(?:-[\w]+)?-color|outline-color|fill|stroke)\s*:\s*([^;{}]+)/gi;
+const FONT_DECL_RE = /font-family\s*:\s*([^;{}]+)/gi;
+const MEDIA_RE = /@media[^{]*/gi;
+const MEDIA_WIDTH_RE = /\(\s*(?:min|max)-width\s*:\s*(\d+)px\s*\)/gi;
+
+export function foundation(site: SiteModel, aggregates?: FoundationAggregates): FoundationTokens {
+  const cssFragments = collectCssFragments(site);
+  const cssTexts = cssFragments.map((fragment) => stripCssComments(fragment.css));
+
+  const tokens: FoundationTokens = {
+    palette: extractPalette(cssTexts),
+    typography: extractTypography(cssTexts),
+    breakpoints: extractBreakpoints(cssTexts),
+  };
+
+  const aggregatePalette = coercePalette(aggregates?.palette);
+  if (aggregatePalette) tokens.palette = aggregatePalette;
+
+  const aggregateTypography = coerceTypography(aggregates?.typography);
+  if (aggregateTypography) {
+    tokens.typography = { ...tokens.typography, ...aggregateTypography };
+  }
+
+  const aggregateBreakpoints = coerceBreakpoints(aggregates?.breakpoints);
+  if (aggregateBreakpoints) {
+    tokens.breakpoints = { ...tokens.breakpoints, ...aggregateBreakpoints };
+  }
+
+  return tokens;
+}
+
+function collectCssFragments(site: SiteModel): CssFragment[] {
+  const root = resolve(site.root);
+  const fragments: CssFragment[] = [];
+  const linked = new Set<string>();
+
+  for (const page of sortedPages(site.pages)) {
+    const $ = cheerio.load(page.html);
+
+    $('link').each((index, element) => {
+      const rel = ($(element).attr('rel') ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+      if (!rel.includes('stylesheet')) return;
+
+      const cssPath = resolveStylesheetPath(root, page, $(element).attr('href'));
+      if (!cssPath || linked.has(cssPath) || !existsSync(cssPath)) return;
+
+      linked.add(cssPath);
+      fragments.push({
+        key: `link:${relative(root, cssPath)}`,
+        css: readFileSync(cssPath, 'utf8'),
+      });
+    });
+
+    $('style').each((index, element) => {
+      fragments.push({
+        key: `style:${page.relPath}:${index.toString().padStart(4, '0')}`,
+        css: $(element).html() ?? $(element).text(),
+      });
+    });
+  }
+
+  return fragments.sort((a, b) => a.key.localeCompare(b.key));
+}
+
+function sortedPages(pages: SitePage[]): SitePage[] {
+  return [...pages].sort((a, b) => {
+    const rel = a.relPath.localeCompare(b.relPath);
+    if (rel !== 0) return rel;
+    return a.slug.localeCompare(b.slug);
+  });
+}
+
+function resolveStylesheetPath(root: string, page: SitePage, href: string | undefined): string | null {
+  const cleanHref = cleanLocalHref(href);
+  if (!cleanHref) return null;
+
+  const cssPath = cleanHref.startsWith('/')
+    ? resolve(root, `.${cleanHref}`)
+    : resolve(root, dirname(page.relPath), cleanHref);
+
+  return isInside(root, cssPath) ? cssPath : null;
+}
+
+function cleanLocalHref(href: string | undefined): string | null {
+  const trimmed = href?.trim();
+  if (!trimmed) return null;
+  if (/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(trimmed)) return null;
+
+  const withoutHash = trimmed.split('#', 1)[0] ?? '';
+  const withoutQuery = withoutHash.split('?', 1)[0] ?? '';
+  return withoutQuery || null;
+}
+
+function isInside(root: string, file: string): boolean {
+  const rel = relative(root, file);
+  return rel === '' || (!rel.startsWith('..') && !rel.startsWith('/'));
+}
+
+function stripCssComments(css: string): string {
+  return css.replace(/\/\*[\s\S]*?\*\//g, '');
+}
+
+function extractPalette(cssTexts: string[]): FoundationTokens['palette'] {
+  const candidates = new Map<string, ColorCandidate>();
+  let index = 0;
+
+  for (const css of cssTexts) {
+    for (const declaration of css.matchAll(COLOR_DECL_RE)) {
+      const property = declaration[1] ?? '';
+      const value = declaration[2] ?? '';
+      const name = property.startsWith('--') ? nameFromToken(property) : undefined;
+      for (const colorMatch of value.matchAll(COLOR_VALUE_RE)) {
+        addColor(candidates, normalizeColor(colorMatch[0]), index, name);
+        index += 1;
+      }
+    }
+  }
+
+  return Array.from(candidates.values())
+    .sort(compareColorCandidates)
+    .slice(0, MAX_PALETTE_COLORS)
+    .map((candidate, paletteIndex) => ({
+      name: candidate.name ?? `Color ${paletteIndex + 1}`,
+      color: candidate.color,
+    }));
+}
+
+function addColor(
+  candidates: Map<string, ColorCandidate>,
+  color: string,
+  firstIndex: number,
+  name: string | undefined
+): void {
+  const existing = candidates.get(color);
+  if (existing) {
+    existing.count += 1;
+    if (!existing.name && name) existing.name = name;
+    return;
+  }
+
+  candidates.set(color, {
+    color,
+    count: 1,
+    firstIndex,
+    ...(name ? { name } : {}),
+  });
+}
+
+function compareColorCandidates(a: ColorCandidate, b: ColorCandidate): number {
+  return b.count - a.count || a.firstIndex - b.firstIndex || a.color.localeCompare(b.color);
+}
+
+function normalizeColor(color: string): string {
+  const trimmed = color.trim().replace(/\s+/g, ' ');
+  return trimmed.startsWith('#') ? trimmed.toLowerCase() : trimmed;
+}
+
+function extractTypography(cssTexts: string[]): FoundationTokens['typography'] {
+  const candidates = new Map<string, FontCandidate>();
+  let index = 0;
+
+  for (const css of cssTexts) {
+    for (const match of css.matchAll(FONT_DECL_RE)) {
+      const family = normalizeFontFamily(match[1] ?? '');
+      if (!family) continue;
+
+      const selector = selectorForDeclaration(css, match.index ?? 0);
+      const candidate = candidates.get(family) ?? {
+        family,
+        count: 0,
+        firstIndex: index,
+        bodyCount: 0,
+        displayCount: 0,
+      };
+
+      candidate.count += 1;
+      if (isBodySelector(selector)) candidate.bodyCount += 1;
+      if (isDisplaySelector(selector)) candidate.displayCount += 1;
+      candidates.set(family, candidate);
+      index += 1;
+    }
+  }
+
+  const ranked = Array.from(candidates.values()).sort(compareFontCandidates);
+  if (ranked.length === 0) return {};
+
+  const body = selectFont(ranked, 'bodyCount')?.family ?? ranked[0]?.family;
+  const display = selectFont(ranked, 'displayCount')?.family ?? ranked.find((font) => font.family !== body)?.family ?? body;
+
+  return {
+    ...(body ? { body } : {}),
+    ...(display ? { display } : {}),
+  };
+}
+
+function normalizeFontFamily(value: string): string {
+  return value.replace(/\s*!important\s*$/i, '').replace(/\s+/g, ' ').trim();
+}
+
+function selectorForDeclaration(css: string, declarationIndex: number): string {
+  const blockStart = css.lastIndexOf('{', declarationIndex);
+  if (blockStart === -1) return '';
+
+  const previousBlockEnd = css.lastIndexOf('}', blockStart);
+  return css.slice(previousBlockEnd + 1, blockStart).trim();
+}
+
+function isBodySelector(selector: string): boolean {
+  return /(?:^|[\s,{>+~])(?:html|body|main|article|p)(?:$|[\s,.#:>+~])/i.test(selector);
+}
+
+function isDisplaySelector(selector: string): boolean {
+  return /(?:^|[\s,{>+~.])(?:h[1-6]|heading|title|display|hero)(?:$|[\s,.#:>+~-])/i.test(selector);
+}
+
+function compareFontCandidates(a: FontCandidate, b: FontCandidate): number {
+  return b.count - a.count || a.firstIndex - b.firstIndex || a.family.localeCompare(b.family);
+}
+
+function selectFont(
+  candidates: FontCandidate[],
+  preferredCount: 'bodyCount' | 'displayCount'
+): FontCandidate | undefined {
+  return [...candidates]
+    .sort(
+      (a, b) =>
+        b[preferredCount] - a[preferredCount] ||
+        b.count - a.count ||
+        a.firstIndex - b.firstIndex ||
+        a.family.localeCompare(b.family)
+    )
+    .find((candidate) => candidate[preferredCount] > 0);
+}
+
+function extractBreakpoints(cssTexts: string[]): FoundationTokens['breakpoints'] {
+  const widths = new Set<number>();
+
+  for (const css of cssTexts) {
+    for (const media of css.matchAll(MEDIA_RE)) {
+      for (const width of media[0].matchAll(MEDIA_WIDTH_RE)) {
+        widths.add(Number(width[1]));
+      }
+    }
+  }
+
+  const sorted = Array.from(widths).filter(Number.isInteger).sort((a, b) => a - b);
+  return {
+    ...(sorted[0] !== undefined ? { md: `${sorted[0]}px` } : {}),
+    ...(sorted[1] !== undefined ? { lg: `${sorted[1]}px` } : {}),
+    ...(sorted[2] !== undefined ? { xl: `${sorted[2]}px` } : {}),
+  };
+}
+
+function coercePalette(value: unknown): FoundationTokens['palette'] | undefined {
+  if (Array.isArray(value)) {
+    return value.flatMap((entry, index) => {
+      if (typeof entry === 'string') {
+        const color = normalizeColor(entry);
+        return color ? [{ name: `Color ${index + 1}`, color }] : [];
+      }
+
+      if (!isRecord(entry) || typeof entry.color !== 'string') return [];
+      const name = typeof entry.name === 'string' && entry.name.trim() ? entry.name.trim() : `Color ${index + 1}`;
+      return [{ name, color: normalizeColor(entry.color) }];
+    });
+  }
+
+  if (!isRecord(value)) return undefined;
+  return Object.entries(value).flatMap(([name, color]) =>
+    typeof color === 'string' ? [{ name: nameFromToken(name) ?? name, color: normalizeColor(color) }] : []
+  );
+}
+
+function coerceTypography(value: unknown): FoundationTokens['typography'] | undefined {
+  if (!isRecord(value)) return undefined;
+
+  const body = typeof value.body === 'string' ? normalizeFontFamily(value.body) : undefined;
+  const display = typeof value.display === 'string' ? normalizeFontFamily(value.display) : undefined;
+
+  return {
+    ...(body ? { body } : {}),
+    ...(display ? { display } : {}),
+  };
+}
+
+function coerceBreakpoints(value: unknown): FoundationTokens['breakpoints'] | undefined {
+  if (!isRecord(value)) return undefined;
+
+  return {
+    ...coerceBreakpoint('md', value.md),
+    ...coerceBreakpoint('lg', value.lg),
+    ...coerceBreakpoint('xl', value.xl),
+  };
+}
+
+function coerceBreakpoint(
+  key: keyof FoundationTokens['breakpoints'],
+  value: unknown
+): FoundationTokens['breakpoints'] {
+  if (typeof value === 'number' && Number.isInteger(value)) return { [key]: `${value}px` };
+  if (typeof value === 'string' && value.trim()) return { [key]: value.trim() };
+  return {};
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function nameFromToken(token: string): string | undefined {
+  const words = token
+    .replace(/^--/, '')
+    .replace(/\bcolor\b/g, '')
+    .split(/[-_\s]+/)
+    .map((word) => word.trim())
+    .filter(Boolean);
+
+  if (words.length === 0) return undefined;
+  return words.map((word) => word[0]?.toUpperCase() + word.slice(1)).join(' ');
+}
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 89315a11..4a18572e 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -1,12 +1,12 @@
-export {
-  assemble,
-  foundation,
-  reconstruct,
-  siteToTheme,
-  writeTheme,
-} from './stages.js';
+export { assemble } from './assemble.js';
+export { foundation } from './foundation.js';
 export { ingest } from './ingest.js';
+export { reconstruct } from './reconstruct.js';
 export { sectionExtract } from './section-extract.js';
+export { siteToTheme } from './site-to-theme.js';
+export { lintThemeJson } from './theme-json-lint.js';
+export { writeTheme } from './write-theme.js';
 
 export type * from './section-spec.js';
 export type * from './types.js';
+export type { ThemeJsonLintResult } from './theme-json-lint.js';
diff --git a/packages/blocks-engine/src/theme/reconstruct.ts b/packages/blocks-engine/src/theme/reconstruct.ts
index 34ad84fa..df4e38e6 100644
--- a/packages/blocks-engine/src/theme/reconstruct.ts
+++ b/packages/blocks-engine/src/theme/reconstruct.ts
@@ -1 +1,95 @@
-export { reconstruct } from './stages.js';
+import { convert } from '../convert.js';
+import { escapeHtmlAttr, escapeHtmlText } from '../escape.js';
+import type { WorkerPool } from '../pool/types.js';
+import type { SectionSpec, SectionSpecButton, SectionSpecImage } from './section-spec.js';
+import type { SectionBlocks, SiteToThemeHooks, StageCtx } from './types.js';
+
+const BLOCK_COMMENT_RE = /<!--\s+wp:/;
+const HTML_ISLAND_RE = /<!--\s+wp:(?:core\/)?html(?:\s|-->|{)/;
+
+function nonEmpty(value: string | null | undefined): string | null {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function imageHtml(image: SectionSpecImage): string | null {
+  const src = nonEmpty(image.url) ?? nonEmpty(image.sourceUrl);
+  if (!src) return null;
+
+  const alt = escapeHtmlAttr(image.alt);
+  return `<figure><img src="${escapeHtmlAttr(src)}" alt="${alt}"></figure>`;
+}
+
+function buttonHtml(button: SectionSpecButton): string | null {
+  const label = nonEmpty(button.label);
+  if (!label) return null;
+
+  const href = nonEmpty(button.href) ?? '#';
+  return `<p><a href="${escapeHtmlAttr(href)}">${escapeHtmlText(label)}</a></p>`;
+}
+
+function semanticFallbackHtml(spec: SectionSpec): string {
+  const fragments: string[] = [];
+
+  for (const [index, heading] of spec.headings.entries()) {
+    const text = nonEmpty(heading);
+    if (!text) continue;
+
+    const level = index === 0 ? 2 : 3;
+    fragments.push(`<h${level}>${escapeHtmlText(text)}</h${level}>`);
+  }
+
+  for (const body of spec.bodyText) {
+    const text = nonEmpty(body);
+    if (text) fragments.push(`<p>${escapeHtmlText(text)}</p>`);
+  }
+
+  const structuredButtons =
+    spec.buttons?.map(buttonHtml).filter((html): html is string => html !== null) ?? [];
+  const labelButtons = spec.buttonLabels
+    .map((label) => nonEmpty(label))
+    .filter((label): label is string => label !== null)
+    .map((label) => `<p><a href="#">${escapeHtmlText(label)}</a></p>`);
+  const buttons = structuredButtons.length > 0 ? structuredButtons : labelButtons;
+  fragments.push(...buttons);
+
+  fragments.push(...spec.images.map(imageHtml).filter((html): html is string => html !== null));
+
+  return fragments.length > 0 ? `<section>${fragments.join('')}</section>` : '<section></section>';
+}
+
+function sectionInputHtml(spec: SectionSpec): string {
+  return spec.sectionHtml?.trim() ? spec.sectionHtml : semanticFallbackHtml(spec);
+}
+
+function skeletonCoverage(blocks: string): number {
+  if (HTML_ISLAND_RE.test(blocks)) return 0;
+  return BLOCK_COMMENT_RE.test(blocks) ? 1 : 0;
+}
+
+export async function reconstruct(
+  specs: SectionSpec[],
+  ctx: StageCtx,
+  pool: WorkerPool,
+  hooks: SiteToThemeHooks,
+  coverageFloor: number
+): Promise<SectionBlocks[]> {
+  const sections: SectionBlocks[] = [];
+
+  for (const spec of specs) {
+    const blocks = await convert(sectionInputHtml(spec), { url: '' }, { pool });
+    const section: SectionBlocks = {
+      spec,
+      blocks,
+      coverage: skeletonCoverage(blocks),
+    };
+
+    sections.push(
+      section.coverage <= coverageFloor && hooks.onSection
+        ? await hooks.onSection(section, ctx)
+        : section,
+    );
+  }
+
+  return sections;
+}
diff --git a/packages/blocks-engine/src/theme/site-to-theme.ts b/packages/blocks-engine/src/theme/site-to-theme.ts
index bcaaa2c1..e3bb228d 100644
--- a/packages/blocks-engine/src/theme/site-to-theme.ts
+++ b/packages/blocks-engine/src/theme/site-to-theme.ts
@@ -1 +1,102 @@
-export { siteToTheme } from './stages.js';
+import { join } from 'node:path';
+
+import { createWorker } from '../pool/pool.js';
+import { assemble } from './assemble.js';
+import { foundation } from './foundation.js';
+import { ingest } from './ingest.js';
+import { reconstruct } from './reconstruct.js';
+import { sectionExtract } from './section-extract.js';
+import { writeTheme } from './write-theme.js';
+import type {
+  SectionBlocks,
+  SiteToThemeOptions,
+  StageCtx,
+  ThemeBuildResult,
+  ThemeMeta,
+} from './types.js';
+
+export async function siteToTheme(
+  srcDir: string,
+  options?: SiteToThemeOptions
+): Promise<ThemeBuildResult> {
+  const site = ingest(srcDir);
+  const warnings: string[] = [];
+  const themeMeta = normalizeThemeMeta(srcDir, options?.themeMeta);
+  const ctx: StageCtx = {
+    srcDir,
+    site,
+    themeMeta,
+    warn(message: string) {
+      warnings.push(message);
+    },
+  };
+  const ownsPool = options?.pool === undefined;
+  const pool = options?.pool ?? createWorker();
+  const outDir = options?.outDir ?? join(srcDir, 'theme');
+  const coverageFloor = options?.coverageFloor ?? 0;
+  const hooks = options?.hooks ?? {};
+  void options?.fetchImpl;
+
+  try {
+    const baseTokens = foundation(site, options?.foundationAggregates);
+    const tokens = hooks.onFoundation ? await hooks.onFoundation(baseTokens, ctx) : baseTokens;
+    const pages: Record<string, SectionBlocks[]> = {};
+
+    for (const page of site.pages) {
+      const specs = options?.sections?.[page.slug] ?? sectionExtract(page);
+      pages[page.slug] = await reconstruct(specs, ctx, pool, hooks, coverageFloor);
+    }
+
+    const assembled = assemble({ site, tokens, pages, meta: themeMeta });
+    const model = hooks.onRefine ? await hooks.onRefine(assembled, ctx) : assembled;
+    const written = await writeTheme(model, outDir);
+
+    return {
+      outDir,
+      model,
+      written,
+      tallies: {
+        pages: site.pages.length,
+        sections: Object.values(pages).reduce((sum, sections) => sum + sections.length, 0),
+        templates: Object.keys(model.templates).length,
+        parts: Object.keys(model.parts).length,
+        patterns: Object.keys(model.patterns).length,
+        assets: model.assets.length,
+        warnings: warnings.length,
+      },
+      warnings,
+    };
+  } finally {
+    if (ownsPool) {
+      await pool.stop();
+    }
+  }
+}
+
+function normalizeThemeMeta(srcDir: string, meta: Partial<ThemeMeta> | undefined): ThemeMeta {
+  const fallback = srcDir.split(/[\\/]+/).filter(Boolean).at(-1) ?? 'blocks-engine-theme';
+  const slug = slugify(meta?.slug ?? fallback);
+  return {
+    name: meta?.name ?? titleFromSlug(slug),
+    slug,
+    ...(meta?.author ? { author: meta.author } : {}),
+  };
+}
+
+function titleFromSlug(slug: string): string {
+  return slug
+    .split('-')
+    .filter(Boolean)
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join(' ') || 'Blocks Engine Theme';
+}
+
+function slugify(value: string): string {
+  return (
+    value
+      .toLowerCase()
+      .replace(/[^a-z0-9-]+/g, '-')
+      .replace(/-{2,}/g, '-')
+      .replace(/^-+|-+$/g, '') || 'blocks-engine-theme'
+  );
+}
diff --git a/packages/blocks-engine/src/theme/stages.ts b/packages/blocks-engine/src/theme/stages.ts
index c594c8aa..cc57d3cb 100644
--- a/packages/blocks-engine/src/theme/stages.ts
+++ b/packages/blocks-engine/src/theme/stages.ts
@@ -1,82 +1,5 @@
-import { BlocksEngineError } from '../errors.js';
-import type { WorkerPool } from '../pool/types.js';
-import type { SectionSpec } from './section-spec.js';
-import type {
-  FoundationAggregates,
-  FoundationTokens,
-  SectionBlocks,
-  SiteModel,
-  SitePage,
-  SiteToThemeHooks,
-  SiteToThemeOptions,
-  StageCtx,
-  ThemeBuildResult,
-  ThemeMeta,
-  ThemeModel,
-} from './types.js';
-
-export function siteToTheme(
-  srcDir: string,
-  options?: SiteToThemeOptions
-): Promise<ThemeBuildResult> {
-  throw new BlocksEngineError('not implemented', {
-    code: 'STAGE_STUB',
-    hint: 'Phase 0 skeleton',
-  });
-}
-
-export function writeTheme(model: ThemeModel, outDir: string): Promise<string[]> {
-  throw new BlocksEngineError('not implemented', {
-    code: 'STAGE_STUB',
-    hint: 'Phase 0 skeleton',
-  });
-}
-
-export function ingest(srcDir: string): SiteModel {
-  throw new BlocksEngineError('not implemented', {
-    code: 'STAGE_STUB',
-    hint: 'Phase 0 skeleton',
-  });
-}
-
-export function sectionExtract(page: SitePage): SectionSpec[] {
-  throw new BlocksEngineError('not implemented', {
-    code: 'STAGE_STUB',
-    hint: 'Phase 0 skeleton',
-  });
-}
-
-export function foundation(
-  site: SiteModel,
-  aggregates?: FoundationAggregates
-): FoundationTokens {
-  throw new BlocksEngineError('not implemented', {
-    code: 'STAGE_STUB',
-    hint: 'Phase 0 skeleton',
-  });
-}
-
-export function reconstruct(
-  specs: SectionSpec[],
-  ctx: StageCtx,
-  pool: WorkerPool,
-  hooks: SiteToThemeHooks,
-  coverageFloor: number
-): Promise<SectionBlocks[]> {
-  throw new BlocksEngineError('not implemented', {
-    code: 'STAGE_STUB',
-    hint: 'Phase 0 skeleton',
-  });
-}
-
-export function assemble(parts: {
-  site: SiteModel;
-  tokens: FoundationTokens;
-  pages: Record<string, SectionBlocks[]>;
-  meta: ThemeMeta;
-}): ThemeModel {
-  throw new BlocksEngineError('not implemented', {
-    code: 'STAGE_STUB',
-    hint: 'Phase 0 skeleton',
-  });
-}
+export { assemble } from './assemble.js';
+export { foundation } from './foundation.js';
+export { reconstruct } from './reconstruct.js';
+export { siteToTheme } from './site-to-theme.js';
+export { writeTheme } from './write-theme.js';
diff --git a/packages/blocks-engine/src/theme/theme-json-lint.ts b/packages/blocks-engine/src/theme/theme-json-lint.ts
index c69275b4..a6aa6a5b 100644
--- a/packages/blocks-engine/src/theme/theme-json-lint.ts
+++ b/packages/blocks-engine/src/theme/theme-json-lint.ts
@@ -4,6 +4,19 @@ export interface ThemeJsonLintResult {
 }
 
 export function lintThemeJson(theme: Record<string, unknown>): ThemeJsonLintResult {
-  void theme;
-  return { ok: false, errors: ['not implemented'] };
+  const errors: string[] = [];
+  if (theme.version !== 3) errors.push('theme.json version must be 3');
+  if (!theme.$schema) errors.push('theme.json must include $schema');
+  const settings = theme.settings as Record<string, unknown> | undefined;
+  const spacing = settings?.spacing as Record<string, unknown> | undefined;
+  const spacingScale = spacing?.spacingScale as Record<string, unknown> | undefined;
+  if (spacingScale && spacingScale.theme === false) {
+    errors.push(
+      'settings.spacing.spacingScale.theme:false fatals on activation; omit spacingScale when providing spacingSizes'
+    );
+  }
+  if (spacing?.spacingSizes && spacing?.spacingScale) {
+    errors.push('provide settings.spacing.spacingSizes OR spacingScale, not both');
+  }
+  return { ok: errors.length === 0, errors };
 }
diff --git a/packages/blocks-engine/src/theme/write-theme.ts b/packages/blocks-engine/src/theme/write-theme.ts
index 170bd866..17aa5b95 100644
--- a/packages/blocks-engine/src/theme/write-theme.ts
+++ b/packages/blocks-engine/src/theme/write-theme.ts
@@ -1 +1,94 @@
-export { writeTheme } from './stages.js';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, normalize } from 'node:path';
+import type { AssetFile, ThemeModel } from './types.js';
+
+type FileContent = string | Uint8Array;
+
+export async function writeTheme(model: ThemeModel, outDir: string): Promise<string[]> {
+  await mkdir(outDir, { recursive: true });
+  await Promise.all([
+    mkdir(join(outDir, 'templates'), { recursive: true }),
+    mkdir(join(outDir, 'parts'), { recursive: true }),
+    mkdir(join(outDir, 'patterns'), { recursive: true }),
+  ]);
+
+  const files: Array<[string, FileContent]> = [
+    ['style.css', model.styleCss],
+    ['theme.json', JSON.stringify(model.themeJson, null, 2) + '\n'],
+    ...recordFiles('templates', model.templates),
+    ...recordFiles('parts', model.parts),
+    ...recordFiles('patterns', model.patterns),
+  ];
+
+  for (const asset of model.assets) {
+    files.push([safeRelativePath(asset.relPath), await assetContent(asset)]);
+  }
+
+  const written: string[] = [];
+  for (const [relativePath, content] of files) {
+    const safePath = safeRelativePath(relativePath);
+    await atomicWrite(join(outDir, safePath), content);
+    written.push(safePath);
+  }
+
+  return written;
+}
+
+function recordFiles(baseDir: string, files: Record<string, string>): Array<[string, string]> {
+  return Object.entries(files)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, content]) => [recordRelativePath(baseDir, key), content]);
+}
+
+function recordRelativePath(baseDir: string, key: string): string {
+  const trimmed = key.trim();
+  if (trimmed.startsWith(`${baseDir}/`) || trimmed.includes('/')) {
+    return safeRelativePath(trimmed);
+  }
+
+  const filename = /\.[a-z0-9]+$/i.test(trimmed) ? trimmed : `${trimmed}.html`;
+  return safeRelativePath(join(baseDir, filename));
+}
+
+async function assetContent(asset: AssetFile): Promise<FileContent> {
+  if (asset.bytes) return asset.bytes;
+  if (asset.sourcePath) return readFile(asset.sourcePath);
+  return new Uint8Array();
+}
+
+async function atomicWrite(path: string, content: FileContent): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+
+  try {
+    await writeFile(tmpPath, content);
+    await rename(tmpPath, path);
+  } catch (error) {
+    await removeTmpBestEffort(tmpPath);
+    throw error;
+  }
+}
+
+async function removeTmpBestEffort(path: string): Promise<void> {
+  try {
+    const { rm } = await import('node:fs/promises');
+    await rm(path, { force: true });
+  } catch {
+    // The original write/rename failure is the actionable error.
+  }
+}
+
+function safeRelativePath(path: string): string {
+  const input = path.replace(/\\/g, '/');
+  const normalized = normalize(input).replace(/\\/g, '/');
+  if (
+    !normalized ||
+    normalized === '.' ||
+    isAbsolute(input) ||
+    normalized === '..' ||
+    normalized.startsWith('../')
+  ) {
+    throw new Error(`theme path must stay relative to outDir: ${path}`);
+  }
+  return normalized;
+}

From 2182ea5d4a24297c1cd4de633cee77395e6d0283 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 13:01:32 -0400
Subject: [PATCH 038/113] feat(theme): freeze P1-1 asset contracts

---
 .../__tests__/fixtures/site/assets/logo.png   | Bin 0 -> 68 bytes
 .../src/__tests__/fixtures/site/index.html    |   1 +
 .../src/__tests__/fixtures/site/style.css     |  16 ++++++++-
 .../blocks-engine/src/theme/assets-static.ts  |  33 ++++++++++++++++++
 packages/blocks-engine/src/theme/assets.ts    |  22 ++++++++++++
 .../blocks-engine/src/theme/font-faces.ts     |  25 +++++++++++++
 packages/blocks-engine/src/theme/index.ts     |   4 +++
 7 files changed, 100 insertions(+), 1 deletion(-)
 create mode 100644 packages/blocks-engine/src/__tests__/fixtures/site/assets/logo.png
 create mode 100644 packages/blocks-engine/src/theme/assets-static.ts
 create mode 100644 packages/blocks-engine/src/theme/assets.ts
 create mode 100644 packages/blocks-engine/src/theme/font-faces.ts

diff --git a/packages/blocks-engine/src/__tests__/fixtures/site/assets/logo.png b/packages/blocks-engine/src/__tests__/fixtures/site/assets/logo.png
new file mode 100644
index 0000000000000000000000000000000000000000..e0ccec79f1b36f25d0ea94a047499d8b63045bba
GIT binary patch
literal 68
zcmeAS@N?(olHy`uVBq!ia0vp^j3CUx0wlM}@Gt=>Zci7-kcwN$fBwreFf%hTyx+h4
QHc*(s)78&qol`;+0FQDG@c;k-

literal 0
HcmV?d00001

diff --git a/packages/blocks-engine/src/__tests__/fixtures/site/index.html b/packages/blocks-engine/src/__tests__/fixtures/site/index.html
index df1d7ec0..896d5c99 100644
--- a/packages/blocks-engine/src/__tests__/fixtures/site/index.html
+++ b/packages/blocks-engine/src/__tests__/fixtures/site/index.html
@@ -16,6 +16,7 @@
       <section id="hero">
         <h1>Build calmer block themes</h1>
         <p>Static source pages become a structured theme pipeline.</p>
+        <img src="assets/logo.png" alt="Blocks Engine mark" />
         <a class="button" href="./about.html">Learn more</a>
       </section>
       <section id="empty"></section>
diff --git a/packages/blocks-engine/src/__tests__/fixtures/site/style.css b/packages/blocks-engine/src/__tests__/fixtures/site/style.css
index 6f5bfdf9..32d13697 100644
--- a/packages/blocks-engine/src/__tests__/fixtures/site/style.css
+++ b/packages/blocks-engine/src/__tests__/fixtures/site/style.css
@@ -1,5 +1,19 @@
+@font-face {
+  font-family: "Fixture Sans";
+  src: url("assets/fixture-sans.woff2") format("woff2");
+  font-weight: 400;
+  font-style: normal;
+}
+
+@font-face {
+  font-family: "Unused Fixture";
+  src: url("assets/unused-fixture.woff2") format("woff2");
+  font-weight: 700;
+  font-style: normal;
+}
+
 body {
-  font-family: system-ui, sans-serif;
+  font-family: "Fixture Sans", system-ui, sans-serif;
   margin: 0;
 }
 
diff --git a/packages/blocks-engine/src/theme/assets-static.ts b/packages/blocks-engine/src/theme/assets-static.ts
new file mode 100644
index 00000000..209bb1a0
--- /dev/null
+++ b/packages/blocks-engine/src/theme/assets-static.ts
@@ -0,0 +1,33 @@
+import type { AssetFile, SiteModel } from './types.js';
+
+export interface StaticImgRef {
+  ref: string;
+  themeRel: string;
+  sourcePath: string;
+}
+
+export interface StaticAssetResult {
+  assets: AssetFile[];
+  imgRefsByPage: Record<string, StaticImgRef[]>;
+}
+
+export function collectStaticAssets(site: SiteModel, themeSlug: string): StaticAssetResult {
+  void site;
+  void themeSlug;
+  return stageStub('collectStaticAssets');
+}
+
+export function rewriteHtmlImageSrcs(
+  html: string,
+  refs: StaticImgRef[],
+  themeSlug: string
+): string {
+  void html;
+  void refs;
+  void themeSlug;
+  return stageStub('rewriteHtmlImageSrcs');
+}
+
+function stageStub(name: string): never {
+  throw new Error(`STAGE_STUB:${name}`);
+}
diff --git a/packages/blocks-engine/src/theme/assets.ts b/packages/blocks-engine/src/theme/assets.ts
new file mode 100644
index 00000000..56bad321
--- /dev/null
+++ b/packages/blocks-engine/src/theme/assets.ts
@@ -0,0 +1,22 @@
+import type { StaticImgRef } from './assets-static.js';
+import type { AssetInventory, StageCtx } from './types.js';
+
+export interface AssetStageResult {
+  inventory: AssetInventory;
+  imgRefsByPage: Record<string, StaticImgRef[]>;
+  fontCss: string;
+  warnings: string[];
+}
+
+export function assets(
+  ctx: StageCtx,
+  opts: { fetchImpl?: typeof fetch }
+): Promise<AssetStageResult> {
+  void ctx;
+  void opts;
+  return stageStub('assets');
+}
+
+function stageStub(name: string): never {
+  throw new Error(`STAGE_STUB:${name}`);
+}
diff --git a/packages/blocks-engine/src/theme/font-faces.ts b/packages/blocks-engine/src/theme/font-faces.ts
new file mode 100644
index 00000000..c0d20662
--- /dev/null
+++ b/packages/blocks-engine/src/theme/font-faces.ts
@@ -0,0 +1,25 @@
+export interface ParsedFontFace {
+  family: string;
+  src: string;
+  format?: string;
+  weight?: string;
+  style?: string;
+}
+
+export function parseFontFaces(...cssOrHtml: string[]): ParsedFontFace[] {
+  void cssOrHtml;
+  return stageStub('parseFontFaces');
+}
+
+export function stripUnusedFontFaces(
+  css: string,
+  usageText: string
+): { css: string; removed: number } {
+  void css;
+  void usageText;
+  return stageStub('stripUnusedFontFaces');
+}
+
+function stageStub(name: string): never {
+  throw new Error(`STAGE_STUB:${name}`);
+}
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 4a18572e..0d207e4e 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -1,4 +1,5 @@
 export { assemble } from './assemble.js';
+export { assets } from './assets.js';
 export { foundation } from './foundation.js';
 export { ingest } from './ingest.js';
 export { reconstruct } from './reconstruct.js';
@@ -7,6 +8,9 @@ export { siteToTheme } from './site-to-theme.js';
 export { lintThemeJson } from './theme-json-lint.js';
 export { writeTheme } from './write-theme.js';
 
+export type * from './assets-static.js';
+export type * from './assets.js';
+export type * from './font-faces.js';
 export type * from './section-spec.js';
 export type * from './types.js';
 export type { ThemeJsonLintResult } from './theme-json-lint.js';

From 7a12649df3f181eefd0f32b56e15e696551163c9 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 13:12:55 -0400
Subject: [PATCH 039/113] feat(theme): implement P1-1 asset stage

---
 .../src/__tests__/theme-assets-stage.test.ts  |  37 ++++
 .../src/__tests__/theme-assets-static.test.ts | 143 +++++++++++++
 .../src/__tests__/theme-font-faces.test.ts    |  88 ++++++++
 .../blocks-engine/src/theme/assets-static.ts  | 197 +++++++++++++++++-
 packages/blocks-engine/src/theme/assets.ts    | 120 ++++++++++-
 .../blocks-engine/src/theme/font-faces.ts     | 148 ++++++++++++-
 6 files changed, 710 insertions(+), 23 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-assets-stage.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/theme-assets-static.test.ts
 create mode 100644 packages/blocks-engine/src/__tests__/theme-font-faces.test.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-assets-stage.test.ts b/packages/blocks-engine/src/__tests__/theme-assets-stage.test.ts
new file mode 100644
index 00000000..305cdfd0
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-assets-stage.test.ts
@@ -0,0 +1,37 @@
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import { assets, ingest, type StageCtx } from '../theme/index.js';
+
+const fixtureRoot = join(import.meta.dirname, 'fixtures/site');
+
+function fixtureCtx(): StageCtx {
+  const site = ingest(fixtureRoot);
+
+  return {
+    srcDir: fixtureRoot,
+    site,
+    themeMeta: {
+      name: 'Fixture Theme',
+      slug: 'fixture-theme',
+    },
+    warn() {},
+  };
+}
+
+describe('theme assets stage', () => {
+  it('returns static inventory without wiring font CSS in P1-1', async () => {
+    const result = await assets(fixtureCtx(), {});
+
+    expect(result.inventory.assets).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          relPath: 'assets/logo.png',
+        }),
+      ])
+    );
+    expect(result.fontCss).toBe('');
+    expect(result.warnings).toEqual([]);
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/theme-assets-static.test.ts b/packages/blocks-engine/src/__tests__/theme-assets-static.test.ts
new file mode 100644
index 00000000..b91dffa4
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-assets-static.test.ts
@@ -0,0 +1,143 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import {
+  collectStaticAssets,
+  rewriteHtmlImageSrcs,
+  type StaticImgRef,
+} from '../theme/assets-static.js';
+import { ingest } from '../theme/ingest.js';
+import type { SiteModel } from '../theme/types.js';
+
+const fixtureRoot = join(import.meta.dirname, 'fixtures/site');
+
+function withTempSite<T>(fn: (paths: { parent: string; root: string }) => T): T {
+  const parent = mkdtempSync(join(tmpdir(), 'blocks-engine-theme-assets-static-'));
+  const root = join(parent, 'site');
+  mkdirSync(root);
+
+  try {
+    return fn({ parent, root });
+  } finally {
+    rmSync(parent, { recursive: true, force: true });
+  }
+}
+
+describe('theme static assets', () => {
+  it('collects fixture image assets with source paths and page refs', () => {
+    const site = ingest(fixtureRoot);
+    const sourcePath = join(fixtureRoot, 'assets/logo.png');
+
+    const result = collectStaticAssets(site, 'calm-theme');
+
+    expect(result.assets).toEqual([
+      {
+        relPath: 'assets/logo.png',
+        sourcePath,
+      },
+    ]);
+    expect(result.imgRefsByPage.home).toEqual([
+      {
+        ref: 'assets/logo.png',
+        themeRel: 'assets/logo.png',
+        sourcePath,
+      },
+    ]);
+    expect(result.imgRefsByPage.about).toBeUndefined();
+  });
+
+  it('rewrites double-quoted and single-quoted image src values', () => {
+    const refs: StaticImgRef[] = [
+      {
+        ref: 'assets/logo.png',
+        themeRel: 'assets/logo.png',
+        sourcePath: '/tmp/logo.png',
+      },
+      {
+        ref: 'images/hero.jpg',
+        themeRel: 'assets/images/hero.jpg',
+        sourcePath: '/tmp/hero.jpg',
+      },
+    ];
+
+    expect(
+      rewriteHtmlImageSrcs(
+        `<img src="assets/logo.png"><img alt="Hero" src='images/hero.jpg'>`,
+        refs,
+        'calm-theme'
+      )
+    ).toBe(
+      `<img src="/wp-content/themes/calm-theme/assets/logo.png"><img alt="Hero" src='/wp-content/themes/calm-theme/assets/images/hero.jpg'>`
+    );
+  });
+
+  it('leaves unrelated src values untouched', () => {
+    const refs: StaticImgRef[] = [
+      {
+        ref: 'assets/logo.png',
+        themeRel: 'assets/logo.png',
+        sourcePath: '/tmp/logo.png',
+      },
+    ];
+    const html = [
+      `<script src="assets/logo.png"></script>`,
+      `<img src="assets/other.png">`,
+      `<img data-src="assets/logo.png">`,
+      `<source src="assets/logo.png">`,
+    ].join('');
+
+    expect(rewriteHtmlImageSrcs(html, refs, 'calm-theme')).toBe(html);
+  });
+
+  it('ignores non-local, missing, and escaping image refs while deduping assets', () => {
+    withTempSite(({ parent, root }) => {
+      mkdirSync(join(root, 'assets'));
+      mkdirSync(join(root, 'pages'));
+      writeFileSync(join(root, 'assets/logo.png'), 'png', 'utf8');
+      writeFileSync(join(parent, 'outside.png'), 'png', 'utf8');
+
+      const site: SiteModel = {
+        root,
+        pages: [
+          {
+            relPath: 'pages/index.html',
+            slug: 'home',
+            title: 'Home',
+            html: [
+              `<img src="../assets/logo.png">`,
+              `<img src="/assets/logo.png">`,
+              `<img src="https://example.test/logo.png">`,
+              `<img src="//example.test/logo.png">`,
+              `<img src="data:image/png;base64,AA==">`,
+              `<img src="#fragment">`,
+              `<img src="missing.png">`,
+              `<img src="../../outside.png">`,
+            ].join(''),
+          },
+        ],
+      };
+
+      const result = collectStaticAssets(site, 'calm-theme');
+
+      expect(result.assets).toEqual([
+        {
+          relPath: 'assets/logo.png',
+          sourcePath: join(root, 'assets/logo.png'),
+        },
+      ]);
+      expect(result.imgRefsByPage.home).toEqual([
+        {
+          ref: '../assets/logo.png',
+          themeRel: 'assets/logo.png',
+          sourcePath: join(root, 'assets/logo.png'),
+        },
+        {
+          ref: '/assets/logo.png',
+          themeRel: 'assets/logo.png',
+          sourcePath: join(root, 'assets/logo.png'),
+        },
+      ]);
+    });
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/theme-font-faces.test.ts b/packages/blocks-engine/src/__tests__/theme-font-faces.test.ts
new file mode 100644
index 00000000..21a710f9
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-font-faces.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import { parseFontFaces, stripUnusedFontFaces } from '../theme/font-faces.js';
+
+describe('parseFontFaces', () => {
+  it('parses family, preferred source, format, normalized weight, and style', () => {
+    const faces = parseFontFaces(`
+      @font-face {
+        font-family: "Acme Display";
+        src: url("/fonts/acme.woff") format("woff"),
+          url("/fonts/acme.woff2?cache=1") format("woff2");
+        font-weight: bold;
+        font-style: oblique 12deg;
+      }
+    `);
+
+    expect(faces).toEqual([
+      {
+        family: 'Acme Display',
+        src: '/fonts/acme.woff2?cache=1',
+        format: 'woff2',
+        weight: '700',
+        style: 'oblique',
+      },
+    ]);
+  });
+
+  it('filters generic CSS font families', () => {
+    const faces = parseFontFaces(`
+      @font-face {
+        font-family: serif;
+        src: url("/fonts/serif.woff2") format("woff2");
+      }
+      @font-face {
+        font-family: system-ui;
+        src: url("/fonts/system.woff2") format("woff2");
+      }
+    `);
+
+    expect(faces).toEqual([]);
+  });
+
+  it('keeps remote gstatic and typekit faces for later self-hosting', () => {
+    const faces = parseFontFaces(`
+      @font-face {
+        font-family: "Roboto";
+        src: url("https://fonts.gstatic.com/s/roboto/v30/roboto.woff2") format("woff2");
+        font-weight: 400;
+      }
+      @font-face {
+        font-family: "Adobe Face";
+        src: url("https://use.typekit.net/abc123.woff") format("woff");
+        font-style: italic;
+      }
+    `);
+
+    expect(faces.map((face) => face.src)).toEqual([
+      'https://fonts.gstatic.com/s/roboto/v30/roboto.woff2',
+      'https://use.typekit.net/abc123.woff',
+    ]);
+  });
+
+  it('deduplicates identical parsed faces', () => {
+    const block = `
+      @font-face {
+        font-family: "Acme";
+        src: url("/fonts/acme.woff2") format("woff2");
+        font-weight: normal;
+      }
+    `;
+
+    expect(parseFontFaces(block, block)).toHaveLength(1);
+  });
+});
+
+describe('stripUnusedFontFaces', () => {
+  it('removes unused font-face blocks while keeping used blocks', () => {
+    const usedFace = `@font-face{font-family:'Libre Baskerville';src:url(/fonts/libre.woff2) format("woff2")}`;
+    const unusedFace = `@font-face{font-family:'Unused Sans';src:url(/fonts/unused.woff2) format("woff2")}`;
+    const usage = `.title{font-family:"Libre Baskerville",serif}`;
+
+    const result = stripUnusedFontFaces(`${usedFace}\n${unusedFace}\n${usage}`, usage);
+
+    expect(result.removed).toBe(1);
+    expect(result.css).toContain("font-family:'Libre Baskerville'");
+    expect(result.css).not.toContain('Unused Sans');
+    expect(result.css).toContain(usage);
+  });
+});
diff --git a/packages/blocks-engine/src/theme/assets-static.ts b/packages/blocks-engine/src/theme/assets-static.ts
index 209bb1a0..b525033c 100644
--- a/packages/blocks-engine/src/theme/assets-static.ts
+++ b/packages/blocks-engine/src/theme/assets-static.ts
@@ -1,4 +1,6 @@
-import type { AssetFile, SiteModel } from './types.js';
+import { statSync } from 'node:fs';
+import { dirname, extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import type { AssetFile, SiteModel, SitePage } from './types.js';
 
 export interface StaticImgRef {
   ref: string;
@@ -11,10 +13,55 @@ export interface StaticAssetResult {
   imgRefsByPage: Record<string, StaticImgRef[]>;
 }
 
+const IMG_TAG_RE = /<img\b[^>]*>/gi;
+const SRC_ATTR_RE = /(\s+src\s*=\s*)(["'])([\s\S]*?)\2/gi;
+const FIRST_SRC_ATTR_RE = /(\s+src\s*=\s*)(["'])([\s\S]*?)\2/i;
+const URL_SCHEME_OR_PROTOCOL_RELATIVE_RE = /^(?:[a-z][a-z\d+.-]*:|\/\/)/i;
+
 export function collectStaticAssets(site: SiteModel, themeSlug: string): StaticAssetResult {
-  void site;
   void themeSlug;
-  return stageStub('collectStaticAssets');
+
+  const root = resolve(site.root);
+  const sourceToThemeRel = new Map<string, string>();
+  const themeRelToSource = new Map<string, string>();
+  const assetsByThemeRel = new Map<string, AssetFile>();
+  const imgRefsByPage: Record<string, StaticImgRef[]> = {};
+
+  for (const page of sortedPages(site.pages)) {
+    const refs: StaticImgRef[] = [];
+    const refsSeenOnPage = new Set<string>();
+
+    for (const ref of extractImgSrcRefs(page.html)) {
+      const sourcePath = resolveLocalImagePath(root, page, ref);
+      if (!sourcePath) continue;
+
+      const themeRel = themeRelForSource(
+        root,
+        sourcePath,
+        sourceToThemeRel,
+        themeRelToSource
+      );
+      const pageRefKey = `${ref}\0${themeRel}\0${sourcePath}`;
+      if (refsSeenOnPage.has(pageRefKey)) continue;
+
+      refsSeenOnPage.add(pageRefKey);
+      refs.push({ ref, themeRel, sourcePath });
+
+      if (!assetsByThemeRel.has(themeRel)) {
+        assetsByThemeRel.set(themeRel, {
+          relPath: themeRel,
+          sourcePath,
+        });
+      }
+    }
+
+    if (refs.length > 0) {
+      imgRefsByPage[page.slug] = refs;
+    }
+  }
+
+  const assets = [...assetsByThemeRel.values()].sort(compareAssetFiles);
+  return { assets, imgRefsByPage };
 }
 
 export function rewriteHtmlImageSrcs(
@@ -22,12 +69,144 @@ export function rewriteHtmlImageSrcs(
   refs: StaticImgRef[],
   themeSlug: string
 ): string {
-  void html;
-  void refs;
-  void themeSlug;
-  return stageStub('rewriteHtmlImageSrcs');
+  const replacements = new Map<string, string>();
+  for (const ref of refs) {
+    if (!replacements.has(ref.ref)) {
+      replacements.set(ref.ref, themeAssetUrl(themeSlug, ref.themeRel));
+    }
+  }
+
+  if (replacements.size === 0) return html;
+
+  return html.replace(IMG_TAG_RE, (tag) =>
+    tag.replace(SRC_ATTR_RE, (match, prefix: string, quote: string, ref: string) => {
+      const replacement = replacements.get(ref);
+      return replacement ? `${prefix}${quote}${replacement}${quote}` : match;
+    })
+  );
+}
+
+function sortedPages(pages: SitePage[]): SitePage[] {
+  return [...pages].sort((a, b) => {
+    const rel = a.relPath.localeCompare(b.relPath);
+    if (rel !== 0) return rel;
+    return a.slug.localeCompare(b.slug);
+  });
+}
+
+function extractImgSrcRefs(html: string): string[] {
+  const refs: string[] = [];
+  for (const tagMatch of html.matchAll(IMG_TAG_RE)) {
+    const srcAttr = FIRST_SRC_ATTR_RE.exec(tagMatch[0]);
+    if (srcAttr?.[3] !== undefined) {
+      refs.push(srcAttr[3]);
+    }
+  }
+  return refs;
+}
+
+function resolveLocalImagePath(root: string, page: SitePage, ref: string): string | null {
+  const cleanRef = cleanLocalRef(ref);
+  if (!cleanRef) return null;
+
+  const sourcePath = cleanRef.startsWith('/')
+    ? resolve(root, `.${cleanRef}`)
+    : resolve(root, dirname(page.relPath), cleanRef);
+
+  if (!isInside(root, sourcePath) || !isFile(sourcePath)) return null;
+  return sourcePath;
+}
+
+function cleanLocalRef(ref: string): string | null {
+  const trimmed = ref.trim();
+  if (!trimmed || trimmed.startsWith('#')) return null;
+  if (URL_SCHEME_OR_PROTOCOL_RELATIVE_RE.test(trimmed)) return null;
+
+  const withoutHash = trimmed.split('#', 1)[0] ?? '';
+  const withoutQuery = withoutHash.split('?', 1)[0] ?? '';
+  if (!withoutQuery) return null;
+
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(withoutQuery);
+  } catch {
+    return null;
+  }
+
+  const clean = decoded.trim();
+  if (!clean || clean.startsWith('#') || clean.includes('\0')) return null;
+  if (URL_SCHEME_OR_PROTOCOL_RELATIVE_RE.test(clean)) return null;
+  return clean;
+}
+
+function themeRelForSource(
+  root: string,
+  sourcePath: string,
+  sourceToThemeRel: Map<string, string>,
+  themeRelToSource: Map<string, string>
+): string {
+  const existing = sourceToThemeRel.get(sourcePath);
+  if (existing) return existing;
+
+  const preferred = preferredThemeRel(root, sourcePath);
+  const themeRel = uniqueThemeRel(preferred, sourcePath, themeRelToSource);
+  sourceToThemeRel.set(sourcePath, themeRel);
+  themeRelToSource.set(themeRel, sourcePath);
+  return themeRel;
+}
+
+function preferredThemeRel(root: string, sourcePath: string): string {
+  const sourceRel = toPosixPath(relative(root, sourcePath));
+  return sourceRel === 'assets' || sourceRel.startsWith('assets/')
+    ? sourceRel
+    : `assets/${sourceRel}`;
+}
+
+function uniqueThemeRel(
+  preferred: string,
+  sourcePath: string,
+  themeRelToSource: Map<string, string>
+): string {
+  if (!themeRelToSource.has(preferred) || themeRelToSource.get(preferred) === sourcePath) {
+    return preferred;
+  }
+
+  const ext = extname(preferred);
+  const base = ext ? preferred.slice(0, -ext.length) : preferred;
+  let suffix = 2;
+  let candidate = `${base}-${suffix}${ext}`;
+
+  while (themeRelToSource.has(candidate) && themeRelToSource.get(candidate) !== sourcePath) {
+    suffix += 1;
+    candidate = `${base}-${suffix}${ext}`;
+  }
+
+  return candidate;
+}
+
+function compareAssetFiles(a: AssetFile, b: AssetFile): number {
+  const rel = a.relPath.localeCompare(b.relPath);
+  if (rel !== 0) return rel;
+  return (a.sourcePath ?? '').localeCompare(b.sourcePath ?? '');
+}
+
+function themeAssetUrl(themeSlug: string, themeRel: string): string {
+  return `/wp-content/themes/${themeSlug}/${themeRel.replace(/^\/+/, '')}`;
+}
+
+function isInside(root: string, file: string): boolean {
+  const rel = relative(root, file);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
 }
 
-function stageStub(name: string): never {
-  throw new Error(`STAGE_STUB:${name}`);
+function toPosixPath(path: string): string {
+  return path.split(sep).join('/');
 }
diff --git a/packages/blocks-engine/src/theme/assets.ts b/packages/blocks-engine/src/theme/assets.ts
index 56bad321..249ab8e2 100644
--- a/packages/blocks-engine/src/theme/assets.ts
+++ b/packages/blocks-engine/src/theme/assets.ts
@@ -1,5 +1,8 @@
-import type { StaticImgRef } from './assets-static.js';
-import type { AssetInventory, StageCtx } from './types.js';
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { collectStaticAssets, type StaticImgRef } from './assets-static.js';
+import { parseFontFaces, type ParsedFontFace } from './font-faces.js';
+import type { AssetInventory, SitePage, StageCtx } from './types.js';
 
 export interface AssetStageResult {
   inventory: AssetInventory;
@@ -12,11 +15,114 @@ export function assets(
   ctx: StageCtx,
   opts: { fetchImpl?: typeof fetch }
 ): Promise<AssetStageResult> {
-  void ctx;
-  void opts;
-  return stageStub('assets');
+  void opts.fetchImpl;
+
+  const { assets, imgRefsByPage } = collectStaticAssets(ctx.site, ctx.themeMeta.slug);
+  const parsedFontFaces: ParsedFontFace[] = parseFontFaces(...collectLinkedStylesheetCss(ctx));
+  void parsedFontFaces;
+
+  return Promise.resolve({
+    inventory: { assets },
+    imgRefsByPage,
+    fontCss: '',
+    warnings: [],
+  });
+}
+
+function collectLinkedStylesheetCss(ctx: StageCtx): string[] {
+  const root = resolve(ctx.srcDir);
+  const cssByPath = new Map<string, string>();
+
+  for (const page of sortedPages(ctx.site.pages)) {
+    for (const tag of page.html.matchAll(/<link\b[^>]*>/gi)) {
+      const attrs = attributesFromTag(tag[0]);
+      const rel = (attrs.get('rel') ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+      if (!rel.includes('stylesheet')) continue;
+
+      const cssPath = resolveLocalStylesheet(root, page, attrs.get('href'));
+      if (!cssPath || cssByPath.has(cssPath)) continue;
+
+      try {
+        cssByPath.set(cssPath, readFileSync(cssPath, 'utf8'));
+      } catch {
+        // P1-1 treats linked CSS as inventory readiness only.
+      }
+    }
+  }
+
+  return Array.from(cssByPath.entries())
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([, css]) => css);
+}
+
+function resolveLocalStylesheet(
+  root: string,
+  page: SitePage,
+  href: string | undefined
+): string | null {
+  const cleanHref = cleanLocalRef(href);
+  if (!cleanHref) return null;
+
+  const path = cleanHref.startsWith('/')
+    ? resolve(root, `.${cleanHref}`)
+    : resolve(root, dirname(page.relPath), cleanHref);
+
+  if (!isInside(root, path) || !isFile(path)) return null;
+  return path;
+}
+
+function cleanLocalRef(ref: string | undefined): string | null {
+  const trimmed = ref?.trim();
+  if (!trimmed || trimmed.startsWith('#')) return null;
+  if (/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(trimmed)) return null;
+
+  const withoutHash = trimmed.split('#', 1)[0] ?? '';
+  const withoutQuery = withoutHash.split('?', 1)[0] ?? '';
+  if (!withoutQuery) return null;
+
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(withoutQuery);
+  } catch {
+    return null;
+  }
+
+  const clean = decoded.trim();
+  if (!clean || clean.startsWith('#') || clean.includes('\0')) return null;
+  if (/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(clean)) return null;
+  return clean;
+}
+
+function isInside(root: string, file: string): boolean {
+  const rel = relative(root, file);
+  return rel === '' || (!rel.startsWith('..') && !rel.startsWith('/'));
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function attributesFromTag(tag: string): Map<string, string> {
+  const attrs = new Map<string, string>();
+  const attrPattern = /([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+
+  for (const match of tag.matchAll(attrPattern)) {
+    const key = match[1]?.toLowerCase();
+    if (!key || key === 'link') continue;
+    attrs.set(key, match[2] ?? match[3] ?? match[4] ?? '');
+  }
+
+  return attrs;
 }
 
-function stageStub(name: string): never {
-  throw new Error(`STAGE_STUB:${name}`);
+function sortedPages(pages: SitePage[]): SitePage[] {
+  return [...pages].sort((a, b) => {
+    const rel = a.relPath.localeCompare(b.relPath);
+    if (rel !== 0) return rel;
+    return a.slug.localeCompare(b.slug);
+  });
 }
diff --git a/packages/blocks-engine/src/theme/font-faces.ts b/packages/blocks-engine/src/theme/font-faces.ts
index c0d20662..c25b089d 100644
--- a/packages/blocks-engine/src/theme/font-faces.ts
+++ b/packages/blocks-engine/src/theme/font-faces.ts
@@ -6,20 +6,154 @@ export interface ParsedFontFace {
   style?: string;
 }
 
+const FONT_EXTENSIONS = new Set(['woff2', 'woff', 'ttf', 'otf', 'eot', 'svg']);
+const GENERIC_FAMILIES = new Set([
+  'serif',
+  'sans-serif',
+  'monospace',
+  'cursive',
+  'fantasy',
+  'system-ui',
+  'ui-serif',
+  'ui-sans-serif',
+  'ui-monospace',
+  'ui-rounded',
+  'emoji',
+  'math',
+  'fangsong',
+  'inherit',
+  'initial',
+  'unset',
+  'revert',
+  'revert-layer',
+]);
+const FONT_FACE_BLOCK = /@font-face\s*\{[^{}]*\}/gi;
+
 export function parseFontFaces(...cssOrHtml: string[]): ParsedFontFace[] {
-  void cssOrHtml;
-  return stageStub('parseFontFaces');
+  const faces: ParsedFontFace[] = [];
+  const seen = new Set<string>();
+
+  for (const input of cssOrHtml) {
+    if (!input) continue;
+
+    const blockRe = /@font-face\s*\{([^{}]*)\}/gi;
+    let block: RegExpExecArray | null;
+    while ((block = blockRe.exec(input)) !== null) {
+      const body = block[1];
+      const family = normalizeFamily(readDeclaration(body, 'font-family'));
+      if (!family || GENERIC_FAMILIES.has(family.toLowerCase())) continue;
+
+      const srcDecl = readDeclaration(body, 'src');
+      if (!srcDecl) continue;
+
+      const picked = pickBestFontUrl(srcDecl);
+      if (!picked) continue;
+
+      const weight = normalizeWeight(readDeclaration(body, 'font-weight') ?? '400');
+      const style = normalizeStyle(readDeclaration(body, 'font-style'));
+      const key = `${family.toLowerCase()}|${weight}|${style}|${picked.url}`;
+      if (seen.has(key)) continue;
+
+      seen.add(key);
+      faces.push({ family, src: picked.url, format: picked.format, weight, style });
+    }
+  }
+
+  return faces;
 }
 
 export function stripUnusedFontFaces(
   css: string,
   usageText: string
 ): { css: string; removed: number } {
-  void css;
-  void usageText;
-  return stageStub('stripUnusedFontFaces');
+  const usage = usageText.toLowerCase();
+  let removed = 0;
+
+  const out = css.replace(FONT_FACE_BLOCK, (block) => {
+    const family = normalizeFamily(readDeclaration(block, 'font-family'));
+    const used = family != null && usage.includes(family.toLowerCase());
+    if (used) return block;
+
+    removed++;
+    return '';
+  });
+
+  return { css: out, removed };
+}
+
+function readDeclaration(body: string, prop: string): string | null {
+  const re = new RegExp(`${prop}\\s*:\\s*([^;]+)`, 'i');
+  const match = re.exec(body);
+  return match ? match[1].trim() : null;
+}
+
+function normalizeFamily(raw: string | null): string | null {
+  const family = raw?.replace(/^["']|["']$/g, '').trim();
+  return family ? family : null;
+}
+
+function pickBestFontUrl(srcDecl: string): { url: string; format: string } | null {
+  const urlRe = /url\(\s*(['"]?)([^'")]+)\1\s*\)\s*(?:format\(\s*(['"]?)([^'")]+)\3\s*\))?/gi;
+  const candidates: Array<{ url: string; format: string; index: number }> = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = urlRe.exec(srcDecl)) !== null) {
+    const url = match[2].trim();
+    if (!url || url.toLowerCase().startsWith('data:')) continue;
+
+    const format = fontExtension(url) ?? normalizeFormat(match[4]);
+    if (!format) continue;
+
+    candidates.push({ url, format, index: candidates.length });
+  }
+
+  if (candidates.length === 0) return null;
+
+  candidates.sort((a, b) => fontPreference(a.format) - fontPreference(b.format) || a.index - b.index);
+  const picked = candidates[0];
+  return { url: picked.url, format: picked.format };
+}
+
+function fontExtension(url: string): string | null {
+  const clean = url.split('?')[0].split('#')[0];
+  const dot = clean.lastIndexOf('.');
+  if (dot < 0) return null;
+
+  const ext = clean.slice(dot + 1).toLowerCase();
+  return FONT_EXTENSIONS.has(ext) ? ext : null;
+}
+
+function normalizeFormat(raw: string | undefined): string | null {
+  const value = raw?.trim().toLowerCase();
+  if (!value) return null;
+
+  if (value === 'woff2' || value === 'woff') return value;
+  if (value === 'truetype') return 'ttf';
+  if (value === 'opentype') return 'otf';
+  if (value === 'embedded-opentype') return 'eot';
+  if (FONT_EXTENSIONS.has(value)) return value;
+
+  return null;
+}
+
+function fontPreference(format: string): number {
+  if (format === 'woff2') return 0;
+  if (format === 'woff') return 1;
+  return 2;
+}
+
+function normalizeWeight(raw: string): string {
+  const value = raw.trim().toLowerCase();
+  if (value === 'normal') return '400';
+  if (value === 'bold') return '700';
+
+  const number = /\d{3}/.exec(value);
+  return number ? number[0] : '400';
 }
 
-function stageStub(name: string): never {
-  throw new Error(`STAGE_STUB:${name}`);
+function normalizeStyle(raw: string | null): string {
+  const value = (raw ?? '').trim().toLowerCase();
+  if (value === 'italic') return 'italic';
+  if (value.startsWith('oblique')) return 'oblique';
+  return 'normal';
 }

From c085c4265816a3e684d0454586579c0d0560b530 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 13:23:32 -0400
Subject: [PATCH 040/113] test(theme): freeze P1-2 font network contract

---
 .../src/__tests__/fixtures/site/index.html    |  1 +
 .../blocks-engine/src/theme/fonts-network.ts  | 19 +++++++++++++++++++
 2 files changed, 20 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/fonts-network.ts

diff --git a/packages/blocks-engine/src/__tests__/fixtures/site/index.html b/packages/blocks-engine/src/__tests__/fixtures/site/index.html
index 896d5c99..779f509e 100644
--- a/packages/blocks-engine/src/__tests__/fixtures/site/index.html
+++ b/packages/blocks-engine/src/__tests__/fixtures/site/index.html
@@ -4,6 +4,7 @@
     <meta charset="utf-8" />
     <title>Home</title>
     <link rel="stylesheet" href="./style.css" />
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter" />
   </head>
   <body data-page="home" data-template="front">
     <header>
diff --git a/packages/blocks-engine/src/theme/fonts-network.ts b/packages/blocks-engine/src/theme/fonts-network.ts
new file mode 100644
index 00000000..3b7ac504
--- /dev/null
+++ b/packages/blocks-engine/src/theme/fonts-network.ts
@@ -0,0 +1,19 @@
+import type { ParsedFontFace } from './font-faces.js';
+import type { AssetFile } from './types.js';
+
+export interface FontSelfHostResult {
+  assets: AssetFile[];
+  localizedCss: string;
+  warnings: string[];
+}
+
+export function selfHostFonts(
+  cssUrls: string[],
+  parsed: ParsedFontFace[],
+  opts: { themeSlug: string; fetchImpl?: typeof fetch }
+): Promise<FontSelfHostResult> {
+  void cssUrls;
+  void parsed;
+  void opts;
+  throw new Error('STAGE_STUB');
+}

From 6905035cd121b418f3aa72e7e681939770e93e11 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 13:37:44 -0400
Subject: [PATCH 041/113] feat(theme): self-host network fonts via fetchImpl

---
 .../src/__tests__/theme-assets-stage.test.ts  |  74 +++-
 .../src/__tests__/theme-fonts-network.test.ts | 155 +++++++
 packages/blocks-engine/src/theme/assets.ts    | 141 ++++++-
 .../blocks-engine/src/theme/fonts-network.ts  | 382 +++++++++++++++++-
 4 files changed, 732 insertions(+), 20 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-fonts-network.test.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-assets-stage.test.ts b/packages/blocks-engine/src/__tests__/theme-assets-stage.test.ts
index 305cdfd0..5b05bc0a 100644
--- a/packages/blocks-engine/src/__tests__/theme-assets-stage.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-assets-stage.test.ts
@@ -1,10 +1,12 @@
 import { join } from 'node:path';
 
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 
 import { assets, ingest, type StageCtx } from '../theme/index.js';
 
 const fixtureRoot = join(import.meta.dirname, 'fixtures/site');
+const googleCssUrl = 'https://fonts.googleapis.com/css2?family=Inter';
+const gstaticFontUrl = 'https://fonts.gstatic.com/s/inter/v12/inter-latin.woff2';
 
 function fixtureCtx(): StageCtx {
   const site = ingest(fixtureRoot);
@@ -20,8 +22,37 @@ function fixtureCtx(): StageCtx {
   };
 }
 
+function textResponse(body: string): Response {
+  return new Response(body, {
+    status: 200,
+    headers: { 'content-type': 'text/css' },
+  }) as Response;
+}
+
+function bytesResponse(bytes: Uint8Array): Response {
+  return new Response(bytes, {
+    status: 200,
+    headers: { 'content-type': 'font/woff2' },
+  }) as Response;
+}
+
+function routeFetch(routes: Record<string, Response>): {
+  fetchImpl: typeof fetch;
+  fetchMock: ReturnType<typeof vi.fn>;
+} {
+  const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]) => {
+    const url = String(input);
+    const response = routes[url];
+    if (!response) throw new Error(`Unexpected fetch: ${url}`);
+
+    return response.clone();
+  });
+
+  return { fetchImpl: fetchMock as unknown as typeof fetch, fetchMock };
+}
+
 describe('theme assets stage', () => {
-  it('returns static inventory without wiring font CSS in P1-1', async () => {
+  it('returns static inventory and no font CSS without fetchImpl', async () => {
     const result = await assets(fixtureCtx(), {});
 
     expect(result.inventory.assets).toEqual(
@@ -32,6 +63,43 @@ describe('theme assets stage', () => {
       ])
     );
     expect(result.fontCss).toBe('');
-    expect(result.warnings).toEqual([]);
+  });
+
+  it('self-hosts fixture Google fonts when fetchImpl is provided', async () => {
+    const fontBytes = new Uint8Array([5, 6, 7, 8]);
+    const googleCss = `
+      @font-face {
+        font-family: 'Inter';
+        src: url('${gstaticFontUrl}') format('woff2');
+        font-weight: 400;
+        font-style: normal;
+      }
+    `;
+    const { fetchImpl, fetchMock } = routeFetch({
+      [googleCssUrl]: textResponse(googleCss),
+      [gstaticFontUrl]: bytesResponse(fontBytes),
+    });
+
+    const result = await assets(fixtureCtx(), { fetchImpl });
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(result.inventory.assets).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          relPath: 'assets/logo.png',
+        }),
+      ])
+    );
+
+    const fontAsset = result.inventory.assets.find((asset) =>
+      asset.relPath.startsWith('assets/fonts/')
+    );
+    expect(fontAsset).toEqual(
+      expect.objectContaining({
+        bytes: fontBytes,
+      })
+    );
+    expect(result.fontCss).toContain('assets/fonts/');
+    expect(result.fontCss).not.toContain(gstaticFontUrl);
   });
 });
diff --git a/packages/blocks-engine/src/__tests__/theme-fonts-network.test.ts b/packages/blocks-engine/src/__tests__/theme-fonts-network.test.ts
new file mode 100644
index 00000000..9a37dace
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-fonts-network.test.ts
@@ -0,0 +1,155 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { ParsedFontFace } from '../theme/font-faces.js';
+import { selfHostFonts } from '../theme/fonts-network.js';
+
+const googleCssUrl = 'https://fonts.googleapis.com/css2?family=Inter';
+const gstaticFontUrl = 'https://fonts.gstatic.com/s/inter/v12/inter-latin.woff2';
+
+function textResponse(body: string): Response {
+  return new Response(body, {
+    status: 200,
+    headers: { 'content-type': 'text/css' },
+  }) as Response;
+}
+
+function bytesResponse(bytes: Uint8Array): Response {
+  return new Response(bytes, {
+    status: 200,
+    headers: { 'content-type': 'font/woff2' },
+  }) as Response;
+}
+
+function routeFetch(routes: Record<string, Response>): {
+  fetchImpl: typeof fetch;
+  fetchMock: ReturnType<typeof vi.fn>;
+  urls: string[];
+} {
+  const urls: string[] = [];
+  const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]) => {
+    const url = String(input);
+    urls.push(url);
+
+    const response = routes[url];
+    if (!response) throw new Error(`Unexpected fetch: ${url}`);
+
+    return response.clone();
+  });
+
+  return { fetchImpl: fetchMock as unknown as typeof fetch, fetchMock, urls };
+}
+
+function throwingFetch(error: Error): {
+  fetchImpl: typeof fetch;
+  fetchMock: ReturnType<typeof vi.fn>;
+} {
+  const fetchMock = vi.fn(async () => {
+    throw error;
+  });
+
+  return { fetchImpl: fetchMock as unknown as typeof fetch, fetchMock };
+}
+
+describe('selfHostFonts', () => {
+  it('self-hosts Google CSS font files and localizes gstatic URLs', async () => {
+    const fontBytes = new Uint8Array([0, 1, 2, 3, 4]);
+    const googleCss = `
+      @font-face {
+        font-family: 'Inter';
+        src: url('${gstaticFontUrl}') format('woff2');
+        font-weight: 400;
+        font-style: normal;
+      }
+    `;
+    const { fetchImpl, fetchMock } = routeFetch({
+      [googleCssUrl]: textResponse(googleCss),
+      [gstaticFontUrl]: bytesResponse(fontBytes),
+    });
+
+    const result = await selfHostFonts([googleCssUrl], [], {
+      themeSlug: 'fixture-theme',
+      fetchImpl,
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(result.warnings).toEqual([]);
+    expect(result.assets).toHaveLength(1);
+
+    const [asset] = result.assets;
+    expect(asset.bytes).toEqual(fontBytes);
+    expect(asset.relPath).toMatch(/^assets\/fonts\/[^/]+\.woff2$/);
+
+    expect(result.localizedCss).toContain(asset.relPath);
+    expect(result.localizedCss).not.toContain(gstaticFontUrl);
+  });
+
+  it('rejects SSRF and file font sources without fetching them', async () => {
+    const metadataUrl = 'http://169.254.169.254/latest/meta-data/font.woff2';
+    const fileUrl = 'file:///tmp/private-font.woff2';
+    const parsed: ParsedFontFace[] = [
+      {
+        family: 'Blocked Metadata',
+        src: metadataUrl,
+        format: 'woff2',
+        weight: '400',
+        style: 'normal',
+      },
+      {
+        family: 'Blocked File',
+        src: fileUrl,
+        format: 'woff2',
+        weight: '400',
+        style: 'normal',
+      },
+      {
+        family: 'Blocked Mapped IPv6',
+        src: 'http://[::ffff:7f00:1]/font.woff2',
+        format: 'woff2',
+        weight: '400',
+        style: 'normal',
+      },
+    ];
+    const fetchMock = vi.fn(async () => {
+      throw new Error('blocked URLs must not be fetched');
+    });
+
+    const result = await selfHostFonts([], parsed, {
+      themeSlug: 'fixture-theme',
+      fetchImpl: fetchMock as unknown as typeof fetch,
+    });
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(result.assets).toEqual([]);
+    expect(result.localizedCss).toContain(metadataUrl);
+    expect(result.localizedCss).toContain(fileUrl);
+    expect(result.localizedCss).toContain('http://[::ffff:7f00:1]/font.woff2');
+    expect(result.warnings.join('\n')).toContain(metadataUrl);
+    expect(result.warnings.join('\n')).toContain(fileUrl);
+    expect(result.warnings.join('\n')).toContain('http://[::ffff:7f00:1]/font.woff2');
+  });
+
+  it('degrades offline fetch failures into warnings without throwing', async () => {
+    const parsed: ParsedFontFace[] = [
+      {
+        family: 'Inter',
+        src: gstaticFontUrl,
+        format: 'woff2',
+        weight: '400',
+        style: 'normal',
+      },
+    ];
+    const { fetchImpl, fetchMock } = throwingFetch(new Error('offline'));
+
+    const result = await selfHostFonts([], parsed, {
+      themeSlug: 'fixture-theme',
+      fetchImpl,
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(result.assets).toEqual([]);
+    expect(result.localizedCss).toContain(gstaticFontUrl);
+    expect(result.localizedCss).toContain('font-family: "Inter"');
+    expect(result.warnings.length).toBeGreaterThan(0);
+    expect(result.warnings.join('\n')).toContain(gstaticFontUrl);
+  });
+});
diff --git a/packages/blocks-engine/src/theme/assets.ts b/packages/blocks-engine/src/theme/assets.ts
index 249ab8e2..4aa351f6 100644
--- a/packages/blocks-engine/src/theme/assets.ts
+++ b/packages/blocks-engine/src/theme/assets.ts
@@ -2,7 +2,8 @@ import { readFileSync, statSync } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
 import { collectStaticAssets, type StaticImgRef } from './assets-static.js';
 import { parseFontFaces, type ParsedFontFace } from './font-faces.js';
-import type { AssetInventory, SitePage, StageCtx } from './types.js';
+import { selfHostFonts } from './fonts-network.js';
+import type { AssetFile, AssetInventory, SitePage, StageCtx } from './types.js';
 
 export interface AssetStageResult {
   inventory: AssetInventory;
@@ -11,22 +12,79 @@ export interface AssetStageResult {
   warnings: string[];
 }
 
-export function assets(
+const MISSING_FETCH_WARNING =
+  'Remote font assets were detected but fetchImpl was not provided; skipping font self-hosting.';
+const GOOGLE_FONTS_ORIGIN = 'https://fonts.googleapis.com';
+const REMOTE_HTTP_RE = /^https?:\/\//i;
+
+export async function assets(
   ctx: StageCtx,
   opts: { fetchImpl?: typeof fetch }
 ): Promise<AssetStageResult> {
-  void opts.fetchImpl;
-
   const { assets, imgRefsByPage } = collectStaticAssets(ctx.site, ctx.themeMeta.slug);
-  const parsedFontFaces: ParsedFontFace[] = parseFontFaces(...collectLinkedStylesheetCss(ctx));
-  void parsedFontFaces;
+  const linkedCss = collectLinkedStylesheetCss(ctx);
+  const parsedFontFaces: ParsedFontFace[] = parseFontFaces(...linkedCss);
+  const remoteFontFaces = parsedFontFaces.filter(isRemoteFontFace);
+  const cssUrls = collectGoogleFontCssUrls(ctx, linkedCss);
+
+  if (cssUrls.length === 0 && remoteFontFaces.length === 0) {
+    return {
+      inventory: { assets },
+      imgRefsByPage,
+      fontCss: '',
+      warnings: [],
+    };
+  }
 
-  return Promise.resolve({
-    inventory: { assets },
-    imgRefsByPage,
-    fontCss: '',
-    warnings: [],
+  if (!opts.fetchImpl) {
+    ctx.warn(MISSING_FETCH_WARNING);
+    return {
+      inventory: { assets },
+      imgRefsByPage,
+      fontCss: '',
+      warnings: [MISSING_FETCH_WARNING],
+    };
+  }
+
+  const hosted = await selfHostFonts(cssUrls, remoteFontFaces, {
+    themeSlug: ctx.themeMeta.slug,
+    fetchImpl: opts.fetchImpl,
   });
+
+  for (const warning of hosted.warnings) {
+    ctx.warn(warning);
+  }
+
+  return {
+    inventory: { assets: sortAssetFiles([...assets, ...hosted.assets]) },
+    imgRefsByPage,
+    fontCss: hosted.localizedCss,
+    warnings: hosted.warnings,
+  };
+}
+
+function collectGoogleFontCssUrls(ctx: StageCtx, linkedCss: string[]): string[] {
+  const urls = new Set<string>();
+
+  for (const page of sortedPages(ctx.site.pages)) {
+    for (const tag of page.html.matchAll(/<link\b[^>]*>/gi)) {
+      const attrs = attributesFromTag(tag[0]);
+      const rel = (attrs.get('rel') ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+      if (!rel.includes('stylesheet')) continue;
+
+      const href = normalizeGoogleFontCssUrl(attrs.get('href'));
+      if (href) urls.add(href);
+    }
+  }
+
+  for (const css of linkedCss) {
+    for (const ref of googleFontCssImports(css)) {
+      const href = normalizeGoogleFontCssUrl(ref);
+      if (href) urls.add(href);
+    }
+  }
+
+  return [...urls].sort((a, b) => a.localeCompare(b));
 }
 
 function collectLinkedStylesheetCss(ctx: StageCtx): string[] {
@@ -71,6 +129,53 @@ function resolveLocalStylesheet(
   return path;
 }
 
+function googleFontCssImports(css: string): string[] {
+  const refs: string[] = [];
+  const importPattern =
+    /@import\s+(?:url\(\s*)?(?:"([^"]+)"|'([^']+)'|([^'"\s)]+))\s*\)?/gi;
+
+  for (const match of css.matchAll(importPattern)) {
+    const ref = match[1] ?? match[2] ?? match[3];
+    if (ref) refs.push(ref);
+  }
+
+  return refs;
+}
+
+function normalizeGoogleFontCssUrl(ref: string | undefined): string | null {
+  const trimmed = decodeHtmlRef(ref).trim();
+  if (!trimmed) return null;
+
+  let candidate = trimmed;
+  if (candidate.startsWith('//')) {
+    candidate = `https:${candidate}`;
+  } else if (candidate.startsWith('/css?') || candidate.startsWith('/css2?')) {
+    candidate = `${GOOGLE_FONTS_ORIGIN}${candidate}`;
+  }
+
+  let url: URL;
+  try {
+    url = new URL(candidate);
+  } catch {
+    return null;
+  }
+
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+  if (url.hostname !== 'fonts.googleapis.com') return null;
+  if (url.pathname !== '/css' && url.pathname !== '/css2') return null;
+  if (!url.search) return null;
+
+  url.hash = '';
+  return url.toString();
+}
+
+function decodeHtmlRef(ref: string | undefined): string {
+  return (ref ?? '')
+    .replace(/&amp;/gi, '&')
+    .replace(/&#38;/g, '&')
+    .replace(/&#x26;/gi, '&');
+}
+
 function cleanLocalRef(ref: string | undefined): string | null {
   const trimmed = ref?.trim();
   if (!trimmed || trimmed.startsWith('#')) return null;
@@ -106,6 +211,20 @@ function isFile(path: string): boolean {
   }
 }
 
+function isRemoteFontFace(face: ParsedFontFace): boolean {
+  return REMOTE_HTTP_RE.test(face.src);
+}
+
+function sortAssetFiles(files: AssetFile[]): AssetFile[] {
+  return [...files].sort(compareAssetFiles);
+}
+
+function compareAssetFiles(a: AssetFile, b: AssetFile): number {
+  const rel = a.relPath.localeCompare(b.relPath);
+  if (rel !== 0) return rel;
+  return (a.sourcePath ?? '').localeCompare(b.sourcePath ?? '');
+}
+
 function attributesFromTag(tag: string): Map<string, string> {
   const attrs = new Map<string, string>();
   const attrPattern = /([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
diff --git a/packages/blocks-engine/src/theme/fonts-network.ts b/packages/blocks-engine/src/theme/fonts-network.ts
index 3b7ac504..299fe288 100644
--- a/packages/blocks-engine/src/theme/fonts-network.ts
+++ b/packages/blocks-engine/src/theme/fonts-network.ts
@@ -1,4 +1,4 @@
-import type { ParsedFontFace } from './font-faces.js';
+import { parseFontFaces, type ParsedFontFace } from './font-faces.js';
 import type { AssetFile } from './types.js';
 
 export interface FontSelfHostResult {
@@ -7,13 +7,383 @@ export interface FontSelfHostResult {
   warnings: string[];
 }
 
-export function selfHostFonts(
+const FONTS_DIR = 'assets/fonts';
+const WOFF2_USER_AGENT =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36';
+
+class FontUrlBlockedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FontUrlBlockedError';
+  }
+}
+
+export async function selfHostFonts(
   cssUrls: string[],
   parsed: ParsedFontFace[],
   opts: { themeSlug: string; fetchImpl?: typeof fetch }
 ): Promise<FontSelfHostResult> {
-  void cssUrls;
-  void parsed;
-  void opts;
-  throw new Error('STAGE_STUB');
+  const fetchFn = opts.fetchImpl;
+  if (!fetchFn) {
+    return {
+      assets: [],
+      localizedCss: '',
+      warnings: ['font self-hosting skipped: opts.fetchImpl is required'],
+    };
+  }
+
+  const assets: AssetFile[] = [];
+  const warnings: string[] = [];
+  const downloaded = new Map<string, string>();
+  const failed = new Set<string>();
+  const usedFilenames = new Map<string, string>();
+  const localizedParts: string[] = [];
+
+  for (const cssUrl of cssUrls) {
+    const css = await fetchFontCss(cssUrl, fetchFn, warnings);
+    if (!css) continue;
+
+    let localized = css.text;
+    for (const face of parseFontFaces(css.text)) {
+      const relPath = await downloadFontFace(face, {
+        baseUrl: css.url,
+        fetchFn,
+        assets,
+        downloaded,
+        failed,
+        usedFilenames,
+        warnings,
+      });
+
+      if (relPath) {
+        localized = localized.split(face.src).join(relPath);
+      }
+    }
+
+    localizedParts.push(localized);
+  }
+
+  for (const face of parsed) {
+    const relPath = await downloadFontFace(face, {
+      fetchFn,
+      assets,
+      downloaded,
+      failed,
+      usedFilenames,
+      warnings,
+    });
+    localizedParts.push(fontFaceCss(face, relPath ?? face.src));
+  }
+
+  return {
+    assets,
+    localizedCss: localizedParts.join('\n\n'),
+    warnings,
+  };
+}
+
+async function fetchFontCss(
+  rawUrl: string,
+  fetchFn: typeof fetch,
+  warnings: string[]
+): Promise<{ url: string; text: string } | null> {
+  let url: URL;
+  try {
+    url = assertPublicHttpUrl(rawUrl);
+  } catch (err) {
+    warnings.push(`skipped font CSS ${quote(rawUrl)}: ${errorMessage(err)}`);
+    return null;
+  }
+
+  try {
+    // Standard fetch follows redirects internally; redirect-target
+    // revalidation is unavailable through this fetch seam.
+    const res = await fetchFn(url.toString(), {
+      headers: { 'User-Agent': WOFF2_USER_AGENT },
+    });
+
+    if (!isSuccess(res)) {
+      warnings.push(`skipped font CSS ${quote(url.toString())}: HTTP ${res.status}`);
+      return null;
+    }
+
+    const text = await res.text();
+    if (text.length === 0) {
+      warnings.push(`skipped font CSS ${quote(url.toString())}: empty response body`);
+      return null;
+    }
+
+    return { url: url.toString(), text };
+  } catch (err) {
+    warnings.push(`skipped font CSS ${quote(url.toString())}: ${errorMessage(err)}`);
+    return null;
+  }
+}
+
+interface DownloadFontFaceCtx {
+  baseUrl?: string;
+  fetchFn: typeof fetch;
+  assets: AssetFile[];
+  downloaded: Map<string, string>;
+  failed: Set<string>;
+  usedFilenames: Map<string, string>;
+  warnings: string[];
+}
+
+async function downloadFontFace(face: ParsedFontFace, ctx: DownloadFontFaceCtx): Promise<string | null> {
+  let fontUrl: URL;
+  try {
+    fontUrl = resolvePublicFontUrl(face.src, ctx.baseUrl);
+  } catch (err) {
+    ctx.warnings.push(`skipped font ${describeFace(face)}: ${errorMessage(err)}`);
+    return null;
+  }
+
+  const absolute = fontUrl.toString();
+  const existing = ctx.downloaded.get(absolute);
+  if (existing) return existing;
+  if (ctx.failed.has(absolute)) return null;
+
+  try {
+    const res = await ctx.fetchFn(absolute, {
+      headers: { 'User-Agent': WOFF2_USER_AGENT },
+    });
+
+    if (!isSuccess(res)) {
+      throw new Error(`HTTP ${res.status}`);
+    }
+
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    if (bytes.byteLength === 0) {
+      throw new Error('empty response body');
+    }
+
+    const filename = allocateFilename(fontFilename(face, fontUrl), absolute, ctx.usedFilenames);
+    const relPath = `${FONTS_DIR}/${filename}`;
+    ctx.downloaded.set(absolute, relPath);
+    ctx.assets.push({ relPath, bytes });
+    return relPath;
+  } catch (err) {
+    ctx.failed.add(absolute);
+    ctx.warnings.push(`skipped font ${describeFace(face, absolute)}: ${errorMessage(err)}`);
+    return null;
+  }
+}
+
+function resolvePublicFontUrl(rawUrl: string, baseUrl?: string): URL {
+  if (!baseUrl) return assertPublicHttpUrl(rawUrl);
+
+  let resolved: string;
+  try {
+    resolved = new URL(rawUrl, baseUrl).toString();
+  } catch {
+    throw new FontUrlBlockedError(`unparseable URL: ${truncate(rawUrl)}`);
+  }
+
+  return assertPublicHttpUrl(resolved);
+}
+
+function isSuccess(res: Response): boolean {
+  return res.status >= 200 && res.status < 300;
+}
+
+function fontFilename(face: ParsedFontFace, url: URL): string {
+  const basename = sanitizedUrlBasename(url);
+  if (basename) return basename;
+
+  const family = sanitizeFilenamePart(face.family) || 'font';
+  const weight = sanitizeFilenamePart(face.weight ?? '400') || '400';
+  const italic = face.style === 'italic' ? '-italic' : '';
+  const ext = face.format === 'woff' ? 'woff' : 'woff2';
+  return `${family}-${weight}${italic}.${ext}`;
+}
+
+function fontFaceCss(face: ParsedFontFace, src: string): string {
+  const lines = [
+    '@font-face {',
+    `  font-family: ${cssString(face.family)};`,
+    `  src: url(${cssString(src)})${face.format ? ` format(${cssString(face.format)})` : ''};`,
+  ];
+
+  if (face.weight) {
+    lines.push(`  font-weight: ${face.weight};`);
+  }
+  if (face.style) {
+    lines.push(`  font-style: ${face.style};`);
+  }
+
+  lines.push('}');
+  return lines.join('\n');
+}
+
+function cssString(value: string): string {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function sanitizedUrlBasename(url: URL): string | null {
+  const raw = url.pathname.split('/').pop() ?? '';
+  const decoded = safeDecodeURIComponent(raw);
+  const sanitized = decoded.replace(/[^A-Za-z0-9._-]+/g, '');
+  return hasExtension(sanitized) ? sanitized : null;
+}
+
+function hasExtension(filename: string): boolean {
+  const dot = filename.lastIndexOf('.');
+  return dot > 0 && dot < filename.length - 1 && /^[A-Za-z0-9]+$/.test(filename.slice(dot + 1));
+}
+
+function sanitizeFilenamePart(value: string): string {
+  return value.replace(/[^A-Za-z0-9_-]+/g, '');
+}
+
+function allocateFilename(preferred: string, absoluteUrl: string, used: Map<string, string>): string {
+  const existing = used.get(preferred);
+  if (!existing) {
+    used.set(preferred, absoluteUrl);
+    return preferred;
+  }
+  if (existing === absoluteUrl) return preferred;
+
+  const { stem, ext } = splitExtension(preferred);
+  for (let index = 2; ; index++) {
+    const candidate = `${stem}-${index}${ext}`;
+    const owner = used.get(candidate);
+    if (!owner) {
+      used.set(candidate, absoluteUrl);
+      return candidate;
+    }
+    if (owner === absoluteUrl) return candidate;
+  }
+}
+
+function splitExtension(filename: string): { stem: string; ext: string } {
+  const dot = filename.lastIndexOf('.');
+  if (dot <= 0) return { stem: filename, ext: '' };
+  return { stem: filename.slice(0, dot), ext: filename.slice(dot) };
+}
+
+function safeDecodeURIComponent(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function assertPublicHttpUrl(rawUrl: string): URL {
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new FontUrlBlockedError(`unparseable URL: ${truncate(rawUrl)}`);
+  }
+
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new FontUrlBlockedError(`disallowed URL scheme "${url.protocol}"`);
+  }
+
+  const host = url.hostname.toLowerCase();
+  if (!host) {
+    throw new FontUrlBlockedError('URL has no host');
+  }
+
+  const lit = literalIp(host);
+  if (lit) {
+    const internal = lit.kind === 'ipv4' ? isInternalIpv4(lit.value) : isInternalIpv6(lit.value);
+    if (internal) {
+      throw new FontUrlBlockedError(`internal/loopback IP address not allowed: ${host}`);
+    }
+    return url;
+  }
+
+  if (host === 'localhost' || host.endsWith('.localhost')) {
+    throw new FontUrlBlockedError(`loopback hostname not allowed: ${host}`);
+  }
+  if (host.endsWith('.local')) {
+    throw new FontUrlBlockedError(`mDNS/.local hostname not allowed: ${host}`);
+  }
+  if (!host.includes('.')) {
+    throw new FontUrlBlockedError(`bare single-label hostname not allowed: ${host}`);
+  }
+
+  return url;
+}
+
+function literalIp(host: string): { kind: 'ipv4' | 'ipv6'; value: string } | null {
+  let h = host;
+  if (h.startsWith('[') && h.endsWith(']')) h = h.slice(1, -1);
+
+  const pct = h.indexOf('%');
+  if (pct >= 0) h = h.slice(0, pct);
+
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(h)) {
+    const parts = h.split('.').map((part) => Number(part));
+    if (parts.every((part) => part >= 0 && part <= 255)) {
+      return { kind: 'ipv4', value: h };
+    }
+  }
+
+  if (h.includes(':') && /^[0-9a-fA-F:]+$/.test(h)) {
+    return { kind: 'ipv6', value: h.toLowerCase() };
+  }
+
+  return null;
+}
+
+function isInternalIpv4(ip: string): boolean {
+  const [a, b] = ip.split('.').map((part) => Number(part));
+  if (a === 0) return true;
+  if (a === 127) return true;
+  if (a === 10) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a >= 224) return true;
+  return false;
+}
+
+function isInternalIpv6(ip: string): boolean {
+  const value = ip.toLowerCase();
+  if (value === '::1') return true;
+  if (value === '::' || value === '0:0:0:0:0:0:0:0') return true;
+  if (value.startsWith('fc') || value.startsWith('fd')) return true;
+  if (value.startsWith('fe8') || value.startsWith('fe9') || value.startsWith('fea') || value.startsWith('feb')) {
+    return true;
+  }
+
+  const dottedMapped = value.match(/::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  if (dottedMapped) return isInternalIpv4(dottedMapped[1]);
+
+  const hexMapped = value.match(/^(?:::ffff:|0:0:0:0:0:ffff:)([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (hexMapped) {
+    const high = Number.parseInt(hexMapped[1], 16);
+    const low = Number.parseInt(hexMapped[2], 16);
+    const mappedIpv4 = [
+      (high >> 8) & 255,
+      high & 255,
+      (low >> 8) & 255,
+      low & 255,
+    ].join('.');
+    return isInternalIpv4(mappedIpv4);
+  }
+
+  return false;
+}
+
+function describeFace(face: ParsedFontFace, url?: string): string {
+  const suffix = url ? ` ${quote(url)}` : ` ${quote(face.src)}`;
+  return `${quote(face.family)}${suffix}`;
+}
+
+function quote(value: string): string {
+  return `"${truncate(value)}"`;
+}
+
+function truncate(value: string): string {
+  return value.length > 200 ? `${value.slice(0, 200)}...` : value;
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
 }

From 36ed439978d49e2bdf631814b4f5a614481d84de Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 14:02:00 -0400
Subject: [PATCH 042/113] Wire site-to-theme assets stage

---
 .../src/__tests__/site-to-theme.e2e.test.ts   | 400 +++++++++++++++++-
 packages/blocks-engine/src/theme/assemble.ts  | 124 +++++-
 .../blocks-engine/src/theme/site-to-theme.ts  |  33 +-
 3 files changed, 536 insertions(+), 21 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
index 266f2a07..4a43897c 100644
--- a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
+++ b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createRequire } from 'node:module';
@@ -6,9 +6,20 @@ import { createRequire } from 'node:module';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import type { WorkerPool } from '../pool/types.js';
-import type { SectionBlocks, SectionSpec } from '../theme/index.js';
+import type {
+  AssetFile,
+  FoundationTokens,
+  SectionBlocks,
+  SectionSpec,
+  SiteModel,
+  StaticImgRef,
+  ThemeMeta,
+} from '../theme/index.js';
 
 const fixtureRoot = join(import.meta.dirname, 'fixtures/site');
+const googleCssUrl = 'https://fonts.googleapis.com/css2?family=Inter';
+const gstaticFontUrl = 'https://fonts.gstatic.com/s/inter/v12/inter-latin.woff2';
+const fontBytes = new Uint8Array([9, 8, 7, 6]);
 const requireFromHere = createRequire(import.meta.url);
 const requireWithCache = requireFromHere as typeof requireFromHere & {
   resolve(id: string): string;
@@ -40,6 +51,7 @@ function copyFixtureSite(dest: string): void {
   for (const file of ['index.html', 'about.html', 'style.css']) {
     writeFileSync(join(dest, file), readFileSync(join(fixtureRoot, file), 'utf8'), 'utf8');
   }
+  cpSync(join(fixtureRoot, 'assets'), join(dest, 'assets'), { recursive: true });
 }
 
 function semanticSpec(sectionIndex = 0): SectionSpec {
@@ -75,11 +87,46 @@ function semanticSpec(sectionIndex = 0): SectionSpec {
   };
 }
 
+function imageSpec(sectionIndex = 0): SectionSpec {
+  return {
+    ...semanticSpec(sectionIndex),
+    sectionIndex,
+    headings: ['Asset heading'],
+    bodyText: ['Asset body copy.'],
+    sectionHtml: [
+      '<section>',
+      '<h1>Asset heading</h1>',
+      '<p>Asset body copy.</p>',
+      '<img src="assets/logo.png" alt="Blocks Engine mark" />',
+      '</section>',
+    ].join(''),
+  };
+}
+
+function p1Sections(): Record<string, SectionSpec[]> {
+  return {
+    about: [semanticSpec(0)],
+    home: [imageSpec(0)],
+  };
+}
+
+function imageBlockMarkup(): string {
+  return [
+    '<!-- wp:image -->',
+    '<figure class="wp-block-image"><img src="assets/logo.png" alt="Blocks Engine mark"/></figure>',
+    '<!-- /wp:image -->',
+  ].join('\n');
+}
+
 function fakePool(markup: string): WorkerPool & { stopCalls: number } {
+  return mappedPool(() => markup);
+}
+
+function mappedPool(markupForInput: (html: string) => string): WorkerPool & { stopCalls: number } {
   return {
     stopCalls: 0,
     async rawConvert(items: string[]) {
-      return items.map(() => ({ html: markup, wpHtmlResidue: 0 }));
+      return items.map((html) => ({ html: markupForInput(html), wpHtmlResidue: 0 }));
     },
     async canonicalize(items: string[]) {
       return items.map((html) => ({ html, changed: false, fixedIssues: [] }));
@@ -90,12 +137,351 @@ function fakePool(markup: string): WorkerPool & { stopCalls: number } {
   };
 }
 
+function p1Pool(): WorkerPool & { stopCalls: number } {
+  return mappedPool((html) =>
+    html.includes('assets/logo.png')
+      ? imageBlockMarkup()
+      : '<!-- wp:paragraph -->\n<p>Stable.</p>\n<!-- /wp:paragraph -->'
+  );
+}
+
+function themeMeta(): ThemeMeta {
+  return {
+    name: 'Fixture Theme',
+    slug: 'fixture-theme',
+  };
+}
+
+function foundationTokens(): FoundationTokens {
+  return {
+    palette: [{ name: 'Text Default', color: '#111111' }],
+    typography: { body: 'Fixture Sans' },
+    breakpoints: { md: '768px', lg: '960px' },
+  };
+}
+
+function siteModel(root = fixtureRoot): SiteModel {
+  return {
+    root,
+    pages: [
+      {
+        relPath: 'index.html',
+        slug: 'home',
+        html: readFileSync(join(fixtureRoot, 'index.html'), 'utf8'),
+        title: 'Home',
+      },
+    ],
+  };
+}
+
+function logoAsset(sourceRoot = fixtureRoot): AssetFile {
+  return {
+    relPath: 'assets/logo.png',
+    sourcePath: join(sourceRoot, 'assets/logo.png'),
+  };
+}
+
+function logoRef(sourceRoot = fixtureRoot): StaticImgRef {
+  return {
+    ref: 'assets/logo.png',
+    themeRel: 'assets/logo.png',
+    sourcePath: join(sourceRoot, 'assets/logo.png'),
+  };
+}
+
+type AssemblePartsWithAssets = {
+  site: SiteModel;
+  tokens: FoundationTokens;
+  pages: Record<string, SectionBlocks[]>;
+  meta: ThemeMeta;
+  assets: AssetFile[];
+  fontCss: string;
+  imgRefsByPage: Record<string, StaticImgRef[]>;
+};
+
+function textResponse(body: string): Response {
+  return new Response(body, {
+    status: 200,
+    headers: { 'content-type': 'text/css' },
+  }) as Response;
+}
+
+function bytesResponse(bytes: Uint8Array): Response {
+  return new Response(bytes, {
+    status: 200,
+    headers: { 'content-type': 'font/woff2' },
+  }) as Response;
+}
+
+function routeFetch(routes: Record<string, Response>): {
+  fetchImpl: typeof fetch;
+  fetchMock: ReturnType<typeof vi.fn>;
+} {
+  const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]) => {
+    const url = String(input);
+    const response = routes[url];
+    if (!response) throw new Error(`Unexpected fetch: ${url}`);
+
+    return response.clone();
+  });
+
+  return { fetchImpl: fetchMock as unknown as typeof fetch, fetchMock };
+}
+
+function mockFontFetch(): {
+  fetchImpl: typeof fetch;
+  fetchMock: ReturnType<typeof vi.fn>;
+} {
+  const googleCss = `
+    @font-face {
+      font-family: 'Inter';
+      src: url('${gstaticFontUrl}') format('woff2');
+      font-weight: 400;
+      font-style: normal;
+    }
+  `;
+
+  return routeFetch({
+    [googleCssUrl]: textResponse(googleCss),
+    [gstaticFontUrl]: bytesResponse(fontBytes),
+  });
+}
+
+function expectThemesByteIdentical(leftDir: string, rightDir: string, files: string[]): void {
+  for (const file of files) {
+    expect(readFileSync(join(rightDir, file))).toEqual(readFileSync(join(leftDir, file)));
+  }
+}
+
 afterEach(() => {
   vi.doUnmock('../pool/pool.js');
   vi.resetModules();
 });
 
 describe('site-to-theme P0-3 orchestration', () => {
+  it('assemble-threads-assets adds copied assets, font CSS, and rewrites template images', async () => {
+    const { assemble } = await import('../theme/index.js');
+    const parts: AssemblePartsWithAssets = {
+      site: siteModel(),
+      tokens: foundationTokens(),
+      pages: {
+        home: [
+          {
+            spec: imageSpec(0),
+            blocks: imageBlockMarkup(),
+            coverage: 1,
+          },
+        ],
+      },
+      meta: themeMeta(),
+      assets: [logoAsset()],
+      fontCss: '/*f*/\n@font-face { font-family: "Inter"; src: url("assets/fonts/inter.woff2"); }',
+      imgRefsByPage: {
+        home: [logoRef()],
+      },
+    };
+
+    const model = assemble(parts as Parameters<typeof assemble>[0]);
+
+    expect(model.assets).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          relPath: 'assets/logo.png',
+        }),
+      ])
+    );
+    expect(model.styleCss).toContain('/*f*/');
+    expect(model.templates['index.html']).toContain(
+      '/wp-content/themes/fixture-theme/assets/logo.png'
+    );
+    expect(model.templates['index.html']).not.toContain('src="assets/logo.png"');
+  });
+
+  it('assemble-threads-assets lets asset-stage entries win relPath collisions', async () => {
+    const { assemble } = await import('../theme/index.js');
+    const siteWithLegacyAsset = {
+      ...siteModel(),
+      assets: [
+        {
+          relPath: 'assets/logo.png',
+          bytes: new Uint8Array([1, 2, 3]),
+        },
+      ],
+    };
+    const assetStageLogo = logoAsset();
+
+    const model = assemble({
+      site: siteWithLegacyAsset,
+      tokens: foundationTokens(),
+      pages: {},
+      meta: themeMeta(),
+      assets: [assetStageLogo],
+    } as Parameters<typeof assemble>[0]);
+
+    expect(model.assets.find((asset) => asset.relPath === 'assets/logo.png')).toEqual(
+      assetStageLogo
+    );
+  });
+
+  it('siteToTheme-e2e-assets-on-disk writes copied images and mocked font assets', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+    const { fetchImpl, fetchMock } = mockFontFetch();
+
+    await withTempDir('blocks-engine-site-to-theme-assets-', async (siteDir) => {
+      copyFixtureSite(siteDir);
+      const outDir = join(siteDir, 'theme-out');
+
+      const result = await siteToTheme(siteDir, {
+        outDir,
+        pool: p1Pool(),
+        sections: p1Sections(),
+        fetchImpl,
+        themeMeta: themeMeta(),
+      });
+
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      expect(result.written).toEqual(expect.arrayContaining(['assets/logo.png']));
+      expect(existsSync(join(outDir, 'assets', 'logo.png'))).toBe(true);
+
+      const fontFile = result.written.find((file) =>
+        /^assets\/fonts\/[^/]+\.woff2$/.test(file)
+      );
+      expect(fontFile).toBeTypeOf('string');
+      expect(existsSync(join(outDir, fontFile as string))).toBe(true);
+
+      const styleCss = readFileSync(join(outDir, 'style.css'), 'utf8');
+      expect(styleCss).toContain('assets/fonts/');
+      expect(styleCss).not.toContain(gstaticFontUrl);
+
+      const template = readFileSync(join(outDir, 'templates', 'index.html'), 'utf8');
+      expect(template).toContain('/wp-content/themes/fixture-theme/assets/logo.png');
+      expect(template).not.toContain('src="assets/logo.png"');
+    });
+  });
+
+  it('siteToTheme-e2e-assets-on-disk keeps assets stage and assemble slug parity', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+
+    await withTempDir('blocks-engine-site-to-theme-slug-assets-', async (siteDir) => {
+      copyFixtureSite(siteDir);
+      const outDir = join(siteDir, 'theme-out');
+
+      const result = await siteToTheme(siteDir, {
+        outDir,
+        pool: p1Pool(),
+        sections: p1Sections(),
+        themeMeta: {
+          name: 'Fixture Theme',
+          slug: 'Fixture Theme!',
+        },
+      });
+
+      const template = readFileSync(join(outDir, 'templates', 'index.html'), 'utf8');
+      expect(result.model.assets.map((asset) => asset.relPath)).toContain('assets/logo.png');
+      expect(template).toContain('/wp-content/themes/fixture-theme/assets/logo.png');
+      expect(template).not.toContain('/wp-content/themes/Fixture Theme!');
+    });
+  });
+
+  it('onAssets-decoration-drop removes decorative assets from the written theme model', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+    const { fetchImpl } = mockFontFetch();
+
+    await withTempDir('blocks-engine-site-to-theme-decoration-', async (siteDir) => {
+      copyFixtureSite(siteDir);
+      const outDir = join(siteDir, 'theme-out');
+      const inventories: string[][] = [];
+
+      const result = await siteToTheme(siteDir, {
+        outDir,
+        pool: p1Pool(),
+        sections: p1Sections(),
+        fetchImpl,
+        themeMeta: themeMeta(),
+        hooks: {
+          async onAssets(inventory) {
+            const relPaths = inventory.assets.map((asset) => asset.relPath);
+            inventories.push(relPaths);
+            return {
+              keep: relPaths,
+              decoration: ['assets/logo.png'],
+            };
+          },
+        },
+      });
+
+      expect(inventories[0]).toContain('assets/logo.png');
+      expect(result.model.assets.map((asset) => asset.relPath)).not.toContain('assets/logo.png');
+      expect(result.written).not.toContain('assets/logo.png');
+      expect(existsSync(join(outDir, 'assets', 'logo.png'))).toBe(false);
+    });
+  });
+
+  it('hooks-absent-identity keeps asset output byte-identical for absent, empty, and identity hooks', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+
+    await withTempDir('blocks-engine-site-to-theme-hooks-assets-', async (rootDir) => {
+      const siteDir = join(rootDir, 'site');
+      mkdirSync(siteDir);
+      copyFixtureSite(siteDir);
+      const firstOut = join(rootDir, 'theme-no-hooks');
+      const secondOut = join(rootDir, 'theme-empty-hooks');
+      const thirdOut = join(rootDir, 'theme-identity-hooks');
+      const firstFetch = mockFontFetch();
+      const secondFetch = mockFontFetch();
+      const thirdFetch = mockFontFetch();
+
+      const first = await siteToTheme(siteDir, {
+        outDir: firstOut,
+        pool: p1Pool(),
+        sections: p1Sections(),
+        fetchImpl: firstFetch.fetchImpl,
+        themeMeta: themeMeta(),
+      });
+      const second = await siteToTheme(siteDir, {
+        outDir: secondOut,
+        pool: p1Pool(),
+        sections: p1Sections(),
+        fetchImpl: secondFetch.fetchImpl,
+        themeMeta: themeMeta(),
+        hooks: {},
+      });
+      const third = await siteToTheme(siteDir, {
+        outDir: thirdOut,
+        pool: p1Pool(),
+        sections: p1Sections(),
+        fetchImpl: thirdFetch.fetchImpl,
+        themeMeta: themeMeta(),
+        hooks: {
+          async onFoundation(tokens) {
+            return tokens;
+          },
+          async onSection(section) {
+            return section;
+          },
+          async onAssets(inventory) {
+            return {
+              keep: inventory.assets.map((asset) => asset.relPath),
+              decoration: [],
+            };
+          },
+          async onRefine(theme) {
+            return theme;
+          },
+        },
+      });
+
+      expect(first.written).toEqual(expect.arrayContaining(['assets/logo.png']));
+      expect(first.written.some((file) => file.startsWith('assets/fonts/'))).toBe(true);
+      expect(second.model).toEqual(first.model);
+      expect(second.written).toEqual(first.written);
+      expectThemesByteIdentical(firstOut, secondOut, first.written);
+      expect(third.model).toEqual(first.model);
+      expect(third.written).toEqual(first.written);
+      expectThemesByteIdentical(firstOut, thirdOut, first.written);
+    });
+  });
+
   it('writes a lintable block theme with native block markup for semantic input', async () => {
     const { siteToTheme, lintThemeJson } = await import('../theme/index.js');
 
@@ -231,7 +617,7 @@ describe('site-to-theme P0-3 orchestration', () => {
     });
   });
 
-  it('exports siteToTheme from the main entry without loading @wordpress/blocks in this process', async () => {
+  it('react-isolation-after-full-run exports siteToTheme without loading @wordpress/blocks in this process', async () => {
     clearWordPressBlocksRequireCache();
 
     const entry = await import('../index.js');
@@ -245,8 +631,10 @@ describe('site-to-theme P0-3 orchestration', () => {
       copyFixtureSite(siteDir);
       await entry.siteToTheme(siteDir, {
         outDir: join(siteDir, 'theme-out'),
-        pool: fakePool('<!-- wp:paragraph -->\n<p>Main entry.</p>\n<!-- /wp:paragraph -->'),
-        sections: { about: [semanticSpec(0)], home: [semanticSpec(0)] },
+        pool: p1Pool(),
+        sections: p1Sections(),
+        fetchImpl: mockFontFetch().fetchImpl,
+        themeMeta: themeMeta(),
       });
     });
 
diff --git a/packages/blocks-engine/src/theme/assemble.ts b/packages/blocks-engine/src/theme/assemble.ts
index b00390a5..2bede2b0 100644
--- a/packages/blocks-engine/src/theme/assemble.ts
+++ b/packages/blocks-engine/src/theme/assemble.ts
@@ -1,3 +1,5 @@
+import { escapeHtmlAttr } from '../escape.js';
+import { rewriteHtmlImageSrcs, type StaticImgRef } from './assets-static.js';
 import type {
   AssetFile,
   FoundationTokens,
@@ -12,6 +14,9 @@ type ThemeAssemblyParts = {
   tokens: FoundationTokens;
   pages: Record<string, SectionBlocks[]>;
   meta: ThemeMeta;
+  assets?: AssetFile[];
+  fontCss?: string;
+  imgRefsByPage?: Record<string, StaticImgRef[]>;
 };
 
 type PaletteEntry = {
@@ -30,12 +35,18 @@ export function assemble(parts: ThemeAssemblyParts): ThemeModel {
   const themeSlug = slugify(parts.meta.slug || parts.meta.name) || 'blocks-engine-theme';
   const palette = buildPalette(parts.tokens);
   const fontFamilies = buildFontFamilies(parts.tokens);
+  const styleCss = buildStyleCss(parts.meta, themeSlug);
 
   return {
-    styleCss: buildStyleCss(parts.meta, themeSlug),
+    styleCss: appendFontCss(styleCss, parts.fontCss),
     themeJson: buildThemeJson(parts.tokens, palette, fontFamilies),
     templates: {
-      'index.html': buildIndexTemplate(parts.site, parts.pages),
+      'index.html': buildIndexTemplate(
+        parts.site,
+        parts.pages,
+        parts.imgRefsByPage ?? {},
+        themeSlug
+      ),
     },
     parts: {},
     patterns: {},
@@ -43,6 +54,10 @@ export function assemble(parts: ThemeAssemblyParts): ThemeModel {
   };
 }
 
+function appendFontCss(styleCss: string, fontCss: string | undefined): string {
+  return fontCss ? `${styleCss}${fontCss}` : styleCss;
+}
+
 function buildStyleCss(meta: ThemeMeta, themeSlug: string): string {
   return buildThemeHeader([
     ['Theme Name', meta.name],
@@ -152,8 +167,13 @@ function colorValueFor(palette: PaletteEntry[], preferredSlugs: string[], fallba
   return fallback;
 }
 
-function buildIndexTemplate(site: SiteModel, pages: Record<string, SectionBlocks[]>): string {
-  const pageBlocks = orderedPageBlocks(site, pages);
+function buildIndexTemplate(
+  site: SiteModel,
+  pages: Record<string, SectionBlocks[]>,
+  imgRefsByPage: Record<string, StaticImgRef[]>,
+  themeSlug: string
+): string {
+  const pageBlocks = orderedPageBlocks(site, pages, imgRefsByPage, themeSlug);
   const blocks = pageBlocks.length > 0
     ? pageBlocks.join('\n\n')
     : '<!-- wp:paragraph -->\n<p></p>\n<!-- /wp:paragraph -->';
@@ -166,12 +186,17 @@ ${blocks}
 `;
 }
 
-function orderedPageBlocks(site: SiteModel, pages: Record<string, SectionBlocks[]>): string[] {
+function orderedPageBlocks(
+  site: SiteModel,
+  pages: Record<string, SectionBlocks[]>,
+  imgRefsByPage: Record<string, StaticImgRef[]>,
+  themeSlug: string
+): string[] {
   const out: string[] = [];
   const seen = new Set<string>();
 
   for (const page of site.pages) {
-    const blocks = blocksForPage(page.slug, pages);
+    const blocks = blocksForPage(page.slug, pages, imgRefsByPage, themeSlug);
     if (!blocks) continue;
     out.push(blocks);
     seen.add(page.slug);
@@ -179,28 +204,101 @@ function orderedPageBlocks(site: SiteModel, pages: Record<string, SectionBlocks[
 
   for (const [slug, sections] of Object.entries(pages).sort(([a], [b]) => a.localeCompare(b))) {
     if (seen.has(slug)) continue;
-    const blocks = joinSectionBlocks(sections);
+    const blocks = rewritePageBlocks(
+      slug,
+      joinSectionBlocks(sections, imgRefsByPage[slug] ?? []),
+      imgRefsByPage,
+      themeSlug
+    );
     if (blocks) out.push(blocks);
   }
 
   return out;
 }
 
-function blocksForPage(slug: string, pages: Record<string, SectionBlocks[]>): string | null {
-  return joinSectionBlocks(pages[slug] ?? []);
+function blocksForPage(
+  slug: string,
+  pages: Record<string, SectionBlocks[]>,
+  imgRefsByPage: Record<string, StaticImgRef[]>,
+  themeSlug: string
+): string | null {
+  return rewritePageBlocks(
+    slug,
+    joinSectionBlocks(pages[slug] ?? [], imgRefsByPage[slug] ?? []),
+    imgRefsByPage,
+    themeSlug
+  );
 }
 
-function joinSectionBlocks(sections: SectionBlocks[]): string | null {
-  const blocks = sections.map((section) => section.blocks.trim()).filter(Boolean);
+function joinSectionBlocks(sections: SectionBlocks[], refs: StaticImgRef[]): string | null {
+  const blocks = sections
+    .map((section) => sectionBlocksWithMissingImages(section, refs).trim())
+    .filter(Boolean);
   return blocks.length > 0 ? blocks.join('\n\n') : null;
 }
 
-function collectAssets(parts: ThemeAssemblyParts): AssetFile[] {
+function sectionBlocksWithMissingImages(section: SectionBlocks, refs: StaticImgRef[]): string {
+  const blocks = section.blocks.trim();
+  const missingImages = missingImageBlocks(section, refs, blocks);
+  if (missingImages.length === 0) return blocks;
+  return [blocks, ...missingImages].filter(Boolean).join('\n\n');
+}
+
+function missingImageBlocks(
+  section: SectionBlocks,
+  refs: StaticImgRef[],
+  blocks: string
+): string[] {
+  const out: string[] = [];
+  const emitted = new Set<string>();
+
+  for (const image of section.spec.images) {
+    const ref = refs.find(
+      (candidate) => candidate.ref === image.url || candidate.ref === image.sourceUrl
+    );
+    if (!ref || emitted.has(ref.ref) || blocks.includes(ref.ref)) continue;
+
+    emitted.add(ref.ref);
+    out.push(imageBlock(ref.ref, image.alt));
+  }
+
+  return out;
+}
+
+function imageBlock(src: string, alt: string): string {
   return [
+    '<!-- wp:image -->',
+    `<figure class="wp-block-image"><img src="${escapeHtmlAttr(src)}" alt="${escapeHtmlAttr(alt)}"/></figure>`,
+    '<!-- /wp:image -->',
+  ].join('\n');
+}
+
+function rewritePageBlocks(
+  slug: string,
+  blocks: string | null,
+  imgRefsByPage: Record<string, StaticImgRef[]>,
+  themeSlug: string
+): string | null {
+  if (!blocks) return null;
+  return rewriteHtmlImageSrcs(blocks, imgRefsByPage[slug] ?? [], themeSlug);
+}
+
+function collectAssets(parts: ThemeAssemblyParts): AssetFile[] {
+  const assetsByRelPath = new Map<string, AssetFile>();
+
+  for (const asset of [
     ...assetFilesFromUnknown(parts.site),
     ...assetFilesFromUnknown(parts.tokens),
     ...assetFilesFromUnknown(parts.meta),
-  ];
+  ]) {
+    assetsByRelPath.set(asset.relPath, asset);
+  }
+
+  for (const asset of parts.assets ?? []) {
+    assetsByRelPath.set(asset.relPath, asset);
+  }
+
+  return [...assetsByRelPath.values()];
 }
 
 function assetFilesFromUnknown(value: unknown): AssetFile[] {
diff --git a/packages/blocks-engine/src/theme/site-to-theme.ts b/packages/blocks-engine/src/theme/site-to-theme.ts
index e3bb228d..50205f28 100644
--- a/packages/blocks-engine/src/theme/site-to-theme.ts
+++ b/packages/blocks-engine/src/theme/site-to-theme.ts
@@ -2,12 +2,15 @@ import { join } from 'node:path';
 
 import { createWorker } from '../pool/pool.js';
 import { assemble } from './assemble.js';
+import { assets as runAssetsStage } from './assets.js';
 import { foundation } from './foundation.js';
 import { ingest } from './ingest.js';
 import { reconstruct } from './reconstruct.js';
 import { sectionExtract } from './section-extract.js';
 import { writeTheme } from './write-theme.js';
 import type {
+  AssetInventory,
+  AssetVerdicts,
   SectionBlocks,
   SiteToThemeOptions,
   StageCtx,
@@ -35,7 +38,6 @@ export async function siteToTheme(
   const outDir = options?.outDir ?? join(srcDir, 'theme');
   const coverageFloor = options?.coverageFloor ?? 0;
   const hooks = options?.hooks ?? {};
-  void options?.fetchImpl;
 
   try {
     const baseTokens = foundation(site, options?.foundationAggregates);
@@ -47,7 +49,22 @@ export async function siteToTheme(
       pages[page.slug] = await reconstruct(specs, ctx, pool, hooks, coverageFloor);
     }
 
-    const assembled = assemble({ site, tokens, pages, meta: themeMeta });
+    const assetStage = await runAssetsStage(ctx, { fetchImpl: options?.fetchImpl });
+    const inventory = hooks.onAssets
+      ? filterDecorativeAssets(
+          assetStage.inventory,
+          await hooks.onAssets(assetStage.inventory, ctx)
+        )
+      : assetStage.inventory;
+    const assembled = assemble({
+      site,
+      tokens,
+      pages,
+      meta: themeMeta,
+      assets: inventory.assets,
+      fontCss: assetStage.fontCss,
+      imgRefsByPage: assetStage.imgRefsByPage,
+    });
     const model = hooks.onRefine ? await hooks.onRefine(assembled, ctx) : assembled;
     const written = await writeTheme(model, outDir);
 
@@ -73,6 +90,18 @@ export async function siteToTheme(
   }
 }
 
+function filterDecorativeAssets(
+  inventory: AssetInventory,
+  verdicts: AssetVerdicts
+): AssetInventory {
+  const decoration = new Set(verdicts.decoration);
+  if (decoration.size === 0) return inventory;
+
+  return {
+    assets: inventory.assets.filter((asset) => !decoration.has(asset.relPath)),
+  };
+}
+
 function normalizeThemeMeta(srcDir: string, meta: Partial<ThemeMeta> | undefined): ThemeMeta {
   const fallback = srcDir.split(/[\\/]+/).filter(Boolean).at(-1) ?? 'blocks-engine-theme';
   const slug = slugify(meta?.slug ?? fallback);

From 90378e16bbf5e622c9feadbd4b34c90e92904dfb Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 14:20:40 -0400
Subject: [PATCH 043/113] Fix honest site-to-theme asset rewrite

---
 .../src/__tests__/fixtures/site/index.html    |  2 +-
 .../src/__tests__/site-to-theme.e2e.test.ts   |  6 ++-
 packages/blocks-engine/src/theme/assemble.ts  | 45 ++-----------------
 3 files changed, 9 insertions(+), 44 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/fixtures/site/index.html b/packages/blocks-engine/src/__tests__/fixtures/site/index.html
index 779f509e..94807741 100644
--- a/packages/blocks-engine/src/__tests__/fixtures/site/index.html
+++ b/packages/blocks-engine/src/__tests__/fixtures/site/index.html
@@ -17,13 +17,13 @@
       <section id="hero">
         <h1>Build calmer block themes</h1>
         <p>Static source pages become a structured theme pipeline.</p>
-        <img src="assets/logo.png" alt="Blocks Engine mark" />
         <a class="button" href="./about.html">Learn more</a>
       </section>
       <section id="empty"></section>
       <section aria-labelledby="features-title">
         <h2 id="features-title">What carries forward</h2>
         <p>Headings, body copy, selectors, and simple calls to action.</p>
+        <img src="assets/logo.png" alt="Blocks Engine mark" />
       </section>
     </main>
     <footer>
diff --git a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
index 4a43897c..3493d066 100644
--- a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
+++ b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
@@ -333,8 +333,6 @@ describe('site-to-theme P0-3 orchestration', () => {
 
       const result = await siteToTheme(siteDir, {
         outDir,
-        pool: p1Pool(),
-        sections: p1Sections(),
         fetchImpl,
         themeMeta: themeMeta(),
       });
@@ -355,6 +353,10 @@ describe('site-to-theme P0-3 orchestration', () => {
 
       const template = readFileSync(join(outDir, 'templates', 'index.html'), 'utf8');
       expect(template).toContain('/wp-content/themes/fixture-theme/assets/logo.png');
+      expect(template).toMatch(
+        /<!-- wp:html \{"metadata":\{"name":"lib-coverage-island"\}\} -->[\s\S]*<img src="\/wp-content\/themes\/fixture-theme\/assets\/logo\.png" alt="Blocks Engine mark">[\s\S]*<!-- \/wp:html -->/
+      );
+      expect(template).not.toContain('<!-- wp:image -->');
       expect(template).not.toContain('src="assets/logo.png"');
     });
   });
diff --git a/packages/blocks-engine/src/theme/assemble.ts b/packages/blocks-engine/src/theme/assemble.ts
index 2bede2b0..fed623d7 100644
--- a/packages/blocks-engine/src/theme/assemble.ts
+++ b/packages/blocks-engine/src/theme/assemble.ts
@@ -1,4 +1,3 @@
-import { escapeHtmlAttr } from '../escape.js';
 import { rewriteHtmlImageSrcs, type StaticImgRef } from './assets-static.js';
 import type {
   AssetFile,
@@ -206,7 +205,7 @@ function orderedPageBlocks(
     if (seen.has(slug)) continue;
     const blocks = rewritePageBlocks(
       slug,
-      joinSectionBlocks(sections, imgRefsByPage[slug] ?? []),
+      joinSectionBlocks(sections),
       imgRefsByPage,
       themeSlug
     );
@@ -224,55 +223,19 @@ function blocksForPage(
 ): string | null {
   return rewritePageBlocks(
     slug,
-    joinSectionBlocks(pages[slug] ?? [], imgRefsByPage[slug] ?? []),
+    joinSectionBlocks(pages[slug] ?? []),
     imgRefsByPage,
     themeSlug
   );
 }
 
-function joinSectionBlocks(sections: SectionBlocks[], refs: StaticImgRef[]): string | null {
+function joinSectionBlocks(sections: SectionBlocks[]): string | null {
   const blocks = sections
-    .map((section) => sectionBlocksWithMissingImages(section, refs).trim())
+    .map((section) => section.blocks.trim())
     .filter(Boolean);
   return blocks.length > 0 ? blocks.join('\n\n') : null;
 }
 
-function sectionBlocksWithMissingImages(section: SectionBlocks, refs: StaticImgRef[]): string {
-  const blocks = section.blocks.trim();
-  const missingImages = missingImageBlocks(section, refs, blocks);
-  if (missingImages.length === 0) return blocks;
-  return [blocks, ...missingImages].filter(Boolean).join('\n\n');
-}
-
-function missingImageBlocks(
-  section: SectionBlocks,
-  refs: StaticImgRef[],
-  blocks: string
-): string[] {
-  const out: string[] = [];
-  const emitted = new Set<string>();
-
-  for (const image of section.spec.images) {
-    const ref = refs.find(
-      (candidate) => candidate.ref === image.url || candidate.ref === image.sourceUrl
-    );
-    if (!ref || emitted.has(ref.ref) || blocks.includes(ref.ref)) continue;
-
-    emitted.add(ref.ref);
-    out.push(imageBlock(ref.ref, image.alt));
-  }
-
-  return out;
-}
-
-function imageBlock(src: string, alt: string): string {
-  return [
-    '<!-- wp:image -->',
-    `<figure class="wp-block-image"><img src="${escapeHtmlAttr(src)}" alt="${escapeHtmlAttr(alt)}"/></figure>`,
-    '<!-- /wp:image -->',
-  ].join('\n');
-}
-
 function rewritePageBlocks(
   slug: string,
   blocks: string | null,

From 2b193dba38188068591f13695ae1361cbeca03a1 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 14:33:26 -0400
Subject: [PATCH 044/113] Freeze chrome split contract

---
 packages/blocks-engine/src/theme/chrome-split.ts | 9 +++++++++
 packages/blocks-engine/src/theme/index.ts        | 2 ++
 2 files changed, 11 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/chrome-split.ts

diff --git a/packages/blocks-engine/src/theme/chrome-split.ts b/packages/blocks-engine/src/theme/chrome-split.ts
new file mode 100644
index 00000000..0e015594
--- /dev/null
+++ b/packages/blocks-engine/src/theme/chrome-split.ts
@@ -0,0 +1,9 @@
+export interface RegionSplit {
+  headerHtml: string;
+  mainHtml: string;
+  footerHtml: string;
+}
+
+export function splitPageChrome(bodyHtml: string): RegionSplit {
+  return { headerHtml: '', mainHtml: bodyHtml, footerHtml: '' };
+}
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 0d207e4e..113596f3 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -1,5 +1,6 @@
 export { assemble } from './assemble.js';
 export { assets } from './assets.js';
+export { splitPageChrome } from './chrome-split.js';
 export { foundation } from './foundation.js';
 export { ingest } from './ingest.js';
 export { reconstruct } from './reconstruct.js';
@@ -10,6 +11,7 @@ export { writeTheme } from './write-theme.js';
 
 export type * from './assets-static.js';
 export type * from './assets.js';
+export type { RegionSplit } from './chrome-split.js';
 export type * from './font-faces.js';
 export type * from './section-spec.js';
 export type * from './types.js';

From 0fb8c21b87ecd8c2bebc8003841d4200a74cc9b9 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 14:40:22 -0400
Subject: [PATCH 045/113] Implement browser-free chrome split

---
 .../src/__tests__/theme-chrome-split.test.ts  |  86 +++++++
 .../blocks-engine/src/theme/chrome-split.ts   | 227 ++++++++++++++++++
 2 files changed, 313 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-chrome-split.test.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-chrome-split.test.ts b/packages/blocks-engine/src/__tests__/theme-chrome-split.test.ts
new file mode 100644
index 00000000..9054d6f0
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-chrome-split.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+
+import { splitPageChrome, type RegionSplit } from '../theme/index.js';
+
+describe('splitPageChrome', () => {
+  it('splits shallow top-level header, main, and footer regions', () => {
+    const input =
+      '<header><nav>Primary</nav></header><main><h1>Welcome</h1><p>Body copy.</p></main><footer><p>Footer copy.</p></footer>';
+
+    const split: RegionSplit = splitPageChrome(input);
+
+    expect(split).toEqual({
+      headerHtml: '<header><nav>Primary</nav></header>',
+      mainHtml: '<main><h1>Welcome</h1><p>Body copy.</p></main>',
+      footerHtml: '<footer><p>Footer copy.</p></footer>',
+    });
+  });
+
+  it('falls back to the shallow role-based splitter when no semantic tags exist', () => {
+    const input =
+      '<div role="banner"><nav>Primary</nav></div><main><p>Body copy.</p></main><div role="contentinfo"><p>Footer copy.</p></div>';
+
+    expect(splitPageChrome(input)).toEqual({
+      headerHtml: '<div role="banner"><nav>Primary</nav></div>',
+      mainHtml: '<main><p>Body copy.</p></main>',
+      footerHtml: '<div role="contentinfo"><p>Footer copy.</p></div>',
+    });
+  });
+
+  it('finds deep nested chrome while keeping the surrounding page wrapper and content', () => {
+    const input =
+      '<div class="site"><div class="frame"><header id="SITE_HEADER"><nav>Primary</nav></header><main data-page="home"><section id="hero"><h1>Hero</h1></section><section id="story"><p>Story copy.</p></section></main><footer id="SITE_FOOTER"><p>Footer copy.</p></footer></div></div>';
+
+    const split = splitPageChrome(input);
+
+    expect(split.headerHtml).toBe('<header id="SITE_HEADER"><nav>Primary</nav></header>');
+    expect(split.footerHtml).toBe('<footer id="SITE_FOOTER"><p>Footer copy.</p></footer>');
+    expect(split.mainHtml).toBe(
+      '<div class="site"><div class="frame"><main data-page="home"><section id="hero"><h1>Hero</h1></section><section id="story"><p>Story copy.</p></section></main></div></div>'
+    );
+    expect(split.mainHtml).toContain('<div class="site"><div class="frame">');
+    expect(split.mainHtml).toContain('<section id="hero"><h1>Hero</h1></section>');
+    expect(split.mainHtml).toContain('<section id="story"><p>Story copy.</p></section>');
+    expect(split.mainHtml).not.toContain('SITE_HEADER');
+    expect(split.mainHtml).not.toContain('SITE_FOOTER');
+    expect(split.mainHtml).not.toContain('<nav>Primary</nav>');
+    expect(split.mainHtml).not.toContain('<p>Footer copy.</p>');
+  });
+
+  it('keeps custom elements that start with header inside main content', () => {
+    const input =
+      '<header><header-drawer>Menu</header-drawer><nav>Primary</nav></header><main><header-menu>Inline menu widget</header-menu><p>Body copy.</p></main><footer>Footer</footer>';
+
+    const split = splitPageChrome(input);
+
+    expect(split.headerHtml).toBe(
+      '<header><header-drawer>Menu</header-drawer><nav>Primary</nav></header>'
+    );
+    expect(split.mainHtml).toBe(
+      '<main><header-menu>Inline menu widget</header-menu><p>Body copy.</p></main>'
+    );
+    expect(split.footerHtml).toBe('<footer>Footer</footer>');
+  });
+
+  it('returns header-only chrome with the remaining body as main HTML', () => {
+    const input =
+      '<div class="site"><header id="SITE_HEADER">Header</header><main><section>Only body</section></main></div>';
+
+    expect(splitPageChrome(input)).toEqual({
+      headerHtml: '<header id="SITE_HEADER">Header</header>',
+      mainHtml: '<div class="site"><main><section>Only body</section></main></div>',
+      footerHtml: '',
+    });
+  });
+
+  it('passes through body HTML exactly when no chrome is present', () => {
+    const input =
+      '<div class="content"><section><h2>Plain content</h2><p>No site chrome here.</p></section></div>';
+
+    expect(splitPageChrome(input)).toEqual({
+      headerHtml: '',
+      mainHtml: input,
+      footerHtml: '',
+    });
+  });
+});
diff --git a/packages/blocks-engine/src/theme/chrome-split.ts b/packages/blocks-engine/src/theme/chrome-split.ts
index 0e015594..ea52ccb3 100644
--- a/packages/blocks-engine/src/theme/chrome-split.ts
+++ b/packages/blocks-engine/src/theme/chrome-split.ts
@@ -1,9 +1,236 @@
+import * as cheerio from 'cheerio';
+
 export interface RegionSplit {
   headerHtml: string;
   mainHtml: string;
   footerHtml: string;
 }
 
+interface DeepRegionSplit {
+  found: boolean;
+  openWrap: string;
+  headerHtml: string;
+  midBefore: string;
+  sectionsHtml: string[];
+  midAfter: string;
+  footerHtml: string;
+  closeWrap: string;
+}
+
+function splitRegions(bodyHtml: string): RegionSplit {
+  const $ = cheerio.load(bodyHtml, null, false);
+  const root = $.root();
+
+  const header = root.children('header, [role="banner"]').first();
+  const footer = root.children('footer, [role="contentinfo"]').last();
+
+  const headerHtml = header.length ? $.html(header) : '';
+  const footerHtml = footer.length ? $.html(footer) : '';
+
+  if (header.length) header.remove();
+  if (footer.length) footer.remove();
+
+  const mainHtml = $.html(root).trim();
+  return { headerHtml, mainHtml, footerHtml };
+}
+
+function balancedSpan(html: string, tag: string, which: 'first' | 'last'): [number, number] | null {
+  const open = new RegExp(`<${tag}(?![\\w-])[^>]*>`, 'gi');
+  const close = new RegExp(`</${tag}\\s*>`, 'gi');
+  const toks: Array<{ i: number; end: number; open: boolean }> = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = open.exec(html))) {
+    toks.push({ i: match.index, end: match.index + match[0].length, open: true });
+  }
+  while ((match = close.exec(html))) {
+    toks.push({ i: match.index, end: match.index + match[0].length, open: false });
+  }
+
+  toks.sort((a, b) => a.i - b.i);
+
+  const spans: Array<[number, number]> = [];
+  let depth = 0;
+  let start = -1;
+
+  for (const tok of toks) {
+    if (tok.open) {
+      if (depth === 0) start = tok.i;
+      depth++;
+    } else if (depth > 0) {
+      depth--;
+      if (depth === 0 && start >= 0) spans.push([start, tok.end]);
+    }
+  }
+
+  if (spans.length === 0) return null;
+  return which === 'first' ? spans[0] : spans[spans.length - 1];
+}
+
+function idStart(html: string, id: string): number {
+  const match = new RegExp(`<[a-zA-Z][^>]*\\bid="${id}"`, 'i').exec(html);
+  return match ? match.index : -1;
+}
+
+function findChrome(
+  html: string,
+  opts: { tag: 'header' | 'footer'; id: string; which: 'first' | 'last' }
+): [number, number] | null {
+  const idx = idStart(html, opts.id);
+  if (idx >= 0) {
+    const span = balancedSpan(html.slice(idx), opts.tag, 'first');
+    if (span) return [idx + span[0], idx + span[1]];
+  }
+
+  return balancedSpan(html, opts.tag, opts.which);
+}
+
+function divSpanEnd(html: string, start: number): number {
+  const re = /<div(?![\w-])|<\/div\s*>/gi;
+  re.lastIndex = start;
+  let depth = 0;
+  let match: RegExpExecArray | null;
+
+  while ((match = re.exec(html))) {
+    if (match[0][1] === '/') {
+      depth--;
+      if (depth === 0) return match.index + match[0].length;
+    } else {
+      depth++;
+    }
+  }
+
+  return html.length;
+}
+
+function extendToHeaderGroup(html: string, header: [number, number]): [number, number] {
+  const marker = 'shopify-section-group-header-group';
+  let firstStart = -1;
+  let lastEnd = -1;
+  let from = 0;
+
+  for (;;) {
+    const markerIndex = html.indexOf(marker, from);
+    if (markerIndex < 0) break;
+
+    const lt = html.lastIndexOf('<', markerIndex);
+    if (lt < 0) break;
+
+    const end = divSpanEnd(html, lt);
+    if (firstStart < 0) firstStart = lt;
+    else if (html.slice(lastEnd, lt).trim() !== '') break;
+
+    lastEnd = end;
+    from = end;
+  }
+
+  if (firstStart >= 0 && firstStart <= header[0] && lastEnd >= header[1]) {
+    return [firstStart, lastEnd];
+  }
+
+  return header;
+}
+
+function topLevelSections(html: string): Array<[number, number]> {
+  const re = /<\/?section\b[^>]*>/gi;
+  const out: Array<[number, number]> = [];
+  let depth = 0;
+  let start = -1;
+  let match: RegExpExecArray | null;
+
+  while ((match = re.exec(html))) {
+    const isClose = match[0].startsWith('</');
+    if (!isClose) {
+      if (depth === 0) start = match.index;
+      depth++;
+    } else if (depth > 0) {
+      depth--;
+      if (depth === 0 && start >= 0) out.push([start, match.index + match[0].length]);
+    }
+  }
+
+  return out;
+}
+
+function splitRegionsDeep(bodyHtml: string): DeepRegionSplit {
+  const empty: DeepRegionSplit = {
+    found: false,
+    openWrap: '',
+    headerHtml: '',
+    midBefore: '',
+    sectionsHtml: [],
+    midAfter: '',
+    footerHtml: '',
+    closeWrap: '',
+  };
+
+  const headerEl = findChrome(bodyHtml, { tag: 'header', id: 'SITE_HEADER', which: 'first' });
+  const header = headerEl ? extendToHeaderGroup(bodyHtml, headerEl) : null;
+  const footer = findChrome(bodyHtml, { tag: 'footer', id: 'SITE_FOOTER', which: 'last' });
+
+  if (!header && !footer) return empty;
+
+  const headerStart = header ? header[0] : 0;
+  const headerEnd = header ? header[1] : 0;
+  const footerStart = footer ? footer[0] : bodyHtml.length;
+  const footerEnd = footer ? footer[1] : bodyHtml.length;
+
+  if (footerStart < headerEnd) return empty;
+
+  const openWrap = bodyHtml.slice(0, headerStart);
+  const headerHtml = header ? bodyHtml.slice(headerStart, headerEnd) : '';
+  const middle = bodyHtml.slice(headerEnd, footerStart);
+  const footerHtml = footer ? bodyHtml.slice(footerStart, footerEnd) : '';
+  const closeWrap = bodyHtml.slice(footerEnd);
+
+  const sections = topLevelSections(middle);
+  if (sections.length === 0) {
+    return {
+      found: true,
+      openWrap,
+      headerHtml,
+      midBefore: '',
+      sectionsHtml: middle ? [middle] : [],
+      midAfter: '',
+      footerHtml,
+      closeWrap,
+    };
+  }
+
+  const midBefore = middle.slice(0, sections[0][0]);
+  const midAfter = middle.slice(sections[sections.length - 1][1]);
+  const sectionsHtml: string[] = [];
+
+  for (let idx = 0; idx < sections.length; idx++) {
+    const end = idx + 1 < sections.length ? sections[idx + 1][0] : sections[idx][1];
+    sectionsHtml.push(middle.slice(sections[idx][0], end));
+  }
+
+  return {
+    found: true,
+    openWrap,
+    headerHtml,
+    midBefore,
+    sectionsHtml,
+    midAfter,
+    footerHtml,
+    closeWrap,
+  };
+}
+
 export function splitPageChrome(bodyHtml: string): RegionSplit {
+  const deep = splitRegionsDeep(bodyHtml);
+  if (deep.found) {
+    return {
+      headerHtml: deep.headerHtml,
+      mainHtml:
+        deep.openWrap + deep.midBefore + deep.sectionsHtml.join('') + deep.midAfter + deep.closeWrap,
+      footerHtml: deep.footerHtml,
+    };
+  }
+
+  const shallow = splitRegions(bodyHtml);
+  if (shallow.headerHtml || shallow.footerHtml) return shallow;
+
   return { headerHtml: '', mainHtml: bodyHtml, footerHtml: '' };
 }

From 61fbeaec5265614d6fe1d8189e18f343172a9559 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 14:47:15 -0400
Subject: [PATCH 046/113] Freeze chrome signature contract

---
 .../__tests__/theme-chrome-signature.test.ts  | 26 +++++++++++++++++++
 .../src/theme/chrome-signature.ts             | 20 ++++++++++++++
 packages/blocks-engine/src/theme/index.ts     |  2 ++
 3 files changed, 48 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-chrome-signature.test.ts
 create mode 100644 packages/blocks-engine/src/theme/chrome-signature.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-chrome-signature.test.ts b/packages/blocks-engine/src/__tests__/theme-chrome-signature.test.ts
new file mode 100644
index 00000000..cd45972d
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-chrome-signature.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import {
+  assignChromeVariants,
+  chromeSignature,
+  type ChromeSlugs,
+} from '../theme/index.js';
+
+describe('chrome signature contract', () => {
+  it('freezes the public signatures exported from the theme entrypoint', () => {
+    expect(typeof chromeSignature).toBe('function');
+    expect(typeof assignChromeVariants).toBe('function');
+
+    expectTypeOf(chromeSignature).toEqualTypeOf<
+      (headerHtml: string, footerHtml: string) => string
+    >();
+    expectTypeOf(assignChromeVariants).toEqualTypeOf<
+      (
+        pages: Array<{ slug: string; headerHtml: string; footerHtml: string }>
+      ) => {
+        slugsByPage: Record<string, ChromeSlugs>;
+        canonical: Record<string, { headerHtml: string; footerHtml: string }>;
+      }
+    >();
+  });
+});
diff --git a/packages/blocks-engine/src/theme/chrome-signature.ts b/packages/blocks-engine/src/theme/chrome-signature.ts
new file mode 100644
index 00000000..a2c956f5
--- /dev/null
+++ b/packages/blocks-engine/src/theme/chrome-signature.ts
@@ -0,0 +1,20 @@
+export function chromeSignature(headerHtml: string, footerHtml: string): string {
+  void headerHtml;
+  void footerHtml;
+  return '';
+}
+
+export interface ChromeSlugs {
+  header: string;
+  footer: string;
+}
+
+export function assignChromeVariants(
+  pages: Array<{ slug: string; headerHtml: string; footerHtml: string }>
+): {
+  slugsByPage: Record<string, ChromeSlugs>;
+  canonical: Record<string, { headerHtml: string; footerHtml: string }>;
+} {
+  void pages;
+  return { slugsByPage: {}, canonical: {} };
+}
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 113596f3..2a3e95c1 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -1,5 +1,6 @@
 export { assemble } from './assemble.js';
 export { assets } from './assets.js';
+export { assignChromeVariants, chromeSignature } from './chrome-signature.js';
 export { splitPageChrome } from './chrome-split.js';
 export { foundation } from './foundation.js';
 export { ingest } from './ingest.js';
@@ -11,6 +12,7 @@ export { writeTheme } from './write-theme.js';
 
 export type * from './assets-static.js';
 export type * from './assets.js';
+export type { ChromeSlugs } from './chrome-signature.js';
 export type { RegionSplit } from './chrome-split.js';
 export type * from './font-faces.js';
 export type * from './section-spec.js';

From 53cadd140c99930f6f23af9b0c4e825a17f42736 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 14:53:43 -0400
Subject: [PATCH 047/113] Implement chrome signature variants

---
 .../__tests__/theme-chrome-signature.test.ts  | 155 ++++++++++++++++++
 .../src/theme/chrome-signature.ts             |  63 ++++++-
 2 files changed, 213 insertions(+), 5 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/theme-chrome-signature.test.ts b/packages/blocks-engine/src/__tests__/theme-chrome-signature.test.ts
index cd45972d..b03fe5b3 100644
--- a/packages/blocks-engine/src/__tests__/theme-chrome-signature.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-chrome-signature.test.ts
@@ -23,4 +23,159 @@ describe('chrome signature contract', () => {
       }
     >();
   });
+
+  it('treats active nav state and lowercase Wix comp instance ids as signature-neutral', () => {
+    const footerHtml = `
+      <footer id="comp-footeraaa">
+        <p>Acme Studio</p>
+      </footer>
+    `;
+
+    const headerHtml = `
+      <header id="comp-headeraaa">
+        <nav>
+          <a id="comp-homeaaa" href="/" aria-current="page" data-selected="true" data-interactive="false">Home</a>
+          <a id="comp-aboutaaa" href="/about" data-interactive="true">About</a>
+        </nav>
+      </header>
+    `;
+    const sameHeaderHtml = `
+      <header id="comp-headerbbb">
+        <nav>
+          <a id="comp-homebbb" href="/" data-interactive="true">Home</a>
+          <a id="comp-aboutbbb" href="/about" aria-current="page" data-selected="true" data-interactive="false">About</a>
+        </nav>
+      </header>
+    `;
+    const differentHeaderHtml = `
+      <header id="comp-headerccc">
+        <nav>
+          <a id="comp-homeccc" href="/" aria-current="page" data-selected="true" data-interactive="false">Home</a>
+          <a id="comp-contactccc" href="/contact" data-interactive="true">Contact</a>
+        </nav>
+      </header>
+    `;
+
+    expect(chromeSignature(headerHtml, footerHtml)).toBe(
+      chromeSignature(sameHeaderHtml, footerHtml)
+    );
+    expect(chromeSignature(headerHtml, footerHtml)).not.toBe(
+      chromeSignature(differentHeaderHtml, footerHtml)
+    );
+  });
+
+  it('preserves shared Wix component tails while normalizing page instance prefixes', () => {
+    const headerHtml =
+      '<header id="comp-aaa_r_comp-shared"><nav><a id="comp-linkaaa_r_comp-menu" href="/">Home</a></nav></header>';
+    const sameHeaderHtml =
+      '<header id="comp-bbb_r_comp-shared"><nav><a id="comp-linkbbb_r_comp-menu" href="/">Home</a></nav></header>';
+    const differentComponentTailHtml =
+      '<header id="comp-ccc_r_comp-different"><nav><a id="comp-linkccc_r_comp-menu" href="/">Home</a></nav></header>';
+
+    expect(chromeSignature(headerHtml, '')).toBe(chromeSignature(sameHeaderHtml, ''));
+    expect(chromeSignature(headerHtml, '')).not.toBe(
+      chromeSignature(differentComponentTailHtml, '')
+    );
+  });
+
+  it('assigns stable chrome variants and keeps the first page markup canonical', () => {
+    const pageAHeaderHtml = `
+      <header id="comp-headeraaa">
+        <nav>
+          <a id="comp-homeaaa" href="/" aria-current="page" data-selected="true" data-interactive="false">Home</a>
+          <a id="comp-workaaa" href="/work" data-interactive="true">Work</a>
+        </nav>
+      </header>
+    `;
+    const pageAFooterHtml = `
+      <footer id="comp-footeraaa">
+        <p>Acme Studio</p>
+      </footer>
+    `;
+    const pageBHeaderHtml = `
+      <header id="comp-headerbbb">
+        <nav>
+          <a id="comp-homebbb" href="/" data-interactive="true">Home</a>
+          <a id="comp-workbbb" href="/work" aria-current="page" data-selected="true" data-interactive="false">Work</a>
+        </nav>
+      </header>
+    `;
+    const pageBFooterHtml = `
+      <footer id="comp-footerbbb">
+        <p>Acme Studio</p>
+      </footer>
+    `;
+    const pageCHeaderHtml = `
+      <header id="comp-headerccc">
+        <nav>
+          <a id="comp-homeccc" href="/" aria-current="page" data-selected="true" data-interactive="false">Home</a>
+          <a id="comp-servicesccc" href="/services" data-interactive="true">Services</a>
+        </nav>
+      </header>
+    `;
+    const pageCFooterHtml = `
+      <footer id="comp-footerccc">
+        <p>Acme Services</p>
+      </footer>
+    `;
+
+    const variants = assignChromeVariants([
+      { slug: 'a', headerHtml: pageAHeaderHtml, footerHtml: pageAFooterHtml },
+      { slug: 'b', headerHtml: pageBHeaderHtml, footerHtml: pageBFooterHtml },
+      { slug: 'c', headerHtml: pageCHeaderHtml, footerHtml: pageCFooterHtml },
+    ]);
+
+    expect(variants.slugsByPage).toEqual({
+      a: { header: 'header', footer: 'footer' },
+      b: { header: 'header', footer: 'footer' },
+      c: { header: 'header-2', footer: 'footer-2' },
+    });
+    expect(Object.keys(variants.canonical)).toEqual(['header', 'header-2']);
+    expect(variants.canonical.header).toEqual({
+      headerHtml: pageAHeaderHtml,
+      footerHtml: pageAFooterHtml,
+    });
+    expect(variants.canonical['header-2']).toEqual({
+      headerHtml: pageCHeaderHtml,
+      footerHtml: pageCFooterHtml,
+    });
+  });
+
+  it('assigns variant names by input page order instead of slug order', () => {
+    const firstHeader = '<header id="comp-first"><nav><a href="/first">First</a></nav></header>';
+    const secondHeader =
+      '<header id="comp-second"><nav><a href="/second">Second</a></nav></header>';
+
+    const variants = assignChromeVariants([
+      { slug: 'z-last', headerHtml: firstHeader, footerHtml: '' },
+      { slug: 'a-first', headerHtml: secondHeader, footerHtml: '' },
+      { slug: 'm-middle', headerHtml: firstHeader, footerHtml: '' },
+    ]);
+
+    expect(variants.slugsByPage).toEqual({
+      'z-last': { header: 'header', footer: 'footer' },
+      'a-first': { header: 'header-2', footer: 'footer-2' },
+      'm-middle': { header: 'header', footer: 'footer' },
+    });
+    expect(variants.canonical).toEqual({
+      header: { headerHtml: firstHeader, footerHtml: '' },
+      'header-2': { headerHtml: secondHeader, footerHtml: '' },
+    });
+  });
+
+  it('keeps an empty header and footer addressable by signature and slugs', () => {
+    expect(chromeSignature('', '')).toEqual(expect.any(String));
+    expect(chromeSignature('', '')).not.toBe('');
+
+    expect(
+      assignChromeVariants([{ slug: 'empty', headerHtml: '', footerHtml: '' }])
+    ).toEqual({
+      slugsByPage: {
+        empty: { header: 'header', footer: 'footer' },
+      },
+      canonical: {
+        header: { headerHtml: '', footerHtml: '' },
+      },
+    });
+  });
 });
diff --git a/packages/blocks-engine/src/theme/chrome-signature.ts b/packages/blocks-engine/src/theme/chrome-signature.ts
index a2c956f5..11d1aa52 100644
--- a/packages/blocks-engine/src/theme/chrome-signature.ts
+++ b/packages/blocks-engine/src/theme/chrome-signature.ts
@@ -1,7 +1,6 @@
 export function chromeSignature(headerHtml: string, footerHtml: string): string {
-  void headerHtml;
-  void footerHtml;
-  return '';
+  const neutral = [stripActiveNavState(headerHtml), stripActiveNavState(footerHtml)].join('\u0001');
+  return canonicalizeInstanceIds(neutral);
 }
 
 export interface ChromeSlugs {
@@ -15,6 +14,60 @@ export function assignChromeVariants(
   slugsByPage: Record<string, ChromeSlugs>;
   canonical: Record<string, { headerHtml: string; footerHtml: string }>;
 } {
-  void pages;
-  return { slugsByPage: {}, canonical: {} };
+  const slugsByPage: Record<string, ChromeSlugs> = {};
+  const canonical: Record<string, { headerHtml: string; footerHtml: string }> = {};
+  const slugBySignature = new Map<string, ChromeSlugs>();
+
+  for (const page of pages) {
+    const signature = chromeSignature(page.headerHtml, page.footerHtml);
+    let slugs = slugBySignature.get(signature);
+
+    if (!slugs) {
+      slugs = chromeSlugsForIndex(slugBySignature.size);
+      slugBySignature.set(signature, slugs);
+      canonical[slugs.header] = {
+        headerHtml: page.headerHtml,
+        footerHtml: page.footerHtml,
+      };
+    }
+
+    slugsByPage[page.slug] = slugs;
+  }
+
+  return { slugsByPage, canonical };
+}
+
+function stripActiveNavState(html: string): string {
+  return html
+    .replace(/ ?data-selected="true"/g, '')
+    .replace(/ ?aria-current="page"/g, '')
+    .replace(/data-interactive="false"/g, 'data-interactive="true"');
+}
+
+function canonicalizeInstanceIds(s: string): string {
+  const order: string[] = [];
+  const seen = new Set<string>();
+
+  for (const match of s.matchAll(/(?<!_r_)comp-([a-z0-9]+)/g)) {
+    const instanceId = match[1];
+    if (!seen.has(instanceId)) {
+      seen.add(instanceId);
+      order.push(instanceId);
+    }
+  }
+
+  let out = s;
+  order.forEach((instanceId, index) => {
+    out = out.replace(
+      new RegExp(`(?<!_r_)comp-${instanceId}(?![a-z0-9])`, 'g'),
+      `comp-INSTANCE${index}`
+    );
+  });
+
+  return out;
+}
+
+function chromeSlugsForIndex(index: number): ChromeSlugs {
+  const suffix = index === 0 ? '' : `-${index + 1}`;
+  return { header: `header${suffix}`, footer: `footer${suffix}` };
 }

From 6db7e5dd31d7751a6904b4781bdb09982043f84e Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 15:04:36 -0400
Subject: [PATCH 048/113] Freeze chrome parts contract

---
 .../src/__tests__/theme-chrome-parts.test.ts  | 30 +++++++++++++++++++
 .../blocks-engine/src/theme/chrome-parts.ts   | 13 ++++++++
 packages/blocks-engine/src/theme/chrome.ts    | 21 +++++++++++++
 packages/blocks-engine/src/theme/index.ts     |  3 ++
 4 files changed, 67 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-chrome-parts.test.ts
 create mode 100644 packages/blocks-engine/src/theme/chrome-parts.ts
 create mode 100644 packages/blocks-engine/src/theme/chrome.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-chrome-parts.test.ts b/packages/blocks-engine/src/__tests__/theme-chrome-parts.test.ts
new file mode 100644
index 00000000..f02ed072
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-chrome-parts.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import {
+  buildChromePart,
+  chrome,
+  type ChromeResult,
+  type ChromeSlugs,
+  type StageCtx,
+} from '../theme/index.js';
+import type { WorkerPool } from '../pool/types.js';
+
+describe('chrome parts contract', () => {
+  it('freezes the public signatures exported from the theme entrypoint', () => {
+    expect(typeof buildChromePart).toBe('function');
+    expect(typeof chrome).toBe('function');
+
+    expectTypeOf(buildChromePart).toEqualTypeOf<
+      (html: string, ctx: StageCtx, pool: WorkerPool) => Promise<string>
+    >();
+    expectTypeOf(chrome).toEqualTypeOf<
+      (ctx: StageCtx, pool: WorkerPool) => Promise<ChromeResult>
+    >();
+    expectTypeOf<ChromeResult>().toEqualTypeOf<{
+      parts: Record<string, string>;
+      slugsByPage: Record<string, ChromeSlugs>;
+      mainHtmlByPage: Record<string, string>;
+      warnings: string[];
+    }>();
+  });
+});
diff --git a/packages/blocks-engine/src/theme/chrome-parts.ts b/packages/blocks-engine/src/theme/chrome-parts.ts
new file mode 100644
index 00000000..c07b64bd
--- /dev/null
+++ b/packages/blocks-engine/src/theme/chrome-parts.ts
@@ -0,0 +1,13 @@
+import type { WorkerPool } from '../pool/types.js';
+import type { StageCtx } from './types.js';
+
+export async function buildChromePart(
+  html: string,
+  ctx: StageCtx,
+  pool: WorkerPool
+): Promise<string> {
+  void html;
+  void ctx;
+  void pool;
+  return '';
+}
diff --git a/packages/blocks-engine/src/theme/chrome.ts b/packages/blocks-engine/src/theme/chrome.ts
new file mode 100644
index 00000000..a75e6b19
--- /dev/null
+++ b/packages/blocks-engine/src/theme/chrome.ts
@@ -0,0 +1,21 @@
+import type { WorkerPool } from '../pool/types.js';
+import type { ChromeSlugs } from './chrome-signature.js';
+import type { StageCtx } from './types.js';
+
+export interface ChromeResult {
+  parts: Record<string, string>;
+  slugsByPage: Record<string, ChromeSlugs>;
+  mainHtmlByPage: Record<string, string>;
+  warnings: string[];
+}
+
+export async function chrome(ctx: StageCtx, pool: WorkerPool): Promise<ChromeResult> {
+  void ctx;
+  void pool;
+  return {
+    parts: {},
+    slugsByPage: {},
+    mainHtmlByPage: {},
+    warnings: [],
+  };
+}
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 2a3e95c1..11c0897e 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -1,5 +1,7 @@
 export { assemble } from './assemble.js';
 export { assets } from './assets.js';
+export { buildChromePart } from './chrome-parts.js';
+export { chrome } from './chrome.js';
 export { assignChromeVariants, chromeSignature } from './chrome-signature.js';
 export { splitPageChrome } from './chrome-split.js';
 export { foundation } from './foundation.js';
@@ -12,6 +14,7 @@ export { writeTheme } from './write-theme.js';
 
 export type * from './assets-static.js';
 export type * from './assets.js';
+export type { ChromeResult } from './chrome.js';
 export type { ChromeSlugs } from './chrome-signature.js';
 export type { RegionSplit } from './chrome-split.js';
 export type * from './font-faces.js';

From c74e1bf2e270b337170b82ad33b6d618e754e967 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 15:16:07 -0400
Subject: [PATCH 049/113] Implement chrome part stage

---
 .../src/__tests__/fixtures/site/about.html    |   9 +
 .../src/__tests__/fixtures/site/services.html |  26 ++
 .../src/__tests__/theme-chrome-parts.test.ts  | 239 +++++++++++++++++-
 .../src/__tests__/theme-ingest.test.ts        |  21 +-
 .../blocks-engine/src/theme/chrome-parts.ts   |   5 +-
 packages/blocks-engine/src/theme/chrome.ts    |  84 +++++-
 6 files changed, 372 insertions(+), 12 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/fixtures/site/services.html

diff --git a/packages/blocks-engine/src/__tests__/fixtures/site/about.html b/packages/blocks-engine/src/__tests__/fixtures/site/about.html
index a16ca932..efcafe0d 100644
--- a/packages/blocks-engine/src/__tests__/fixtures/site/about.html
+++ b/packages/blocks-engine/src/__tests__/fixtures/site/about.html
@@ -6,11 +6,20 @@
     <link rel="stylesheet" href="./style.css" />
   </head>
   <body data-page="about">
+    <header>
+      <nav aria-label="Primary">
+        <a href="./index.html">Home</a>
+        <a href="./about.html">About</a>
+      </nav>
+    </header>
     <main>
       <article>
         <h1>About the assembler</h1>
         <p>The first browser-free pass extracts stable page sections.</p>
       </article>
     </main>
+    <footer>
+      <p>Blocks Engine</p>
+    </footer>
   </body>
 </html>
diff --git a/packages/blocks-engine/src/__tests__/fixtures/site/services.html b/packages/blocks-engine/src/__tests__/fixtures/site/services.html
new file mode 100644
index 00000000..23bbfdcc
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/fixtures/site/services.html
@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Services</title>
+    <link rel="stylesheet" href="./style.css" />
+  </head>
+  <body data-page="services" data-template="services">
+    <header>
+      <nav aria-label="Primary">
+        <a href="./index.html">Home</a>
+        <a href="./about.html">About</a>
+        <a href="./services.html">Services</a>
+      </nav>
+    </header>
+    <main>
+      <section id="services">
+        <h1>Service design for block themes</h1>
+        <p>We map static chrome into reusable WordPress template parts.</p>
+      </section>
+    </main>
+    <footer>
+      <p>Blocks Engine Services</p>
+    </footer>
+  </body>
+</html>
diff --git a/packages/blocks-engine/src/__tests__/theme-chrome-parts.test.ts b/packages/blocks-engine/src/__tests__/theme-chrome-parts.test.ts
index f02ed072..22f39caa 100644
--- a/packages/blocks-engine/src/__tests__/theme-chrome-parts.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-chrome-parts.test.ts
@@ -1,13 +1,122 @@
+import { join } from 'node:path';
+
 import { describe, expect, expectTypeOf, it } from 'vitest';
 
 import {
   buildChromePart,
   chrome,
+  ingest,
   type ChromeResult,
   type ChromeSlugs,
+  type SiteModel,
   type StageCtx,
 } from '../theme/index.js';
-import type { WorkerPool } from '../pool/types.js';
+import type { RawConvertResult, WorkerPool } from '../pool/types.js';
+
+const fixtureRoot = join(import.meta.dirname, 'fixtures/site');
+
+type CapturingPool = WorkerPool & {
+  rawInputs: string[][];
+  canonicalInputs: string[][];
+  stopCalls: number;
+};
+
+const sharedHeaderHtml = [
+  '<header>',
+  '      <nav aria-label="Primary">',
+  '        <a href="./index.html">Home</a>',
+  '        <a href="./about.html">About</a>',
+  '      </nav>',
+  '    </header>',
+].join('\n');
+
+const sharedFooterHtml = [
+  '<footer>',
+  '      <p>Blocks Engine</p>',
+  '    </footer>',
+].join('\n');
+
+const servicesHeaderHtml = [
+  '<header>',
+  '      <nav aria-label="Primary">',
+  '        <a href="./index.html">Home</a>',
+  '        <a href="./about.html">About</a>',
+  '        <a href="./services.html">Services</a>',
+  '      </nav>',
+  '    </header>',
+].join('\n');
+
+const servicesFooterHtml = [
+  '<footer>',
+  '      <p>Blocks Engine Services</p>',
+  '    </footer>',
+].join('\n');
+
+function coverageIsland(html: string): string {
+  return [
+    '<!-- wp:html {"metadata":{"name":"lib-coverage-island"}} -->',
+    html.trim(),
+    '<!-- /wp:html -->',
+  ].join('\n');
+}
+
+function stageCtx(site: SiteModel, warnings: string[] = []): StageCtx {
+  return {
+    srcDir: site.root,
+    site,
+    themeMeta: {
+      name: 'Fixture Theme',
+      slug: 'fixture-theme',
+    },
+    warn(message) {
+      warnings.push(message);
+    },
+  };
+}
+
+function fakePool(rawForHtml: (html: string) => RawConvertResult): CapturingPool {
+  return {
+    rawInputs: [],
+    canonicalInputs: [],
+    stopCalls: 0,
+    async rawConvert(items) {
+      this.rawInputs.push(items);
+      return items.map(rawForHtml);
+    },
+    async canonicalize(items) {
+      this.canonicalInputs.push(items);
+      return items.map((html) => ({
+        html,
+        changed: false,
+        fixedIssues: [],
+      }));
+    },
+    async stop() {
+      this.stopCalls += 1;
+    },
+  };
+}
+
+function fallbackPool(): CapturingPool {
+  return fakePool(() => ({ html: null, wpHtmlResidue: 0 }));
+}
+
+function fixtureChromeCtx(warnings: string[] = []): StageCtx {
+  return stageCtx(ingest(fixtureRoot), warnings);
+}
+
+function expectMainWithoutChrome(
+  mainHtml: string,
+  bodyText: string,
+  headerHtml: string,
+  footerHtml: string
+): void {
+  expect(mainHtml).toContain(bodyText);
+  expect(mainHtml).not.toContain(headerHtml);
+  expect(mainHtml).not.toContain(footerHtml);
+  expect(mainHtml).not.toContain('<header>');
+  expect(mainHtml).not.toContain('<footer>');
+}
 
 describe('chrome parts contract', () => {
   it('freezes the public signatures exported from the theme entrypoint', () => {
@@ -27,4 +136,132 @@ describe('chrome parts contract', () => {
       warnings: string[];
     }>();
   });
+
+  it('returns native raw convert output without adding chrome wrappers', async () => {
+    const html = '<header><nav>Primary</nav></header>';
+    const nativePart = [
+      '<!-- wp:navigation -->',
+      '<nav class="wp-block-navigation">Primary</nav>',
+      '<!-- /wp:navigation -->',
+    ].join('\n');
+    const pool = fakePool(() => ({ html: nativePart, wpHtmlResidue: 0 }));
+
+    const out = await buildChromePart(html, stageCtx({ root: fixtureRoot, pages: [] }), pool);
+
+    expect(out).toBe(nativePart);
+    expect(out).not.toContain('<header>');
+    expect(pool.rawInputs).toEqual([[html]]);
+    expect(pool.canonicalInputs).toEqual([[nativePart]]);
+    expect(pool.stopCalls).toBe(0);
+  });
+
+  it('returns fallback core/html lib coverage island output when raw convert leaves residue', async () => {
+    const html = '<div class="site-chrome"><span>Primary chrome</span></div>';
+    const expected = coverageIsland(html);
+    const pool = fakePool(() => ({
+      html: '<!-- wp:html -->raw residue<!-- /wp:html -->',
+      wpHtmlResidue: 1,
+    }));
+
+    const out = await buildChromePart(html, stageCtx({ root: fixtureRoot, pages: [] }), pool);
+
+    expect(out).toBe(expected);
+    expect(pool.rawInputs).toEqual([[html]]);
+    expect(pool.canonicalInputs).toEqual([[expected]]);
+    expect(pool.stopCalls).toBe(0);
+  });
+
+  it('passes empty chrome input through convert without stage special casing', async () => {
+    const expected = coverageIsland('');
+    const pool = fallbackPool();
+
+    const out = await buildChromePart('', stageCtx({ root: fixtureRoot, pages: [] }), pool);
+
+    expect(out).toBe(expected);
+    expect(pool.rawInputs).toEqual([['']]);
+    expect(pool.canonicalInputs).toEqual([[expected]]);
+    expect(pool.stopCalls).toBe(0);
+  });
+
+  it('builds deterministic fixture chrome parts, variant slugs, and page main HTML', async () => {
+    const warnings: string[] = [];
+    const first = await chrome(fixtureChromeCtx(warnings), fallbackPool());
+    const second = await chrome(fixtureChromeCtx(), fallbackPool());
+
+    expect(first).toEqual(second);
+    expect(first.warnings).toEqual([]);
+    expect(warnings).toEqual([]);
+    expect(Object.keys(first.parts).sort()).toEqual([
+      'footer-2.html',
+      'footer.html',
+      'header-2.html',
+      'header.html',
+    ]);
+    expect(first.parts).toEqual({
+      'header.html': coverageIsland(sharedHeaderHtml),
+      'footer.html': coverageIsland(sharedFooterHtml),
+      'header-2.html': coverageIsland(servicesHeaderHtml),
+      'footer-2.html': coverageIsland(servicesFooterHtml),
+    });
+    expect(first.slugsByPage).toEqual({
+      about: { header: 'header', footer: 'footer' },
+      home: { header: 'header', footer: 'footer' },
+      services: { header: 'header-2', footer: 'footer-2' },
+    });
+
+    expectMainWithoutChrome(
+      first.mainHtmlByPage.home,
+      'Build calmer block themes',
+      sharedHeaderHtml,
+      sharedFooterHtml
+    );
+    expectMainWithoutChrome(
+      first.mainHtmlByPage.about,
+      'About the assembler',
+      sharedHeaderHtml,
+      sharedFooterHtml
+    );
+    expectMainWithoutChrome(
+      first.mainHtmlByPage.services,
+      'Service design for block themes',
+      servicesHeaderHtml,
+      servicesFooterHtml
+    );
+  });
+
+  it('skips empty canonical chrome sources with warnings', async () => {
+    const warnings: string[] = [];
+    const html =
+      '<!doctype html><html><head><title>Plain</title></head><body><main><p>No chrome</p></main></body></html>';
+    const pool = fallbackPool();
+
+    const out = await chrome(
+      stageCtx(
+        {
+          root: fixtureRoot,
+          pages: [{ relPath: 'plain.html', slug: 'plain', html, title: 'Plain' }],
+        },
+        warnings
+      ),
+      pool
+    );
+
+    expect(out).toEqual({
+      parts: {},
+      slugsByPage: {
+        plain: { header: 'header', footer: 'footer' },
+      },
+      mainHtmlByPage: {
+        plain: html,
+      },
+      warnings: [
+        'skipped empty header chrome source for header.html',
+        'skipped empty footer chrome source for footer.html',
+      ],
+    });
+    expect(warnings).toEqual(out.warnings);
+    expect(pool.rawInputs).toEqual([]);
+    expect(pool.canonicalInputs).toEqual([]);
+    expect(pool.stopCalls).toBe(0);
+  });
 });
diff --git a/packages/blocks-engine/src/__tests__/theme-ingest.test.ts b/packages/blocks-engine/src/__tests__/theme-ingest.test.ts
index 0c4ef491..51e92166 100644
--- a/packages/blocks-engine/src/__tests__/theme-ingest.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-ingest.test.ts
@@ -25,14 +25,15 @@ function writeHtml(path: string, title: string): void {
 }
 
 describe('theme ingest', () => {
-  it('ingests fixture index and about pages with stable slugs and body data', () => {
+  it('ingests fixture pages with stable slugs and body data', () => {
     const site = ingest(fixtureRoot);
 
     expect(site.root).toBe(fixtureRoot);
-    expect(site.pages.map((page) => page.slug)).toEqual(['about', 'home']);
+    expect(site.pages.map((page) => page.slug)).toEqual(['about', 'home', 'services']);
 
     const home = site.pages.find((page) => page.slug === 'home');
     const about = site.pages.find((page) => page.slug === 'about');
+    const services = site.pages.find((page) => page.slug === 'services');
 
     expect(home).toMatchObject({
       relPath: 'index.html',
@@ -43,6 +44,8 @@ describe('theme ingest', () => {
       },
     });
     expect(home?.html).toContain('Build calmer block themes');
+    expect(home?.html).toContain('<header>');
+    expect(home?.html).toContain('<footer>');
 
     expect(about).toMatchObject({
       relPath: 'about.html',
@@ -51,6 +54,20 @@ describe('theme ingest', () => {
         page: 'about',
       },
     });
+    expect(about?.html).toContain('About the assembler');
+    expect(about?.html).toContain('<header>');
+    expect(about?.html).toContain('<footer>');
+
+    expect(services).toMatchObject({
+      relPath: 'services.html',
+      title: 'Services',
+      bodyData: {
+        page: 'services',
+        template: 'services',
+      },
+    });
+    expect(services?.html).toContain('Service design for block themes');
+    expect(services?.html).toContain('Blocks Engine Services');
   });
 
   it('maps nested paths to DLA-compatible slugs', () => {
diff --git a/packages/blocks-engine/src/theme/chrome-parts.ts b/packages/blocks-engine/src/theme/chrome-parts.ts
index c07b64bd..201f679a 100644
--- a/packages/blocks-engine/src/theme/chrome-parts.ts
+++ b/packages/blocks-engine/src/theme/chrome-parts.ts
@@ -1,3 +1,4 @@
+import { convert } from '../convert.js';
 import type { WorkerPool } from '../pool/types.js';
 import type { StageCtx } from './types.js';
 
@@ -6,8 +7,6 @@ export async function buildChromePart(
   ctx: StageCtx,
   pool: WorkerPool
 ): Promise<string> {
-  void html;
   void ctx;
-  void pool;
-  return '';
+  return convert(html, { url: '' }, { pool });
 }
diff --git a/packages/blocks-engine/src/theme/chrome.ts b/packages/blocks-engine/src/theme/chrome.ts
index a75e6b19..811af549 100644
--- a/packages/blocks-engine/src/theme/chrome.ts
+++ b/packages/blocks-engine/src/theme/chrome.ts
@@ -1,5 +1,8 @@
 import type { WorkerPool } from '../pool/types.js';
 import type { ChromeSlugs } from './chrome-signature.js';
+import { assignChromeVariants } from './chrome-signature.js';
+import { splitPageChrome } from './chrome-split.js';
+import { buildChromePart } from './chrome-parts.js';
 import type { StageCtx } from './types.js';
 
 export interface ChromeResult {
@@ -10,12 +13,81 @@ export interface ChromeResult {
 }
 
 export async function chrome(ctx: StageCtx, pool: WorkerPool): Promise<ChromeResult> {
-  void ctx;
-  void pool;
+  const pages = ctx.site.pages.map((page) => {
+    const split = splitPageChrome(page.html);
+    return {
+      slug: page.slug,
+      headerHtml: split.headerHtml,
+      mainHtml: split.mainHtml,
+      footerHtml: split.footerHtml,
+    };
+  });
+
+  const mainHtmlByPage: Record<string, string> = {};
+  for (const page of pages) {
+    mainHtmlByPage[page.slug] = page.mainHtml;
+  }
+
+  const { slugsByPage, canonical } = assignChromeVariants(pages);
+  const parts: Record<string, string> = {};
+  const warnings: string[] = [];
+
+  const warn = (message: string) => {
+    warnings.push(message);
+    ctx.warn(message);
+  };
+
+  for (const [headerSlug, variant] of Object.entries(canonical)) {
+    const footerSlug = footerSlugFromHeaderSlug(headerSlug);
+
+    await buildPartIfPresent({
+      html: variant.headerHtml,
+      slug: headerSlug,
+      kind: 'header',
+      ctx,
+      pool,
+      parts,
+      warn,
+    });
+    await buildPartIfPresent({
+      html: variant.footerHtml,
+      slug: footerSlug,
+      kind: 'footer',
+      ctx,
+      pool,
+      parts,
+      warn,
+    });
+  }
+
   return {
-    parts: {},
-    slugsByPage: {},
-    mainHtmlByPage: {},
-    warnings: [],
+    parts,
+    slugsByPage,
+    mainHtmlByPage,
+    warnings,
   };
 }
+
+function footerSlugFromHeaderSlug(headerSlug: ChromeSlugs['header']): ChromeSlugs['footer'] {
+  if (headerSlug === 'header') return 'footer';
+  return headerSlug.replace(/^header/, 'footer');
+}
+
+async function buildPartIfPresent(args: {
+  html: string;
+  slug: string;
+  kind: 'header' | 'footer';
+  ctx: StageCtx;
+  pool: WorkerPool;
+  parts: Record<string, string>;
+  warn(message: string): void;
+}): Promise<void> {
+  const partKey = `${args.slug}.html`;
+  if (args.html.trim() === '') {
+    args.warn(`skipped empty ${args.kind} chrome source for ${partKey}`);
+    return;
+  }
+
+  const part = await buildChromePart(args.html, args.ctx, args.pool);
+  args.parts[partKey] = part;
+}

From 9f6a62923b9e2e3f20e0899290cfde4f460e7f1c Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 15:38:05 -0400
Subject: [PATCH 050/113] Wire chrome parts into site theme assembly

---
 .../src/__tests__/site-to-theme.e2e.test.ts   | 256 ++++++++++++++++++
 packages/blocks-engine/src/theme/assemble.ts  |  48 +++-
 .../blocks-engine/src/theme/site-to-theme.ts  |   8 +-
 3 files changed, 307 insertions(+), 5 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
index 3493d066..826a2b77 100644
--- a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
+++ b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
@@ -145,6 +145,18 @@ function p1Pool(): WorkerPool & { stopCalls: number } {
   );
 }
 
+function coverageIslandMarkup(html: string): string {
+  return [
+    '<!-- wp:html {"metadata":{"name":"lib-coverage-island"}} -->',
+    html.trim(),
+    '<!-- /wp:html -->',
+  ].join('\n');
+}
+
+function passthroughIslandPool(): WorkerPool & { stopCalls: number } {
+  return mappedPool((html) => coverageIslandMarkup(html));
+}
+
 function themeMeta(): ThemeMeta {
   return {
     name: 'Fixture Theme',
@@ -253,6 +265,22 @@ function expectThemesByteIdentical(leftDir: string, rightDir: string, files: str
   }
 }
 
+function homeChromeRefs(): { headerRef: string; footerRef: string } {
+  return {
+    headerRef: '<!-- wp:template-part {"slug":"header","tagName":"header"} /-->',
+    footerRef: '<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->',
+  };
+}
+
+function betweenChromeRefs(template: string): string {
+  const { headerRef, footerRef } = homeChromeRefs();
+  const headerIndex = template.indexOf(headerRef);
+  const footerIndex = template.indexOf(footerRef);
+  expect(headerIndex).toBeGreaterThanOrEqual(0);
+  expect(footerIndex).toBeGreaterThan(headerIndex);
+  return template.slice(headerIndex + headerRef.length, footerIndex);
+}
+
 afterEach(() => {
   vi.doUnmock('../pool/pool.js');
   vi.resetModules();
@@ -297,6 +325,149 @@ describe('site-to-theme P0-3 orchestration', () => {
     expect(model.templates['index.html']).not.toContain('src="assets/logo.png"');
   });
 
+  it('assemble-threads-chrome emits real parts and wraps index with template-part refs', async () => {
+    const { assemble } = await import('../theme/index.js');
+    const { headerRef, footerRef } = homeChromeRefs();
+    const chromeParts = {
+      'header.html': '<!-- wp:html -->\n<header><nav>Primary</nav></header>\n<!-- /wp:html -->',
+      'footer.html': '<!-- wp:html -->\n<footer>Footer</footer>\n<!-- /wp:html -->',
+    };
+
+    const model = assemble({
+      site: siteModel(),
+      tokens: foundationTokens(),
+      pages: {
+        home: [
+          {
+            spec: imageSpec(0),
+            blocks: imageBlockMarkup(),
+            coverage: 1,
+          },
+        ],
+      },
+      meta: themeMeta(),
+      assets: [logoAsset()],
+      fontCss: '/*f*/\n',
+      imgRefsByPage: {
+        home: [logoRef()],
+      },
+      chromeParts,
+      chromeSlugsByPage: {
+        home: { header: 'header', footer: 'footer' },
+      },
+    } as Parameters<typeof assemble>[0]);
+
+    const template = model.templates['index.html'];
+    const body = betweenChromeRefs(template);
+
+    expect(model.parts).toEqual(chromeParts);
+    expect(template.indexOf(headerRef)).toBeLessThan(template.indexOf('<!-- wp:group'));
+    expect(template.indexOf(footerRef)).toBeGreaterThan(template.indexOf('<!-- /wp:group -->'));
+    expect(body).toContain('/wp-content/themes/fixture-theme/assets/logo.png');
+    expect(body).not.toMatch(/<(?:header|nav|footer)(?:\s|>)/);
+  });
+
+  it('assemble-threads-chrome defaults missing home slugs to canonical header and footer', async () => {
+    const { assemble } = await import('../theme/index.js');
+    const { headerRef, footerRef } = homeChromeRefs();
+
+    const model = assemble({
+      site: siteModel(),
+      tokens: foundationTokens(),
+      pages: {
+        home: [
+          {
+            spec: semanticSpec(0),
+            blocks: '<!-- wp:paragraph -->\n<p>Home.</p>\n<!-- /wp:paragraph -->',
+            coverage: 1,
+          },
+        ],
+      },
+      meta: themeMeta(),
+      chromeParts: {
+        'header.html': '<!-- wp:html -->header<!-- /wp:html -->',
+        'footer.html': '<!-- wp:html -->footer<!-- /wp:html -->',
+      },
+      chromeSlugsByPage: {},
+    } as Parameters<typeof assemble>[0]);
+
+    expect(model.templates['index.html']).toContain(headerRef);
+    expect(model.templates['index.html']).toContain(footerRef);
+  });
+
+  it('assemble-threads-chrome does not reference chrome parts that were not emitted', async () => {
+    const { assemble } = await import('../theme/index.js');
+
+    const model = assemble({
+      site: siteModel(),
+      tokens: foundationTokens(),
+      pages: {
+        home: [
+          {
+            spec: semanticSpec(0),
+            blocks: '<!-- wp:paragraph -->\n<p>Home.</p>\n<!-- /wp:paragraph -->',
+            coverage: 1,
+          },
+        ],
+      },
+      meta: themeMeta(),
+      chromeParts: {},
+      chromeSlugsByPage: {
+        home: { header: 'header', footer: 'footer' },
+      },
+    } as Parameters<typeof assemble>[0]);
+
+    expect(model.parts).toEqual({});
+    expect(model.templates['index.html']).not.toContain('wp:template-part');
+  });
+
+  it('assemble-threads-chrome chooses the home page slugs even when home is not first', async () => {
+    const { assemble } = await import('../theme/index.js');
+    const aboutPage = {
+      relPath: 'about.html',
+      slug: 'about',
+      html: readFileSync(join(fixtureRoot, 'about.html'), 'utf8'),
+      title: 'About',
+    };
+    const homePage = siteModel().pages[0];
+
+    const model = assemble({
+      site: {
+        root: fixtureRoot,
+        pages: [aboutPage, homePage],
+      },
+      tokens: foundationTokens(),
+      pages: {
+        home: [
+          {
+            spec: semanticSpec(0),
+            blocks: '<!-- wp:paragraph -->\n<p>Home.</p>\n<!-- /wp:paragraph -->',
+            coverage: 1,
+          },
+        ],
+      },
+      meta: themeMeta(),
+      chromeParts: {
+        'about-header.html': '<!-- wp:html -->about header<!-- /wp:html -->',
+        'about-footer.html': '<!-- wp:html -->about footer<!-- /wp:html -->',
+        'home-header.html': '<!-- wp:html -->home header<!-- /wp:html -->',
+        'home-footer.html': '<!-- wp:html -->home footer<!-- /wp:html -->',
+      },
+      chromeSlugsByPage: {
+        about: { header: 'about-header', footer: 'about-footer' },
+        home: { header: 'home-header', footer: 'home-footer' },
+      },
+    } as Parameters<typeof assemble>[0]);
+
+    expect(model.templates['index.html']).toContain(
+      '<!-- wp:template-part {"slug":"home-header","tagName":"header"} /-->'
+    );
+    expect(model.templates['index.html']).toContain(
+      '<!-- wp:template-part {"slug":"home-footer","tagName":"footer"} /-->'
+    );
+    expect(model.templates['index.html']).not.toContain('"slug":"about-header"');
+  });
+
   it('assemble-threads-assets lets asset-stage entries win relPath collisions', async () => {
     const { assemble } = await import('../theme/index.js');
     const siteWithLegacyAsset = {
@@ -339,7 +510,12 @@ describe('site-to-theme P0-3 orchestration', () => {
 
       expect(fetchMock).toHaveBeenCalledTimes(2);
       expect(result.written).toEqual(expect.arrayContaining(['assets/logo.png']));
+      expect(result.written).toEqual(
+        expect.arrayContaining(['parts/header.html', 'parts/footer.html'])
+      );
       expect(existsSync(join(outDir, 'assets', 'logo.png'))).toBe(true);
+      expect(existsSync(join(outDir, 'parts', 'header.html'))).toBe(true);
+      expect(existsSync(join(outDir, 'parts', 'footer.html'))).toBe(true);
 
       const fontFile = result.written.find((file) =>
         /^assets\/fonts\/[^/]+\.woff2$/.test(file)
@@ -352,12 +528,92 @@ describe('site-to-theme P0-3 orchestration', () => {
       expect(styleCss).not.toContain(gstaticFontUrl);
 
       const template = readFileSync(join(outDir, 'templates', 'index.html'), 'utf8');
+      const { headerRef, footerRef } = homeChromeRefs();
+      const body = betweenChromeRefs(template);
+      const headerPart = readFileSync(join(outDir, 'parts', 'header.html'), 'utf8');
+      const footerPart = readFileSync(join(outDir, 'parts', 'footer.html'), 'utf8');
+
+      expect(template).toContain(headerRef);
+      expect(template).toContain(footerRef);
+      expect(template).not.toMatch(/<(?:header|nav|footer)(?:\s|>)/);
+      expect(body).not.toMatch(/<(?:header|nav|footer)(?:\s|>)/);
       expect(template).toContain('/wp-content/themes/fixture-theme/assets/logo.png');
       expect(template).toMatch(
         /<!-- wp:html \{"metadata":\{"name":"lib-coverage-island"\}\} -->[\s\S]*<img src="\/wp-content\/themes\/fixture-theme\/assets\/logo\.png" alt="Blocks Engine mark">[\s\S]*<!-- \/wp:html -->/
       );
       expect(template).not.toContain('<!-- wp:image -->');
       expect(template).not.toContain('src="assets/logo.png"');
+      expect(headerPart).toContain('About');
+      expect(footerPart).toContain('Blocks Engine');
+    });
+  });
+
+  it('siteToTheme-e2e-chrome runs chrome extraction even when body sections are injected', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+
+    await withTempDir('blocks-engine-site-to-theme-chrome-sections-', async (siteDir) => {
+      copyFixtureSite(siteDir);
+      const outDir = join(siteDir, 'theme-out');
+
+      await siteToTheme(siteDir, {
+        outDir,
+        pool: passthroughIslandPool(),
+        sections: p1Sections(),
+        themeMeta: themeMeta(),
+      });
+
+      const headerPart = readFileSync(join(outDir, 'parts', 'header.html'), 'utf8');
+      const footerPart = readFileSync(join(outDir, 'parts', 'footer.html'), 'utf8');
+
+      expect(headerPart).toContain('<nav aria-label="Primary">');
+      expect(headerPart).toContain('About');
+      expect(footerPart).toContain('<footer>');
+      expect(footerPart).toContain('Blocks Engine');
+    });
+  });
+
+  it('siteToTheme-e2e-chrome keeps injected body sections free of raw chrome tags', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+
+    await withTempDir('blocks-engine-site-to-theme-chrome-body-', async (siteDir) => {
+      copyFixtureSite(siteDir);
+      const outDir = join(siteDir, 'theme-out');
+
+      await siteToTheme(siteDir, {
+        outDir,
+        pool: passthroughIslandPool(),
+        sections: p1Sections(),
+        themeMeta: themeMeta(),
+      });
+
+      const template = readFileSync(join(outDir, 'templates', 'index.html'), 'utf8');
+      const body = betweenChromeRefs(template);
+
+      expect(template).not.toMatch(/<(?:header|nav|footer)(?:\s|>)/);
+      expect(body).not.toMatch(/<(?:header|nav|footer)(?:\s|>)/);
+      expect(body).toContain('/wp-content/themes/fixture-theme/assets/logo.png');
+    });
+  });
+
+  it('siteToTheme-e2e-chrome reports canonical header and footer parts in outputs', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+
+    await withTempDir('blocks-engine-site-to-theme-chrome-tallies-', async (siteDir) => {
+      copyFixtureSite(siteDir);
+      const outDir = join(siteDir, 'theme-out');
+
+      const result = await siteToTheme(siteDir, {
+        outDir,
+        pool: passthroughIslandPool(),
+        sections: p1Sections(),
+        themeMeta: themeMeta(),
+      });
+
+      expect(result.tallies.parts).toBe(2);
+      expect(Object.keys(result.model.parts).sort()).toEqual(['footer.html', 'header.html']);
+      expect(result.written).toEqual(
+        expect.arrayContaining(['parts/header.html', 'parts/footer.html'])
+      );
     });
   });
 
diff --git a/packages/blocks-engine/src/theme/assemble.ts b/packages/blocks-engine/src/theme/assemble.ts
index fed623d7..39a602dc 100644
--- a/packages/blocks-engine/src/theme/assemble.ts
+++ b/packages/blocks-engine/src/theme/assemble.ts
@@ -1,4 +1,5 @@
 import { rewriteHtmlImageSrcs, type StaticImgRef } from './assets-static.js';
+import type { ChromeSlugs } from './chrome-signature.js';
 import type {
   AssetFile,
   FoundationTokens,
@@ -16,6 +17,8 @@ type ThemeAssemblyParts = {
   assets?: AssetFile[];
   fontCss?: string;
   imgRefsByPage?: Record<string, StaticImgRef[]>;
+  chromeParts?: Record<string, string>;
+  chromeSlugsByPage?: Record<string, ChromeSlugs>;
 };
 
 type PaletteEntry = {
@@ -44,10 +47,12 @@ export function assemble(parts: ThemeAssemblyParts): ThemeModel {
         parts.site,
         parts.pages,
         parts.imgRefsByPage ?? {},
-        themeSlug
+        themeSlug,
+        parts.chromeParts ?? {},
+        parts.chromeSlugsByPage
       ),
     },
-    parts: {},
+    parts: { ...(parts.chromeParts ?? {}) },
     patterns: {},
     assets: collectAssets(parts),
   };
@@ -170,19 +175,54 @@ function buildIndexTemplate(
   site: SiteModel,
   pages: Record<string, SectionBlocks[]>,
   imgRefsByPage: Record<string, StaticImgRef[]>,
-  themeSlug: string
+  themeSlug: string,
+  chromeParts: Record<string, string>,
+  chromeSlugsByPage: Record<string, ChromeSlugs> | undefined
 ): string {
   const pageBlocks = orderedPageBlocks(site, pages, imgRefsByPage, themeSlug);
   const blocks = pageBlocks.length > 0
     ? pageBlocks.join('\n\n')
     : '<!-- wp:paragraph -->\n<p></p>\n<!-- /wp:paragraph -->';
 
-  return `<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
+  const mainTemplate = `<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
 <main class="wp-block-group">
 ${blocks}
 </main>
 <!-- /wp:group -->
 `;
+  if (!chromeSlugsByPage) return mainTemplate;
+
+  const homeSlugs = chromeSlugsByPage[homeSlugForSite(site)] ?? {
+    header: 'header',
+    footer: 'footer',
+  };
+  if (!hasChromePart(chromeParts, homeSlugs.header) || !hasChromePart(chromeParts, homeSlugs.footer)) {
+    return mainTemplate;
+  }
+
+  return [
+    templatePartRef(homeSlugs.header, 'header'),
+    mainTemplate.trimEnd(),
+    templatePartRef(homeSlugs.footer, 'footer'),
+    '',
+  ].join('\n');
+}
+
+function hasChromePart(chromeParts: Record<string, string>, slug: string): boolean {
+  return Object.prototype.hasOwnProperty.call(chromeParts, `${slug}.html`);
+}
+
+function homeSlugForSite(site: SiteModel): string {
+  return (
+    site.pages.find((page) => page.slug === 'home')?.slug ??
+    site.pages.find((page) => /(^|[\\/])index\.html?$/i.test(page.relPath))?.slug ??
+    site.pages[0]?.slug ??
+    'home'
+  );
+}
+
+function templatePartRef(slug: string, tagName: 'header' | 'footer'): string {
+  return `<!-- wp:template-part ${JSON.stringify({ slug, tagName })} /-->`;
 }
 
 function orderedPageBlocks(
diff --git a/packages/blocks-engine/src/theme/site-to-theme.ts b/packages/blocks-engine/src/theme/site-to-theme.ts
index 50205f28..7014a60d 100644
--- a/packages/blocks-engine/src/theme/site-to-theme.ts
+++ b/packages/blocks-engine/src/theme/site-to-theme.ts
@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { createWorker } from '../pool/pool.js';
 import { assemble } from './assemble.js';
 import { assets as runAssetsStage } from './assets.js';
+import { chrome } from './chrome.js';
 import { foundation } from './foundation.js';
 import { ingest } from './ingest.js';
 import { reconstruct } from './reconstruct.js';
@@ -42,10 +43,13 @@ export async function siteToTheme(
   try {
     const baseTokens = foundation(site, options?.foundationAggregates);
     const tokens = hooks.onFoundation ? await hooks.onFoundation(baseTokens, ctx) : baseTokens;
+    const chromeRes = await chrome(ctx, pool);
     const pages: Record<string, SectionBlocks[]> = {};
 
     for (const page of site.pages) {
-      const specs = options?.sections?.[page.slug] ?? sectionExtract(page);
+      const specs =
+        options?.sections?.[page.slug] ??
+        sectionExtract({ ...page, html: chromeRes.mainHtmlByPage[page.slug] ?? page.html });
       pages[page.slug] = await reconstruct(specs, ctx, pool, hooks, coverageFloor);
     }
 
@@ -64,6 +68,8 @@ export async function siteToTheme(
       assets: inventory.assets,
       fontCss: assetStage.fontCss,
       imgRefsByPage: assetStage.imgRefsByPage,
+      chromeParts: chromeRes.parts,
+      chromeSlugsByPage: chromeRes.slugsByPage,
     });
     const model = hooks.onRefine ? await hooks.onRefine(assembled, ctx) : assembled;
     const written = await writeTheme(model, outDir);

From e62b3057abc417c0e4f2d891b3d6c12536dc40fb Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 15:48:21 -0400
Subject: [PATCH 051/113] Freeze template plan contract

---
 packages/blocks-engine/src/theme/index.ts     |  2 ++
 .../blocks-engine/src/theme/template-plan.ts  | 25 +++++++++++++++++++
 2 files changed, 27 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/template-plan.ts

diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 11c0897e..e94a618e 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -6,6 +6,7 @@ export { assignChromeVariants, chromeSignature } from './chrome-signature.js';
 export { splitPageChrome } from './chrome-split.js';
 export { foundation } from './foundation.js';
 export { ingest } from './ingest.js';
+export { planTemplates } from './template-plan.js';
 export { reconstruct } from './reconstruct.js';
 export { sectionExtract } from './section-extract.js';
 export { siteToTheme } from './site-to-theme.js';
@@ -19,5 +20,6 @@ export type { ChromeSlugs } from './chrome-signature.js';
 export type { RegionSplit } from './chrome-split.js';
 export type * from './font-faces.js';
 export type * from './section-spec.js';
+export type { TemplatePlan } from './template-plan.js';
 export type * from './types.js';
 export type { ThemeJsonLintResult } from './theme-json-lint.js';
diff --git a/packages/blocks-engine/src/theme/template-plan.ts b/packages/blocks-engine/src/theme/template-plan.ts
new file mode 100644
index 00000000..cd1e1429
--- /dev/null
+++ b/packages/blocks-engine/src/theme/template-plan.ts
@@ -0,0 +1,25 @@
+import type { SiteModel } from './types.js';
+
+export type TemplatePlan = {
+  templatesByPage: Record<string, 'front-page' | 'page'>;
+};
+
+export function planTemplates(site: SiteModel): TemplatePlan {
+  const homeSlug = homeSlugForSite(site);
+  const templatesByPage: TemplatePlan['templatesByPage'] = {};
+
+  for (const page of site.pages) {
+    templatesByPage[page.slug] = page.slug === homeSlug ? 'front-page' : 'page';
+  }
+
+  return { templatesByPage };
+}
+
+function homeSlugForSite(site: SiteModel): string {
+  return (
+    site.pages.find((page) => page.slug === 'home')?.slug ??
+    site.pages.find((page) => /(^|[\\/])index\.html?$/i.test(page.relPath))?.slug ??
+    site.pages[0]?.slug ??
+    'home'
+  );
+}

From f1e33c20d6bd398f7721e3670f99c414fd909c86 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 15:56:58 -0400
Subject: [PATCH 052/113] Implement front page template plan

---
 .../src/__tests__/site-to-theme.e2e.test.ts   | 249 ++++++++++++++++--
 .../src/__tests__/theme-contracts.test.ts     |  11 +
 packages/blocks-engine/src/theme/assemble.ts  |  79 +++---
 3 files changed, 274 insertions(+), 65 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
index 826a2b77..b70c30a4 100644
--- a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
+++ b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
@@ -281,12 +281,150 @@ function betweenChromeRefs(template: string): string {
   return template.slice(headerIndex + headerRef.length, footerIndex);
 }
 
+function expectGenericQueriedContentTemplate(template: string): void {
+  const { headerRef, footerRef } = homeChromeRefs();
+
+  expect(template).toContain(headerRef);
+  expect(template).toContain(footerRef);
+  expect(template).toContain('<!-- wp:post-content {"layout":{"type":"constrained"}} /-->');
+  expect(template).not.toMatch(/<(?:header|nav|footer)(?:\s|>)/);
+}
+
 afterEach(() => {
   vi.doUnmock('../pool/pool.js');
   vi.resetModules();
 });
 
 describe('site-to-theme P0-3 orchestration', () => {
+  it('planTemplates maps home to front-page and source pages to page', async () => {
+    const { planTemplates } = await import('../theme/index.js');
+    const homePage = siteModel().pages[0];
+    const aboutPage = {
+      relPath: 'about.html',
+      slug: 'about',
+      html: readFileSync(join(fixtureRoot, 'about.html'), 'utf8'),
+      title: 'About',
+    };
+
+    expect(planTemplates({ root: fixtureRoot, pages: [homePage, aboutPage] })).toEqual({
+      templatesByPage: {
+        home: 'front-page',
+        about: 'page',
+      },
+    });
+  });
+
+  it('planTemplates falls back to index.html as front-page when home slug is absent', async () => {
+    const { planTemplates } = await import('../theme/index.js');
+
+    expect(
+      planTemplates({
+        root: fixtureRoot,
+        pages: [
+          {
+            relPath: 'landing/index.html',
+            slug: 'landing',
+            html: '<main>Landing</main>',
+            title: 'Landing',
+          },
+          {
+            relPath: 'about.html',
+            slug: 'about',
+            html: '<main>About</main>',
+            title: 'About',
+          },
+        ],
+      })
+    ).toEqual({
+      templatesByPage: {
+        landing: 'front-page',
+        about: 'page',
+      },
+    });
+  });
+
+  it('planTemplates falls back to the first page when no home or index page exists', async () => {
+    const { planTemplates } = await import('../theme/index.js');
+
+    expect(
+      planTemplates({
+        root: fixtureRoot,
+        pages: [
+          {
+            relPath: 'about.html',
+            slug: 'about',
+            html: '<main>About</main>',
+            title: 'About',
+          },
+          {
+            relPath: 'services.html',
+            slug: 'services',
+            html: '<main>Services</main>',
+            title: 'Services',
+          },
+        ],
+      })
+    ).toEqual({
+      templatesByPage: {
+        about: 'front-page',
+        services: 'page',
+      },
+    });
+  });
+
+  it('assemble-template-plan leaves non-home source bodies for queried page content', async () => {
+    const { assemble } = await import('../theme/index.js');
+    const homePage = siteModel().pages[0];
+    const aboutPage = {
+      relPath: 'about.html',
+      slug: 'about',
+      html: readFileSync(join(fixtureRoot, 'about.html'), 'utf8'),
+      title: 'About',
+    };
+
+    const model = assemble({
+      site: {
+        root: fixtureRoot,
+        pages: [homePage, aboutPage],
+      },
+      tokens: foundationTokens(),
+      pages: {
+        home: [
+          {
+            spec: semanticSpec(0),
+            blocks: '<!-- wp:paragraph -->\n<p>Home body.</p>\n<!-- /wp:paragraph -->',
+            coverage: 1,
+          },
+        ],
+        about: [
+          {
+            spec: semanticSpec(0),
+            blocks: '<!-- wp:paragraph -->\n<p>About body.</p>\n<!-- /wp:paragraph -->',
+            coverage: 1,
+          },
+        ],
+      },
+      meta: themeMeta(),
+      chromeParts: {
+        'header.html': '<!-- wp:html -->header<!-- /wp:html -->',
+        'footer.html': '<!-- wp:html -->footer<!-- /wp:html -->',
+      },
+      chromeSlugsByPage: {
+        home: { header: 'header', footer: 'footer' },
+        about: { header: 'header', footer: 'footer' },
+      },
+    } as Parameters<typeof assemble>[0]);
+
+    expect(model.templates['front-page.html']).toContain('Home body.');
+    expect(model.templates['front-page.html']).not.toContain('About body.');
+    expect(model.templates['index.html']).not.toContain('Home body.');
+    expect(model.templates['index.html']).not.toContain('About body.');
+    expect(model.templates['page.html']).not.toContain('Home body.');
+    expect(model.templates['page.html']).not.toContain('About body.');
+    expectGenericQueriedContentTemplate(model.templates['index.html']);
+    expectGenericQueriedContentTemplate(model.templates['page.html']);
+  });
+
   it('assemble-threads-assets adds copied assets, font CSS, and rewrites template images', async () => {
     const { assemble } = await import('../theme/index.js');
     const parts: AssemblePartsWithAssets = {
@@ -319,13 +457,15 @@ describe('site-to-theme P0-3 orchestration', () => {
       ])
     );
     expect(model.styleCss).toContain('/*f*/');
-    expect(model.templates['index.html']).toContain(
+    expect(model.templates['front-page.html']).toContain(
       '/wp-content/themes/fixture-theme/assets/logo.png'
     );
-    expect(model.templates['index.html']).not.toContain('src="assets/logo.png"');
+    expect(model.templates['front-page.html']).not.toContain('src="assets/logo.png"');
+    expect(model.templates['index.html']).toContain('wp:post-content');
+    expect(model.templates['page.html']).toContain('wp:post-content');
   });
 
-  it('assemble-threads-chrome emits real parts and wraps index with template-part refs', async () => {
+  it('assemble-threads-chrome emits real parts and wraps front-page with template-part refs', async () => {
     const { assemble } = await import('../theme/index.js');
     const { headerRef, footerRef } = homeChromeRefs();
     const chromeParts = {
@@ -357,7 +497,7 @@ describe('site-to-theme P0-3 orchestration', () => {
       },
     } as Parameters<typeof assemble>[0]);
 
-    const template = model.templates['index.html'];
+    const template = model.templates['front-page.html'];
     const body = betweenChromeRefs(template);
 
     expect(model.parts).toEqual(chromeParts);
@@ -365,6 +505,8 @@ describe('site-to-theme P0-3 orchestration', () => {
     expect(template.indexOf(footerRef)).toBeGreaterThan(template.indexOf('<!-- /wp:group -->'));
     expect(body).toContain('/wp-content/themes/fixture-theme/assets/logo.png');
     expect(body).not.toMatch(/<(?:header|nav|footer)(?:\s|>)/);
+    expectGenericQueriedContentTemplate(model.templates['index.html']);
+    expectGenericQueriedContentTemplate(model.templates['page.html']);
   });
 
   it('assemble-threads-chrome defaults missing home slugs to canonical header and footer', async () => {
@@ -391,8 +533,10 @@ describe('site-to-theme P0-3 orchestration', () => {
       chromeSlugsByPage: {},
     } as Parameters<typeof assemble>[0]);
 
-    expect(model.templates['index.html']).toContain(headerRef);
-    expect(model.templates['index.html']).toContain(footerRef);
+    expect(model.templates['front-page.html']).toContain(headerRef);
+    expect(model.templates['front-page.html']).toContain(footerRef);
+    expectGenericQueriedContentTemplate(model.templates['index.html']);
+    expectGenericQueriedContentTemplate(model.templates['page.html']);
   });
 
   it('assemble-threads-chrome does not reference chrome parts that were not emitted', async () => {
@@ -418,7 +562,11 @@ describe('site-to-theme P0-3 orchestration', () => {
     } as Parameters<typeof assemble>[0]);
 
     expect(model.parts).toEqual({});
+    expect(model.templates['front-page.html']).not.toContain('wp:template-part');
     expect(model.templates['index.html']).not.toContain('wp:template-part');
+    expect(model.templates['page.html']).not.toContain('wp:template-part');
+    expect(model.templates['index.html']).toContain('wp:post-content');
+    expect(model.templates['page.html']).toContain('wp:post-content');
   });
 
   it('assemble-threads-chrome chooses the home page slugs even when home is not first', async () => {
@@ -459,13 +607,14 @@ describe('site-to-theme P0-3 orchestration', () => {
       },
     } as Parameters<typeof assemble>[0]);
 
-    expect(model.templates['index.html']).toContain(
+    expect(model.templates['front-page.html']).toContain(
       '<!-- wp:template-part {"slug":"home-header","tagName":"header"} /-->'
     );
-    expect(model.templates['index.html']).toContain(
+    expect(model.templates['front-page.html']).toContain(
       '<!-- wp:template-part {"slug":"home-footer","tagName":"footer"} /-->'
     );
-    expect(model.templates['index.html']).not.toContain('"slug":"about-header"');
+    expect(model.templates['front-page.html']).not.toContain('"slug":"about-header"');
+    expect(model.templates['index.html']).toContain('wp:post-content');
   });
 
   it('assemble-threads-assets lets asset-stage entries win relPath collisions', async () => {
@@ -527,7 +676,9 @@ describe('site-to-theme P0-3 orchestration', () => {
       expect(styleCss).toContain('assets/fonts/');
       expect(styleCss).not.toContain(gstaticFontUrl);
 
-      const template = readFileSync(join(outDir, 'templates', 'index.html'), 'utf8');
+      const template = readFileSync(join(outDir, 'templates', 'front-page.html'), 'utf8');
+      const indexTemplate = readFileSync(join(outDir, 'templates', 'index.html'), 'utf8');
+      const pageTemplate = readFileSync(join(outDir, 'templates', 'page.html'), 'utf8');
       const { headerRef, footerRef } = homeChromeRefs();
       const body = betweenChromeRefs(template);
       const headerPart = readFileSync(join(outDir, 'parts', 'header.html'), 'utf8');
@@ -543,6 +694,10 @@ describe('site-to-theme P0-3 orchestration', () => {
       );
       expect(template).not.toContain('<!-- wp:image -->');
       expect(template).not.toContain('src="assets/logo.png"');
+      expectGenericQueriedContentTemplate(indexTemplate);
+      expectGenericQueriedContentTemplate(pageTemplate);
+      expect(indexTemplate).not.toContain('/wp-content/themes/fixture-theme/assets/logo.png');
+      expect(pageTemplate).not.toContain('/wp-content/themes/fixture-theme/assets/logo.png');
       expect(headerPart).toContain('About');
       expect(footerPart).toContain('Blocks Engine');
     });
@@ -586,12 +741,16 @@ describe('site-to-theme P0-3 orchestration', () => {
         themeMeta: themeMeta(),
       });
 
-      const template = readFileSync(join(outDir, 'templates', 'index.html'), 'utf8');
+      const template = readFileSync(join(outDir, 'templates', 'front-page.html'), 'utf8');
+      const indexTemplate = readFileSync(join(outDir, 'templates', 'index.html'), 'utf8');
+      const pageTemplate = readFileSync(join(outDir, 'templates', 'page.html'), 'utf8');
       const body = betweenChromeRefs(template);
 
       expect(template).not.toMatch(/<(?:header|nav|footer)(?:\s|>)/);
       expect(body).not.toMatch(/<(?:header|nav|footer)(?:\s|>)/);
       expect(body).toContain('/wp-content/themes/fixture-theme/assets/logo.png');
+      expectGenericQueriedContentTemplate(indexTemplate);
+      expectGenericQueriedContentTemplate(pageTemplate);
     });
   });
 
@@ -617,6 +776,34 @@ describe('site-to-theme P0-3 orchestration', () => {
     });
   });
 
+  it('siteToTheme-e2e-template-structure writes front-page and generic page shells', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+
+    await withTempDir('blocks-engine-site-to-theme-templates-', async (siteDir) => {
+      copyFixtureSite(siteDir);
+      const outDir = join(siteDir, 'theme-out');
+
+      await siteToTheme(siteDir, {
+        outDir,
+        pool: p1Pool(),
+        sections: p1Sections(),
+        fetchImpl: mockFontFetch().fetchImpl,
+        themeMeta: themeMeta(),
+      });
+
+      const frontPage = readFileSync(join(outDir, 'templates', 'front-page.html'), 'utf8');
+      const indexTemplate = readFileSync(join(outDir, 'templates', 'index.html'), 'utf8');
+      const pageTemplate = readFileSync(join(outDir, 'templates', 'page.html'), 'utf8');
+
+      expect(frontPage).toContain('/wp-content/themes/fixture-theme/assets/logo.png');
+      expect(frontPage).not.toMatch(/<(?:header|nav|footer)(?:\s|>)/);
+      expectGenericQueriedContentTemplate(indexTemplate);
+      expectGenericQueriedContentTemplate(pageTemplate);
+      expect(indexTemplate).not.toContain('/wp-content/themes/fixture-theme/assets/logo.png');
+      expect(pageTemplate).not.toContain('/wp-content/themes/fixture-theme/assets/logo.png');
+    });
+  });
+
   it('siteToTheme-e2e-assets-on-disk keeps assets stage and assemble slug parity', async () => {
     const { siteToTheme } = await import('../theme/index.js');
 
@@ -634,7 +821,7 @@ describe('site-to-theme P0-3 orchestration', () => {
         },
       });
 
-      const template = readFileSync(join(outDir, 'templates', 'index.html'), 'utf8');
+      const template = readFileSync(join(outDir, 'templates', 'front-page.html'), 'utf8');
       expect(result.model.assets.map((asset) => asset.relPath)).toContain('assets/logo.png');
       expect(template).toContain('/wp-content/themes/fixture-theme/assets/logo.png');
       expect(template).not.toContain('/wp-content/themes/Fixture Theme!');
@@ -753,19 +940,31 @@ describe('site-to-theme P0-3 orchestration', () => {
       });
 
       expect(result.written).toEqual(
-        expect.arrayContaining(['style.css', 'theme.json', 'templates/index.html'])
+        expect.arrayContaining([
+          'style.css',
+          'theme.json',
+          'templates/front-page.html',
+          'templates/index.html',
+          'templates/page.html',
+        ])
       );
       expect(existsSync(join(outDir, 'style.css'))).toBe(true);
       expect(existsSync(join(outDir, 'theme.json'))).toBe(true);
+      expect(existsSync(join(outDir, 'templates', 'front-page.html'))).toBe(true);
       expect(existsSync(join(outDir, 'templates', 'index.html'))).toBe(true);
+      expect(existsSync(join(outDir, 'templates', 'page.html'))).toBe(true);
 
       const themeJson = JSON.parse(readFileSync(join(outDir, 'theme.json'), 'utf8'));
       expect(lintThemeJson(themeJson)).toEqual({ ok: true, errors: [] });
 
-      const template = readFileSync(join(outDir, 'templates', 'index.html'), 'utf8');
-      expect(template).toContain('<!-- wp:heading');
-      expect(template).toContain('<!-- wp:paragraph');
-      expect(template).not.toMatch(/^<!-- wp:html -->[\s\S]*<!-- \/wp:html -->$/);
+      const frontPage = readFileSync(join(outDir, 'templates', 'front-page.html'), 'utf8');
+      const indexTemplate = readFileSync(join(outDir, 'templates', 'index.html'), 'utf8');
+      const pageTemplate = readFileSync(join(outDir, 'templates', 'page.html'), 'utf8');
+      expect(frontPage).toContain('<!-- wp:heading');
+      expect(frontPage).toContain('<!-- wp:paragraph');
+      expect(frontPage).not.toMatch(/^<!-- wp:html -->[\s\S]*<!-- \/wp:html -->$/);
+      expectGenericQueriedContentTemplate(indexTemplate);
+      expectGenericQueriedContentTemplate(pageTemplate);
     });
   });
 
@@ -815,16 +1014,20 @@ describe('site-to-theme P0-3 orchestration', () => {
       expect(readFileSync(join(secondOut, 'theme.json'), 'utf8')).toBe(
         readFileSync(join(firstOut, 'theme.json'), 'utf8')
       );
-      expect(readFileSync(join(secondOut, 'templates', 'index.html'), 'utf8')).toBe(
-        readFileSync(join(firstOut, 'templates', 'index.html'), 'utf8')
-      );
+      for (const templateFile of ['front-page.html', 'index.html', 'page.html']) {
+        expect(readFileSync(join(secondOut, 'templates', templateFile), 'utf8')).toBe(
+          readFileSync(join(firstOut, 'templates', templateFile), 'utf8')
+        );
+      }
       expect(third.model).toEqual(first.model);
       expect(readFileSync(join(thirdOut, 'theme.json'), 'utf8')).toBe(
         readFileSync(join(firstOut, 'theme.json'), 'utf8')
       );
-      expect(readFileSync(join(thirdOut, 'templates', 'index.html'), 'utf8')).toBe(
-        readFileSync(join(firstOut, 'templates', 'index.html'), 'utf8')
-      );
+      for (const templateFile of ['front-page.html', 'index.html', 'page.html']) {
+        expect(readFileSync(join(thirdOut, 'templates', templateFile), 'utf8')).toBe(
+          readFileSync(join(firstOut, 'templates', templateFile), 'utf8')
+        );
+      }
     });
   });
 
diff --git a/packages/blocks-engine/src/__tests__/theme-contracts.test.ts b/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
index 517d65f7..8159cc42 100644
--- a/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
@@ -4,6 +4,7 @@ import {
   assemble,
   foundation,
   ingest,
+  planTemplates,
   reconstruct,
   sectionExtract,
   siteToTheme,
@@ -28,6 +29,7 @@ import {
   type SiteToThemeHooks,
   type SiteToThemeOptions,
   type StageCtx,
+  type TemplatePlan,
   type ThemeBuildResult,
   type ThemeMeta,
   type ThemeModel,
@@ -41,6 +43,7 @@ type ThemeStageSignatures = {
   ingest: (srcDir: string) => SiteModel;
   sectionExtract: (page: SitePage) => SectionSpec[];
   foundation: (site: SiteModel, aggregates?: FoundationAggregates) => FoundationTokens;
+  planTemplates: (site: SiteModel) => TemplatePlan;
   reconstruct: (
     specs: SectionSpec[],
     ctx: StageCtx,
@@ -62,6 +65,7 @@ const themeStageSignatures: ThemeStageSignatures = {
   ingest,
   sectionExtract,
   foundation,
+  planTemplates,
   reconstruct,
   assemble,
 };
@@ -223,6 +227,12 @@ type CompileOnlyThemeContractAssignments = {
       assets: AssetFile[];
     }
   >;
+  templatePlan: Satisfies<
+    TemplatePlan,
+    {
+      templatesByPage: Record<string, 'front-page' | 'page'>;
+    }
+  >;
   sectionBlocks: Satisfies<
     SectionBlocks,
     {
@@ -304,6 +314,7 @@ describe('theme public contract', () => {
       [ingest, 1],
       [sectionExtract, 1],
       [foundation, 2],
+      [planTemplates, 1],
       [reconstruct, 5],
       [assemble, 1],
     ] as const;
diff --git a/packages/blocks-engine/src/theme/assemble.ts b/packages/blocks-engine/src/theme/assemble.ts
index 39a602dc..2773e2a9 100644
--- a/packages/blocks-engine/src/theme/assemble.ts
+++ b/packages/blocks-engine/src/theme/assemble.ts
@@ -1,5 +1,6 @@
 import { rewriteHtmlImageSrcs, type StaticImgRef } from './assets-static.js';
 import type { ChromeSlugs } from './chrome-signature.js';
+import { planTemplates, type TemplatePlan } from './template-plan.js';
 import type {
   AssetFile,
   FoundationTokens,
@@ -38,19 +39,23 @@ export function assemble(parts: ThemeAssemblyParts): ThemeModel {
   const palette = buildPalette(parts.tokens);
   const fontFamilies = buildFontFamilies(parts.tokens);
   const styleCss = buildStyleCss(parts.meta, themeSlug);
+  const templatePlan = planTemplates(parts.site);
 
   return {
     styleCss: appendFontCss(styleCss, parts.fontCss),
     themeJson: buildThemeJson(parts.tokens, palette, fontFamilies),
     templates: {
-      'index.html': buildIndexTemplate(
+      'front-page.html': buildFrontPageTemplate(
         parts.site,
         parts.pages,
         parts.imgRefsByPage ?? {},
         themeSlug,
         parts.chromeParts ?? {},
-        parts.chromeSlugsByPage
+        parts.chromeSlugsByPage,
+        templatePlan
       ),
+      'index.html': buildGenericQueriedContentTemplate(parts.chromeParts ?? {}),
+      'page.html': buildGenericQueriedContentTemplate(parts.chromeParts ?? {}),
     },
     parts: { ...(parts.chromeParts ?? {}) },
     patterns: {},
@@ -171,18 +176,19 @@ function colorValueFor(palette: PaletteEntry[], preferredSlugs: string[], fallba
   return fallback;
 }
 
-function buildIndexTemplate(
+function buildFrontPageTemplate(
   site: SiteModel,
   pages: Record<string, SectionBlocks[]>,
   imgRefsByPage: Record<string, StaticImgRef[]>,
   themeSlug: string,
   chromeParts: Record<string, string>,
-  chromeSlugsByPage: Record<string, ChromeSlugs> | undefined
+  chromeSlugsByPage: Record<string, ChromeSlugs> | undefined,
+  templatePlan: TemplatePlan
 ): string {
-  const pageBlocks = orderedPageBlocks(site, pages, imgRefsByPage, themeSlug);
-  const blocks = pageBlocks.length > 0
-    ? pageBlocks.join('\n\n')
-    : '<!-- wp:paragraph -->\n<p></p>\n<!-- /wp:paragraph -->';
+  const homeSlug = homeSlugFromPlan(site, templatePlan);
+  const blocks =
+    blocksForPage(homeSlug, pages, imgRefsByPage, themeSlug) ??
+    '<!-- wp:paragraph -->\n<p></p>\n<!-- /wp:paragraph -->';
 
   const mainTemplate = `<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
 <main class="wp-block-group">
@@ -192,7 +198,7 @@ ${blocks}
 `;
   if (!chromeSlugsByPage) return mainTemplate;
 
-  const homeSlugs = chromeSlugsByPage[homeSlugForSite(site)] ?? {
+  const homeSlugs = chromeSlugsByPage[homeSlug] ?? {
     header: 'header',
     footer: 'footer',
   };
@@ -208,14 +214,33 @@ ${blocks}
   ].join('\n');
 }
 
+function buildGenericQueriedContentTemplate(chromeParts: Record<string, string>): string {
+  const mainTemplate =
+    '<!-- wp:group {"tagName":"main"} --><main class="wp-block-group"><!-- wp:post-content {"layout":{"type":"constrained"}} /--></main><!-- /wp:group -->';
+
+  if (!hasChromePart(chromeParts, 'header') || !hasChromePart(chromeParts, 'footer')) {
+    return `${mainTemplate}\n`;
+  }
+
+  return [
+    templatePartRef('header', 'header'),
+    mainTemplate,
+    templatePartRef('footer', 'footer'),
+    '',
+  ].join('\n');
+}
+
 function hasChromePart(chromeParts: Record<string, string>, slug: string): boolean {
   return Object.prototype.hasOwnProperty.call(chromeParts, `${slug}.html`);
 }
 
-function homeSlugForSite(site: SiteModel): string {
+function homeSlugFromPlan(site: SiteModel, templatePlan: TemplatePlan): string {
+  const plannedHome = Object.entries(templatePlan.templatesByPage).find(
+    ([, template]) => template === 'front-page'
+  )?.[0];
+
   return (
-    site.pages.find((page) => page.slug === 'home')?.slug ??
-    site.pages.find((page) => /(^|[\\/])index\.html?$/i.test(page.relPath))?.slug ??
+    plannedHome ??
     site.pages[0]?.slug ??
     'home'
   );
@@ -225,36 +250,6 @@ function templatePartRef(slug: string, tagName: 'header' | 'footer'): string {
   return `<!-- wp:template-part ${JSON.stringify({ slug, tagName })} /-->`;
 }
 
-function orderedPageBlocks(
-  site: SiteModel,
-  pages: Record<string, SectionBlocks[]>,
-  imgRefsByPage: Record<string, StaticImgRef[]>,
-  themeSlug: string
-): string[] {
-  const out: string[] = [];
-  const seen = new Set<string>();
-
-  for (const page of site.pages) {
-    const blocks = blocksForPage(page.slug, pages, imgRefsByPage, themeSlug);
-    if (!blocks) continue;
-    out.push(blocks);
-    seen.add(page.slug);
-  }
-
-  for (const [slug, sections] of Object.entries(pages).sort(([a], [b]) => a.localeCompare(b))) {
-    if (seen.has(slug)) continue;
-    const blocks = rewritePageBlocks(
-      slug,
-      joinSectionBlocks(sections),
-      imgRefsByPage,
-      themeSlug
-    );
-    if (blocks) out.push(blocks);
-  }
-
-  return out;
-}
-
 function blocksForPage(
   slug: string,
   pages: Record<string, SectionBlocks[]>,

From 3426a1e82fe70e56ec325a892f88d798103372a3 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 16:11:34 -0400
Subject: [PATCH 053/113] Freeze section coverage contract

---
 packages/blocks-engine/src/theme/index.ts     |  2 ++
 .../src/theme/section-coverage.ts             | 25 +++++++++++++++++++
 2 files changed, 27 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/section-coverage.ts

diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index e94a618e..1aec1dd5 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -8,6 +8,7 @@ export { foundation } from './foundation.js';
 export { ingest } from './ingest.js';
 export { planTemplates } from './template-plan.js';
 export { reconstruct } from './reconstruct.js';
+export { captureSectionContent, measureSectionCoverage, TEXT_FLOOR } from './section-coverage.js';
 export { sectionExtract } from './section-extract.js';
 export { siteToTheme } from './site-to-theme.js';
 export { lintThemeJson } from './theme-json-lint.js';
@@ -18,6 +19,7 @@ export type * from './assets.js';
 export type { ChromeResult } from './chrome.js';
 export type { ChromeSlugs } from './chrome-signature.js';
 export type { RegionSplit } from './chrome-split.js';
+export type { CapturedSectionContent, CoverageResult } from './section-coverage.js';
 export type * from './font-faces.js';
 export type * from './section-spec.js';
 export type { TemplatePlan } from './template-plan.js';
diff --git a/packages/blocks-engine/src/theme/section-coverage.ts b/packages/blocks-engine/src/theme/section-coverage.ts
new file mode 100644
index 00000000..a40fad7b
--- /dev/null
+++ b/packages/blocks-engine/src/theme/section-coverage.ts
@@ -0,0 +1,25 @@
+import type { SectionSpec } from './section-spec.js';
+
+export interface CapturedSectionContent {
+  text: string[];
+  images: string[];
+}
+
+export interface CoverageResult {
+  textCoverage: number;
+  missingImages: string[];
+  lost: boolean;
+}
+
+export const TEXT_FLOOR = 0.5;
+
+export function captureSectionContent(_spec: SectionSpec): CapturedSectionContent {
+  return { text: [], images: [] };
+}
+
+export function measureSectionCoverage(
+  _captured: CapturedSectionContent,
+  _renderedMarkup: string
+): CoverageResult {
+  return { textCoverage: 1, missingImages: [], lost: false };
+}

From a6c08297f1cb8aae70a0c042dd3e201b62bdfd8b Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 16:21:29 -0400
Subject: [PATCH 054/113] Implement section coverage measurement

---
 .../__tests__/theme-section-coverage.test.ts  | 166 ++++++++++++++++++
 .../src/theme/section-coverage.ts             |  62 ++++++-
 2 files changed, 223 insertions(+), 5 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-section-coverage.test.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-section-coverage.test.ts b/packages/blocks-engine/src/__tests__/theme-section-coverage.test.ts
new file mode 100644
index 00000000..42a6e343
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-section-coverage.test.ts
@@ -0,0 +1,166 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  captureSectionContent,
+  measureSectionCoverage,
+  TEXT_FLOOR,
+  type CapturedSectionContent,
+} from '../theme/section-coverage.js';
+import type { SectionSpec, SectionSpecImage } from '../theme/section-spec.js';
+
+function image(overrides: Partial<SectionSpecImage> = {}): SectionSpecImage {
+  return {
+    url: 'assets/hero.jpg',
+    sourceUrl: 'source/hero.jpg',
+    alt: 'Hero',
+    kind: 'img',
+    width: 1200,
+    height: 800,
+    ...overrides,
+  };
+}
+
+function sectionSpec(overrides: Partial<SectionSpec> = {}): SectionSpec {
+  return {
+    sectionIndex: 0,
+    interactionModel: 'static',
+    top: 0,
+    height: 640,
+    headings: [],
+    bodyText: [],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 1,
+    backgroundColor: '#ffffff',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: {
+      motionClass: 'none',
+      signals: [],
+      animatedElements: 0,
+    },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: {
+      containerWidth: 1200,
+      padding: '0',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '0',
+    },
+    ...overrides,
+  };
+}
+
+function captured(text: string[], images: string[] = []): CapturedSectionContent {
+  return { text, images };
+}
+
+describe('theme section coverage contract', () => {
+  describe('captureSectionContent', () => {
+    it('collects normalized headings, body text, button labels, and structured button labels', () => {
+      const result = captureSectionContent(
+        sectionSpec({
+          headings: ['  Hero   headline  ', '', 'Hero headline'],
+          bodyText: ['Body\tcopy', ' Body copy ', '   '],
+          buttonLabels: ['Start now', ' Start   now ', ''],
+          buttons: [
+            { label: 'Learn more', href: '#learn' },
+            { label: ' Learn    more ', href: '#learn-again' },
+            { label: '', href: '#empty' },
+          ],
+        })
+      );
+
+      expect(result.text).toEqual([
+        'hero headline',
+        'hero headline',
+        'body copy',
+        'body copy',
+        'start now',
+        'start now',
+        'learn more',
+        'learn more',
+      ]);
+    });
+
+    it('captures image effective URLs preferring url and falling back to sourceUrl', () => {
+      const result = captureSectionContent(
+        sectionSpec({
+          images: [
+            image({ url: 'assets/generated.jpg', sourceUrl: 'source/original.jpg' }),
+            image({ url: '', sourceUrl: 'source/fallback.jpg' }),
+          ],
+        })
+      );
+
+      expect(result.images).toEqual(['assets/generated.jpg', 'source/fallback.jpg']);
+    });
+  });
+
+  describe('measureSectionCoverage', () => {
+    it('reports full text and image coverage as not lost', () => {
+      const result = measureSectionCoverage(
+        captured(['Hero headline', 'Detailed copy', 'Start now'], ['assets/hero.jpg']),
+        [
+          '<section>',
+          '<h2>Hero headline</h2>',
+          '<p>Detailed copy</p>',
+          '<a href="/start">Start now</a>',
+          '<img src="assets/hero.jpg" alt="Hero">',
+          '</section>',
+        ].join('')
+      );
+
+      expect(result).toEqual({
+        textCoverage: 1,
+        missingImages: [],
+        lost: false,
+      });
+    });
+
+    it('marks sections lost when missing heading and text coverage falls below the text floor', () => {
+      const result = measureSectionCoverage(
+        captured(['Hero headline', 'Detailed copy', 'Start now']),
+        '<section><p>Detailed copy</p></section>'
+      );
+
+      expect(result.textCoverage).toBeCloseTo(1 / 3);
+      expect(result.textCoverage).toBeLessThan(TEXT_FLOOR);
+      expect(result.lost).toBe(true);
+    });
+
+    it('marks sections lost when an image is missing even if text coverage is full', () => {
+      const result = measureSectionCoverage(
+        captured(['Hero headline', 'Detailed copy'], ['assets/missing.jpg']),
+        '<section><h2>Hero headline</h2><p>Detailed copy</p></section>'
+      );
+
+      expect(result.textCoverage).toBe(1);
+      expect(result.missingImages).toEqual(['assets/missing.jpg']);
+      expect(result.lost).toBe(true);
+    });
+
+    it('matches rendered text after HTML entity decoding and glyph folding', () => {
+      const result = measureSectionCoverage(
+        captured(["You're ready - set & launch"]),
+        '<section><p>You&#8217;re ready &#8211; set &amp; launch</p></section>'
+      );
+
+      expect(result.textCoverage).toBe(1);
+      expect(result.missingImages).toEqual([]);
+      expect(result.lost).toBe(false);
+    });
+
+    it('treats empty captured content as fully covered and not lost', () => {
+      const result = measureSectionCoverage(captured([]), '<section></section>');
+
+      expect(result).toEqual({
+        textCoverage: 1,
+        missingImages: [],
+        lost: false,
+      });
+    });
+  });
+});
diff --git a/packages/blocks-engine/src/theme/section-coverage.ts b/packages/blocks-engine/src/theme/section-coverage.ts
index a40fad7b..d5793c6e 100644
--- a/packages/blocks-engine/src/theme/section-coverage.ts
+++ b/packages/blocks-engine/src/theme/section-coverage.ts
@@ -1,3 +1,4 @@
+import * as cheerio from 'cheerio';
 import type { SectionSpec } from './section-spec.js';
 
 export interface CapturedSectionContent {
@@ -13,13 +14,64 @@ export interface CoverageResult {
 
 export const TEXT_FLOOR = 0.5;
 
-export function captureSectionContent(_spec: SectionSpec): CapturedSectionContent {
-  return { text: [], images: [] };
+function foldText(value: string): string {
+  return value
+    .replace(/[\u2018\u2019\u201b]/g, "'")
+    .replace(/[\u201c\u201d]/g, '"')
+    .replace(/[\u2013\u2014\u2012]/g, '-')
+    .replace(/\u2026/g, '...')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+function normalizedText(value: string | null | undefined): string | null {
+  const folded = foldText(value ?? '');
+  return folded.length > 0 ? folded : null;
+}
+
+function addText(values: string[], value: string | null | undefined): void {
+  const normalized = normalizedText(value);
+  if (!normalized) return;
+
+  values.push(normalized);
+}
+
+function imageUrl(image: SectionSpec['images'][number]): string | null {
+  const url = image.url.trim();
+  if (url) return url;
+
+  const sourceUrl = image.sourceUrl.trim();
+  return sourceUrl ? sourceUrl : null;
+}
+
+export function captureSectionContent(spec: SectionSpec): CapturedSectionContent {
+  const text: string[] = [];
+
+  for (const heading of spec.headings) addText(text, heading);
+  for (const body of spec.bodyText) addText(text, body);
+  for (const label of spec.buttonLabels) addText(text, label);
+  for (const button of spec.buttons ?? []) addText(text, button.label);
+
+  const images = spec.images
+    .map(imageUrl)
+    .filter((url): url is string => url !== null);
+
+  return { text, images };
 }
 
 export function measureSectionCoverage(
-  _captured: CapturedSectionContent,
-  _renderedMarkup: string
+  captured: CapturedSectionContent,
+  renderedMarkup: string
 ): CoverageResult {
-  return { textCoverage: 1, missingImages: [], lost: false };
+  const haystack = foldText(cheerio.load(renderedMarkup, null, false).root().text());
+  const texts = captured.text.map(foldText).filter((text) => text.length > 0);
+  const present = texts.filter((text) => haystack.includes(text)).length;
+  const textCoverage = texts.length === 0 ? 1 : present / texts.length;
+
+  const images = captured.images.map((url) => url.trim()).filter((url) => url.length > 0);
+  const missingImages = images.filter((url) => !renderedMarkup.includes(url));
+  const lost = missingImages.length > 0 || textCoverage < TEXT_FLOOR;
+
+  return { textCoverage, missingImages, lost };
 }

From 9c0f7dca07643d5754579dc151cfec53e3fbd49c Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 16:29:03 -0400
Subject: [PATCH 055/113] Freeze coverage island contract

---
 packages/blocks-engine/src/theme/html-fallback.ts | 6 ++++++
 packages/blocks-engine/src/theme/index.ts         | 1 +
 2 files changed, 7 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/html-fallback.ts

diff --git a/packages/blocks-engine/src/theme/html-fallback.ts b/packages/blocks-engine/src/theme/html-fallback.ts
new file mode 100644
index 00000000..38ad2d4e
--- /dev/null
+++ b/packages/blocks-engine/src/theme/html-fallback.ts
@@ -0,0 +1,6 @@
+import type { SectionSpec } from './section-spec.js';
+
+export function buildCoverageIsland(spec: SectionSpec): string {
+  void spec;
+  throw new Error('buildCoverageIsland contract stub');
+}
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 1aec1dd5..57c978a1 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -8,6 +8,7 @@ export { foundation } from './foundation.js';
 export { ingest } from './ingest.js';
 export { planTemplates } from './template-plan.js';
 export { reconstruct } from './reconstruct.js';
+export { buildCoverageIsland } from './html-fallback.js';
 export { captureSectionContent, measureSectionCoverage, TEXT_FLOOR } from './section-coverage.js';
 export { sectionExtract } from './section-extract.js';
 export { siteToTheme } from './site-to-theme.js';

From fdc18a5e773db8b9af6e6ae522d0fe7ec3a116dc Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 16:36:11 -0400
Subject: [PATCH 056/113] Implement coverage island fallback

---
 .../src/__tests__/theme-html-fallback.test.ts | 168 ++++++++++++++++++
 .../blocks-engine/src/theme/html-fallback.ts  |  57 +++++-
 2 files changed, 223 insertions(+), 2 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-html-fallback.test.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-html-fallback.test.ts b/packages/blocks-engine/src/__tests__/theme-html-fallback.test.ts
new file mode 100644
index 00000000..888ec34c
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-html-fallback.test.ts
@@ -0,0 +1,168 @@
+import * as cheerio from 'cheerio';
+import { describe, expect, it } from 'vitest';
+
+import { buildCoverageIsland } from '../theme/html-fallback.js';
+import {
+  captureSectionContent,
+  measureSectionCoverage,
+} from '../theme/section-coverage.js';
+import type { SectionSpec, SectionSpecImage } from '../theme/section-spec.js';
+
+const COVERAGE_ISLAND_OPENER =
+  '<!-- wp:html {"metadata":{"name":"lib-coverage-island"}} -->';
+const COVERAGE_ISLAND_CLOSER = '<!-- /wp:html -->';
+
+function image(overrides: Partial<SectionSpecImage> = {}): SectionSpecImage {
+  return {
+    url: 'assets/hero.jpg',
+    sourceUrl: 'source/hero.jpg',
+    alt: 'Hero',
+    kind: 'img',
+    width: 1200,
+    height: 800,
+    ...overrides,
+  };
+}
+
+function sectionSpec(overrides: Partial<SectionSpec> = {}): SectionSpec {
+  return {
+    sectionIndex: 0,
+    interactionModel: 'static',
+    top: 0,
+    height: 640,
+    headings: [],
+    bodyText: [],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 1,
+    backgroundColor: '#ffffff',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: {
+      motionClass: 'none',
+      signals: [],
+      animatedElements: 0,
+    },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: {
+      containerWidth: 1200,
+      padding: '0',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '0',
+    },
+    ...overrides,
+  };
+}
+
+function islandBody(markup: string): string {
+  expect(markup.split('\n')[0]).toBe(COVERAGE_ISLAND_OPENER);
+  expect(markup.endsWith(`\n${COVERAGE_ISLAND_CLOSER}`)).toBe(true);
+
+  return markup.slice(
+    `${COVERAGE_ISLAND_OPENER}\n`.length,
+    -`\n${COVERAGE_ISLAND_CLOSER}`.length
+  );
+}
+
+describe('buildCoverageIsland', () => {
+  it('preserves sectionHtml verbatim and round-trips section coverage', () => {
+    const sourceHtml =
+      '<section class="source"><h2>Handmade planters</h2><p>Small-batch ceramics for bright windows.</p><a href="/shop">Shop the drop</a><img src="assets/source-hero.jpg" alt="Hero"></section>';
+    const spec = sectionSpec({
+      sectionHtml: sourceHtml,
+      headings: ['Handmade planters'],
+      bodyText: ['Small-batch ceramics for bright windows.'],
+      buttonLabels: ['Shop the drop'],
+      buttons: [{ label: 'Shop the drop', href: '/shop' }],
+      images: [image({ url: 'assets/source-hero.jpg', alt: 'Hero' })],
+    });
+
+    const markup = buildCoverageIsland(spec);
+
+    expect(islandBody(markup)).toBe(sourceHtml);
+    expect(
+      measureSectionCoverage(captureSectionContent(spec), markup).lost
+    ).toBe(false);
+  });
+
+  it('serializes SectionSpec content and round-trips section coverage', () => {
+    const spec = sectionSpec({
+      headings: ['Studio notes', 'Fresh glaze schedule'],
+      bodyText: [
+        'Glazes are mixed every Friday.',
+        'Pickup windows open at noon.',
+      ],
+      buttonLabels: ['Reserve a kiln tour'],
+      buttons: [{ label: 'Reserve a kiln tour', href: '/tour' }],
+      images: [
+        image({
+          url: 'assets/tiles.jpg',
+          sourceUrl: 'source/tiles.jpg',
+          alt: 'Glazed tiles',
+          width: 640,
+          height: 480,
+        }),
+      ],
+    });
+
+    const markup = buildCoverageIsland(spec);
+    const body = islandBody(markup);
+    const $ = cheerio.load(body, null, false);
+
+    expect($('h2').map((_, el) => $(el).text()).get()).toEqual([
+      'Studio notes',
+    ]);
+    expect($('h3').map((_, el) => $(el).text()).get()).toEqual([
+      'Fresh glaze schedule',
+    ]);
+    expect(
+      $('p')
+        .filter((_, el) => $(el).find('a').length === 0)
+        .map((_, el) => $(el).text())
+        .get()
+    ).toEqual(['Glazes are mixed every Friday.', 'Pickup windows open at noon.']);
+
+    const renderedImage = $('figure img');
+    expect(renderedImage).toHaveLength(1);
+    expect(renderedImage.attr('src')).toBe('assets/tiles.jpg');
+    expect(renderedImage.attr('alt')).toBe('Glazed tiles');
+
+    const renderedButton = $('a');
+    expect(renderedButton).toHaveLength(1);
+    expect(renderedButton.text()).toBe('Reserve a kiln tour');
+    expect(renderedButton.attr('href')).toBe('/tour');
+
+    expect($('h2,h3,p').map((_, el) => $(el).text()).get()).toEqual([
+      'Studio notes',
+      'Fresh glaze schedule',
+      'Glazes are mixed every Friday.',
+      'Pickup windows open at noon.',
+      'Reserve a kiln tour',
+    ]);
+    expect(
+      measureSectionCoverage(captureSectionContent(spec), markup).lost
+    ).toBe(false);
+  });
+
+  it('keeps source text present without fabricating native image blocks or text', () => {
+    const spec = sectionSpec({
+      headings: ['Studio notes'],
+      bodyText: ['Glazes are mixed every Friday.'],
+      buttonLabels: ['Reserve a kiln tour'],
+      images: [image({ url: 'assets/tiles.jpg', alt: 'Glazed tiles' })],
+    });
+
+    const markup = buildCoverageIsland(spec);
+
+    expect(markup).toContain('<h2>Studio notes</h2>');
+    expect(markup).toContain('<p>Glazes are mixed every Friday.</p>');
+    expect(markup).toContain('<a href="#">Reserve a kiln tour</a>');
+    expect(markup).toContain('<img src="assets/tiles.jpg" alt="Glazed tiles">');
+    expect(markup).not.toContain('Invented');
+    expect(markup).not.toContain('<!-- wp:image');
+    expect(markup).not.toContain('wp-block-image');
+  });
+});
diff --git a/packages/blocks-engine/src/theme/html-fallback.ts b/packages/blocks-engine/src/theme/html-fallback.ts
index 38ad2d4e..966c4aa4 100644
--- a/packages/blocks-engine/src/theme/html-fallback.ts
+++ b/packages/blocks-engine/src/theme/html-fallback.ts
@@ -1,6 +1,59 @@
+import { PIPELINE_ISLAND_OPENER } from '../block-policy.js';
+import { escapeHtmlAttr, escapeHtmlText } from '../escape.js';
 import type { SectionSpec } from './section-spec.js';
+import type { SectionSpecButton, SectionSpecImage } from './section-spec.js';
+
+function nonEmpty(value: string | null | undefined): string | null {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function imageHtml(image: SectionSpecImage): string | null {
+  const src = nonEmpty(image.url) ?? nonEmpty(image.sourceUrl);
+  if (!src) return null;
+
+  return `<figure><img src="${escapeHtmlAttr(src)}" alt="${escapeHtmlAttr(image.alt)}"></figure>`;
+}
+
+function buttonHtml(button: SectionSpecButton): string | null {
+  const label = nonEmpty(button.label);
+  if (!label) return null;
+
+  const href = nonEmpty(button.href) ?? '#';
+  return `<p><a href="${escapeHtmlAttr(href)}">${escapeHtmlText(label)}</a></p>`;
+}
+
+function semanticFallbackHtml(spec: SectionSpec): string {
+  const fragments: string[] = [];
+
+  for (const [index, heading] of spec.headings.entries()) {
+    const text = nonEmpty(heading);
+    if (!text) continue;
+
+    const level = index === 0 ? 2 : 3;
+    fragments.push(`<h${level}>${escapeHtmlText(text)}</h${level}>`);
+  }
+
+  for (const body of spec.bodyText) {
+    const text = nonEmpty(body);
+    if (text) fragments.push(`<p>${escapeHtmlText(text)}</p>`);
+  }
+
+  const structuredButtons =
+    spec.buttons?.map(buttonHtml).filter((html): html is string => html !== null) ?? [];
+  const labelButtons = spec.buttonLabels
+    .map((label) => nonEmpty(label))
+    .filter((label): label is string => label !== null)
+    .map((label) => `<p><a href="#">${escapeHtmlText(label)}</a></p>`);
+  const buttons = structuredButtons.length > 0 ? structuredButtons : labelButtons;
+  fragments.push(...buttons);
+
+  fragments.push(...spec.images.map(imageHtml).filter((html): html is string => html !== null));
+
+  return fragments.length > 0 ? `<section>${fragments.join('')}</section>` : '<section></section>';
+}
 
 export function buildCoverageIsland(spec: SectionSpec): string {
-  void spec;
-  throw new Error('buildCoverageIsland contract stub');
+  const body = spec.sectionHtml?.trim() ? spec.sectionHtml : semanticFallbackHtml(spec);
+  return `${PIPELINE_ISLAND_OPENER}\n${body}\n<!-- /wp:html -->`;
 }

From b4b74797e5f04b3635cadd049d2424807b311f61 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 16:49:41 -0400
Subject: [PATCH 057/113] Wire section coverage fallback

---
 .../src/__tests__/site-to-theme.e2e.test.ts   |  23 +++
 .../src/__tests__/theme-reconstruct.test.ts   | 162 ++++++++++++++++++
 .../blocks-engine/src/theme/reconstruct.ts    |  11 +-
 3 files changed, 195 insertions(+), 1 deletion(-)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-reconstruct.test.ts

diff --git a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
index b70c30a4..8ae27df7 100644
--- a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
+++ b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
@@ -688,6 +688,7 @@ describe('site-to-theme P0-3 orchestration', () => {
       expect(template).toContain(footerRef);
       expect(template).not.toMatch(/<(?:header|nav|footer)(?:\s|>)/);
       expect(body).not.toMatch(/<(?:header|nav|footer)(?:\s|>)/);
+      expect(template).toContain('Build calmer block themes');
       expect(template).toContain('/wp-content/themes/fixture-theme/assets/logo.png');
       expect(template).toMatch(
         /<!-- wp:html \{"metadata":\{"name":"lib-coverage-island"\}\} -->[\s\S]*<img src="\/wp-content\/themes\/fixture-theme\/assets\/logo\.png" alt="Blocks Engine mark">[\s\S]*<!-- \/wp:html -->/
@@ -703,6 +704,28 @@ describe('site-to-theme P0-3 orchestration', () => {
     });
   });
 
+  it('siteToTheme-e2e-hero-survives coverage-gated reconstruct', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+    const { fetchImpl } = mockFontFetch();
+
+    await withTempDir('blocks-engine-site-to-theme-hero-survives-', async (siteDir) => {
+      copyFixtureSite(siteDir);
+      const outDir = join(siteDir, 'theme-out');
+
+      await siteToTheme(siteDir, {
+        outDir,
+        fetchImpl,
+        themeMeta: themeMeta(),
+      });
+
+      const template = readFileSync(join(outDir, 'templates', 'front-page.html'), 'utf8');
+
+      expect(template).toContain('Build calmer block themes');
+      expect(template).toContain('Static source pages become a structured theme pipeline.');
+      expect(template).toContain('Learn more');
+    });
+  });
+
   it('siteToTheme-e2e-chrome runs chrome extraction even when body sections are injected', async () => {
     const { siteToTheme } = await import('../theme/index.js');
 
diff --git a/packages/blocks-engine/src/__tests__/theme-reconstruct.test.ts b/packages/blocks-engine/src/__tests__/theme-reconstruct.test.ts
new file mode 100644
index 00000000..132896ba
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-reconstruct.test.ts
@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+
+import type { WorkerPool } from '../pool/types.js';
+import {
+  captureSectionContent,
+  measureSectionCoverage,
+  reconstruct,
+  type SectionSpec,
+  type StageCtx,
+} from '../theme/index.js';
+
+function sectionSpec(overrides: Partial<SectionSpec> = {}): SectionSpec {
+  return {
+    sectionIndex: 0,
+    interactionModel: 'static',
+    top: 0,
+    height: 0,
+    headings: [],
+    bodyText: [],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 1,
+    backgroundColor: 'transparent',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: {
+      motionClass: 'none',
+      signals: [],
+      animatedElements: 0,
+    },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: {
+      containerWidth: 0,
+      padding: '0',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '0',
+    },
+    ...overrides,
+  };
+}
+
+function fakePool(markupForInput: (html: string) => string): WorkerPool {
+  return {
+    async rawConvert(items: string[]) {
+      return items.map((html) => ({ html: markupForInput(html), wpHtmlResidue: 0 }));
+    },
+    async canonicalize(items: string[]) {
+      return items.map((html) => ({ html, changed: false, fixedIssues: [] }));
+    },
+    async stop() {},
+  };
+}
+
+function stageCtx(): StageCtx {
+  return {
+    srcDir: '/tmp/site',
+    site: { root: '/tmp/site', pages: [] },
+    themeMeta: { name: 'Fixture Theme', slug: 'fixture-theme' },
+    warn() {},
+  };
+}
+
+describe('theme reconstruct coverage gate', () => {
+  it('falls back from lossy native blocks to a verbatim coverage island', async () => {
+    const spec = sectionSpec({
+      headings: ['Build calmer block themes'],
+      bodyText: ['Static source pages become a structured theme pipeline.'],
+      buttonLabels: ['Learn more'],
+      sectionHtml: [
+        '<section id="hero">',
+        '<h1>Build calmer block themes</h1>',
+        '<p>Static source pages become a structured theme pipeline.</p>',
+        '<a class="button" href="./about.html">Learn more</a>',
+        '</section>',
+      ].join(''),
+    });
+    const lossyNative =
+      '<!-- wp:buttons -->\n<div class="wp-block-buttons">Learn more</div>\n<!-- /wp:buttons -->';
+
+    const [section] = await reconstruct(
+      [spec],
+      stageCtx(),
+      fakePool(() => lossyNative),
+      {},
+      0
+    );
+
+    expect(section.blocks).toContain('metadata":{"name":"lib-coverage-island"}');
+    expect(section.blocks).toContain('<h1>Build calmer block themes</h1>');
+    expect(section.blocks).toContain(
+      '<p>Static source pages become a structured theme pipeline.</p>'
+    );
+    expect(section.blocks).not.toBe(lossyNative);
+    expect(measureSectionCoverage(captureSectionContent(spec), section.blocks).lost).toBe(false);
+    expect(section.coverage).toBe(0);
+  });
+
+  it('keeps full-coverage native blocks unchanged', async () => {
+    const spec = sectionSpec({
+      headings: ['Native heading'],
+      bodyText: ['Native body copy.'],
+      sectionHtml: '<section><h2>Native heading</h2><p>Native body copy.</p></section>',
+    });
+    const nativeBlocks = [
+      '<!-- wp:heading -->',
+      '<h2>Native heading</h2>',
+      '<!-- /wp:heading -->',
+      '<!-- wp:paragraph -->',
+      '<p>Native body copy.</p>',
+      '<!-- /wp:paragraph -->',
+    ].join('\n');
+
+    const [section] = await reconstruct(
+      [spec],
+      stageCtx(),
+      fakePool(() => nativeBlocks),
+      {},
+      0
+    );
+
+    expect(section.blocks).toBe(nativeBlocks);
+    expect(section.blocks).not.toContain('lib-coverage-island');
+    expect(section.coverage).toBe(1);
+  });
+
+  it('keeps existing onSection coverage-floor gating after fallback', async () => {
+    const spec = sectionSpec({
+      headings: ['Hooked hero'],
+      bodyText: ['Copy that should survive.'],
+      buttonLabels: ['Act now'],
+      sectionHtml:
+        '<section><h1>Hooked hero</h1><p>Copy that should survive.</p><a>Act now</a></section>',
+    });
+    const seenCoverages: number[] = [];
+
+    const [section] = await reconstruct(
+      [spec],
+      stageCtx(),
+      fakePool(
+        () =>
+          '<!-- wp:buttons -->\n<div class="wp-block-buttons">Act now</div>\n<!-- /wp:buttons -->'
+      ),
+      {
+        async onSection(section) {
+          seenCoverages.push(section.coverage);
+          return {
+            ...section,
+            blocks: `${section.blocks}\n<!-- hooked -->`,
+          };
+        },
+      },
+      0
+    );
+
+    expect(seenCoverages).toEqual([0]);
+    expect(section.blocks).toContain('lib-coverage-island');
+    expect(section.blocks).toContain('<!-- hooked -->');
+  });
+});
diff --git a/packages/blocks-engine/src/theme/reconstruct.ts b/packages/blocks-engine/src/theme/reconstruct.ts
index df4e38e6..5c18b1d2 100644
--- a/packages/blocks-engine/src/theme/reconstruct.ts
+++ b/packages/blocks-engine/src/theme/reconstruct.ts
@@ -1,6 +1,8 @@
 import { convert } from '../convert.js';
 import { escapeHtmlAttr, escapeHtmlText } from '../escape.js';
 import type { WorkerPool } from '../pool/types.js';
+import { buildCoverageIsland } from './html-fallback.js';
+import { captureSectionContent, measureSectionCoverage } from './section-coverage.js';
 import type { SectionSpec, SectionSpecButton, SectionSpecImage } from './section-spec.js';
 import type { SectionBlocks, SiteToThemeHooks, StageCtx } from './types.js';
 
@@ -77,7 +79,14 @@ export async function reconstruct(
   const sections: SectionBlocks[] = [];
 
   for (const spec of specs) {
-    const blocks = await convert(sectionInputHtml(spec), { url: '' }, { pool });
+    let blocks = await convert(sectionInputHtml(spec), { url: '' }, { pool });
+    if (
+      !HTML_ISLAND_RE.test(blocks) &&
+      measureSectionCoverage(captureSectionContent(spec), blocks).lost
+    ) {
+      blocks = buildCoverageIsland(spec);
+    }
+
     const section: SectionBlocks = {
       spec,
       blocks,

From 14210c40963b767e3f0176ea46697618f9d4fadc Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 19:18:15 -0400
Subject: [PATCH 058/113] Export chrome signature parity helpers

---
 .../theme-chrome-signature-parity.test.ts     | 57 +++++++++++++++++++
 .../src/theme/chrome-signature.ts             |  4 +-
 packages/blocks-engine/src/theme/index.ts     |  7 ++-
 3 files changed, 65 insertions(+), 3 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-chrome-signature-parity.test.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-chrome-signature-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-chrome-signature-parity.test.ts
new file mode 100644
index 00000000..a6117371
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-chrome-signature-parity.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  canonicalizeInstanceIds,
+  chromeSignature,
+  stripActiveNavState,
+} from '../theme/index.js';
+
+describe('chrome signature DLA parity', () => {
+  it('strips active nav state exactly like DLA chrome-canonicalize', () => {
+    expect(
+      stripActiveNavState(
+        '<a href="/" data-selected="true" aria-current="page" data-interactive="false" selected="true" data-selectedness="true" data-state="data-selected">Home</a>'
+      )
+    ).toBe(
+      '<a href="/" data-interactive="true" selected="true" data-selectedness="true" data-state="data-selected">Home</a>'
+    );
+  });
+
+  it('canonicalizes Wix instance ids in first-appearance order and preserves component tails', () => {
+    expect(
+      canonicalizeInstanceIds(
+        '<header id="comp-head1_r_comp-header"><a id="comp-link1_r_comp-nav" data-ref="comp-head1"></a><span id="_r_comp-head1"></span></header>'
+      )
+    ).toBe(
+      '<header id="comp-INSTANCE0_r_comp-header"><a id="comp-INSTANCE1_r_comp-nav" data-ref="comp-INSTANCE0"></a><span id="_r_comp-head1"></span></header>'
+    );
+  });
+
+  it('does not shear longer alphanumeric instance tokens that share a prefix', () => {
+    expect(
+      canonicalizeInstanceIds(
+        'comp-aa comp-aa1 comp-aa_r_comp-shared comp-aa1_r_comp-shared _r_comp-aa'
+      )
+    ).toBe(
+      'comp-INSTANCE0 comp-INSTANCE1 comp-INSTANCE0_r_comp-shared comp-INSTANCE1_r_comp-shared _r_comp-aa'
+    );
+  });
+
+  it('canonicalizes chrome signatures across active-nav markers and per-page instance ids', () => {
+    const headerA =
+      '<header id="comp-head1_r_comp-header"><nav><a id="comp-home1_r_comp-link" href="/" data-selected="true" aria-current="page" data-interactive="false">Home</a><a id="comp-about1_r_comp-link" href="/about" data-interactive="true">About</a></nav></header>';
+    const footerA = '<footer id="comp-foot1_r_comp-footer"><p>Acme</p></footer>';
+    const headerB =
+      '<header id="comp-head2_r_comp-header"><nav><a id="comp-home2_r_comp-link" href="/" data-interactive="true">Home</a><a id="comp-about2_r_comp-link" href="/about" data-selected="true" aria-current="page" data-interactive="false">About</a></nav></header>';
+    const footerB = '<footer id="comp-foot2_r_comp-footer"><p>Acme</p></footer>';
+    const differentHeader =
+      '<header id="comp-head3_r_comp-header"><nav><a id="comp-home3_r_comp-link" href="/" data-selected="true" aria-current="page" data-interactive="false">Home</a><a id="comp-contact3_r_comp-link" href="/contact" data-interactive="true">Contact</a></nav></header>';
+
+    const expected =
+      '<header id="comp-INSTANCE0_r_comp-header"><nav><a id="comp-INSTANCE1_r_comp-link" href="/" data-interactive="true">Home</a><a id="comp-INSTANCE2_r_comp-link" href="/about" data-interactive="true">About</a></nav></header>\u0001<footer id="comp-INSTANCE3_r_comp-footer"><p>Acme</p></footer>';
+
+    expect(chromeSignature(headerA, footerA)).toBe(expected);
+    expect(chromeSignature(headerB, footerB)).toBe(expected);
+    expect(chromeSignature(differentHeader, footerA)).not.toBe(expected);
+  });
+});
diff --git a/packages/blocks-engine/src/theme/chrome-signature.ts b/packages/blocks-engine/src/theme/chrome-signature.ts
index 11d1aa52..80125a45 100644
--- a/packages/blocks-engine/src/theme/chrome-signature.ts
+++ b/packages/blocks-engine/src/theme/chrome-signature.ts
@@ -37,14 +37,14 @@ export function assignChromeVariants(
   return { slugsByPage, canonical };
 }
 
-function stripActiveNavState(html: string): string {
+export function stripActiveNavState(html: string): string {
   return html
     .replace(/ ?data-selected="true"/g, '')
     .replace(/ ?aria-current="page"/g, '')
     .replace(/data-interactive="false"/g, 'data-interactive="true"');
 }
 
-function canonicalizeInstanceIds(s: string): string {
+export function canonicalizeInstanceIds(s: string): string {
   const order: string[] = [];
   const seen = new Set<string>();
 
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 57c978a1..15b54abf 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -2,7 +2,12 @@ export { assemble } from './assemble.js';
 export { assets } from './assets.js';
 export { buildChromePart } from './chrome-parts.js';
 export { chrome } from './chrome.js';
-export { assignChromeVariants, chromeSignature } from './chrome-signature.js';
+export {
+  assignChromeVariants,
+  canonicalizeInstanceIds,
+  chromeSignature,
+  stripActiveNavState,
+} from './chrome-signature.js';
 export { splitPageChrome } from './chrome-split.js';
 export { foundation } from './foundation.js';
 export { ingest } from './ingest.js';

From 668afeabb5b5e1811dd46c362311400f569adb03 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 19:26:52 -0400
Subject: [PATCH 059/113] Add converted section coverage parity

---
 .../__tests__/theme-section-coverage.test.ts  | 68 +++++++++++++++++++
 packages/blocks-engine/src/theme/index.ts     |  8 ++-
 .../src/theme/section-coverage.ts             | 24 ++++++-
 3 files changed, 98 insertions(+), 2 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/theme-section-coverage.test.ts b/packages/blocks-engine/src/__tests__/theme-section-coverage.test.ts
index 42a6e343..ed1bd7fd 100644
--- a/packages/blocks-engine/src/__tests__/theme-section-coverage.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-section-coverage.test.ts
@@ -2,6 +2,8 @@ import { describe, expect, it } from 'vitest';
 
 import {
   captureSectionContent,
+  foldText,
+  measureConvertedCoverage,
   measureSectionCoverage,
   TEXT_FLOOR,
   type CapturedSectionContent,
@@ -163,4 +165,70 @@ describe('theme section coverage contract', () => {
       });
     });
   });
+
+  describe('measureConvertedCoverage DLA parity', () => {
+    it('reports full converted text and image coverage as not lost', () => {
+      const result = measureConvertedCoverage(
+        captured(['Hero headline', 'Detailed copy', 'Start now'], ['assets/hero.jpg']),
+        [
+          '<section>',
+          '<h2>Hero headline</h2>',
+          '<p>Detailed copy</p>',
+          '<a href="/start">Start now</a>',
+          '<img src="assets/hero.jpg" alt="Hero">',
+          '</section>',
+        ].join('')
+      );
+
+      expect(result).toEqual({
+        textCoverage: 1,
+        missingImages: [],
+        lost: false,
+      });
+    });
+
+    it('matches converted images by basename across CDN and uploads URL forms', () => {
+      const result = measureConvertedCoverage(
+        captured(['Hero headline'], ['https://cdn.example.com/media/hero.jpg?resize=1200']),
+        '<section><h2>Hero headline</h2><img src="/wp-content/uploads/2026/hero.jpg"></section>'
+      );
+
+      expect(result).toEqual({
+        textCoverage: 1,
+        missingImages: [],
+        lost: false,
+      });
+    });
+
+    it('marks converted coverage lost when an image basename is missing', () => {
+      const result = measureConvertedCoverage(
+        captured(['Hero headline'], ['https://cdn.example.com/media/missing.jpg']),
+        '<section><h2>Hero headline</h2><img src="/wp-content/uploads/2026/hero.jpg"></section>'
+      );
+
+      expect(result.textCoverage).toBe(1);
+      expect(result.missingImages).toEqual(['https://cdn.example.com/media/missing.jpg']);
+      expect(result.lost).toBe(true);
+    });
+
+    it('marks converted coverage lost when folded text coverage is below the text floor', () => {
+      const result = measureConvertedCoverage(
+        captured(['Hero headline', 'Detailed copy', 'Start now']),
+        '<section><p>Detailed copy</p></section>'
+      );
+
+      expect(result.textCoverage).toBeCloseTo(1 / 3);
+      expect(result.textCoverage).toBeLessThan(TEXT_FLOOR);
+      expect(result.missingImages).toEqual([]);
+      expect(result.lost).toBe(true);
+    });
+
+    it('folds glyph variants like the DLA section coverage oracle', () => {
+      expect(
+        foldText(
+          '\u2018Smart\u2019 \u201cquotes\u201d \u2013 \u2014 \u2012 wait\u2026\nagain'
+        )
+      ).toBe("'smart' \"quotes\" - - - wait... again");
+    });
+  });
 });
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 15b54abf..d588eacd 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -14,7 +14,13 @@ export { ingest } from './ingest.js';
 export { planTemplates } from './template-plan.js';
 export { reconstruct } from './reconstruct.js';
 export { buildCoverageIsland } from './html-fallback.js';
-export { captureSectionContent, measureSectionCoverage, TEXT_FLOOR } from './section-coverage.js';
+export {
+  captureSectionContent,
+  foldText,
+  measureConvertedCoverage,
+  measureSectionCoverage,
+  TEXT_FLOOR,
+} from './section-coverage.js';
 export { sectionExtract } from './section-extract.js';
 export { siteToTheme } from './site-to-theme.js';
 export { lintThemeJson } from './theme-json-lint.js';
diff --git a/packages/blocks-engine/src/theme/section-coverage.ts b/packages/blocks-engine/src/theme/section-coverage.ts
index d5793c6e..15de13fb 100644
--- a/packages/blocks-engine/src/theme/section-coverage.ts
+++ b/packages/blocks-engine/src/theme/section-coverage.ts
@@ -14,7 +14,7 @@ export interface CoverageResult {
 
 export const TEXT_FLOOR = 0.5;
 
-function foldText(value: string): string {
+export function foldText(value: string): string {
   return value
     .replace(/[\u2018\u2019\u201b]/g, "'")
     .replace(/[\u201c\u201d]/g, '"')
@@ -60,6 +60,28 @@ export function captureSectionContent(spec: SectionSpec): CapturedSectionContent
   return { text, images };
 }
 
+export function measureConvertedCoverage(
+  captured: CapturedSectionContent,
+  convertedMarkup: string
+): CoverageResult {
+  const haystack = foldText(cheerio.load(convertedMarkup, null, false).root().text());
+  const texts = captured.text.map(foldText).filter((text) => text.length > 0);
+  const present = texts.filter((text) => haystack.includes(text)).length;
+  const textCoverage = texts.length === 0 ? 1 : present / texts.length;
+
+  const basename = (url: string): string =>
+    (url.split(/[?#]/)[0].split('/').pop() || '').toLowerCase();
+  const markupLc = convertedMarkup.toLowerCase();
+  const missingImages = captured.images.filter((url) => {
+    const base = basename(url);
+    return base ? !markupLc.includes(base) : !!url && !markupLc.includes(url.toLowerCase());
+  });
+
+  const lost = missingImages.length > 0 || textCoverage < TEXT_FLOOR;
+
+  return { textCoverage, missingImages, lost };
+}
+
 export function measureSectionCoverage(
   captured: CapturedSectionContent,
   renderedMarkup: string

From c04f2e61631661703559a25da7d36f53d6f70961 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 19:33:28 -0400
Subject: [PATCH 060/113] Freeze html fallback parity surface

---
 .../theme-html-fallback-surface.test.ts       | 30 +++++++++++++++++++
 .../blocks-engine/src/theme/html-fallback.ts  | 30 +++++++++++++++++++
 packages/blocks-engine/src/theme/index.ts     | 12 +++++++-
 .../blocks-engine/src/theme/injection-scan.ts |  4 +++
 .../blocks-engine/src/theme/url-rewrite.ts    | 21 +++++++++++++
 5 files changed, 96 insertions(+), 1 deletion(-)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-html-fallback-surface.test.ts
 create mode 100644 packages/blocks-engine/src/theme/injection-scan.ts
 create mode 100644 packages/blocks-engine/src/theme/url-rewrite.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-html-fallback-surface.test.ts b/packages/blocks-engine/src/__tests__/theme-html-fallback-surface.test.ts
new file mode 100644
index 00000000..71368280
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-html-fallback-surface.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildHtmlFallbackBlock,
+  isWpLayoutMarkup,
+  rewriteInternalLinks,
+  rewriteMediaUrls,
+  sanitize,
+  scanForInjection,
+  selectIslandSource,
+  type InternalLinkMap,
+  type IslandTier,
+} from '../theme/index.js';
+
+describe('theme html fallback public surface', () => {
+  it('freezes the additive A3 named exports', () => {
+    const linkMap: InternalLinkMap = new Map([['/about', '/about/']]);
+    const tier: IslandTier = selectIslandSource({ sectionHtml: '<section></section>' }).tier;
+
+    expect(typeof sanitize).toBe('function');
+    expect(typeof isWpLayoutMarkup).toBe('function');
+    expect(typeof selectIslandSource).toBe('function');
+    expect(typeof buildHtmlFallbackBlock).toBe('function');
+    expect(typeof rewriteMediaUrls).toBe('function');
+    expect(typeof rewriteInternalLinks).toBe('function');
+    expect(typeof scanForInjection).toBe('function');
+    expect(linkMap.get('/about')).toBe('/about/');
+    expect(['responsive', 'styled', 'verbatim']).toContain(tier);
+  });
+});
diff --git a/packages/blocks-engine/src/theme/html-fallback.ts b/packages/blocks-engine/src/theme/html-fallback.ts
index 966c4aa4..c2291483 100644
--- a/packages/blocks-engine/src/theme/html-fallback.ts
+++ b/packages/blocks-engine/src/theme/html-fallback.ts
@@ -2,6 +2,36 @@ import { PIPELINE_ISLAND_OPENER } from '../block-policy.js';
 import { escapeHtmlAttr, escapeHtmlText } from '../escape.js';
 import type { SectionSpec } from './section-spec.js';
 import type { SectionSpecButton, SectionSpecImage } from './section-spec.js';
+import type { InternalLinkMap } from './url-rewrite.js';
+
+export interface HtmlFallbackOpts {
+  mediaUrlMap?: Map<string, string>;
+  linkMap?: InternalLinkMap;
+}
+
+export type IslandTier = 'responsive' | 'styled' | 'verbatim';
+
+export function sanitize(html: string): string {
+  return html;
+}
+
+export function isWpLayoutMarkup(html: string): boolean {
+  return html.length > 0 && false;
+}
+
+export function selectIslandSource(
+  section: { sectionHtml?: string; styledHtml?: string },
+): { source: string; tier: IslandTier } {
+  return { source: section.sectionHtml ?? section.styledHtml ?? '', tier: 'verbatim' };
+}
+
+export function buildHtmlFallbackBlock(
+  sectionHtml: string,
+  opts: HtmlFallbackOpts = {},
+): string {
+  void opts;
+  return `${PIPELINE_ISLAND_OPENER}\n${sectionHtml.trim()}\n<!-- /wp:html -->`;
+}
 
 function nonEmpty(value: string | null | undefined): string | null {
   const trimmed = value?.trim();
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index d588eacd..538692b8 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -13,7 +13,13 @@ export { foundation } from './foundation.js';
 export { ingest } from './ingest.js';
 export { planTemplates } from './template-plan.js';
 export { reconstruct } from './reconstruct.js';
-export { buildCoverageIsland } from './html-fallback.js';
+export {
+  buildCoverageIsland,
+  buildHtmlFallbackBlock,
+  isWpLayoutMarkup,
+  sanitize,
+  selectIslandSource,
+} from './html-fallback.js';
 export {
   captureSectionContent,
   foldText,
@@ -31,8 +37,12 @@ export type * from './assets.js';
 export type { ChromeResult } from './chrome.js';
 export type { ChromeSlugs } from './chrome-signature.js';
 export type { RegionSplit } from './chrome-split.js';
+export type { IslandTier } from './html-fallback.js';
+export { rewriteInternalLinks, rewriteMediaUrls } from './url-rewrite.js';
+export { scanForInjection } from './injection-scan.js';
 export type { CapturedSectionContent, CoverageResult } from './section-coverage.js';
 export type * from './font-faces.js';
+export type { InternalLinkMap } from './url-rewrite.js';
 export type * from './section-spec.js';
 export type { TemplatePlan } from './template-plan.js';
 export type * from './types.js';
diff --git a/packages/blocks-engine/src/theme/injection-scan.ts b/packages/blocks-engine/src/theme/injection-scan.ts
new file mode 100644
index 00000000..fe09a4ba
--- /dev/null
+++ b/packages/blocks-engine/src/theme/injection-scan.ts
@@ -0,0 +1,4 @@
+export function scanForInjection(markup: string): string[] {
+  void markup;
+  return [];
+}
diff --git a/packages/blocks-engine/src/theme/url-rewrite.ts b/packages/blocks-engine/src/theme/url-rewrite.ts
new file mode 100644
index 00000000..9b805895
--- /dev/null
+++ b/packages/blocks-engine/src/theme/url-rewrite.ts
@@ -0,0 +1,21 @@
+export type InternalLinkMap = Map<string, string>;
+
+export function rewriteMediaUrls(
+  input: string,
+  mapping: Map<string, string>,
+  opts: { onMissing?: (sourceUrl: string) => void } = {},
+): string {
+  void mapping;
+  void opts;
+  return input;
+}
+
+export function rewriteInternalLinks(
+  input: string,
+  map: InternalLinkMap,
+  opts: { onMissing?: (href: string) => void } = {},
+): string {
+  void map;
+  void opts;
+  return input;
+}

From 1f10947c7b5eec770a6201634deffa4df878ec35 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 19:42:57 -0400
Subject: [PATCH 061/113] Add html fallback parity helpers

---
 .../theme-html-fallback-surface.test.ts       | 148 +++++++++++++
 .../blocks-engine/src/theme/html-fallback.ts  |  61 ++++-
 .../blocks-engine/src/theme/injection-scan.ts |  16 +-
 .../blocks-engine/src/theme/url-rewrite.ts    | 208 +++++++++++++++++-
 4 files changed, 420 insertions(+), 13 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/theme-html-fallback-surface.test.ts b/packages/blocks-engine/src/__tests__/theme-html-fallback-surface.test.ts
index 71368280..5663558c 100644
--- a/packages/blocks-engine/src/__tests__/theme-html-fallback-surface.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-html-fallback-surface.test.ts
@@ -12,6 +12,10 @@ import {
   type IslandTier,
 } from '../theme/index.js';
 
+const COVERAGE_ISLAND_OPENER =
+  '<!-- wp:html {"metadata":{"name":"lib-coverage-island"}} -->';
+const COVERAGE_ISLAND_CLOSER = '<!-- /wp:html -->';
+
 describe('theme html fallback public surface', () => {
   it('freezes the additive A3 named exports', () => {
     const linkMap: InternalLinkMap = new Map([['/about', '/about/']]);
@@ -27,4 +31,148 @@ describe('theme html fallback public surface', () => {
     expect(linkMap.get('/about')).toBe('/about/');
     expect(['responsive', 'styled', 'verbatim']).toContain(tier);
   });
+
+  it('sanitizes active content while preserving inert source markup', () => {
+    const dirty =
+      '<section onclick="evil()" data-ok="1"><script>alert("x")</script><style>.x{color:red}</style><?php echo "x"; ?><? short ?><!-- wp:paragraph --><img src="hero.jpg" onerror=\'boom()\' onload=init alt="Hero"><a href="/shop" onmouseover="track()">Shop</a><p>Keep</p></section>';
+
+    expect(sanitize(dirty)).toBe(
+      '<section data-ok="1"><img src="hero.jpg" alt="Hero"><a href="/shop">Shop</a><p>Keep</p></section>',
+    );
+  });
+
+  it('classifies WordPress layout markup by the DLA marker set', () => {
+    expect(
+      [
+        '<section class="is-layout-constrained"></section>',
+        '<div class="is-layout-flow"></div>',
+        '<nav class="is-layout-flex"></nav>',
+        '<div class="wp-block-group"></div>',
+        '<main class="has-global-padding"></main>',
+      ].map(isWpLayoutMarkup),
+    ).toEqual([true, true, true, true, true]);
+
+    expect(
+      [
+        '<section class="wixui-section"></section>',
+        '<div class="sqs-layout"></div>',
+        '<main class="has-padding-global"></main>',
+      ].map(isWpLayoutMarkup),
+    ).toEqual([false, false, false]);
+  });
+
+  it('selects responsive, styled, and verbatim island tiers with concrete sources', () => {
+    expect(
+      selectIslandSource({
+        sectionHtml: '<section class="wp-block-group is-layout-constrained"><p>Responsive</p></section>',
+        styledHtml: '<section style="width:1440px"><p>Styled</p></section>',
+      }),
+    ).toEqual({
+      source: '<section class="wp-block-group is-layout-constrained"><p>Responsive</p></section>',
+      tier: 'responsive',
+    });
+
+    expect(
+      selectIslandSource({
+        sectionHtml: '<section class="wixui-section"><p>Source</p></section>',
+        styledHtml: '<section style="width:1440px"><p>Styled</p></section>',
+      }),
+    ).toEqual({
+      source: '<section style="width:1440px"><p>Styled</p></section>',
+      tier: 'styled',
+    });
+
+    expect(
+      selectIslandSource({
+        sectionHtml: '<section class="sqs-layout"><p>Verbatim</p></section>',
+      }),
+    ).toEqual({
+      source: '<section class="sqs-layout"><p>Verbatim</p></section>',
+      tier: 'verbatim',
+    });
+  });
+
+  it('builds a sanitized core/html island with media and internal links rewritten', () => {
+    const wixBase = 'https://static.wixstatic.com/media/abc123~mv2.jpg';
+    const wixSmall =
+      `${wixBase}/v1/fill/w_340,h_255,q_90,enc_avif,quality_auto/Studio%20Hero.jpg`;
+    const wixLarge =
+      `${wixBase}/v1/fill/w_680,h_510,q_90,enc_avif,quality_auto/Studio%20Hero.jpg`;
+    const localMedia = '/wp-content/uploads/2026/06/studio-hero.jpg';
+    const sectionHtml =
+      `<section onclick="evil()" class="hero"><script>alert(1)</script><style>.hero{color:red}</style><!-- wp:paragraph --><img src="${wixLarge}" srcset="${wixSmall} 340w, ${wixLarge} 680w" alt="Studio"><a href="https://Example.test/About.html#team">About</a><a href="/contact?ref=nav#hours">Contact</a><p>Keep</p></section>`;
+    const linkMap: InternalLinkMap = new Map([
+      ['example.test/about', '/about/'],
+      ['/contact', '/contact/'],
+    ]);
+
+    expect(
+      buildHtmlFallbackBlock(sectionHtml, {
+        mediaUrlMap: new Map([[wixBase, localMedia]]),
+        linkMap,
+      }),
+    ).toBe(
+      `${COVERAGE_ISLAND_OPENER}\n<section class="hero"><img src="${localMedia}" srcset="${localMedia} 340w, ${localMedia} 680w" alt="Studio"><a href="/about/#team">About</a><a href="/contact/#hours">Contact</a><p>Keep</p></section>\n${COVERAGE_ISLAND_CLOSER}`,
+    );
+  });
+
+  it('throws when sanitization leaves a quote-adjacent event handler', () => {
+    expect(() => buildHtmlFallbackBlock('<img src="x"onerror="alert(1)">')).toThrowError(
+      'html-fallback sanitization left injection vectors: inline event handler attribute (on*=) in markup (not allowed)',
+    );
+  });
+
+  it('rewrites Wix media transforms longest-first without leaving transform tails', () => {
+    const wixBase = 'https://static.wixstatic.com/media/11062b_abcd~mv2.jpg';
+    const wixSmall =
+      `${wixBase}/v1/fill/w_340,h_255,q_90,enc_avif,quality_auto/Cornelius%20Holmes%20(1).jpg`;
+    const wixLarge =
+      `${wixBase}/v1/fill/w_680,h_510,q_90,enc_avif,quality_auto/Cornelius%20Holmes%20(1).jpg`;
+    const localMedia = '/wp-content/uploads/2026/06/cornelius-holmes.jpg';
+    const input =
+      `<img src="${wixLarge}" srcset="${wixSmall} 340w, ${wixLarge} 680w"><a href="${wixBase}">Download</a>`;
+
+    expect(rewriteMediaUrls(input, new Map([[wixBase, localMedia]]))).toBe(
+      `<img src="${localMedia}" srcset="${localMedia} 340w, ${localMedia} 680w"><a href="${localMedia}">Download</a>`,
+    );
+  });
+
+  it('rewrites internal hrefs with DLA path, host, fragment, and quote semantics', () => {
+    const missed: string[] = [];
+    const linkMap: InternalLinkMap = new Map([
+      ['example.test/contact', '/contact/'],
+      ['/about', '/about/'],
+      ['/pricing', '/plans/'],
+      ['/docs/get-started', '/guides/start/'],
+    ]);
+    const input =
+      '<a href="https://www.Example.test/contact.html?utm=1#team">Contact</a><a href=\'/about/?x=1#story\'>About</a><a href="./pricing.html">Pricing</a><a href="../docs/get-started.htm#install">Docs</a><a href="https://other.test/about.html#x">Other</a><a href="#top">Top</a><a href="mailto:hi@example.test">Mail</a><a href="/missing">Missing</a>';
+
+    expect(
+      rewriteInternalLinks(input, linkMap, {
+        onMissing: (href) => missed.push(href),
+      }),
+    ).toBe(
+      '<a href="/contact/#team">Contact</a><a href=\'/about/#story\'>About</a><a href="/plans/">Pricing</a><a href="/guides/start/#install">Docs</a><a href="https://other.test/about.html#x">Other</a><a href="#top">Top</a><a href="mailto:hi@example.test">Mail</a><a href="/missing">Missing</a>',
+    );
+    expect(missed).toEqual(['/missing']);
+  });
+
+  it('reports DLA injection vectors and allows sanctioned theme PHP forms', () => {
+    expect(
+      scanForInjection(
+        '<?php echo "bad"; ?><script>run()</script><img src="x"onerror="alert(1)">',
+      ),
+    ).toEqual([
+      'raw PHP tag in markup (only the pattern-header doc-comment and esc_url(get_theme_file_uri()) are allowed)',
+      'raw <script> tag in markup (not allowed)',
+      'inline event handler attribute (on*=) in markup (not allowed)',
+    ]);
+
+    expect(
+      scanForInjection(
+        "<?php echo esc_url( get_theme_file_uri( 'assets/logo.png' ) ); ?><?php /**\n * Title: Safe Pattern\n */ ?>",
+      ),
+    ).toEqual([]);
+  });
 });
diff --git a/packages/blocks-engine/src/theme/html-fallback.ts b/packages/blocks-engine/src/theme/html-fallback.ts
index c2291483..87a4f80c 100644
--- a/packages/blocks-engine/src/theme/html-fallback.ts
+++ b/packages/blocks-engine/src/theme/html-fallback.ts
@@ -2,7 +2,8 @@ import { PIPELINE_ISLAND_OPENER } from '../block-policy.js';
 import { escapeHtmlAttr, escapeHtmlText } from '../escape.js';
 import type { SectionSpec } from './section-spec.js';
 import type { SectionSpecButton, SectionSpecImage } from './section-spec.js';
-import type { InternalLinkMap } from './url-rewrite.js';
+import { scanForInjection } from './injection-scan.js';
+import { rewriteInternalLinks, rewriteMediaUrls, type InternalLinkMap } from './url-rewrite.js';
 
 export interface HtmlFallbackOpts {
   mediaUrlMap?: Map<string, string>;
@@ -11,26 +12,76 @@ export interface HtmlFallbackOpts {
 
 export type IslandTier = 'responsive' | 'styled' | 'verbatim';
 
+/** Remove script/style/comment blocks, inline event handlers, and PHP tags. */
 export function sanitize(html: string): string {
-  return html;
+  return html
+    // Paired script/style including their contents.
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script\s*>/gi, '')
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style\s*>/gi, '')
+    // Any residual/unclosed script/style tags.
+    .replace(/<\/?(?:script|style)\b[^>]*>/gi, '')
+    // PHP (incl. short tags) — no <?php may survive the injection gate.
+    .replace(/<\?[\s\S]*?\?>/g, '')
+    .replace(/<\?/g, '')
+    // HTML comments — strips noise AND any literal `<!-- wp:… -->` lookalikes
+    // that would otherwise break block parsing of the surrounding markup.
+    .replace(/<!--[\s\S]*?-->/g, '')
+    // Inline event handlers (onclick/onerror/onload/…), quoted or bare.
+    .replace(/\son[a-z]+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, '');
 }
 
+const WP_LAYOUT_MARKER = /(?:is-layout-(?:constrained|flow|flex)|wp-block-|has-global-padding)/;
+
+/** True when the markup carries WP-layout classes the replica block theme styles
+ *  responsively (`is-layout-*`, `wp-block-*`, `has-global-padding`). Used to pick
+ *  the responsive `sectionHtml` snapshot over the frozen `styledHtml` for WP
+ *  sources, so the island reflows via the theme's CSS instead of captured pixels. */
 export function isWpLayoutMarkup(html: string): boolean {
-  return html.length > 0 && false;
+  return WP_LAYOUT_MARKER.test(html);
 }
 
+/** Choose which captured snapshot the core/html island should use, and classify
+ *  the result. WP-native sections (the replica block theme styles their classes)
+ *  use the clean, responsive `sectionHtml`; otherwise the `styledHtml` snapshot
+ *  (computed dims inlined) is load-bearing; with no styled snapshot, the bare
+ *  `sectionHtml` is the verbatim floor. Pure — no I/O. */
 export function selectIslandSource(
   section: { sectionHtml?: string; styledHtml?: string },
 ): { source: string; tier: IslandTier } {
+  if (section.sectionHtml && isWpLayoutMarkup(section.sectionHtml)) {
+    return { source: section.sectionHtml ?? section.styledHtml ?? '', tier: 'responsive' };
+  }
+  if (section.styledHtml) return { source: section.styledHtml, tier: 'styled' };
   return { source: section.sectionHtml ?? section.styledHtml ?? '', tier: 'verbatim' };
 }
 
+/**
+ * Build a sanitized, URL-rewritten `core/html` block from a section's source
+ * outerHTML. Throws if sanitization left any injection vector (defensive — a bad
+ * island must never silently ship past the gate).
+ *
+ * The opening delimiter carries the PIPELINE_ISLAND_OPENER marker
+ * (`metadata.name = "lib-coverage-island"`): install-time validation
+ * (validateReplicaInputs) rejects hand-authored wp:html in theme files but
+ * accepts pipeline-emitted coverage islands by this marker, so a
+ * previously-reconstructed theme can be reinstalled. The marker is markup-only
+ * (a WP-supported block attribute) — it also labels the island in the editor
+ * List View.
+ */
 export function buildHtmlFallbackBlock(
   sectionHtml: string,
   opts: HtmlFallbackOpts = {},
 ): string {
-  void opts;
-  return `${PIPELINE_ISLAND_OPENER}\n${sectionHtml.trim()}\n<!-- /wp:html -->`;
+  let inner = sanitize(sectionHtml);
+  if (opts.mediaUrlMap && opts.mediaUrlMap.size > 0) inner = rewriteMediaUrls(inner, opts.mediaUrlMap);
+  if (opts.linkMap && opts.linkMap.size > 0) inner = rewriteInternalLinks(inner, opts.linkMap);
+
+  const violations = scanForInjection(inner);
+  if (violations.length > 0) {
+    throw new Error(`html-fallback sanitization left injection vectors: ${violations.join('; ')}`);
+  }
+
+  return `${PIPELINE_ISLAND_OPENER}\n${inner.trim()}\n<!-- /wp:html -->`;
 }
 
 function nonEmpty(value: string | null | undefined): string | null {
diff --git a/packages/blocks-engine/src/theme/injection-scan.ts b/packages/blocks-engine/src/theme/injection-scan.ts
index fe09a4ba..e5d381f3 100644
--- a/packages/blocks-engine/src/theme/injection-scan.ts
+++ b/packages/blocks-engine/src/theme/injection-scan.ts
@@ -1,4 +1,16 @@
 export function scanForInjection(markup: string): string[] {
-  void markup;
-  return [];
+  const violations: string[] = [];
+  const SANCTIONED_PHP = /<\?php\s+echo\s+esc_url\(\s*get_theme_file_uri\(\s*'[^']+'\s*\)\s*\);\s*\?>/gi;
+  const SANCTIONED_HEADER = /<\?php\s*\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*\?>/g;
+  const residualPhp = markup.replace(SANCTIONED_PHP, '').replace(SANCTIONED_HEADER, '');
+  if (/<\?/.test(residualPhp)) {
+    violations.push('raw PHP tag in markup (only the pattern-header doc-comment and esc_url(get_theme_file_uri()) are allowed)');
+  }
+  if (/<\s*script/i.test(markup)) {
+    violations.push('raw <script> tag in markup (not allowed)');
+  }
+  if (/[\s"'/]on[a-z]+\s*=/i.test(markup)) {
+    violations.push('inline event handler attribute (on*=) in markup (not allowed)');
+  }
+  return violations;
 }
diff --git a/packages/blocks-engine/src/theme/url-rewrite.ts b/packages/blocks-engine/src/theme/url-rewrite.ts
index 9b805895..f0fc6677 100644
--- a/packages/blocks-engine/src/theme/url-rewrite.ts
+++ b/packages/blocks-engine/src/theme/url-rewrite.ts
@@ -5,9 +5,192 @@ export function rewriteMediaUrls(
   mapping: Map<string, string>,
   opts: { onMissing?: (sourceUrl: string) => void } = {},
 ): string {
-  void mapping;
-  void opts;
-  return input;
+  if (!input || mapping.size === 0) return input;
+
+  const aliasIndex = buildMediaAliasIndex(mapping);
+  const replacements = new Map(mapping);
+  const seen = new Set<string>();
+  const candidates = collectMediaCandidates(input);
+  for (const candidate of candidates) {
+    if (seen.has(candidate)) continue;
+    seen.add(candidate);
+
+    const local = resolveLocalUrl(candidate, mapping, aliasIndex);
+    if (local) {
+      replacements.set(candidate, local);
+    } else if (opts.onMissing) {
+      opts.onMissing(candidate);
+    }
+  }
+
+  let out = input;
+  const ordered = [...replacements.entries()]
+    .filter(([source]) => source)
+    .sort((a, b) => b[0].length - a[0].length);
+  for (const [source, local] of ordered) {
+    out = out.replace(new RegExp(escapeRegex(source), 'g'), () => local);
+  }
+
+  return out;
+}
+
+const URL_LIKE = /https?:\/\/[^\s"'<>\\]+/g;
+
+function collectMediaCandidates(input: string): string[] {
+  const candidates: string[] = [];
+  const attrPatterns: RegExp[] = [
+    /<img[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi,
+    /<a[^>]*\bhref\s*=\s*["']([^"']+\.(?:jpe?g|png|gif|webp|svg|avif|mp4|webm|pdf))["']/gi,
+    /\bsrcset\s*=\s*["']([^"']+)["']/gi,
+    /"src"\s*:\s*"([^"]+)"/g,
+    /"url"\s*:\s*"([^"]+)"/g,
+  ];
+  for (const re of attrPatterns) {
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(input)) !== null) {
+      const value = m[1];
+      if (re.source.includes('srcset')) {
+        let urlMatch: RegExpExecArray | null;
+        const urlRe = new RegExp(URL_LIKE.source, 'g');
+        while ((urlMatch = urlRe.exec(value)) !== null) {
+          candidates.push(urlMatch[0]);
+        }
+      } else {
+        candidates.push(value);
+      }
+    }
+  }
+
+  return candidates
+    .map((c) => c.match(URL_LIKE)?.[0] ?? c)
+    .filter((c) => /^https?:\/\//i.test(c));
+}
+
+interface MediaAliasRecord {
+  local: string;
+  score: number;
+}
+
+function buildMediaAliasIndex(mapping: Map<string, string>): Map<string, MediaAliasRecord> {
+  const out = new Map<string, MediaAliasRecord>();
+  for (const [source, local] of mapping.entries()) {
+    const score = mediaVariantScore(source);
+    for (const key of mediaAliasKeys(source)) {
+      const existing = out.get(key);
+      if (!existing || score > existing.score) {
+        out.set(key, { local, score });
+      }
+    }
+  }
+  return out;
+}
+
+function resolveLocalUrl(
+  source: string,
+  mapping: Map<string, string>,
+  aliasIndex: Map<string, MediaAliasRecord>,
+): string | undefined {
+  const exact = mapping.get(source);
+  if (exact) return exact;
+
+  for (const key of mediaAliasKeys(source)) {
+    const aliased = aliasIndex.get(key);
+    if (aliased) return aliased.local;
+  }
+
+  return undefined;
+}
+
+function mediaAliasKeys(source: string): string[] {
+  const keys: string[] = [];
+  const parsed = parseHttpUrl(source);
+  if (!parsed) return keys;
+
+  if (parsed.hostname === 'static.wixstatic.com') {
+    const asset = wixMediaAssetId(parsed);
+    if (asset) keys.push(`wix:${asset}`);
+  }
+
+  return keys;
+}
+
+function wixMediaAssetId(url: URL): string | undefined {
+  const parts = url.pathname.split('/').filter(Boolean);
+  const mediaIndex = parts.indexOf('media');
+  if (mediaIndex === -1 || mediaIndex + 1 >= parts.length) return undefined;
+  return decodeURIComponent(parts[mediaIndex + 1]);
+}
+
+function mediaVariantScore(source: string): number {
+  const match = source.match(/\bw_(\d+),h_(\d+)/i);
+  if (!match) return 0;
+  return Number(match[1]) * Number(match[2]);
+}
+
+function parseHttpUrl(source: string): URL | undefined {
+  try {
+    const parsed = new URL(source);
+    if (!/^https?:$/i.test(parsed.protocol)) return undefined;
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+function escapeRegex(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+const SKIP_SCHEME = /^(?:mailto:|tel:|javascript:|data:|sms:|geo:|callto:)/i;
+
+interface Candidate {
+  key: string | null;
+  fragment: string;
+  internalRelative: boolean;
+}
+
+function normalizePath(pathname: string): string {
+  let p = pathname;
+  try {
+    p = decodeURIComponent(p);
+  } catch {
+    // Leave malformed percent sequences as-is.
+  }
+  p = p.replace(/\.html?$/i, '');
+  if (!p.startsWith('/')) p = '/' + p;
+  if (p !== '/') p = p.replace(/\/+$/, '');
+  if (p === '') p = '/';
+  return p.toLowerCase();
+}
+
+function normalizeHost(host: string): string {
+  return host.toLowerCase().replace(/^www\./, '');
+}
+
+function analyzeHref(rawHref: string): Candidate {
+  const href = rawHref.trim();
+  const none: Candidate = { key: null, fragment: '', internalRelative: false };
+  if (!href || SKIP_SCHEME.test(href)) return none;
+  if (href.startsWith('#')) return none;
+
+  if (/^https?:\/\//i.test(href) || href.startsWith('//')) {
+    let url: URL;
+    try {
+      url = new URL(href.startsWith('//') ? `https:${href}` : href);
+    } catch {
+      return none;
+    }
+    const key = `${normalizeHost(url.hostname)}${normalizePath(url.pathname)}`;
+    return { key, fragment: url.hash, internalRelative: false };
+  }
+
+  const hashIdx = href.indexOf('#');
+  const fragment = hashIdx >= 0 ? href.slice(hashIdx) : '';
+  let pathPart = hashIdx >= 0 ? href.slice(0, hashIdx) : href;
+  const queryIdx = pathPart.indexOf('?');
+  if (queryIdx >= 0) pathPart = pathPart.slice(0, queryIdx);
+  pathPart = pathPart.replace(/^(?:\.\.?\/)+/, '');
+  return { key: normalizePath(pathPart), fragment, internalRelative: true };
 }
 
 export function rewriteInternalLinks(
@@ -15,7 +198,20 @@ export function rewriteInternalLinks(
   map: InternalLinkMap,
   opts: { onMissing?: (href: string) => void } = {},
 ): string {
-  void map;
-  void opts;
-  return input;
+  if (!input || map.size === 0) return input;
+
+  const warned = new Set<string>();
+  return input.replace(/\bhref\s*=\s*(["'])([^"']*)\1/gi, (whole, quote: string, value: string) => {
+    const { key, fragment, internalRelative } = analyzeHref(value);
+    if (key === null) return whole;
+    const target = map.get(key);
+    if (target) {
+      return `href=${quote}${target}${fragment}${quote}`;
+    }
+    if (internalRelative && opts.onMissing && !warned.has(value)) {
+      warned.add(value);
+      opts.onMissing(value);
+    }
+    return whole;
+  });
 }

From 046c9802328b000520a5e35c108d6bad8961a436 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 19:50:46 -0400
Subject: [PATCH 062/113] Freeze source assets parity surface

---
 packages/blocks-engine/src/theme/index.ts     |   8 +
 .../blocks-engine/src/theme/source-assets.ts  | 423 ++++++++++++++++++
 2 files changed, 431 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/source-assets.ts

diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 538692b8..b5e0cf67 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -20,6 +20,13 @@ export {
   sanitize,
   selectIslandSource,
 } from './html-fallback.js';
+export {
+  collectHtmlImages,
+  collectSourceAssets,
+  localizeCssImages,
+  rewriteHtmlImageSrcs,
+  WP_COMPAT_CSS,
+} from './source-assets.js';
 export {
   captureSectionContent,
   foldText,
@@ -44,6 +51,7 @@ export type { CapturedSectionContent, CoverageResult } from './section-coverage.
 export type * from './font-faces.js';
 export type { InternalLinkMap } from './url-rewrite.js';
 export type * from './section-spec.js';
+export type * from './source-assets.js';
 export type { TemplatePlan } from './template-plan.js';
 export type * from './types.js';
 export type { ThemeJsonLintResult } from './theme-json-lint.js';
diff --git a/packages/blocks-engine/src/theme/source-assets.ts b/packages/blocks-engine/src/theme/source-assets.ts
new file mode 100644
index 00000000..dcac9dec
--- /dev/null
+++ b/packages/blocks-engine/src/theme/source-assets.ts
@@ -0,0 +1,423 @@
+// src/lib/replicate/local-theme/source-assets.ts
+//
+// Stage 1d: carry the SOURCE site's CSS/JS into the theme so the
+// class-preserving block DOM (emit-blocks className/anchor) renders under the
+// designer's own stylesheet — the path to ~100% parity. We OWN the source, so
+// divergences are fixed by deterministic adaptation here, not approximation:
+//   - Google-Fonts @import/link CSS is stripped (faces are already self-hosted
+//     by google-fonts.ts under the same family names).
+//   - A small WP-compat layer is PREPENDED (lowest precedence) neutralizing
+//     WP wrapper interference (template-part div, root layout padding).
+// JS is carried verbatim (user decision: identical replication; the spec's
+// off-by-default hatch is deliberately ON for this flow) — functions.php adds
+// the html.js class snippet so source reveal-gates behave as authored.
+//
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, posix } from 'node:path';
+
+/** Neutralize WP-injected wrappers so source layout selectors keep working.
+ * Prepended (lowest precedence) — source rules always win over it. */
+export const WP_COMPAT_CSS = `/* wp-compat: neutralize WP wrapper interference for carried source CSS */
+/* NOTE deliberately NO .wp-block-template-part{display:contents} here: our
+   parts use tagName header/footer, so the wrapper IS the semantic element —
+   display:contents would destroy the box that source header{}/footer{} rules
+   lay out (class specificity beats the element selector regardless of order).
+   NOTE also deliberately NO blanket child-margin zeroing: the source relies on
+   browser-default element margins (p, h1-h6, ul) — zeroing layout children
+   collapsed the source's vertical rhythm. Blocks render as the same semantic
+   elements, so the defaults already match. */
+:where(body) { margin: 0; }
+/* WP renders site-title as a <p> (default margins the source brand <a> never
+   had) and wraps tables in a margined <figure>. Zero-spec so source rules win.
+   The table figure is emitted CLASSLESS (block-library's .wp-block-table
+   td/th rules would out-rank source element rules), so target it via :has. */
+:where(.wp-block-site-title) { margin: 0; }
+:where(figure:has(> table)) { margin: 0; }
+/* Structural transparency for core/navigation: the source styles nav > a
+   directly, while WP renders nav > ul > li > a. Collapsing the list boxes
+   makes the anchors direct flex items of <nav>, so the source nav rules
+   (display/gap/wrap/justify) drive the exact same geometry. Class-level
+   specificity is required — block-library sets display:flex on these at
+   (0,1,0)+ and a zero-spec :where loses (probe: anchors stayed inside the
+   ul, justify-content flex-start left-packed the rows). Safe: source
+   stylesheets never target wp-* classes. */
+nav.wp-block-navigation ul, nav.wp-block-navigation li { display: contents; }
+/* WP sets .wp-block-post-content{display:flow-root}, which BLOCKS the
+   margin collapse the source layout relies on (last section margin-bottom
+   collapsing with the footer margin-top — walrus probe: footer sat 88px
+   lower). Class-level specificity is required to beat WP's own class rule;
+   safe because no source stylesheet targets a wp-* class. */
+.wp-block-post-content { display: block; }
+/* core/button renders TWO boxes: the source button class lands on the
+   .wp-block-button WRAPPER (core/button stores className there; the fixer
+   strips it off the inner link), so the carried .btn/.btn-* rules style the
+   wrapper pill — while the inner .wp-block-button__link still carries BOTH WP's
+   default button chrome (fill bg + padding + radius) AND the carried source
+   button class the emitter writes onto the link (a .btn box-shadow of 6px 6px 0
+   ink casts a hard offset shadow behind the label — the double-border bug). Strip the
+   inner link's whole box (incl. box-shadow) so the carried wrapper style renders
+   once. The lib-cta marker (emit-blocks) scopes this to carried
+   buttons so genuine native core/button blocks keep their chrome; class-level
+   specificity beats WP's :where()/global-styles button defaults, and source
+   stylesheets never target wp-* classes. */
+.wp-block-button.lib-cta > .wp-block-button__link {
+  background: transparent;
+  border: 0;
+  box-shadow: none;
+  padding: 0;
+  border-radius: inherit;
+  color: inherit;
+  text-decoration: none;
+}
+`;
+
+const GOOGLE_IMPORT_RE = /@import\s+url\(\s*['"]?https:\/\/fonts\.googleapis\.com[^)]*\)\s*;?/g;
+
+/** Image url() targets we localize. Fonts (woff2/woff/ttf/otf/eot) are owned by
+ * the font pipeline (google-fonts.ts / @font-face self-host) and deliberately
+ * NOT touched here — they already resolve via the assets/fonts/ structural
+ * parallel. Data URIs and remote URLs are left verbatim. */
+const IMAGE_EXT_RE = /\.(jpe?g|png|gif|webp|avif|svg|bmp|ico)$/i;
+/** Conservative url() matcher: optional matching quote, no embedded ')' — so a
+ * data: URI with internal parens (the SVG-noise filter) never matches as a
+ * whole and is left verbatim. */
+const CSS_URL_RE = /url\(\s*(['"]?)([^'")]+)\1\s*\)/gi;
+
+/** One source image referenced from carried CSS that must be copied into the
+ * theme so its rewritten relative url() resolves. */
+export interface MediaAsset {
+  /** Absolute path to the source file on disk. */
+  srcAbs: string;
+  /** Theme-relative destination (e.g. assets/css/media/plate.jpg) — sits next
+   * to the carried source.css so the rewritten `url(media/<name>)` resolves. */
+  themeRel: string;
+}
+
+/** One HTML <img src> reference carried from a source page into the theme. */
+export interface ImgAssetRef {
+  /** Exact src string as authored in the page HTML (e.g. "assets/logo.svg"). */
+  ref: string;
+  /** Theme-relative destination the file was copied to (e.g. assets/img/logo.svg). */
+  themeRel: string;
+}
+
+export interface SourceAssets {
+  /** Compat layer + all source CSS (linked files in DOCUMENT order, then unlinked top-level fallback, then inline <style> blocks). */
+  css: string;
+  /** All source JS concatenated (linked scripts in DOCUMENT order, then unlinked top-level fallback). */
+  js: string;
+  /** Relative paths (subdir-aware) in concatenation order. */
+  cssFiles: string[];
+  jsFiles: string[];
+  /** Top-level files SKIPPED because linked assets exist (stale-revision
+   * protection — see the pass-2 comment). Surface as a warning upstream. */
+  skippedUnlinked: string[];
+  /** Image files referenced via CSS url() that the handler must copy into the
+   * theme (the css urls are already rewritten to point at them). */
+  mediaAssets: MediaAsset[];
+  /** Image files referenced via HTML <img src> that the handler must copy into
+   * the theme. Unlike CSS images these are NOT pre-rewritten (post_content has
+   * no carried-stylesheet anchor) — the handler repoints each <img> using the
+   * per-page rewrite list below. */
+  imgAssets: MediaAsset[];
+  /** Per source page (keyed by relPath): the exact <img src> ref strings found
+   * and the theme-relative path each was carried to, for the handler's rewrite. */
+  imgRewritesByPage: Record<string, ImgAssetRef[]>;
+}
+
+/** Theme subdir (relative to assets/css/source.css) holding carried CSS images. */
+const MEDIA_SUBDIR = 'media';
+
+/**
+ * Rewrite relative image url() refs in each CSS part to point at a flat media/
+ * dir beside the carried stylesheet, returning the source→theme copy list.
+ * Pure except for existsSync (a ref to a missing file is left verbatim — we
+ * never fabricate an asset). url()s are resolved per the part's SOURCE dir
+ * (a relative img/ means different files in assets/site.css vs a root inline
+ * style), then flattened to a single basename (collision-suffixed) so one
+ * predictable media/ dir holds them all. Fonts, data URIs, and remote URLs
+ * are untouched.
+ */
+export function localizeCssImages(
+  parts: Array<{ css: string; baseDir: string }>,
+  dir: string,
+): { parts: string[]; mediaAssets: MediaAsset[] } {
+  const bySrc = new Map<string, string>(); // srcAbs → assigned basename
+  const usedNames = new Set<string>();
+  const mediaAssets: MediaAsset[] = [];
+
+  const assign = (srcAbs: string, rawName: string): string => {
+    const existing = bySrc.get(srcAbs);
+    if (existing) return existing;
+    let name = rawName;
+    if (usedNames.has(name)) {
+      const dot = name.lastIndexOf('.');
+      const stem = dot > 0 ? name.slice(0, dot) : name;
+      const ext = dot > 0 ? name.slice(dot) : '';
+      let n = 2;
+      while (usedNames.has(`${stem}-${n}${ext}`)) n++;
+      name = `${stem}-${n}${ext}`;
+    }
+    usedNames.add(name);
+    bySrc.set(srcAbs, name);
+    mediaAssets.push({ srcAbs, themeRel: `assets/css/${MEDIA_SUBDIR}/${name}` });
+    return name;
+  };
+
+  const outParts = parts.map(({ css, baseDir }) =>
+    css.replace(CSS_URL_RE, (whole, _q: string, raw: string) => {
+      if (/^(https?:)?\/\//i.test(raw) || raw.startsWith('data:') || raw.startsWith('#')) return whole;
+      const cleaned = raw.split(/[?#]/)[0];
+      if (!IMAGE_EXT_RE.test(cleaned)) return whole; // fonts + non-image left verbatim
+      // Resolve relative to the part's source dir; leading-slash = site root.
+      const within = cleaned.startsWith('/')
+        ? posix.normalize(cleaned.slice(1))
+        : posix.normalize(posix.join(baseDir, cleaned));
+      if (within.startsWith('..')) return whole; // never escape the source root
+      const srcAbs = join(dir, within);
+      if (!existsSync(srcAbs)) return whole; // missing → leave as authored
+      const name = assign(srcAbs, posix.basename(within));
+      return `url(${MEDIA_SUBDIR}/${name})`;
+    }),
+  );
+  return { parts: outParts, mediaAssets };
+}
+
+/** Inline <script> bodies are carried into the concatenated bundle ONLY when
+ * they are executable JS — type absent/empty, a JS MIME, or `module`. Data
+ * blocks (`application/ld+json` SEO, `application/json`, `importmap`,
+ * `speculationrules`, `text/*` microtemplates) are NOT JS: concatenating one
+ * injects a parse-time SyntaxError that aborts the ENTIRE bundle (the per-chunk
+ * try/catch catches RUNTIME throws only, never parse errors), silently killing
+ * every carried behavior — reveal, nav, accordions. So they are skipped. */
+const EXECUTABLE_INLINE_JS_TYPES = new Set([
+  'text/javascript',
+  'application/javascript',
+  'application/x-javascript',
+  'text/ecmascript',
+  'application/ecmascript',
+  'module',
+]);
+function isExecutableInlineScript(openTagAttrs: string): boolean {
+  const m = openTagAttrs.match(/\btype\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i);
+  if (!m) return true; // no type attribute → classic JS
+  const type = (m[1] ?? m[2] ?? m[3] ?? '').trim().toLowerCase();
+  if (type === '') return true; // type="" is classic JS per the HTML spec
+  return EXECUTABLE_INLINE_JS_TYPES.has(type);
+}
+
+/** Theme subdir (relative to the theme root) holding carried HTML <img> assets. */
+const IMG_SUBDIR = 'assets/img';
+
+/** Harvest LOCAL <img src> image references from each page's HTML, returning the
+ * copy-list (unique source files → a flat assets/img/<name>, collision-suffixed)
+ * and a per-page rewrite list (exact ref string → themeRel). The handler copies
+ * the files into the theme and repoints each <img src> at the theme URL — HTML
+ * <img>s, unlike CSS url()s, have no carried stylesheet to anchor a relative
+ * path against, so they need an absolute theme URL. Remote (http/protocol-
+ * relative), data:, fragment, and missing refs are left verbatim (never
+ * fabricated). */
+export function collectHtmlImages(
+  pageHtmls: Array<{ html: string; relPath: string }>,
+  dir: string,
+): { imgAssets: MediaAsset[]; rewritesByPage: Record<string, ImgAssetRef[]> } {
+  const bySrc = new Map<string, string>(); // srcAbs → assigned basename
+  const usedNames = new Set<string>();
+  const imgAssets: MediaAsset[] = [];
+  const rewritesByPage: Record<string, ImgAssetRef[]> = {};
+
+  const assign = (srcAbs: string, rawName: string): string => {
+    const existing = bySrc.get(srcAbs);
+    if (existing) return existing;
+    let name = rawName;
+    if (usedNames.has(name)) {
+      const dot = name.lastIndexOf('.');
+      const stem = dot > 0 ? name.slice(0, dot) : name;
+      const ext = dot > 0 ? name.slice(dot) : '';
+      let n = 2;
+      while (usedNames.has(`${stem}-${n}${ext}`)) n++;
+      name = `${stem}-${n}${ext}`;
+    }
+    usedNames.add(name);
+    bySrc.set(srcAbs, name);
+    imgAssets.push({ srcAbs, themeRel: `${IMG_SUBDIR}/${name}` });
+    return name;
+  };
+
+  for (const { html, relPath } of pageHtmls) {
+    const baseDir = posix.dirname(relPath);
+    const seenRefs = new Set<string>();
+    const list: ImgAssetRef[] = [];
+    // `\ssrc` (whitespace-anchored) so `data-src` / `xlink:href` never match.
+    for (const m of html.matchAll(/<img\b[^>]*?\ssrc\s*=\s*(?:"([^"]+)"|'([^']+)'|([^\s>]+))/gi)) {
+      const ref = (m[1] ?? m[2] ?? m[3] ?? '').trim();
+      if (!ref || seenRefs.has(ref)) continue;
+      if (/^(?:https?:)?\/\//i.test(ref) || ref.startsWith('data:') || ref.startsWith('#')) continue;
+      const cleaned = ref.split(/[?#]/)[0];
+      const within = cleaned.startsWith('/')
+        ? posix.normalize(cleaned.slice(1))
+        : posix.normalize(posix.join(baseDir, cleaned));
+      if (within.startsWith('..')) continue; // never escape the source root
+      const srcAbs = join(dir, within);
+      if (!existsSync(srcAbs)) continue; // missing → leave as authored
+      seenRefs.add(ref);
+      const name = assign(srcAbs, posix.basename(within));
+      list.push({ ref, themeRel: `${IMG_SUBDIR}/${name}` });
+    }
+    if (list.length > 0) rewritesByPage[relPath] = list;
+  }
+  return { imgAssets, rewritesByPage };
+}
+
+/** Repoint carried <img src> refs at the theme-carried copies. Pure string
+ * replacement bounded by the surrounding quote so a path token can't match
+ * inside another attribute; safe because the refs are literal source paths. */
+export function rewriteHtmlImageSrcs(html: string, refs: ImgAssetRef[], themeSlug: string): string {
+  let out = html;
+  for (const { ref, themeRel } of refs) {
+    const themeUrl = `/wp-content/themes/${themeSlug}/${themeRel}`;
+    out = out.split(`"${ref}"`).join(`"${themeUrl}"`).split(`'${ref}'`).join(`'${themeUrl}'`);
+  }
+  return out;
+}
+
+export function collectSourceAssets(
+  dir: string,
+  pages: Array<{ relPath: string; html: string }>,
+): SourceAssets {
+  const cssFiles: string[] = [];
+  const jsFiles: string[] = [];
+  // Each CSS part carries the SOURCE dir it came from so relative image url()s
+  // resolve correctly (a bare `img/x.jpg` means assets/img/x.jpg in
+  // assets/site.css but img/x.jpg in a root inline style).
+  const cssParts: Array<{ css: string; baseDir: string }> = [];
+  const jsParts: string[] = [];
+
+  // Pass 1: linked assets in DOCUMENT order — the page's <link rel=stylesheet>
+  // / <script src> sequence IS the author's cascade; alphabetical reads would
+  // invert it (e.g. overrides.css before theme.css → wrong winner). First-seen
+  // dedup across pages keeps the earliest page's position authoritative.
+  const seenCss = new Set<string>();
+  const seenJs = new Set<string>();
+  const seenInline = new Set<string>();
+  const pageHtmls: Array<{ html: string; relPath: string }> = [];
+  for (const page of pages) {
+    const html =
+      page.html ||
+      (existsSync(join(dir, page.relPath)) ? readFileSync(join(dir, page.relPath), 'utf8') : '');
+    pageHtmls.push({ html, relPath: page.relPath });
+    for (const m of html.matchAll(/<link[^>]+rel=["']?stylesheet["']?[^>]*>/gi)) {
+      const hrefMatch = m[0].match(/href=["']([^"']+)|href=([^\s>]+)/i);
+      const href = hrefMatch?.[1] ?? hrefMatch?.[2];
+      if (!href || /^https?:\/\//i.test(href)) continue; // skip absolute CDN URLs — captured sites have local copies
+      const rel = href.replace(/^\//, '');
+      if (seenCss.has(rel)) continue;
+      seenCss.add(rel);
+      const absPath = join(dir, rel);
+      if (existsSync(absPath)) {
+        cssFiles.push(rel);
+        cssParts.push({ css: readFileSync(absPath, 'utf8'), baseDir: posix.dirname(rel) });
+      }
+    }
+    for (const m of html.matchAll(/<script[^>]+src=["']([^"']+)|<script[^>]+src=([^\s>]+)/gi)) {
+      const src = m[1] ?? m[2];
+      if (!src || /^https?:\/\//i.test(src)) continue;
+      const rel = src.replace(/^\//, '');
+      if (seenJs.has(rel)) continue;
+      seenJs.add(rel);
+      const absPath = join(dir, rel);
+      if (existsSync(absPath)) {
+        jsFiles.push(rel);
+        jsParts.push(readFileSync(absPath, 'utf8'));
+      }
+    }
+  }
+
+  // Pass 2: top-level unlinked .css/.js fallback (alphabetical, skip already
+  // linked) — catches assets the capture saved but no surviving page references.
+  // GATED per type on pass 1 finding NOTHING: when linked assets exist, an
+  // unlinked top-level file is working clutter (maison-clouet: a stale
+  // style.css revision appended AFTER the real assets/site.css won the cascade
+  // and repainted the replica with rules the source never loads). Skipped
+  // files are reported so the handler can surface them.
+  const skippedUnlinked: string[] = [];
+  // Snapshot the LINKED counts before the loop — the gate must not trip on
+  // fallback files added by this very loop (multiple unlinked files in the
+  // no-linked case all collect, as before).
+  const linkedCssCount = cssFiles.length;
+  const linkedJsCount = jsFiles.length;
+  for (const name of readdirSync(dir).sort()) {
+    if (name.endsWith('.css') && !seenCss.has(name)) {
+      if (linkedCssCount > 0) {
+        skippedUnlinked.push(name);
+        continue;
+      }
+      seenCss.add(name);
+      cssFiles.push(name);
+      cssParts.push({ css: readFileSync(join(dir, name), 'utf8'), baseDir: '.' });
+    } else if (name.endsWith('.js') && !seenJs.has(name)) {
+      if (linkedJsCount > 0) {
+        skippedUnlinked.push(name);
+        continue;
+      }
+      seenJs.add(name);
+      jsFiles.push(name);
+      jsParts.push(readFileSync(join(dir, name), 'utf8'));
+    }
+  }
+
+  // Inline <style> blocks from each page (first occurrence set, dedup by content).
+  // NOTE: a page-scoped inline style becomes GLOBAL in the carried bundle —
+  // acceptable while captured sites' inline rules are page-prefixed or
+  // idempotent; revisit if a page-specific rule leaks across pages.
+  for (const { html, relPath } of pageHtmls) {
+    for (const m of html.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) {
+      const body = m[1].trim();
+      if (body && !seenInline.has(body)) {
+        seenInline.add(body);
+        cssParts.push({ css: body, baseDir: posix.dirname(relPath) });
+      }
+    }
+  }
+
+  // Inline <script> blocks (no src) — JS-rendered sites put their MOUNT calls
+  // here (`mountGrid('#grid', …)` at body end), and dropping them leaves the
+  // carried linked libraries with nothing to invoke them (maison-clouet
+  // dogfood: grids stayed empty). Page-scoped like inline styles, so each
+  // chunk is isolated in a try/catch IIFE: a mount call whose target only
+  // exists on ONE page must not throw and kill the rest of the bundle on the
+  // others. Appended AFTER linked js (document order within a page — mounts
+  // follow the libraries they call).
+  const seenInlineJs = new Set<string>();
+  for (const { html } of pageHtmls) {
+    for (const m of html.matchAll(/<script(?![^>]*\bsrc=)([^>]*)>([\s\S]*?)<\/script>/gi)) {
+      // Skip non-JS <script> data blocks (JSON-LD, importmaps, templates): a
+      // parse error in one aborts the whole concatenated bundle.
+      if (!isExecutableInlineScript(m[1])) continue;
+      const body = m[2].trim();
+      if (body && !seenInlineJs.has(body)) {
+        seenInlineJs.add(body);
+        jsParts.push(`(function () { try {\n${body}\n} catch (e) { /* page-scoped inline chunk */ } })();`);
+      }
+    }
+  }
+
+  // Localize relative image url()s (copy list returned for the handler to carry
+  // into the theme) BEFORE concat, so each part resolves against its own source
+  // dir. Then strip Google-Fonts @imports: WP_COMPAT_CSS contains no @imports so
+  // startsWith(WP_COMPAT_CSS) is preserved; Google imports only exist in cssParts.
+  const { parts: localizedParts, mediaAssets } = localizeCssImages(cssParts, dir);
+  const css = (WP_COMPAT_CSS + localizedParts.join('\n\n')).replace(GOOGLE_IMPORT_RE, '');
+  // Carry HTML <img> assets too (content images the CSS pass never sees).
+  const { imgAssets, rewritesByPage: imgRewritesByPage } = collectHtmlImages(pageHtmls, dir);
+  return {
+    css,
+    js: jsParts.join('\n\n'),
+    cssFiles,
+    jsFiles,
+    skippedUnlinked,
+    mediaAssets,
+    imgAssets,
+    imgRewritesByPage,
+  };
+}

From e19eb580b76e0b36649b6b7103f68d152303e5b2 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 19:57:02 -0400
Subject: [PATCH 063/113] Add source assets parity tests

---
 .../theme-source-assets-parity.test.ts        | 308 ++++++++++++++++++
 1 file changed, 308 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-source-assets-parity.test.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-source-assets-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-source-assets-parity.test.ts
new file mode 100644
index 00000000..a8632186
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-source-assets-parity.test.ts
@@ -0,0 +1,308 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import * as theme from '../theme/index.js';
+import {
+  collectHtmlImages,
+  collectSourceAssets,
+  localizeCssImages,
+  rewriteHtmlImageSrcs,
+  WP_COMPAT_CSS,
+} from '../theme/index.js';
+
+const DLA_WP_COMPAT_CSS = `/* wp-compat: neutralize WP wrapper interference for carried source CSS */
+/* NOTE deliberately NO .wp-block-template-part{display:contents} here: our
+   parts use tagName header/footer, so the wrapper IS the semantic element —
+   display:contents would destroy the box that source header{}/footer{} rules
+   lay out (class specificity beats the element selector regardless of order).
+   NOTE also deliberately NO blanket child-margin zeroing: the source relies on
+   browser-default element margins (p, h1-h6, ul) — zeroing layout children
+   collapsed the source's vertical rhythm. Blocks render as the same semantic
+   elements, so the defaults already match. */
+:where(body) { margin: 0; }
+/* WP renders site-title as a <p> (default margins the source brand <a> never
+   had) and wraps tables in a margined <figure>. Zero-spec so source rules win.
+   The table figure is emitted CLASSLESS (block-library's .wp-block-table
+   td/th rules would out-rank source element rules), so target it via :has. */
+:where(.wp-block-site-title) { margin: 0; }
+:where(figure:has(> table)) { margin: 0; }
+/* Structural transparency for core/navigation: the source styles nav > a
+   directly, while WP renders nav > ul > li > a. Collapsing the list boxes
+   makes the anchors direct flex items of <nav>, so the source nav rules
+   (display/gap/wrap/justify) drive the exact same geometry. Class-level
+   specificity is required — block-library sets display:flex on these at
+   (0,1,0)+ and a zero-spec :where loses (probe: anchors stayed inside the
+   ul, justify-content flex-start left-packed the rows). Safe: source
+   stylesheets never target wp-* classes. */
+nav.wp-block-navigation ul, nav.wp-block-navigation li { display: contents; }
+/* WP sets .wp-block-post-content{display:flow-root}, which BLOCKS the
+   margin collapse the source layout relies on (last section margin-bottom
+   collapsing with the footer margin-top — walrus probe: footer sat 88px
+   lower). Class-level specificity is required to beat WP's own class rule;
+   safe because no source stylesheet targets a wp-* class. */
+.wp-block-post-content { display: block; }
+/* core/button renders TWO boxes: the source button class lands on the
+   .wp-block-button WRAPPER (core/button stores className there; the fixer
+   strips it off the inner link), so the carried .btn/.btn-* rules style the
+   wrapper pill — while the inner .wp-block-button__link still carries BOTH WP's
+   default button chrome (fill bg + padding + radius) AND the carried source
+   button class the emitter writes onto the link (a .btn box-shadow of 6px 6px 0
+   ink casts a hard offset shadow behind the label — the double-border bug). Strip the
+   inner link's whole box (incl. box-shadow) so the carried wrapper style renders
+   once. The lib-cta marker (emit-blocks) scopes this to carried
+   buttons so genuine native core/button blocks keep their chrome; class-level
+   specificity beats WP's :where()/global-styles button defaults, and source
+   stylesheets never target wp-* classes. */
+.wp-block-button.lib-cta > .wp-block-button__link {
+  background: transparent;
+  border: 0;
+  box-shadow: none;
+  padding: 0;
+  border-radius: inherit;
+  color: inherit;
+  text-decoration: none;
+}
+`;
+
+function withTempDir<T>(fn: (dir: string) => T): T {
+  const dir = mkdtempSync(join(tmpdir(), 'blocks-engine-source-assets-'));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function writeFixture(dir: string, relPath: string, contents = ''): void {
+  const abs = join(dir, relPath);
+  mkdirSync(join(abs, '..'), { recursive: true });
+  writeFileSync(abs, contents, 'utf8');
+}
+
+describe('source assets DLA parity', () => {
+  it('exposes the additive source-assets public surface from theme/index', () => {
+    expect(theme).toEqual(
+      expect.objectContaining({
+        WP_COMPAT_CSS: expect.any(String),
+        collectHtmlImages: expect.any(Function),
+        collectSourceAssets: expect.any(Function),
+        localizeCssImages: expect.any(Function),
+        rewriteHtmlImageSrcs: expect.any(Function),
+      })
+    );
+  });
+
+  it('keeps the WP compat CSS byte-for-byte equal to the DLA golden string', () => {
+    expect(WP_COMPAT_CSS).toBe(DLA_WP_COMPAT_CSS);
+  });
+
+  it('rewrites exact quoted HTML image refs globally using the theme asset URL', () => {
+    const html =
+      '<main><img src="img/logo.png"><a href="img/logo.png">Logo</a><img src=\'img/logo.png\'><span data-copy=\'img/logo.png\' data-other="icons/logo.png"></span></main>';
+
+    expect(
+      rewriteHtmlImageSrcs(
+        html,
+        [{ ref: 'img/logo.png', themeRel: 'assets/img/logo.png' }],
+        'golden-theme'
+      )
+    ).toBe(
+      '<main><img src="/wp-content/themes/golden-theme/assets/img/logo.png"><a href="/wp-content/themes/golden-theme/assets/img/logo.png">Logo</a><img src=\'/wp-content/themes/golden-theme/assets/img/logo.png\'><span data-copy=\'/wp-content/themes/golden-theme/assets/img/logo.png\' data-other="icons/logo.png"></span></main>'
+    );
+  });
+
+  it('localizes CSS image url refs and leaves data, remote, font, missing, and escaping refs untouched', () => {
+    withTempDir((dir) => {
+      writeFixture(dir, 'assets/img/hero.png');
+      writeFixture(dir, 'assets/img/icon.svg');
+      writeFixture(dir, 'assets/fonts/inter.woff2');
+      writeFixture(dir, 'root.png');
+
+      const css = [
+        '.hero { background: url("../img/hero.png"); }',
+        '.root { background: url("/root.png?v=1#hash"); }',
+        '.data { background: url(data:image/png;base64,abc123); }',
+        '.remote { background: url(https://cdn.example.com/photo.png); }',
+        '.font { src: url("../fonts/inter.woff2"); }',
+        '.missing { background: url("../img/missing.png"); }',
+        '.escape { background: url("../../../escape.png"); }',
+        '.icon { background: url("../img/icon.svg?cache=1"); }',
+      ].join('\n');
+
+      const result = localizeCssImages([{ css, baseDir: 'assets/css' }], dir);
+
+      expect(result.parts).toEqual([
+        [
+          '.hero { background: url(media/hero.png); }',
+          '.root { background: url(media/root.png); }',
+          '.data { background: url(data:image/png;base64,abc123); }',
+          '.remote { background: url(https://cdn.example.com/photo.png); }',
+          '.font { src: url("../fonts/inter.woff2"); }',
+          '.missing { background: url("../img/missing.png"); }',
+          '.escape { background: url("../../../escape.png"); }',
+          '.icon { background: url(media/icon.svg); }',
+        ].join('\n'),
+      ]);
+      expect(result.mediaAssets).toEqual([
+        {
+          srcAbs: join(dir, 'assets/img/hero.png'),
+          themeRel: 'assets/css/media/hero.png',
+        },
+        {
+          srcAbs: join(dir, 'root.png'),
+          themeRel: 'assets/css/media/root.png',
+        },
+        {
+          srcAbs: join(dir, 'assets/img/icon.svg'),
+          themeRel: 'assets/css/media/icon.svg',
+        },
+      ]);
+    });
+  });
+
+  it('collects local HTML img src refs with DLA regex and path resolution semantics', () => {
+    withTempDir((dir) => {
+      writeFixture(dir, 'pages/deep/img/double.png');
+      writeFixture(dir, 'pages/deep/img/single.jpg');
+      writeFixture(dir, 'pages/deep/img/unquoted.webp');
+      writeFixture(dir, 'root.png');
+
+      const html = [
+        '<img src="img/double.png">',
+        '<img alt="duplicate" src="img/double.png">',
+        "<img src='img/single.jpg'>",
+        '<img src=img/unquoted.webp>',
+        '<img src=/root.png>',
+        '<img data-src="img/data-src.png">',
+        '<img xlink:href="img/xlink.png">',
+        '<img src="https://cdn.example.com/remote.png">',
+        '<img src="//cdn.example.com/protocol.png">',
+        '<img src="data:image/png;base64,abc123">',
+        '<img src="#fragment">',
+        '<img src="img/missing.png">',
+        '<img src="../../../escape.png">',
+      ].join('');
+
+      const result = collectHtmlImages(
+        [{ html, relPath: 'pages/deep/index.html' }],
+        dir
+      );
+
+      expect(result.imgAssets).toEqual([
+        {
+          srcAbs: join(dir, 'pages/deep/img/double.png'),
+          themeRel: 'assets/img/double.png',
+        },
+        {
+          srcAbs: join(dir, 'pages/deep/img/single.jpg'),
+          themeRel: 'assets/img/single.jpg',
+        },
+        {
+          srcAbs: join(dir, 'pages/deep/img/unquoted.webp'),
+          themeRel: 'assets/img/unquoted.webp',
+        },
+        {
+          srcAbs: join(dir, 'root.png'),
+          themeRel: 'assets/img/root.png',
+        },
+      ]);
+      expect(result.rewritesByPage).toEqual({
+        'pages/deep/index.html': [
+          { ref: 'img/double.png', themeRel: 'assets/img/double.png' },
+          { ref: 'img/single.jpg', themeRel: 'assets/img/single.jpg' },
+          { ref: 'img/unquoted.webp', themeRel: 'assets/img/unquoted.webp' },
+          { ref: '/root.png', themeRel: 'assets/img/root.png' },
+        ],
+      });
+    });
+  });
+
+  it('collects source CSS, JS, inline code, localized images, skipped stale roots, and HTML img assets from fixtures', () => {
+    withTempDir((dir) => {
+      writeFixture(
+        dir,
+        'assets/css/base.css',
+        [
+          '@import url("https://fonts.googleapis.com/css2?family=Inter");',
+          '.base { background: url("../img/bg.png"); color: black; }',
+        ].join('\n')
+      );
+      writeFixture(dir, 'assets/css/override.css', '.base { color: white; }');
+      writeFixture(dir, 'assets/img/bg.png');
+      writeFixture(dir, 'assets/js/lib.js', 'window.libLoaded = true;');
+      writeFixture(dir, 'assets/js/app.js', 'window.appLoaded = true;');
+      writeFixture(dir, 'content/hero.png');
+      writeFixture(dir, 'root-inline.png');
+      writeFixture(dir, 'stale.js', 'window.stale = true;');
+      writeFixture(dir, 'style.css', '.stale { color: red; }');
+
+      const result = collectSourceAssets(dir, [
+        {
+          relPath: 'index.html',
+          html: [
+            '<link rel="stylesheet" href="assets/css/base.css">',
+            '<script src="assets/js/lib.js"></script>',
+            '<style>.inline { background: url("/root-inline.png"); }</style>',
+            '<script>window.inlineClassic = true;</script>',
+            '<script type="application/json">{"not":"javascript"}</script>',
+            '<img src="content/hero.png">',
+          ].join(''),
+        },
+        {
+          relPath: 'about.html',
+          html: [
+            '<link rel="stylesheet" href="assets/css/override.css">',
+            '<script src="assets/js/app.js"></script>',
+            '<script type="module">window.inlineModule = true;</script>',
+            "<img src='content/hero.png'>",
+          ].join(''),
+        },
+      ]);
+
+      expect(result.cssFiles).toEqual(['assets/css/base.css', 'assets/css/override.css']);
+      expect(result.jsFiles).toEqual(['assets/js/lib.js', 'assets/js/app.js']);
+      expect(result.skippedUnlinked).toEqual(['stale.js', 'style.css']);
+      expect(result.css).toBe(
+        DLA_WP_COMPAT_CSS +
+          [
+            '\n.base { background: url(media/bg.png); color: black; }',
+            '.base { color: white; }',
+            '.inline { background: url(media/root-inline.png); }',
+          ].join('\n\n')
+      );
+      expect(result.css).not.toContain('fonts.googleapis.com');
+      expect(result.js).toBe(
+        [
+          'window.libLoaded = true;',
+          'window.appLoaded = true;',
+          '(function () { try {\nwindow.inlineClassic = true;\n} catch (e) { /* page-scoped inline chunk */ } })();',
+          '(function () { try {\nwindow.inlineModule = true;\n} catch (e) { /* page-scoped inline chunk */ } })();',
+        ].join('\n\n')
+      );
+      expect(result.js).not.toContain('{"not":"javascript"}');
+      expect(result.mediaAssets).toEqual([
+        {
+          srcAbs: join(dir, 'assets/img/bg.png'),
+          themeRel: 'assets/css/media/bg.png',
+        },
+        {
+          srcAbs: join(dir, 'root-inline.png'),
+          themeRel: 'assets/css/media/root-inline.png',
+        },
+      ]);
+      expect(result.imgAssets).toEqual([
+        {
+          srcAbs: join(dir, 'content/hero.png'),
+          themeRel: 'assets/img/hero.png',
+        },
+      ]);
+      expect(result.imgRewritesByPage).toEqual({
+        'about.html': [{ ref: 'content/hero.png', themeRel: 'assets/img/hero.png' }],
+        'index.html': [{ ref: 'content/hero.png', themeRel: 'assets/img/hero.png' }],
+      });
+    });
+  });
+});

From 1ad09b90a658fc67e10a624a456fee77cac0f73f Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 20:15:46 -0400
Subject: [PATCH 064/113] Add deterministic font helper parity

---
 .../src/__tests__/theme-font-faces.test.ts    | 200 ++++++++++++++
 .../theme-source-assets-parity.test.ts        |   9 +
 .../blocks-engine/src/theme/carry-fonts.ts    |  49 ++++
 .../blocks-engine/src/theme/font-capture.ts   | 259 ++++++++++++++++++
 .../blocks-engine/src/theme/google-fonts.ts   |  14 +
 packages/blocks-engine/src/theme/index.ts     |  18 ++
 6 files changed, 549 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/carry-fonts.ts
 create mode 100644 packages/blocks-engine/src/theme/font-capture.ts
 create mode 100644 packages/blocks-engine/src/theme/google-fonts.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-font-faces.test.ts b/packages/blocks-engine/src/__tests__/theme-font-faces.test.ts
index 21a710f9..533e3563 100644
--- a/packages/blocks-engine/src/__tests__/theme-font-faces.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-font-faces.test.ts
@@ -1,5 +1,21 @@
 import { describe, expect, it } from 'vitest';
 import { parseFontFaces, stripUnusedFontFaces } from '../theme/font-faces.js';
+import {
+  absolutizeFontUrl,
+  buildFontFaceCss,
+  consolidateFontFaces,
+  fontFilename,
+  matchCapturedFamily,
+  parseFontFaces as parseCapturedFontFaces,
+  type LocalFontFace,
+  type ParsedFontFace as CapturedParsedFontFace,
+  type ThemeFontFamily,
+} from '../theme/font-capture.js';
+import { extractGoogleFontCssUrls } from '../theme/google-fonts.js';
+import {
+  stripCssSourceMaps,
+  stripUnusedFontFaces as stripUnusedCarryFontFaces,
+} from '../theme/carry-fonts.js';
 
 describe('parseFontFaces', () => {
   it('parses family, preferred source, format, normalized weight, and style', () => {
@@ -86,3 +102,187 @@ describe('stripUnusedFontFaces', () => {
     expect(result.css).toContain(usage);
   });
 });
+
+describe('font helper DLA parity surface', () => {
+  it('extractGoogleFontCssUrls finds unique css/css2 URLs and decodes HTML ampersands', () => {
+    const urls = extractGoogleFontCssUrls([
+      '<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400&amp;display=swap" rel="stylesheet">',
+      "@import url('https://fonts.googleapis.com/css?family=Roboto:wght@700&display=swap');",
+      'https://fonts.googleapis.com/css2?family=Inter:wght@400&amp;display=swap',
+    ]);
+
+    expect(urls).toEqual([
+      'https://fonts.googleapis.com/css2?family=Inter:wght@400&display=swap',
+      'https://fonts.googleapis.com/css?family=Roboto:wght@700&display=swap',
+    ]);
+  });
+
+  it('parseCapturedFontFaces preserves the DLA third-party host filter', () => {
+    const faces = parseCapturedFontFaces(`
+      @font-face {
+        font-family: "Roboto";
+        src: url("https://fonts.gstatic.com/s/roboto/v30/roboto.woff2") format("woff2");
+        font-weight: 400;
+      }
+      @font-face {
+        font-family: "Shop Sans";
+        src: url("https://cdn.shop.example/fonts/shop-sans.woff2") format("woff2");
+        font-weight: bold;
+        font-style: italic;
+      }
+    `);
+
+    expect(faces).toEqual([
+      {
+        family: 'Shop Sans',
+        src: 'https://cdn.shop.example/fonts/shop-sans.woff2',
+        format: 'woff2',
+        weight: '700',
+        style: 'italic',
+      },
+    ]);
+  });
+
+  it('consolidateFontFaces groups variant family names and prefers cleaner woff2 sources', () => {
+    const faces: CapturedParsedFontFace[] = [
+      {
+        family: 'Larsseit Bold',
+        src: 'https://cdn.example/fonts/larsseit-bold_abcdef123.woff2',
+        format: 'woff2',
+        weight: '400',
+        style: 'normal',
+      },
+      {
+        family: 'Larsseit-Bold',
+        src: 'https://cdn.example/fonts/larsseit-bold.woff2',
+        format: 'woff2',
+        weight: '400',
+        style: 'normal',
+      },
+      {
+        family: 'Larsseit Italic',
+        src: 'https://cdn.example/fonts/larsseit-italic.woff',
+        format: 'woff',
+        weight: '400',
+        style: 'italic',
+      },
+    ];
+
+    expect(consolidateFontFaces(faces)).toEqual([
+      {
+        family: 'Larsseit',
+        src: 'https://cdn.example/fonts/larsseit-bold.woff2',
+        format: 'woff2',
+        weight: '700',
+        style: 'normal',
+      },
+      {
+        family: 'Larsseit',
+        src: 'https://cdn.example/fonts/larsseit-italic.woff',
+        format: 'woff',
+        weight: '400',
+        style: 'italic',
+      },
+    ]);
+  });
+
+  it('matchCapturedFamily matches suffix-stripped builder family names', () => {
+    const faces: CapturedParsedFontFace[] = [
+      {
+        family: 'avenir-lt-w01_35',
+        src: 'https://cdn.example/fonts/avenir.woff2',
+        format: 'woff2',
+        weight: '400',
+        style: 'normal',
+      },
+    ];
+
+    expect(matchCapturedFamily('"avenir-lt-w01_35-light1475496", sans-serif', faces)).toBe(
+      'avenir-lt-w01_35'
+    );
+  });
+
+  it('absolutizeFontUrl and fontFilename match DLA golden behavior', () => {
+    expect(absolutizeFontUrl('//cdn.example.com/fonts/acme.woff2')).toBe(
+      'https://cdn.example.com/fonts/acme.woff2'
+    );
+    expect(absolutizeFontUrl('../fonts/acme.woff2', 'https://example.com/css/site/main.css')).toBe(
+      'https://example.com/css/fonts/acme.woff2'
+    );
+
+    const face: CapturedParsedFontFace = {
+      family: 'Acme Display',
+      src: 'https://cdn.example.com/font?id=123',
+      format: 'woff2',
+      weight: '400',
+      style: 'normal',
+    };
+
+    expect(fontFilename(face)).toBe('Acme-Display-400.woff2');
+  });
+
+  it('buildFontFaceCss emits the DLA self-hosted source-font block', () => {
+    const faces: LocalFontFace[] = [
+      {
+        family: 'Acme Display',
+        src: 'https://cdn.example.com/acme-bold.woff2',
+        format: 'woff2',
+        weight: '700',
+        style: 'italic',
+        localPath: 'assets/fonts/acme-bold.woff2',
+      },
+    ];
+    const family: ThemeFontFamily = {
+      fontFamily: 'Acme Display, sans-serif',
+      name: 'Acme Display',
+      slug: 'acme-display',
+      fontFace: [
+        {
+          fontFamily: 'Acme Display',
+          fontWeight: '700',
+          fontStyle: 'italic',
+          src: ['file:./assets/fonts/acme-bold.woff2'],
+        },
+      ],
+    };
+
+    expect(family.slug).toBe('acme-display');
+    expect(buildFontFaceCss(faces)).toBe(`\n/*
+ * Self-hosted source fonts. Captured from the source site's @font-face
+ * declarations and downloaded into assets/fonts/ so headings + body render in
+ * the real typeface rather than a system fallback.
+ */
+@font-face {
+\tfont-family: 'Acme Display';
+\tsrc: url('assets/fonts/acme-bold.woff2') format('woff2');
+\tfont-weight: 700;
+\tfont-style: italic;
+\tfont-display: swap;
+}
+`);
+  });
+
+  it('stripCssSourceMaps removes sourceMappingURL comments only', () => {
+    expect(
+      stripCssSourceMaps(
+        'a{}/*# sourceMappingURL=source.css.map */b{}/* sourceMappingURL=https://cdn.example/map.css.map */'
+      )
+    ).toBe('a{}b{}');
+  });
+
+  it('stripUnusedCarryFontFaces returns kept URLs and DLA stripped count', () => {
+    const usedFace =
+      "@font-face{font-family:'Libre Baskerville';src:url(/fonts/libre.woff2) format('woff2')}";
+    const unusedFace =
+      "@font-face{font-family:'Unused Sans';src:url(/fonts/unused.woff2) format('woff2')}";
+    const usage = '.title{font-family:"Libre Baskerville",serif}';
+
+    const result = stripUnusedCarryFontFaces(`${usedFace}\n${unusedFace}\n${usage}`, usage);
+
+    expect(result).toEqual({
+      css: `${usedFace}\n\n${usage}`,
+      keptUrls: ['/fonts/libre.woff2'],
+      stripped: 1,
+    });
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/theme-source-assets-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-source-assets-parity.test.ts
index a8632186..bd51a61a 100644
--- a/packages/blocks-engine/src/__tests__/theme-source-assets-parity.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-source-assets-parity.test.ts
@@ -89,8 +89,17 @@ describe('source assets DLA parity', () => {
         WP_COMPAT_CSS: expect.any(String),
         collectHtmlImages: expect.any(Function),
         collectSourceAssets: expect.any(Function),
+        extractGoogleFontCssUrls: expect.any(Function),
+        absolutizeFontUrl: expect.any(Function),
+        buildFontFaceCss: expect.any(Function),
+        consolidateFontFaces: expect.any(Function),
+        fontFilename: expect.any(Function),
         localizeCssImages: expect.any(Function),
+        matchCapturedFamily: expect.any(Function),
+        parseCapturedFontFaces: expect.any(Function),
         rewriteHtmlImageSrcs: expect.any(Function),
+        stripCssSourceMaps: expect.any(Function),
+        stripUnusedCarryFontFaces: expect.any(Function),
       })
     );
   });
diff --git a/packages/blocks-engine/src/theme/carry-fonts.ts b/packages/blocks-engine/src/theme/carry-fonts.ts
new file mode 100644
index 00000000..bf05c285
--- /dev/null
+++ b/packages/blocks-engine/src/theme/carry-fonts.ts
@@ -0,0 +1,49 @@
+const FONT_EXT = /\.(woff2|woff|ttf|otf|eot)(?:[?#]|$)/i;
+// @font-face has no nested braces, so [^{}]* safely bounds one block (multi-line ok).
+const FONT_FACE_BLOCK = /@font-face\s*\{[^{}]*\}/gi;
+const URL_IN_DECL = /url\(\s*(['"]?)([^'")]+?)\1\s*\)/gi;
+const FAMILY_DECL = /font-family\s*:\s*(['"]?)([^;'"}]+)\1/i;
+
+/** Extract the font src URLs from an @font-face block body (remote or font-ext, never data:). */
+function fontUrlsInBlock(block: string): string[] {
+  const urls: string[] = [];
+  const re = new RegExp(URL_IN_DECL.source, 'gi');
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(block)) !== null) {
+    const v = m[2].trim();
+    if (v.startsWith('data:')) continue;
+    if (/^(https?:)?\/\//i.test(v) || FONT_EXT.test(v)) urls.push(v);
+  }
+  return urls;
+}
+
+export interface StripResult {
+  /** CSS with unused @font-face blocks removed. */
+  css: string;
+  /** Distinct src URLs from the KEPT (used) @font-face blocks. */
+  keptUrls: string[];
+  /** Number of @font-face blocks removed. */
+  stripped: number;
+}
+
+export function stripUnusedFontFaces(css: string, usageText: string): StripResult {
+  const usage = usageText.toLowerCase();
+  const keptUrls = new Set<string>();
+  let stripped = 0;
+  const out = css.replace(FONT_FACE_BLOCK, (block) => {
+    const fam = FAMILY_DECL.exec(block);
+    const family = fam ? fam[2].trim() : null;
+    const used = family != null && family.length > 0 && usage.includes(family.toLowerCase());
+    if (used) {
+      for (const u of fontUrlsInBlock(block)) keptUrls.add(u);
+      return block;
+    }
+    stripped++;
+    return '';
+  });
+  return { css: out, keptUrls: [...keptUrls], stripped };
+}
+
+export function stripCssSourceMaps(css: string): string {
+  return css.replace(/\/\*#?\s*sourceMappingURL=[^*]*\*\//gi, '');
+}
diff --git a/packages/blocks-engine/src/theme/font-capture.ts b/packages/blocks-engine/src/theme/font-capture.ts
new file mode 100644
index 00000000..c3803546
--- /dev/null
+++ b/packages/blocks-engine/src/theme/font-capture.ts
@@ -0,0 +1,259 @@
+/** One normalized `@font-face` rule extracted from source CSS. */
+export interface ParsedFontFace {
+  /** Declared font-family name, unquoted (e.g. "Larsseit"). */
+  family: string;
+  /** Absolute (or protocol-relative) URL of the first usable font file. */
+  src: string;
+  /** Lowercased file extension without the dot, e.g. "woff" / "woff2" / "ttf". */
+  format: string;
+  /** font-weight value as written (e.g. "400", "700", "normal", "bold"). */
+  weight: string;
+  /** font-style value as written (e.g. "normal", "italic"). */
+  style: string;
+}
+
+/** A captured font with a resolved LOCAL asset path inside the theme. */
+export interface LocalFontFace extends ParsedFontFace {
+  /** Theme-relative path the font file was written to, e.g. "assets/fonts/Larsseit-Regular.woff". */
+  localPath: string;
+}
+
+const FONT_EXTENSIONS = new Set(['woff2', 'woff', 'ttf', 'otf', 'eot', 'svg']);
+
+const GENERIC_FAMILIES = new Set([
+  'serif',
+  'sans-serif',
+  'monospace',
+  'cursive',
+  'fantasy',
+  'system-ui',
+  'ui-sans-serif',
+  'ui-serif',
+  'ui-monospace',
+  'inherit',
+  'initial',
+]);
+
+/** Substrings in a font URL that mark third-party widget fonts (not the site's own). */
+const THIRD_PARTY_FONT_HOST_HINTS = ['klaviyo.com', 'gstatic.com', 'typekit.net', 'use.typekit'];
+
+export function parseFontFaces(...cssOrHtml: string[]): ParsedFontFace[] {
+  const faces: ParsedFontFace[] = [];
+  const seen = new Set<string>();
+
+  for (const input of cssOrHtml) {
+    if (!input) continue;
+    const blockRe = /@font-face\s*\{([^}]*)\}/gi;
+    let block: RegExpExecArray | null;
+    while ((block = blockRe.exec(input)) !== null) {
+      const body = block[1];
+
+      const family = readDeclaration(body, 'font-family');
+      if (!family) continue;
+      const familyClean = family.replace(/^["']|["']$/g, '').trim();
+      if (!familyClean || GENERIC_FAMILIES.has(familyClean.toLowerCase())) continue;
+
+      const srcDecl = readDeclaration(body, 'src');
+      if (!srcDecl) continue;
+      const picked = pickBestFontUrl(srcDecl);
+      if (!picked) continue;
+      if (THIRD_PARTY_FONT_HOST_HINTS.some((h) => picked.url.toLowerCase().includes(h))) continue;
+
+      const weight = normalizeWeight(readDeclaration(body, 'font-weight') ?? '400');
+      const style = normalizeStyle(readDeclaration(body, 'font-style'));
+
+      const key = `${familyClean.toLowerCase()}|${weight}|${style}|${picked.url}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      faces.push({ family: familyClean, src: picked.url, format: picked.format, weight, style });
+    }
+  }
+
+  return faces;
+}
+
+function readDeclaration(body: string, prop: string): string | null {
+  const re = new RegExp(`${prop}\\s*:\\s*([^;]+)`, 'i');
+  const m = re.exec(body);
+  return m ? m[1].trim() : null;
+}
+
+function pickBestFontUrl(srcDecl: string): { url: string; format: string } | null {
+  const urlRe = /url\(\s*(['"]?)([^'")]+)\1\s*\)/gi;
+  const candidates: { url: string; format: string }[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = urlRe.exec(srcDecl)) !== null) {
+    const url = m[2].trim();
+    const ext = fontExtension(url);
+    if (ext) candidates.push({ url, format: ext });
+  }
+  if (candidates.length === 0) return null;
+  const byPref = (c: { format: string }): number =>
+    c.format === 'woff2' ? 0 : c.format === 'woff' ? 1 : 2;
+  candidates.sort((a, b) => byPref(a) - byPref(b));
+  return candidates[0];
+}
+
+function fontExtension(url: string): string | null {
+  // Strip query string + fragment before reading the extension.
+  const clean = url.split('?')[0].split('#')[0];
+  const dot = clean.lastIndexOf('.');
+  if (dot < 0) return null;
+  const ext = clean.slice(dot + 1).toLowerCase();
+  return FONT_EXTENSIONS.has(ext) ? ext : null;
+}
+
+function normalizeWeight(raw: string): string {
+  const v = raw.trim().toLowerCase();
+  if (v === 'normal') return '400';
+  if (v === 'bold') return '700';
+  // Weight ranges ("400 700") - keep the first.
+  const num = /\d{3}/.exec(v);
+  return num ? num[0] : '400';
+}
+
+function normalizeStyle(raw: string | null): string {
+  const v = (raw ?? '').trim().toLowerCase();
+  if (v === 'italic') return 'italic';
+  if (v.startsWith('oblique')) return 'oblique';
+  return 'normal';
+}
+
+export function absolutizeFontUrl(src: string, baseUrl?: string): string {
+  const trimmed = src.trim();
+  if (trimmed.startsWith('//')) return `https:${trimmed}`;
+  if (/^https?:\/\//i.test(trimmed)) return trimmed;
+  if (baseUrl) {
+    try {
+      return new URL(trimmed, baseUrl).toString();
+    } catch {
+      return trimmed;
+    }
+  }
+  return trimmed;
+}
+
+export function fontFilename(face: ParsedFontFace): string {
+  const clean = face.src.split('?')[0].split('#')[0];
+  const seg = clean.slice(clean.lastIndexOf('/') + 1);
+  if (seg && fontExtension(seg)) {
+    return seg.replace(/[^A-Za-z0-9._-]/g, '_');
+  }
+  const familySlug = face.family.replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  const italic = face.style === 'italic' ? '-italic' : '';
+  return `${familySlug}-${face.weight}${italic}.${face.format}`;
+}
+
+export function buildFontFaceCss(faces: LocalFontFace[]): string {
+  if (faces.length === 0) return '';
+  const rules = faces.map((f) => {
+    const fmt = cssFormat(f.format);
+    return `@font-face {
+\tfont-family: '${f.family}';
+\tsrc: url('${f.localPath}')${fmt ? ` format('${fmt}')` : ''};
+\tfont-weight: ${f.weight};
+\tfont-style: ${f.style};
+\tfont-display: swap;
+}`;
+  });
+  return `\n/*\n * Self-hosted source fonts. Captured from the source site's @font-face\n * declarations and downloaded into assets/fonts/ so headings + body render in\n * the real typeface rather than a system fallback.\n */\n${rules.join('\n')}\n`;
+}
+
+function cssFormat(ext: string): string {
+  switch (ext) {
+    case 'woff2': return 'woff2';
+    case 'woff': return 'woff';
+    case 'ttf': return 'truetype';
+    case 'otf': return 'opentype';
+    case 'eot': return 'embedded-opentype';
+    case 'svg': return 'svg';
+    default: return '';
+  }
+}
+
+export interface ThemeFontFamily {
+  fontFamily: string;
+  name: string;
+  slug: string;
+  fontFace?: Array<{
+    fontFamily: string;
+    fontWeight: string;
+    fontStyle: string;
+    src: string[];
+  }>;
+}
+
+export function baseFamilyName(family: string): string {
+  return family
+    .replace(/[-_\s]+(thin|extralight|ultralight|light|regular|book|normal|medium|semibold|demibold|bold|extrabold|ultrabold|black|heavy|italic|oblique)$/i, '')
+    .replace(/[-_\s]+(thin|extralight|ultralight|light|regular|book|normal|medium|semibold|demibold|bold|extrabold|ultrabold|black|heavy|italic|oblique)\b/gi, '')
+    .replace(/[-_\s]+$/g, '')
+    .trim() || family;
+}
+
+function weightFromFamilyName(family: string, declared: string): string {
+  const m = /(thin|extralight|ultralight|light|regular|book|normal|medium|semibold|demibold|bold|extrabold|ultrabold|black|heavy)/i.exec(family);
+  if (!m) return declared;
+  const map: Record<string, string> = {
+    thin: '100', extralight: '200', ultralight: '200', light: '300',
+    regular: '400', book: '400', normal: '400', medium: '500',
+    semibold: '600', demibold: '600', bold: '700', extrabold: '800',
+    ultrabold: '800', black: '900', heavy: '900',
+  };
+  return map[m[1].toLowerCase()] ?? declared;
+}
+
+export function consolidateFontFaces<T extends ParsedFontFace>(faces: T[]): T[] {
+  const byKey = new Map<string, T>();
+  for (const f of faces) {
+    const base = baseFamilyName(f.family);
+    const weight = weightFromFamilyName(f.family, f.weight);
+    const key = `${base.toLowerCase()}|${weight}|${f.style}`;
+    const merged = { ...f, family: base, weight } as T;
+    const existing = byKey.get(key);
+    if (!existing) {
+      byKey.set(key, merged);
+      continue;
+    }
+    // Prefer woff2, then the URL without a hash-style suffix (cleaner filename).
+    const score = (x: ParsedFontFace): number =>
+      (x.format === 'woff2' ? 0 : 2) + (/_[0-9a-f]{8,}\./i.test(x.src) ? 1 : 0);
+    if (score(merged) < score(existing)) byKey.set(key, merged);
+  }
+  return [...byKey.values()];
+}
+
+function normalizeFamilyBase(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/^["']|["']$/g, '')
+    .replace(/[0-9]{3,}/g, '') // drop builder hashes (e.g. ...light1475496)
+    .replace(
+      /[-_ ]+(thin|extra-?light|ultra-?light|light|book|regular|normal|roman|text|medium|semi-?bold|demi-?bold|demi|bold|extra-?bold|ultra-?bold|black|heavy|italic|oblique)\b/g,
+      '',
+    )
+    .replace(/[-_ ]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .trim();
+}
+
+export function matchCapturedFamily(
+  requestedStack: string | null | undefined,
+  faces: ParsedFontFace[],
+): string | null {
+  if (!requestedStack) return null;
+  const first = requestedStack.split(',')[0].trim().replace(/^["']|["']$/g, '').toLowerCase();
+  if (!first) return null;
+  for (const f of faces) {
+    if (f.family.toLowerCase() === first) return f.family;
+  }
+  // Suffix-tolerant fallback: match on the normalized base name.
+  const firstBase = normalizeFamilyBase(first);
+  if (firstBase.length >= 4) {
+    for (const f of faces) {
+      if (normalizeFamilyBase(f.family) === firstBase) return f.family;
+    }
+  }
+  return null;
+}
diff --git a/packages/blocks-engine/src/theme/google-fonts.ts b/packages/blocks-engine/src/theme/google-fonts.ts
new file mode 100644
index 00000000..bb6228cd
--- /dev/null
+++ b/packages/blocks-engine/src/theme/google-fonts.ts
@@ -0,0 +1,14 @@
+// Matches all https://fonts.googleapis.com/css or css2 query-string URLs found in
+// href attributes, @import rules, or bare text. Handles HTML-encoded & (&amp;).
+const GOOGLE_CSS_RE = /https:\/\/fonts\.googleapis\.com\/css2?\?[^"'\s)]+/g;
+
+/** Find unique Google-Fonts css/css2 URLs across html/css source strings (deduped). */
+export function extractGoogleFontCssUrls(sources: string[]): string[] {
+  const found = new Set<string>();
+  for (const src of sources) {
+    for (const m of src.matchAll(GOOGLE_CSS_RE)) {
+      found.add(m[0].replace(/&amp;/g, '&'));
+    }
+  }
+  return [...found];
+}
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index b5e0cf67..95ad4536 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -27,6 +27,19 @@ export {
   rewriteHtmlImageSrcs,
   WP_COMPAT_CSS,
 } from './source-assets.js';
+export { extractGoogleFontCssUrls } from './google-fonts.js';
+export {
+  absolutizeFontUrl,
+  buildFontFaceCss,
+  consolidateFontFaces,
+  fontFilename,
+  matchCapturedFamily,
+  parseFontFaces as parseCapturedFontFaces,
+} from './font-capture.js';
+export {
+  stripCssSourceMaps,
+  stripUnusedFontFaces as stripUnusedCarryFontFaces,
+} from './carry-fonts.js';
 export {
   captureSectionContent,
   foldText,
@@ -48,6 +61,11 @@ export type { IslandTier } from './html-fallback.js';
 export { rewriteInternalLinks, rewriteMediaUrls } from './url-rewrite.js';
 export { scanForInjection } from './injection-scan.js';
 export type { CapturedSectionContent, CoverageResult } from './section-coverage.js';
+export type {
+  LocalFontFace,
+  ParsedFontFace as CapturedParsedFontFace,
+  ThemeFontFamily,
+} from './font-capture.js';
 export type * from './font-faces.js';
 export type { InternalLinkMap } from './url-rewrite.js';
 export type * from './section-spec.js';

From 109de7e53c72c12cbe714ff67e52a1708a6f4e82 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 20:23:42 -0400
Subject: [PATCH 065/113] Freeze segmentPage parity surface

---
 packages/blocks-engine/src/theme/index.ts   |  7 +++++
 packages/blocks-engine/src/theme/segment.ts | 29 +++++++++++++++++++++
 2 files changed, 36 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/segment.ts

diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 95ad4536..ef9c7735 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -9,6 +9,7 @@ export {
   stripActiveNavState,
 } from './chrome-signature.js';
 export { splitPageChrome } from './chrome-split.js';
+export { segmentPage } from './segment.js';
 export { foundation } from './foundation.js';
 export { ingest } from './ingest.js';
 export { planTemplates } from './template-plan.js';
@@ -57,6 +58,12 @@ export type * from './assets.js';
 export type { ChromeResult } from './chrome.js';
 export type { ChromeSlugs } from './chrome-signature.js';
 export type { RegionSplit } from './chrome-split.js';
+export type {
+  LayoutRailWrapperMetadata,
+  LayoutWrapperRailPosition,
+  Section,
+  SectionRole,
+} from './segment.js';
 export type { IslandTier } from './html-fallback.js';
 export { rewriteInternalLinks, rewriteMediaUrls } from './url-rewrite.js';
 export { scanForInjection } from './injection-scan.js';
diff --git a/packages/blocks-engine/src/theme/segment.ts b/packages/blocks-engine/src/theme/segment.ts
new file mode 100644
index 00000000..4e7c4ab0
--- /dev/null
+++ b/packages/blocks-engine/src/theme/segment.ts
@@ -0,0 +1,29 @@
+export type SectionRole = 'body' | 'header' | 'nav' | 'footer';
+
+export type LayoutWrapperRailPosition = 'beforeMain' | 'afterMain';
+
+export interface LayoutRailWrapperMetadata {
+  layoutWrapperTag: string;
+  layoutWrapperClasses: string[];
+  layoutWrapperRailPosition: LayoutWrapperRailPosition;
+}
+
+export interface Section {
+  /** Stable, deterministic id (existing id/class, heading slug, or content hash). */
+  id: string;
+  role: SectionRole;
+  /** Chrome inferred structurally rather than from a body-direct landmark. */
+  chromeSource?: 'layout-rail';
+  /** outerHTML of the section element. */
+  html: string;
+  /** The source element's class list, in order. */
+  classes?: string[];
+  layoutWrapperTag?: string;
+  layoutWrapperClasses?: string[];
+  layoutWrapperRailPosition?: LayoutWrapperRailPosition;
+}
+
+export function segmentPage(html: string): Section[] {
+  void html;
+  throw new Error('STAGE_STUB: segmentPage');
+}

From 1f21e593a0a9bc0593dda50436921d7dfe05cdc5 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 20:34:07 -0400
Subject: [PATCH 066/113] Add segmentPage parity surface

---
 packages/blocks-engine/package.json           |   1 +
 packages/blocks-engine/pnpm-lock.yaml         |   3 +
 .../__tests__/theme-segment-parity.test.ts    | 116 ++++++++
 packages/blocks-engine/src/theme/segment.ts   | 262 +++++++++++++++++-
 4 files changed, 380 insertions(+), 2 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-segment-parity.test.ts

diff --git a/packages/blocks-engine/package.json b/packages/blocks-engine/package.json
index fa03025b..001f87f0 100644
--- a/packages/blocks-engine/package.json
+++ b/packages/blocks-engine/package.json
@@ -41,6 +41,7 @@
   },
   "dependencies": {
     "cheerio": "1.2.0",
+    "domhandler": "5.0.3",
     "@wordpress/block-serialization-default-parser": "5.47.0",
     "@wordpress/blocks": "15.15.0",
     "@wordpress/block-editor": "15.15.0",
diff --git a/packages/blocks-engine/pnpm-lock.yaml b/packages/blocks-engine/pnpm-lock.yaml
index e76ef977..05acf732 100644
--- a/packages/blocks-engine/pnpm-lock.yaml
+++ b/packages/blocks-engine/pnpm-lock.yaml
@@ -29,6 +29,9 @@ importers:
       cheerio:
         specifier: 1.2.0
         version: 1.2.0
+      domhandler:
+        specifier: 5.0.3
+        version: 5.0.3
       jsdom:
         specifier: 29.0.1
         version: 29.0.1
diff --git a/packages/blocks-engine/src/__tests__/theme-segment-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-segment-parity.test.ts
new file mode 100644
index 00000000..f2109fa0
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-segment-parity.test.ts
@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest';
+
+import * as theme from '../theme/index.js';
+import { segmentPage } from '../theme/index.js';
+
+describe('segmentPage DLA parity', () => {
+  it('exposes the additive segmentPage public surface from theme/index', () => {
+    expect(theme).toEqual(
+      expect.objectContaining({
+        segmentPage: expect.any(Function),
+      })
+    );
+  });
+
+  it('identifies header, nav, footer, and body sections on a DLA fixture', () => {
+    const html =
+      '<body><header id="masthead" class="site-head"><nav><a href="x.html">X</a></nav></header><nav id="main-nav" class="primary"><a href="a.html">A</a></nav><main><section id="hero" class="hero splash"><h1>Hi</h1></section><section class="features"><h2>Feat</h2></section></main><footer class="site-foot"><p>(c)</p></footer></body>';
+
+    expect(segmentPage(html)).toEqual([
+      {
+        id: 'header',
+        role: 'header',
+        html: '<header id="masthead" class="site-head"><nav><a href="x.html">X</a></nav></header>',
+        classes: ['site-head'],
+      },
+      {
+        id: 'nav',
+        role: 'nav',
+        html: '<nav id="main-nav" class="primary"><a href="a.html">A</a></nav>',
+        classes: ['primary'],
+      },
+      {
+        id: 'footer',
+        role: 'footer',
+        html: '<footer class="site-foot"><p>(c)</p></footer>',
+        classes: ['site-foot'],
+      },
+      {
+        id: 'hero',
+        role: 'body',
+        html: '<section id="hero" class="hero splash"><h1>Hi</h1></section>',
+        classes: ['hero', 'splash'],
+      },
+      {
+        id: 'feat',
+        role: 'body',
+        html: '<section class="features"><h2>Feat</h2></section>',
+        classes: ['features'],
+      },
+    ]);
+  });
+
+  it('keeps chrome-vs-body split golden for loose body siblings', () => {
+    const html =
+      '<body><aside class="badge">New</aside><main><section id="content"><h1>Content</h1></section></main></body>';
+
+    expect(segmentPage(html)).toEqual([
+      {
+        id: 'badge',
+        role: 'body',
+        html: '<aside class="badge">New</aside>',
+        classes: ['badge'],
+      },
+      {
+        id: 'content',
+        role: 'body',
+        html: '<section id="content"><h1>Content</h1></section>',
+        classes: [],
+      },
+    ]);
+  });
+
+  it('segments a no-chrome page and escapes loose decoded text like DLA', () => {
+    const html =
+      '<main>Hello &lt;b&gt;bold&lt;/b&gt;<section id="s"><p>S text</p></section><script>var x=1;</script></main>';
+
+    expect(segmentPage(html)).toEqual([
+      {
+        id: 'section-0545a7d4-0',
+        role: 'body',
+        html: '<p>Hello &lt;b&gt;bold&lt;/b&gt;</p>',
+        classes: [],
+      },
+      {
+        id: 's',
+        role: 'body',
+        html: '<section id="s"><p>S text</p></section>',
+        classes: [],
+      },
+    ]);
+  });
+
+  it('promotes layout rail sidebars with wrapper metadata', () => {
+    const html =
+      '<body><div class="docs-grid content-shell"><aside class="docs-sidebar"><nav><a href="intro.html">Intro</a><a href="api.html">API</a></nav></aside><main><section id="overview"><h1>Overview</h1></section></main></div></body>';
+
+    expect(segmentPage(html)).toEqual([
+      {
+        id: 'docs-sidebar',
+        role: 'nav',
+        chromeSource: 'layout-rail',
+        html: '<aside class="docs-sidebar"><nav><a href="intro.html">Intro</a><a href="api.html">API</a></nav></aside>',
+        classes: ['docs-sidebar'],
+        layoutWrapperTag: 'div',
+        layoutWrapperClasses: ['docs-grid', 'content-shell'],
+        layoutWrapperRailPosition: 'beforeMain',
+      },
+      {
+        id: 'overview',
+        role: 'body',
+        html: '<section id="overview"><h1>Overview</h1></section>',
+        classes: [],
+      },
+    ]);
+  });
+});
diff --git a/packages/blocks-engine/src/theme/segment.ts b/packages/blocks-engine/src/theme/segment.ts
index 4e7c4ab0..2f827498 100644
--- a/packages/blocks-engine/src/theme/segment.ts
+++ b/packages/blocks-engine/src/theme/segment.ts
@@ -1,3 +1,9 @@
+import { createHash } from 'node:crypto';
+import * as cheerio from 'cheerio';
+import type { Cheerio, CheerioAPI } from 'cheerio';
+import { isTag, isText } from 'domhandler';
+import type { AnyNode, Element } from 'domhandler';
+
 export type SectionRole = 'body' | 'header' | 'nav' | 'footer';
 
 export type LayoutWrapperRailPosition = 'beforeMain' | 'afterMain';
@@ -23,7 +29,259 @@ export interface Section {
   layoutWrapperRailPosition?: LayoutWrapperRailPosition;
 }
 
+/** Non-rendering top-level tags that never become body sections. */
+const SKIP_TAGS = new Set(['script', 'style', 'link', 'template', 'noscript']);
+const LANDMARK_TAGS = new Set(['main', 'nav', 'header', 'footer', 'section', 'article']);
+const CONTENT_LANDMARK_TAGS = new Set(['main', 'article', 'section']);
+const CONTENT_LANDMARK_ROLES = new Set(['main', 'article', 'region']);
+const CHROME_LANDMARK_TAGS = new Set(['header', 'nav', 'footer']);
+const ACTIONABLE_TEXT_MIN = 24;
+
+/** Escape &, <, > — the minimal set for HTML text-node content. */
+function escapeHtmlText(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+/** Escape &, <, >, " — text plus double-quoted attribute values. */
+function escapeHtml(s: string): string {
+  return escapeHtmlText(s).replace(/"/g, '&quot;');
+}
+
+/** Slugify a short text run for use in an id. */
+function textSlug(text: string): string {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+}
+
+/** Hash-branch id — shared by stableId's fallback and synthetic text sections. */
+function hashId(html: string, ordinal: number): string {
+  const hash = createHash('sha1').update(html).digest('hex').slice(0, 8);
+  return `section-${hash}-${ordinal}`;
+}
+
+/**
+ * Stable id: existing id → heading-text slug → first class → content hash.
+ * Heading slug beats class so utility-first markup (class="flex mt-8") yields
+ * a meaningful, collision-resistant id instead of "flex".
+ */
+function stableId($: CheerioAPI, el: Element, ordinal: number): string {
+  const $el = $(el);
+  const existing = $el.attr('id');
+  if (existing) return existing;
+  const heading = $el.find('h1,h2,h3').first().text();
+  const slug = heading.trim() ? textSlug(heading) : '';
+  if (slug) {
+    // Don't let the section anchor collide with a DESCENDANT id — a source
+    // <h2 id="features">Features</h2> yields slug "features", which would
+    // duplicate the heading's own id. Beyond invalid HTML, the duplicate shadows
+    // the heading for any #id-keyed lookup: a parity/diff pass probing source
+    // #features (the heading) but replica #features (the section) patches the
+    // wrong element (e.g. forcing display/margin), collapsing the section.
+    return $el.find(`[id="${slug}"]`).length > 0 ? `${slug}-section` : slug;
+  }
+  const cls = ($el.attr('class') ?? '').split(/\s+/).filter(Boolean)[0];
+  if (cls) return cls;
+  return hashId($.html(el) ?? '', ordinal);
+}
+
+function roleOf($el: Cheerio<Element>): string {
+  return ($el.attr('role') ?? '').trim().toLowerCase();
+}
+
+function classList($el: { attr(name: string): string | undefined }): string[] {
+  return ($el.attr('class') ?? '').split(/\s+/).filter(Boolean);
+}
+
+function nearestLandmarkAncestor(el: Element): string | null {
+  for (let a = el.parent; a && a.type === 'tag'; a = a.parent) {
+    const tag = (a as Element).tagName?.toLowerCase() ?? '';
+    if (LANDMARK_TAGS.has(tag)) return tag;
+  }
+  return null;
+}
+
+function hasContentLandmarkAncestor($: CheerioAPI, el: Element): boolean {
+  for (let a = el.parent; a && a.type === 'tag'; a = a.parent) {
+    const ancestor = a as Element;
+    const tag = ancestor.tagName?.toLowerCase() ?? '';
+    if (CONTENT_LANDMARK_TAGS.has(tag) || CONTENT_LANDMARK_ROLES.has(roleOf($(ancestor)))) return true;
+  }
+  return false;
+}
+
+function isActionableComplementary($: CheerioAPI, el: Element): boolean {
+  const $el = $(el);
+  const textLength = $el.text().replace(/\s+/g, ' ').trim().length;
+  const linkCount = $el.find('a[href]').length;
+  return textLength >= ACTIONABLE_TEXT_MIN || linkCount >= 2;
+}
+
+function hasContentLandmarkDescendant($: CheerioAPI, el: Element): boolean {
+  return ($(el).find('main,article,section,[role]').toArray() as Element[]).some((child) => {
+    const tag = child.tagName?.toLowerCase() ?? '';
+    return CONTENT_LANDMARK_TAGS.has(tag) || CONTENT_LANDMARK_ROLES.has(roleOf($(child)));
+  });
+}
+
+function isLayoutChromeCandidate($: CheerioAPI, el: Element): boolean {
+  const $el = $(el);
+  const tag = el.tagName?.toLowerCase() ?? '';
+  const role = roleOf($el);
+  const isNav = tag === 'nav' || role === 'navigation';
+  const isComplementary = tag === 'aside' || role === 'complementary';
+  if (!isNav && !isComplementary) return false;
+  if (hasContentLandmarkAncestor($, el)) return false;
+  if (hasContentLandmarkDescendant($, el)) return false;
+  const nearest = nearestLandmarkAncestor(el);
+  if (nearest && CONTENT_LANDMARK_TAGS.has(nearest)) return false;
+  if (nearest && CHROME_LANDMARK_TAGS.has(nearest)) return false;
+  return isNav || isActionableComplementary($, el);
+}
+
+function findLayoutRailWrapper($: CheerioAPI, rail: Element): LayoutRailWrapperMetadata | null {
+  if (!rail.parent || !isTag(rail.parent)) return null;
+  const parent = rail.parent as Element;
+  const tag = parent.tagName?.toLowerCase() ?? '';
+  if (!tag || tag === 'body' || tag === 'html') return null;
+
+  const pageMain = $('main').first().get(0);
+  if (!pageMain || !isTag(pageMain)) return null;
+
+  const descendants = $(parent).find('*').toArray() as Element[];
+  const railIndex = descendants.findIndex((node) => node === rail);
+  const mainIndex = descendants.findIndex((node) => node === pageMain);
+  if (railIndex < 0 || mainIndex < 0 || railIndex === mainIndex) return null;
+
+  return {
+    layoutWrapperTag: tag,
+    layoutWrapperClasses: classList($(parent)),
+    layoutWrapperRailPosition: railIndex < mainIndex ? 'beforeMain' : 'afterMain',
+  };
+}
+
 export function segmentPage(html: string): Section[] {
-  void html;
-  throw new Error('STAGE_STUB: segmentPage');
+  const $ = cheerio.load(html);
+  const sections: Section[] = [];
+
+  // Track the exact elements captured as chrome so the body iteration (which
+  // walks ALL top-level nodes when there is no <main>) never double-captures
+  // them as body sections.
+  const classesOf = (el: ReturnType<typeof $>): string[] =>
+    classList(el);
+
+  const chromeEls = new Set<Element>();
+  const pushChrome = (selector: string, role: SectionRole): void => {
+    const el = $(selector).first();
+    if (el.length) {
+      chromeEls.add(el.get(0) as Element);
+      // classes unused by the native-block header path (buildHeaderPart builds
+      // its own); footer path consumes them.
+      sections.push({ id: role, role, html: $.html(el) ?? '', classes: classesOf(el) });
+    }
+  };
+  // Strict body-direct landmarks only. A comma-fallback (bare `header`) would
+  // grab nested landmarks — e.g. an <article>'s own <header> — misclassifying
+  // them as page chrome AND double-capturing them inside the body section.
+  // Missing chrome = emit nothing. A nav INSIDE the header stays embedded in
+  // the header's html (not captured separately).
+  pushChrome('body > header', 'header');
+  pushChrome('body > nav', 'nav');
+  pushChrome('body > footer', 'footer');
+
+  let layoutChromeOrdinal = 0;
+  for (const el of $('body').find('aside, nav, [role]').toArray() as Element[]) {
+    if (chromeEls.has(el)) continue;
+    if (($(el).parents().toArray() as Element[]).some((parent) => chromeEls.has(parent))) continue;
+    if (!isLayoutChromeCandidate($, el)) continue;
+    chromeEls.add(el);
+    const $el = $(el);
+    const section: Section & Partial<LayoutRailWrapperMetadata> = {
+      id: stableId($, el, layoutChromeOrdinal),
+      role: 'nav',
+      chromeSource: 'layout-rail',
+      html: $.html(el) ?? '',
+      classes: classesOf($el),
+    };
+    Object.assign(section, findLayoutRailWrapper($, el) ?? {});
+    sections.push(section);
+    $el.remove();
+    layoutChromeOrdinal += 1;
+  }
+
+  // Body content = EVERY top-level node — wrapper elements (section/article/div)
+  // AND loose content (figure/h1/p/img/…) AND nonempty text nodes. When a <main>
+  // exists its CHILDREN are the body (the <main> wrapper is unwrapped); loose
+  // body-level SIBLINGS of <main> are carried TOO (a .grain overlay before
+  // <header>, a sticky .marquee between header and main) — neither chrome nor
+  // inside <main>, they were previously dropped. The <main> expands in place even
+  // when nested in a layout wrapper, so the wrapper still yields main's children,
+  // not the wrapper itself. No <main> → every top-level body node is a section.
+  const mainEl = $('main').first().get(0) ?? null;
+  // True when a body-level node IS <main> or is an ANCESTOR of it (the layout
+  // wrapper holding <main>): that slot expands to main's own children.
+  const isMainSlot = (node: Element): boolean => {
+    if (!mainEl) return false;
+    if (node === mainEl) return true;
+    for (let p = mainEl.parent; p && isTag(p); p = p.parent) if (p === node) return true;
+    return false;
+  };
+  // Flatten body's top-level nodes in DOM order, expanding the <main> slot to its
+  // own children in place. Loose siblings keep their position relative to main.
+  const bodyNodes: AnyNode[] = [];
+  for (const node of $('body').contents().get()) {
+    if (isTag(node) && isMainSlot(node)) {
+      for (const child of $(mainEl as Element).contents().get()) bodyNodes.push(child);
+    } else {
+      bodyNodes.push(node);
+    }
+  }
+  let ordinal = 0;
+  for (const node of bodyNodes) {
+    if (isTag(node)) {
+      if (SKIP_TAGS.has(node.tagName?.toLowerCase() ?? '')) continue;
+      if (chromeEls.has(node)) continue; // already captured as chrome
+      sections.push({ id: stableId($, node, ordinal), role: 'body', html: $.html(node) ?? '', classes: classesOf($(node)) });
+      ordinal += 1;
+    } else if (isText(node)) {
+      const text = node.data.trim();
+      if (!text) continue;
+      // node.data is entity-DECODED — wrap it RE-ESCAPED so tag-shaped display
+      // text (a source showing "&lt;b&gt;bold&lt;/b&gt;") stays literal text
+      // when the emitter re-parses the wrapper, instead of becoming real
+      // markup (or, for "<script>…", getting eaten entirely). The emitter
+      // decodes and re-escapes on extraction, so the final block markup is
+      // identical for plain text and correct for tag-shaped text.
+      const html = `<p>${escapeHtml(text)}</p>`;
+      sections.push({ id: hashId(html, ordinal), role: 'body', html, classes: [] });
+      ordinal += 1;
+    }
+    // Comments and other node types: skipped.
+  }
+
+  // Dedup duplicate body-section ids with ordinal suffixes (deterministic,
+  // DOM order — matches the media filename-collision convention). Two
+  // class="card" sections are normal; a silent pageContent[id] overwrite
+  // downstream is not. The `used` set is seeded with ALL body ids so a
+  // generated suffix never collides with a pre-existing literal id (e.g. a
+  // source <section id="card-2"> alongside two class="card" sections).
+  const used = new Set(sections.filter((s) => s.role === 'body').map((s) => s.id));
+  const seen = new Map<string, number>();
+  for (const s of sections) {
+    if (s.role !== 'body') continue;
+    const count = (seen.get(s.id) ?? 0) + 1;
+    seen.set(s.id, count);
+    if (count > 1) {
+      let n = count;
+      let candidate = `${s.id}-${n}`;
+      while (used.has(candidate)) candidate = `${s.id}-${++n}`;
+      used.add(candidate);
+      s.id = candidate;
+    }
+  }
+
+  return sections;
 }

From f41746655b2fecfebde5fad8b1c5c6088675d4bc Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 20:43:29 -0400
Subject: [PATCH 067/113] Freeze chrome parts builder parity surface

---
 ...heme-chrome-parts-builders-surface.test.ts |  43 ++++++++
 .../src/theme/chrome-parts-builders.ts        | 101 ++++++++++++++++++
 packages/blocks-engine/src/theme/index.ts     |  18 ++++
 3 files changed, 162 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-chrome-parts-builders-surface.test.ts
 create mode 100644 packages/blocks-engine/src/theme/chrome-parts-builders.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-chrome-parts-builders-surface.test.ts b/packages/blocks-engine/src/__tests__/theme-chrome-parts-builders-surface.test.ts
new file mode 100644
index 00000000..caf89fc6
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-chrome-parts-builders-surface.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import {
+  buildCarriedHeaderPart,
+  buildFooterPart,
+  buildHeaderPart,
+  findChromeMounts,
+  mountPartMarkup,
+  type CarriedHeaderPartOpts,
+  type ChromeMount,
+  type ChromeMounts,
+  type ChromePartConverter,
+  type ChromePartSection,
+  type FooterPartOpts,
+  type HeaderPartOpts,
+  type NavLink,
+  type StickyBehavior,
+} from '../theme/index.js';
+
+describe('chrome-parts builders additive surface', () => {
+  it('exports the frozen A6b PORT surface from theme/index', () => {
+    expect(typeof buildHeaderPart).toBe('function');
+    expect(typeof buildCarriedHeaderPart).toBe('function');
+    expect(typeof buildFooterPart).toBe('function');
+    expect(typeof findChromeMounts).toBe('function');
+    expect(typeof mountPartMarkup).toBe('function');
+  });
+
+  it('freezes public function signatures for the ported builders', () => {
+    expectTypeOf(buildHeaderPart).toEqualTypeOf<
+      (siteTitle: string, nav: NavLink[], pageSlugs: string[], opts?: HeaderPartOpts) => string
+    >();
+    expectTypeOf(buildCarriedHeaderPart).toEqualTypeOf<
+      (header: ChromePartSection, opts?: CarriedHeaderPartOpts) => Promise<string>
+    >();
+    expectTypeOf(buildFooterPart).toEqualTypeOf<
+      (footer: ChromePartSection | null, siteTitle: string, opts?: FooterPartOpts) => Promise<string>
+    >();
+    expectTypeOf(findChromeMounts).toEqualTypeOf<(html: string) => ChromeMounts>();
+    expectTypeOf(mountPartMarkup).toEqualTypeOf<(mount: ChromeMount, sticky?: StickyBehavior) => string>();
+    expectTypeOf<ChromePartConverter>().toEqualTypeOf<(html: string) => string | Promise<string>>();
+  });
+});
diff --git a/packages/blocks-engine/src/theme/chrome-parts-builders.ts b/packages/blocks-engine/src/theme/chrome-parts-builders.ts
new file mode 100644
index 00000000..01a648c7
--- /dev/null
+++ b/packages/blocks-engine/src/theme/chrome-parts-builders.ts
@@ -0,0 +1,101 @@
+import * as cheerio from 'cheerio';
+import type { Element } from 'domhandler';
+
+export interface NavLink {
+  fromSlug: string;
+  toSlug: string;
+  label: string;
+  inNav?: boolean;
+}
+
+export interface StickyBehavior {
+  kind: 'sticky';
+  toggleClass: string;
+  offset: number;
+}
+
+export interface HeaderPartOpts {
+  plain?: boolean;
+  sticky?: StickyBehavior;
+}
+
+export interface ChromePartSection {
+  id: string;
+  role: 'body' | 'header' | 'nav' | 'footer';
+  chromeSource?: 'layout-rail';
+  html: string;
+  classes?: string[];
+}
+
+export type ChromePartConverter = (html: string) => string | Promise<string>;
+
+export interface CarriedHeaderPartOpts {
+  pageSlugs?: string[];
+  sticky?: StickyBehavior;
+  labelToUrl?: (label: string, sourceHref: string) => string | undefined;
+  convertPart?: ChromePartConverter;
+}
+
+export interface FooterPartOpts {
+  pageSlugs?: string[];
+  bgToken?: string;
+  textToken?: string;
+  convertPart?: ChromePartConverter;
+}
+
+export interface ChromeMount {
+  id: string;
+  classes: string[];
+}
+
+export interface ChromeMounts {
+  header?: ChromeMount;
+  footer?: ChromeMount;
+}
+
+export function buildHeaderPart(
+  siteTitle: string,
+  nav: NavLink[],
+  pageSlugs: string[],
+  opts?: HeaderPartOpts
+): string {
+  void siteTitle;
+  void nav;
+  void pageSlugs;
+  void opts;
+  throw new Error('STAGE_STUB: buildHeaderPart');
+}
+
+export async function buildCarriedHeaderPart(
+  header: ChromePartSection,
+  opts?: CarriedHeaderPartOpts
+): Promise<string> {
+  void header;
+  void opts;
+  throw new Error('STAGE_STUB: buildCarriedHeaderPart');
+}
+
+export async function buildFooterPart(
+  footer: ChromePartSection | null,
+  siteTitle: string,
+  opts?: FooterPartOpts
+): Promise<string> {
+  void footer;
+  void siteTitle;
+  void opts;
+  throw new Error('STAGE_STUB: buildFooterPart');
+}
+
+export function findChromeMounts(html: string): ChromeMounts {
+  void cheerio;
+  void html;
+  return {};
+}
+
+export function mountPartMarkup(mount: ChromeMount, sticky?: StickyBehavior): string {
+  void mount;
+  void sticky;
+  throw new Error('STAGE_STUB: mountPartMarkup');
+}
+
+export type { Element as ChromePartElement };
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index ef9c7735..5be97870 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -1,6 +1,13 @@
 export { assemble } from './assemble.js';
 export { assets } from './assets.js';
 export { buildChromePart } from './chrome-parts.js';
+export {
+  buildCarriedHeaderPart,
+  buildFooterPart,
+  buildHeaderPart,
+  findChromeMounts,
+  mountPartMarkup,
+} from './chrome-parts-builders.js';
 export { chrome } from './chrome.js';
 export {
   assignChromeVariants,
@@ -56,6 +63,17 @@ export { writeTheme } from './write-theme.js';
 export type * from './assets-static.js';
 export type * from './assets.js';
 export type { ChromeResult } from './chrome.js';
+export type {
+  CarriedHeaderPartOpts,
+  ChromeMount,
+  ChromeMounts,
+  ChromePartConverter,
+  ChromePartSection,
+  FooterPartOpts,
+  HeaderPartOpts,
+  NavLink,
+  StickyBehavior,
+} from './chrome-parts-builders.js';
 export type { ChromeSlugs } from './chrome-signature.js';
 export type { RegionSplit } from './chrome-split.js';
 export type {

From 7fea7ff87f42fea4838bb1d0a495da1d0f50cd26 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 20:52:25 -0400
Subject: [PATCH 068/113] Add chrome parts builder parity surface

---
 ...theme-chrome-parts-builders-parity.test.ts | 145 ++++++++++++
 .../src/theme/chrome-parts-builders.ts        | 217 ++++++++++++++++--
 2 files changed, 345 insertions(+), 17 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-chrome-parts-builders-parity.test.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-chrome-parts-builders-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-chrome-parts-builders-parity.test.ts
new file mode 100644
index 00000000..a97726d6
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-chrome-parts-builders-parity.test.ts
@@ -0,0 +1,145 @@
+import { describe, expect, it } from 'vitest';
+
+import { blockMarkupRoundtrips } from '../validate.js';
+import {
+  buildCarriedHeaderPart,
+  buildFooterPart,
+  buildHeaderPart,
+  findChromeMounts,
+  mountPartMarkup,
+  type ChromePartConverter,
+  type ChromePartSection,
+  type NavLink,
+} from '../theme/index.js';
+
+describe('chrome-parts builders DLA parity', () => {
+  it('buildHeaderPart emits DLA-faithful native nav markup with inNav preference', () => {
+    const nav: NavLink[] = [
+      { fromSlug: 'home', toSlug: 'home', label: 'Brand Co' },
+      { fromSlug: 'home', toSlug: 'home', label: 'Home', inNav: true },
+      { fromSlug: 'home', toSlug: 'about', label: 'About', inNav: true },
+      { fromSlug: 'home', toSlug: 'services', label: 'inline services link' },
+    ];
+
+    expect(buildHeaderPart('Brand Co', nav, ['home', 'about', 'services'])).toBe(
+      `<!-- wp:group {"align":"full","layout":{"type":"flex","justifyContent":"space-between"},"style":{"spacing":{"padding":{"top":"1rem","bottom":"1rem","left":"1.5rem","right":"1.5rem"}}}} -->\n` +
+        `<div class="wp-block-group alignfull" style="padding-top:1rem;padding-right:1.5rem;padding-bottom:1rem;padding-left:1.5rem">` +
+        `<!-- wp:site-title {"level":0,"className":"brand"} /-->\n` +
+        `<!-- wp:navigation {"overlayMenu":"mobile","layout":{"type":"flex"}} -->\n` +
+        `<!-- wp:navigation-link {"label":"Home","url":"/"} /-->\n` +
+        `<!-- wp:navigation-link {"label":"About","url":"/about/"} /-->\n` +
+        `<!-- /wp:navigation --></div>\n` +
+        `<!-- /wp:group -->`
+    );
+  });
+
+  it('buildCarriedHeaderPart rewrites carried header links before the disclosed convert rewire', async () => {
+    const header: ChromePartSection = {
+      id: 'header',
+      role: 'header',
+      classes: ['bp-header'],
+      html:
+        '<header class="bp-header"><nav><ul>' +
+        '<li><a href="archive.html">Subjects</a></li>' +
+        '<li><a href="archive.html">Community</a></li>' +
+        '<li><a href="page.html">About</a></li>' +
+        '</ul></nav></header>',
+    };
+    const seen: string[] = [];
+    const convertPart: ChromePartConverter = (html) => {
+      seen.push(html);
+      return `<!-- wp:group -->\n<div class="wp-block-group">${html}</div>\n<!-- /wp:group -->`;
+    };
+
+    const html = await buildCarriedHeaderPart(header, {
+      pageSlugs: ['home', 'archive', 'page'],
+      labelToUrl: (label) => {
+        const key = label.toLowerCase().trim();
+        if (key === 'community') return '/category/community/';
+        if (key === 'about') return '/about/';
+        return undefined;
+      },
+      sticky: { kind: 'sticky', toggleClass: 'is-scrolled', offset: 24 },
+      convertPart,
+    });
+
+    expect(seen).toEqual([
+      '<div class="bp-header"><nav><ul><li><a href="/archive/">Subjects</a></li><li><a href="/category/community/">Community</a></li><li><a href="/about/">About</a></li></ul></nav></div>',
+    ]);
+    expect(html).toBe(
+      `<!-- wp:group -->\n` +
+        `<div class="wp-block-group"><div class="bp-header"><nav><ul><li><a href="/archive/">Subjects</a></li><li><a href="/category/community/">Community</a></li><li><a href="/about/">About</a></li></ul></nav></div></div>\n` +
+        `<!-- /wp:group -->\n` +
+        `\n` +
+        `<!-- wp:dla/sticky {"toggleClass":"is-scrolled","offset":24} -->\n` +
+        `<div class="wp-block-dla-sticky" style="display:none" data-wp-interactive="dla/sticky" data-wp-context='{"toggleClass":"is-scrolled","offset":24}' data-wp-init="callbacks.init"></div>\n` +
+        `<!-- /wp:dla/sticky -->`
+    );
+    expect(blockMarkupRoundtrips(html)).toEqual({ ok: true });
+  });
+
+  it('buildFooterPart applies DLA footer normalization, href rewrite, and token wrapper around converted markup', async () => {
+    const footer: ChromePartSection = {
+      id: 'footer',
+      role: 'footer',
+      html: '<footer><p><a href="about.html">About us</a> - <a href="https://x.com">Ext</a></p></footer>',
+    };
+    const seen: string[] = [];
+    const convertPart: ChromePartConverter = (html) => {
+      seen.push(html);
+      return `<!-- wp:paragraph -->\n<p><a href="/about/">About us</a> - <a href="https://x.com">Ext</a></p>\n<!-- /wp:paragraph -->`;
+    };
+
+    const html = await buildFooterPart(footer, 'Acme', {
+      pageSlugs: ['home', 'about'],
+      bgToken: 'surface-inverse',
+      textToken: 'text-inverse',
+      convertPart,
+    });
+
+    expect(seen).toEqual([
+      '<div><p><a href="/about/">About us</a> - <a href="https://x.com">Ext</a></p></div>',
+    ]);
+    expect(html).toBe(
+      `<!-- wp:group {"align":"full","backgroundColor":"surface-inverse","textColor":"text-inverse","layout":{"type":"constrained"},"style":{"spacing":{"padding":{"top":"2.5rem","bottom":"2.5rem"}}}} -->\n` +
+        `<div class="wp-block-group alignfull has-text-inverse-color has-surface-inverse-background-color has-text-color has-background" style="padding-top:2.5rem;padding-bottom:2.5rem">` +
+        `<!-- wp:paragraph -->\n<p><a href="/about/">About us</a> - <a href="https://x.com">Ext</a></p>\n<!-- /wp:paragraph -->` +
+        `</div>\n` +
+        `<!-- /wp:group -->`
+    );
+    expect(blockMarkupRoundtrips(html)).toEqual({ ok: true });
+  });
+
+  it('findChromeMounts discovers DLA JS-rendered chrome mounts around main', () => {
+    const page = `<html><body><div class="page-wrap">
+      <div id="topBanner"><p>Sale</p></div>
+      <div id="siteHeader" class="chrome shell"></div>
+      <main><section id="hero"><h1>Hi</h1><div id="insideMain"></div></section></main>
+      <div id="siteFooter"></div>
+      <div id="lateFooter"></div>
+    </div></body></html>`;
+
+    expect(findChromeMounts(page)).toEqual({
+      header: { id: 'siteHeader', classes: ['chrome', 'shell'] },
+      footer: { id: 'siteFooter', classes: [] },
+    });
+  });
+
+  it('mountPartMarkup emits DLA anchored empty group markup with optional sticky state', () => {
+    const html = mountPartMarkup(
+      { id: 'siteHeader', classes: ['chrome'] },
+      { kind: 'sticky', toggleClass: 'is-scrolled', offset: 24 }
+    );
+
+    expect(html).toBe(
+      `<!-- wp:group {"anchor":"siteHeader","tagName":"div","className":"chrome"} -->\n` +
+        `<div id="siteHeader" class="wp-block-group chrome"></div>\n` +
+        `<!-- /wp:group -->\n` +
+        `\n` +
+        `<!-- wp:dla/sticky {"toggleClass":"is-scrolled","offset":24} -->\n` +
+        `<div class="wp-block-dla-sticky" style="display:none" data-wp-interactive="dla/sticky" data-wp-context='{"toggleClass":"is-scrolled","offset":24}' data-wp-init="callbacks.init"></div>\n` +
+        `<!-- /wp:dla/sticky -->`
+    );
+    expect(blockMarkupRoundtrips(html)).toEqual({ ok: true });
+  });
+});
diff --git a/packages/blocks-engine/src/theme/chrome-parts-builders.ts b/packages/blocks-engine/src/theme/chrome-parts-builders.ts
index 01a648c7..84f3ddf8 100644
--- a/packages/blocks-engine/src/theme/chrome-parts-builders.ts
+++ b/packages/blocks-engine/src/theme/chrome-parts-builders.ts
@@ -1,5 +1,8 @@
 import * as cheerio from 'cheerio';
 import type { Element } from 'domhandler';
+import { convert } from '../convert.js';
+import { escapeHtmlAttr } from '../escape.js';
+import { slugFromRelPath } from './ingest.js';
 
 export interface NavLink {
   fromSlug: string;
@@ -60,19 +63,57 @@ export function buildHeaderPart(
   opts?: HeaderPartOpts
 ): string {
   void siteTitle;
-  void nav;
-  void pageSlugs;
-  void opts;
-  throw new Error('STAGE_STUB: buildHeaderPart');
+  const resolvedOpts = opts ?? {};
+  const links = selectNavLinks(nav, pageSlugs)
+    .map((link) => `<!-- wp:navigation-link {"label":${attrJson(link.label)},"url":${attrJson(link.url)}} /-->`)
+    .join('\n');
+  const siteTitleBlock = `<!-- wp:site-title {"level":0,"className":"brand"} /-->`;
+
+  if (resolvedOpts.plain) {
+    const plainNav =
+      `<!-- wp:navigation {"overlayMenu":"never","layout":{"type":"flex"}} -->\n` +
+      `${links}\n` +
+      `<!-- /wp:navigation -->`;
+    const sticky = resolvedOpts.sticky ? stickyStateBlock(resolvedOpts.sticky) : '';
+    return `${siteTitleBlock}\n${plainNav}${sticky}`;
+  }
+
+  const navBlock =
+    `<!-- wp:navigation {"overlayMenu":"mobile","layout":{"type":"flex"}} -->\n` +
+    `${links}\n` +
+    `<!-- /wp:navigation -->`;
+  return (
+    `<!-- wp:group {"align":"full","layout":{"type":"flex","justifyContent":"space-between"},"style":{"spacing":{"padding":{"top":"1rem","bottom":"1rem","left":"1.5rem","right":"1.5rem"}}}} -->\n` +
+    `<div class="wp-block-group alignfull" style="padding-top:1rem;padding-right:1.5rem;padding-bottom:1rem;padding-left:1.5rem">` +
+    `${siteTitleBlock}\n` +
+    navBlock +
+    `</div>\n` +
+    `<!-- /wp:group -->`
+  );
 }
 
 export async function buildCarriedHeaderPart(
   header: ChromePartSection,
   opts?: CarriedHeaderPartOpts
 ): Promise<string> {
-  void header;
-  void opts;
-  throw new Error('STAGE_STUB: buildCarriedHeaderPart');
+  const resolvedOpts = opts ?? {};
+  let html = header.html;
+  if (resolvedOpts.pageSlugs?.length) html = rewriteInternalHrefs(html, resolvedOpts.pageSlugs);
+  if (resolvedOpts.labelToUrl) {
+    const $ = cheerio.load(html);
+    $('a[href]').each((_, el) => {
+      const label = $(el).text().trim();
+      const href = $(el).attr('href') ?? '';
+      const resolved = resolvedOpts.labelToUrl?.(label, href);
+      if (resolved) $(el).attr('href', resolved);
+    });
+    html = $('body').html() ?? html;
+  }
+
+  const normalizedHtml = html.replace(/^<header(\b[^>]*>)/i, '<div$1').replace(/<\/header>\s*$/i, '</div>');
+  const markup = await convertPartMarkup(normalizedHtml, resolvedOpts.convertPart);
+  const sticky = resolvedOpts.sticky ? `\n${stickyStateBlock(resolvedOpts.sticky)}` : '';
+  return markup + sticky;
 }
 
 export async function buildFooterPart(
@@ -80,22 +121,164 @@ export async function buildFooterPart(
   siteTitle: string,
   opts?: FooterPartOpts
 ): Promise<string> {
-  void footer;
-  void siteTitle;
-  void opts;
-  throw new Error('STAGE_STUB: buildFooterPart');
+  const resolvedOpts = opts ?? {};
+
+  if (footer) {
+    let html = footer.html;
+    if (resolvedOpts.pageSlugs?.length) html = rewriteInternalHrefs(html, resolvedOpts.pageSlugs);
+    const normalizedHtml = html.replace(/^<footer(\b[^>]*>)/i, '<div$1').replace(/<\/footer>\s*$/i, '</div>');
+    const inner = await convertPartMarkup(normalizedHtml, resolvedOpts.convertPart);
+    return wrapFooterGroup(inner, resolvedOpts);
+  }
+
+  return wrapFooterGroup(
+    `<!-- wp:group {"align":"full","layout":{"type":"constrained"},"style":{"spacing":{"padding":{"top":"2rem","bottom":"2rem"}}}} -->\n` +
+      `<div class="wp-block-group alignfull" style="padding-top:2rem;padding-bottom:2rem">` +
+      `<!-- wp:paragraph {"align":"center"} -->\n<p class="has-text-align-center">${escapeHtmlAttr(siteTitle)}</p>\n<!-- /wp:paragraph -->` +
+      `</div>\n` +
+      `<!-- /wp:group -->`,
+    resolvedOpts
+  );
 }
 
 export function findChromeMounts(html: string): ChromeMounts {
-  void cheerio;
-  void html;
-  return {};
+  const $ = cheerio.load(html);
+  const main = $('main').first();
+  if (main.length === 0) return {};
+
+  const all = $('*').toArray() as Element[];
+  const mainIdx = all.indexOf(main.get(0)!);
+  const out: ChromeMounts = {};
+
+  for (const el of all) {
+    if (el.tagName !== 'div') continue;
+    const $el = $(el);
+    const id = $el.attr('id');
+    if (!id) continue;
+    if (main.length && ($.contains(main.get(0)!, el) || main.get(0) === el)) continue;
+    if ($el.children().length > 0 || $el.text().trim()) continue;
+    const idx = all.indexOf(el);
+    const classes = ($el.attr('class') ?? '').split(/\s+/).filter(Boolean);
+    if (idx < mainIdx) {
+      out.header = { id, classes };
+    } else if (!out.footer) {
+      out.footer = { id, classes };
+    }
+  }
+
+  return out;
 }
 
 export function mountPartMarkup(mount: ChromeMount, sticky?: StickyBehavior): string {
-  void mount;
-  void sticky;
-  throw new Error('STAGE_STUB: mountPartMarkup');
+  const cls = mount.classes.join(' ');
+  const pairs = [`"anchor":${attrJson(mount.id)}`, '"tagName":"div"'];
+  if (cls) pairs.push(`"className":${attrJson(cls)}`);
+  const divCls = ['wp-block-group', cls].filter(Boolean).join(' ');
+  const stickyBlock = sticky ? `\n${stickyStateBlock(sticky)}` : '';
+  return (
+    `<!-- wp:group {${pairs.join(',')}} -->\n` +
+    `<div id="${escapeHtmlAttr(mount.id)}" class="${escapeHtmlAttr(divCls)}"></div>\n` +
+    `<!-- /wp:group -->${stickyBlock}`
+  );
 }
 
 export type { Element as ChromePartElement };
+
+function selectNavLinks(nav: NavLink[], pageSlugs: string[]): Array<{ label: string; url: string }> {
+  const fromHome = nav.filter((link) => link.fromSlug === 'home');
+  const pool = fromHome.some((link) => link.inNav) ? fromHome.filter((link) => link.inNav) : fromHome;
+  const seen = new Set<string>();
+  const links: Array<{ label: string; url: string }> = [];
+
+  for (const link of pool) {
+    if (seen.has(link.toSlug)) continue;
+    seen.add(link.toSlug);
+    links.push({ label: link.label || link.toSlug, url: slugToUrl(link.toSlug) });
+  }
+
+  if (links.length > 0) return links;
+  return pageSlugs
+    .filter((slug) => slug !== 'home')
+    .map((slug) => ({
+      label: slug
+        .split('-')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' '),
+      url: slugToUrl(slug),
+    }));
+}
+
+function attrJson(value: string): string {
+  return JSON.stringify(value).replace(/--/g, '\\u002d\\u002d');
+}
+
+function stickyStateBlock(sticky: StickyBehavior): string {
+  const json = `{"toggleClass":${attrJson(sticky.toggleClass)},"offset":${JSON.stringify(sticky.offset)}}`.replace(
+    /'/g,
+    '\\u0027'
+  );
+  return (
+    `\n<!-- wp:dla/sticky ${json} -->\n` +
+    `<div class="wp-block-dla-sticky" style="display:none" data-wp-interactive="dla/sticky"` +
+    ` data-wp-context='${json}' data-wp-init="callbacks.init"></div>\n` +
+    `<!-- /wp:dla/sticky -->`
+  );
+}
+
+function slugToUrl(slug: string): string {
+  return slug === 'home' ? '/' : `/${slug}/`;
+}
+
+function rewriteInternalHrefs(html: string, pageSlugs: string[]): string {
+  const $ = cheerio.load(html);
+  const known = new Set(pageSlugs);
+
+  $('a[href]').each((_, el) => {
+    const raw = $(el).attr('href') ?? '';
+    if (!raw || /^[a-z]+:/i.test(raw) || raw.startsWith('//') || raw.startsWith('#')) return;
+
+    let cleaned = raw.split(/[?#]/)[0];
+    try {
+      cleaned = decodeURIComponent(cleaned);
+    } catch {
+      // Keep malformed escapes in their original source form.
+    }
+
+    const slug = slugFromRelPath(cleaned.replace(/^\.\//, '').replace(/^\//, ''));
+    if (!known.has(slug)) return;
+    $(el).attr('href', slugToUrl(slug));
+  });
+
+  return $('body').html() ?? html;
+}
+
+async function convertPartMarkup(html: string, convertPart?: ChromePartConverter): Promise<string> {
+  const markup = convertPart ? await convertPart(html) : await convert(html, { url: '' });
+  return unwrapHtmlIslands(markup);
+}
+
+function unwrapHtmlIslands(markup: string): string {
+  return markup.replace(/<!-- wp:html(?:\s+\{[\s\S]*?\})? -->\n?([\s\S]*?)\n?<!-- \/wp:html -->/g, (_match, inner: string) =>
+    inner.trim()
+  );
+}
+
+function wrapFooterGroup(inner: string, opts: FooterPartOpts): string {
+  if (!opts.bgToken && !opts.textToken) return inner;
+  const attrs: string[] = ['"align":"full"'];
+  if (opts.bgToken) attrs.push(`"backgroundColor":"${opts.bgToken}"`);
+  if (opts.textToken) attrs.push(`"textColor":"${opts.textToken}"`);
+  attrs.push('"layout":{"type":"constrained"}', '"style":{"spacing":{"padding":{"top":"2.5rem","bottom":"2.5rem"}}}');
+
+  const classes = ['wp-block-group', 'alignfull'];
+  if (opts.textToken) classes.push(`has-${opts.textToken}-color`);
+  if (opts.bgToken) classes.push(`has-${opts.bgToken}-background-color`);
+  if (opts.textToken) classes.push('has-text-color');
+  if (opts.bgToken) classes.push('has-background');
+
+  return (
+    `<!-- wp:group {${attrs.join(',')}} -->\n` +
+    `<div class="${classes.join(' ')}" style="padding-top:2.5rem;padding-bottom:2.5rem">${inner}</div>\n` +
+    `<!-- /wp:group -->`
+  );
+}

From f3593d9cc31a46611ea9be495fc91638cc8cd528 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 20:59:04 -0400
Subject: [PATCH 069/113] chore(blocks-engine): freeze page reconstruct helper
 surface

---
 packages/blocks-engine/src/theme/index.ts     |  7 ++++++
 .../src/theme/page-reconstruct-helpers.ts     | 22 +++++++++++++++++++
 2 files changed, 29 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/page-reconstruct-helpers.ts

diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 5be97870..4c3defa9 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -20,6 +20,12 @@ export { segmentPage } from './segment.js';
 export { foundation } from './foundation.js';
 export { ingest } from './ingest.js';
 export { planTemplates } from './template-plan.js';
+export {
+  normalizeCopy,
+  sanitizePatternHeaderField,
+  sanitizeSvgAsset,
+  stripChrome,
+} from './page-reconstruct-helpers.js';
 export { reconstruct } from './reconstruct.js';
 export {
   buildCoverageIsland,
@@ -92,6 +98,7 @@ export type {
   ThemeFontFamily,
 } from './font-capture.js';
 export type * from './font-faces.js';
+export type { FontFamilyToken } from './page-reconstruct-helpers.js';
 export type { InternalLinkMap } from './url-rewrite.js';
 export type * from './section-spec.js';
 export type * from './source-assets.js';
diff --git a/packages/blocks-engine/src/theme/page-reconstruct-helpers.ts b/packages/blocks-engine/src/theme/page-reconstruct-helpers.ts
new file mode 100644
index 00000000..3bc2469a
--- /dev/null
+++ b/packages/blocks-engine/src/theme/page-reconstruct-helpers.ts
@@ -0,0 +1,22 @@
+import type { SectionSpec } from './section-spec.js';
+
+export interface FontFamilyToken {
+  slug: string;
+  family: string;
+}
+
+export function normalizeCopy(s: string): string {
+  return s;
+}
+
+export function sanitizePatternHeaderField(s: string): string {
+  return s;
+}
+
+export function stripChrome(sections: SectionSpec[]): SectionSpec[] {
+  return sections;
+}
+
+export function sanitizeSvgAsset(svg: string): string {
+  return svg;
+}

From bb061687cbb75eae9a2b10fa8d577648b5504a30 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 21:06:36 -0400
Subject: [PATCH 070/113] Add page reconstruct helper parity surface

---
 ...me-page-reconstruct-helpers-parity.test.ts | 154 ++++++++++++++++++
 .../src/theme/page-reconstruct-helpers.ts     | 109 ++++++++++++-
 2 files changed, 259 insertions(+), 4 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-page-reconstruct-helpers-parity.test.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-page-reconstruct-helpers-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-page-reconstruct-helpers-parity.test.ts
new file mode 100644
index 00000000..8cd39b12
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-page-reconstruct-helpers-parity.test.ts
@@ -0,0 +1,154 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import * as theme from '../theme/index.js';
+import {
+  normalizeCopy,
+  sanitizePatternHeaderField,
+  sanitizeSvgAsset,
+  stripChrome,
+  type FontFamilyToken,
+} from '../theme/index.js';
+import type { SectionSpec } from '../theme/section-spec.js';
+
+function section(partial: Partial<SectionSpec>): SectionSpec {
+  return {
+    sectionIndex: 0,
+    interactionModel: 'static',
+    top: 0,
+    height: 400,
+    headings: [],
+    bodyText: [],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 255,
+    backgroundColor: 'rgb(255, 255, 255)',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: { motionClass: 'none', signals: [], animatedElements: 0 },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: {
+      containerWidth: 1200,
+      padding: '0',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '0',
+    },
+    ...partial,
+  };
+}
+
+describe('page reconstruct helper public surface', () => {
+  it('exports the DLA page-reconstruct helper surface from theme/index', () => {
+    expect(theme).toEqual(
+      expect.objectContaining({
+        normalizeCopy: expect.any(Function),
+        sanitizePatternHeaderField: expect.any(Function),
+        sanitizeSvgAsset: expect.any(Function),
+        stripChrome: expect.any(Function),
+      })
+    );
+
+    expectTypeOf(normalizeCopy).toEqualTypeOf<(s: string) => string>();
+    expectTypeOf(sanitizePatternHeaderField).toEqualTypeOf<(s: string) => string>();
+    expectTypeOf(sanitizeSvgAsset).toEqualTypeOf<(svg: string) => string>();
+    expectTypeOf(stripChrome).toEqualTypeOf<(sections: SectionSpec[]) => SectionSpec[]>();
+    expectTypeOf<FontFamilyToken>().toEqualTypeOf<{ slug: string; family: string }>();
+  });
+
+  it('uses the public FontFamilyToken type shape for registered theme font families', () => {
+    const token: FontFamilyToken = {
+      slug: 'display',
+      family: 'Caldera Display, serif',
+    };
+
+    expect(token).toEqual({
+      slug: 'display',
+      family: 'Caldera Display, serif',
+    });
+  });
+});
+
+describe('normalizeCopy DLA parity', () => {
+  it('collapses whitespace and strips soft-hyphen and zero-width copy noise', () => {
+    expect(normalizeCopy('  foo\u00ad\u200b   bar\n baz ')).toBe('foo bar baz');
+    expect(normalizeCopy('\ufeffA\u200c\tB\u200d\r\nC\u00ad')).toBe('A B C');
+  });
+});
+
+describe('sanitizePatternHeaderField DLA parity', () => {
+  it('strips PHP doc-comment and PHP-tag delimiters without rewriting visible text', () => {
+    expect(sanitizePatternHeaderField('*/ evil(); /*')).toBe('evil();');
+    expect(sanitizePatternHeaderField('a <?php b ?> c')).toBe('a php b  c');
+    expect(sanitizePatternHeaderField('line1\r\nline2\nline3')).toBe('line1 line2 line3');
+    expect(sanitizePatternHeaderField('demo-replica/page-x')).toBe('demo-replica/page-x');
+    expect(sanitizePatternHeaderField('Page \u2014 X')).toBe('Page \u2014 X');
+  });
+});
+
+describe('stripChrome DLA parity', () => {
+  it('drops leading header chrome and trailing footer/nav chrome while preserving middle content', () => {
+    const out = stripChrome([
+      section({
+        sectionIndex: 0,
+        interactionModel: 'static',
+        height: 116,
+        headings: ['Acme Co 555-0142'],
+        bodyText: ['PRODUCTS', 'GALLERY', 'JOB OPPORTUNITIES', 'ABOUT US'],
+      }),
+      section({
+        sectionIndex: 1,
+        height: 760,
+        headings: ['Premium Hardwood'],
+        bodyText: ['A content section that must remain in the reconstructed page body.'],
+      }),
+      section({
+        sectionIndex: 2,
+        backgroundColor: 'rgb(47, 56, 78)',
+        headings: ['100 Night Happiness Guarantee'],
+        bodyText: ['This dark middle band is page content, not sitewide chrome.'],
+      }),
+      section({
+        sectionIndex: 3,
+        interactionModel: 'footer',
+        bodyText: ['PRODUCTS', 'GALLERY', 'CALL US', '\u00a9 2026 Website by Acme Studio'],
+      }),
+      section({
+        sectionIndex: 4,
+        interactionModel: 'nav',
+        bodyText: ['Privacy Policy', 'Terms of Service'],
+      }),
+    ]);
+
+    expect(out.map((s) => s.sectionIndex)).toEqual([1, 2]);
+    expect(out.map((s) => s.headings)).toEqual([
+      ['Premium Hardwood'],
+      ['100 Night Happiness Guarantee'],
+    ]);
+  });
+});
+
+describe('sanitizeSvgAsset DLA parity', () => {
+  it('removes active SVG content and keeps inert icon markup as concrete goldens', () => {
+    expect(
+      sanitizeSvgAsset(
+        '<svg><script>alert(1)</script><foreignObject><p>x</p></foreignObject><path d="M3 9h4"/></svg>'
+      )
+    ).toBe('<svg><path d="M3 9h4"/></svg>');
+
+    expect(
+      sanitizeSvgAsset(
+        '<svg><set attributeName="onload" to="alert(1)"/><animate attributeName="onbegin" to="x"></animate><path onload="evil()" onclick=\'evil2()\' d="M3 9h4"/></svg>'
+      )
+    ).toBe('<svg><path d="M3 9h4"/></svg>');
+
+    expect(
+      sanitizeSvgAsset(
+        '<svg><image href="https://evil.example/x"/><a xlink:href="javascript:alert(1)">x</a><use href="#local-glyph"/><image href="data:image/png;base64,abc"/></svg>'
+      )
+    ).toBe(
+      '<svg><image/><a xlink:href="alert(1)">x</a><use href="#local-glyph"/><image href="data:image/png;base64,abc"/></svg>'
+    );
+  });
+});
diff --git a/packages/blocks-engine/src/theme/page-reconstruct-helpers.ts b/packages/blocks-engine/src/theme/page-reconstruct-helpers.ts
index 3bc2469a..c4430e1b 100644
--- a/packages/blocks-engine/src/theme/page-reconstruct-helpers.ts
+++ b/packages/blocks-engine/src/theme/page-reconstruct-helpers.ts
@@ -1,22 +1,123 @@
 import type { SectionSpec } from './section-spec.js';
 
+/** Registered theme fontFamily token ({slug, family}); used to map a captured
+ *  computed font-family to the nearest registered token (the gate wants a token,
+ *  not a raw family, and the file must be self-hosted). */
 export interface FontFamilyToken {
   slug: string;
   family: string;
 }
 
+/** Collapse whitespace; drop zero-width + soft-hyphen noise. Keeps copy verbatim. */
 export function normalizeCopy(s: string): string {
-  return s;
+  return s
+    .replace(/­/g, '')
+    .replace(/[​-‍]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
 }
 
+/**
+ * Neutralize a value interpolated into the PHP pattern doc-comment header so a
+ * crafted source-derived title/slug cannot break OUT of the doc-comment and
+ * inject executable PHP. A title shaped like a comment-close + code + comment-open
+ * would, in PHP, close the doc-comment early, run the code, then re-open a comment
+ * that swallows the rest through the real header close — a comment-breakout RCE.
+ * (`validate_artifacts` also defends this via a tempered header match, but the
+ * renderer must never EMIT such a header in the first place.) The header is
+ * metadata only, never rendered copy, so stripping comment/PHP-tag delimiters and
+ * collapsing to one line is lossless here.
+ */
 export function sanitizePatternHeaderField(s: string): string {
-  return s;
+  return s
+    .replace(/\*\//g, '') // cannot close the doc-comment early
+    .replace(/\/\*/g, '') // cannot open a nested comment
+    .replace(/<\?/g, '') // no PHP open tag
+    .replace(/\?>/g, '') // no PHP close tag
+    .replace(/[\r\n]+/g, ' ') // single line
+    .trim();
 }
 
+/** Footer/nav chrome detection — the sitewide footer leaks into every page
+ *  capture as trailing sections. We render page body only; header + footer come
+ *  from the theme parts, so a captured footer section must be stripped or the
+ *  page shows TWO footers (the reconstructed one + the theme footer part). */
+function isChromeSection(s: SectionSpec): boolean {
+  if (s.interactionModel === 'footer' || s.interactionModel === 'nav') return true;
+  const heads = s.headings.map((h) => normalizeCopy(h).toLowerCase());
+  const body = (s.bodyText ?? []).map((b) => normalizeCopy(b));
+  const buttons = (s.buttonLabels ?? []).map((b) => normalizeCopy(b));
+  const allText = [...heads, ...body, ...buttons];
+  // GENERIC footer signal: a copyright / attribution line. Only footers carry
+  // "© <year>", "all rights reserved", "website by", "powered by" — and
+  // stripChrome only removes TRAILING sections, so a stray mid-page mention
+  // can't be falsely stripped. (This is what swiftlumber's footer carries:
+  // "© 2026 Website by Tokuda Technology".)
+  const hasCopyright = allText.some((t) =>
+    /(?:©|\(c\)\s|copyright\b|all rights reserved|website by|powered by)/i.test(t),
+  );
+  // getsnooz's footer nav + newsletter (kept for back-compat).
+  const hasFooterNav = heads.includes('shop') && heads.includes('support') && heads.includes('company');
+  const hasNewsletter = body.some((b) => /get some good snooz/i.test(b));
+  return hasCopyright || hasFooterNav || hasNewsletter;
+}
+
+/** Leading site-header chrome: a SHORT top-of-page band dominated by nav links
+ *  (+ logo), with no real prose. When the section detector captures the whole
+ *  page as <section> tiles (flat Wix pages), the header tile arrives as a
+ *  `static` section rather than model `nav`, so the nav-model check alone misses
+ *  it and the page renders the menu/contact block above its content. The theme
+ *  supplies its own header part, so a leading header band is always redundant.
+ *  Guarded by height so a tall hero or content band can never match. */
+function isHeaderChrome(s: SectionSpec): boolean {
+  if (s.interactionModel === 'nav') return true;
+  if (s.height > 200) return false; // headers are thin; heroes/content are tall
+  const body = (s.bodyText ?? []).map((b) => normalizeCopy(b)).filter(Boolean);
+  const heads = s.headings.map((h) => normalizeCopy(h)).filter(Boolean);
+  const shortLinkish = body.filter((b) => b.length <= 30).length;
+  const hasLongProse = [...body, ...heads].some((t) => t.length > 80);
+  return shortLinkish >= 3 && !hasLongProse;
+}
+
+/**
+ * Drop trailing sitewide chrome (footer + newsletter) and leading header/nav.
+ * Only strips from the ends — a dark-bg content band in the page middle (e.g.
+ * the "100 Night Happiness Guarantee" block) is preserved.
+ */
 export function stripChrome(sections: SectionSpec[]): SectionSpec[] {
-  return sections;
+  let start = 0;
+  let end = sections.length;
+  while (start < end && isHeaderChrome(sections[start])) start++;
+  while (end > start && isChromeSection(sections[end - 1])) end--;
+  return sections.slice(start, end);
 }
 
+/**
+ * Sanitize a source-captured inline SVG before it's written as a theme asset and
+ * referenced from a `core/image`. Loading SVG via `<img src>` already prevents
+ * script execution in browsers, but strip active content defensively (the SVG is
+ * source-derived = attacker-controlled per the project trust boundary): no
+ * <script>, <foreignObject>, event-handler attributes, or javascript: URLs.
+ */
 export function sanitizeSvgAsset(svg: string): string {
-  return svg;
+  return (
+    svg
+      .replace(/<script[\s\S]*?<\/script\s*>/gi, '')
+      .replace(/<foreignObject[\s\S]*?<\/foreignObject\s*>/gi, '')
+      // SMIL animation elements can set event-handler attributes at runtime
+      // (e.g. <set attributeName="onload" to="…">) — a direct-navigation XSS
+      // vector that the on*= attribute strip below misses. A static icon glyph
+      // never animates, so drop these wholesale (both self-closing and paired).
+      .replace(/<(set|animate|animateTransform|animateMotion)\b[\s\S]*?(?:\/>|<\/\1\s*>)/gi, '')
+      // External / script href on <a>/<use>/<image> (tracking + SSRF-ish on
+      // direct navigation). Keep local #fragment refs and inline data:image.
+      .replace(
+        /\s(?:xlink:)?href\s*=\s*["']\s*(?:https?:|\/\/|data:(?!image\/))[^"']*["']/gi,
+        '',
+      )
+      .replace(/\son[a-z]+\s*=\s*"[^"]*"/gi, '')
+      .replace(/\son[a-z]+\s*=\s*'[^']*'/gi, '')
+      .replace(/javascript:/gi, '')
+      .trim()
+  );
 }

From fd76e2c758f11ad9ef6da78beab9c4db8f1dc368 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 21:33:42 -0400
Subject: [PATCH 071/113] feat(blocks-engine): align reconstruct converted gate
 with DLA

---
 .../src/__tests__/theme-reconstruct.test.ts   | 159 ++++++++++++++++++
 packages/blocks-engine/src/theme/index.ts     |   2 +-
 .../blocks-engine/src/theme/injection-scan.ts |  10 ++
 .../blocks-engine/src/theme/reconstruct.ts    |  50 +++++-
 4 files changed, 213 insertions(+), 8 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/theme-reconstruct.test.ts b/packages/blocks-engine/src/__tests__/theme-reconstruct.test.ts
index 132896ba..eff833c7 100644
--- a/packages/blocks-engine/src/__tests__/theme-reconstruct.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-reconstruct.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it } from 'vitest';
 import type { WorkerPool } from '../pool/types.js';
 import {
   captureSectionContent,
+  hasUnmigratedRemoteAsset,
   measureSectionCoverage,
   reconstruct,
   type SectionSpec,
@@ -42,6 +43,21 @@ function sectionSpec(overrides: Partial<SectionSpec> = {}): SectionSpec {
   };
 }
 
+function sectionImage(
+  url: string,
+  overrides: Partial<SectionSpec['images'][number]> = {}
+): SectionSpec['images'][number] {
+  return {
+    url,
+    sourceUrl: url,
+    alt: 'Hero image',
+    kind: 'img',
+    width: 1200,
+    height: 800,
+    ...overrides,
+  };
+}
+
 function fakePool(markupForInput: (html: string) => string): WorkerPool {
   return {
     async rawConvert(items: string[]) {
@@ -126,6 +142,149 @@ describe('theme reconstruct coverage gate', () => {
     expect(section.coverage).toBe(1);
   });
 
+  it('falls back from converted native blocks with unmigrated remote assets to an island', async () => {
+    const remoteImage = 'https://cdn.example.com/uploads/hero.jpg';
+    const spec = sectionSpec({
+      headings: ['Remote asset hero'],
+      bodyText: ['Coverage can pass while asset provenance fails.'],
+      images: [sectionImage(remoteImage)],
+      sectionHtml: [
+        '<section>',
+        '<h2>Remote asset hero</h2>',
+        '<p>Coverage can pass while asset provenance fails.</p>',
+        `<img src="${remoteImage}" alt="Hero image">`,
+        '</section>',
+      ].join(''),
+    });
+    const convertedNative = [
+      '<!-- wp:heading -->',
+      '<h2>Remote asset hero</h2>',
+      '<!-- /wp:heading -->',
+      '<!-- wp:paragraph -->',
+      '<p>Coverage can pass while asset provenance fails.</p>',
+      '<!-- /wp:paragraph -->',
+      '<!-- wp:image -->',
+      `<figure class="wp-block-image"><img src="${remoteImage}" alt="Hero image"></figure>`,
+      '<!-- /wp:image -->',
+    ].join('\n');
+
+    expect(hasUnmigratedRemoteAsset(convertedNative)).toBe(true);
+
+    const [section] = await reconstruct(
+      [spec],
+      stageCtx(),
+      fakePool(() => convertedNative),
+      {},
+      0
+    );
+
+    expect(section.blocks).toContain('metadata":{"name":"lib-coverage-island"}');
+    expect(section.blocks).not.toBe(convertedNative);
+    expect(section.coverage).toBe(0);
+  });
+
+  it('falls back from converted native blocks with injection or placeholders to an island', async () => {
+    const injectionSpec = sectionSpec({
+      headings: ['Safe hero'],
+      bodyText: ['Fallback copy survives.'],
+      sectionHtml:
+        '<section><h2>Safe hero</h2><p>Fallback copy survives.</p><script>alert(1)</script></section>',
+    });
+    const injectedNative = [
+      '<!-- wp:heading -->',
+      '<h2>Safe hero</h2>',
+      '<!-- /wp:heading -->',
+      '<!-- wp:paragraph -->',
+      '<p>Fallback copy survives.</p>',
+      '<!-- /wp:paragraph -->',
+      '<script>alert(1)</script>',
+    ].join('\n');
+
+    const [injectedSection] = await reconstruct(
+      [injectionSpec],
+      stageCtx(),
+      fakePool(() => injectedNative),
+      {},
+      0
+    );
+
+    expect(injectedSection.blocks).toContain('metadata":{"name":"lib-coverage-island"}');
+    expect(injectedSection.blocks).toContain('<p>Fallback copy survives.</p>');
+    expect(injectedSection.blocks).not.toContain('<script');
+    expect(injectedSection.blocks).not.toBe(injectedNative);
+
+    const placeholderSpec = sectionSpec({
+      headings: ['Personalized hero'],
+      bodyText: ['Clean fallback copy.'],
+      sectionHtml: '<section><h2>Personalized hero</h2><p>Clean fallback copy.</p></section>',
+    });
+    const placeholderNative = [
+      '<!-- wp:heading -->',
+      '<h2>Personalized hero</h2>',
+      '<!-- /wp:heading -->',
+      '<!-- wp:paragraph -->',
+      '<p>Clean fallback copy.</p>',
+      '<!-- /wp:paragraph -->',
+      '<!-- wp:paragraph -->',
+      '<p>{{first-name}}</p>',
+      '<!-- /wp:paragraph -->',
+    ].join('\n');
+
+    const [placeholderSection] = await reconstruct(
+      [placeholderSpec],
+      stageCtx(),
+      fakePool(() => placeholderNative),
+      {},
+      0
+    );
+
+    expect(placeholderSection.blocks).toContain('metadata":{"name":"lib-coverage-island"}');
+    expect(placeholderSection.blocks).toContain('<p>Clean fallback copy.</p>');
+    expect(placeholderSection.blocks).not.toContain('{{first-name}}');
+    expect(placeholderSection.blocks).not.toBe(placeholderNative);
+  });
+
+  it('keeps converted native blocks when converted coverage matches image basename', async () => {
+    const remoteImage = 'https://cdn.example.com/uploads/hero.jpg?width=1200';
+    const uploadsImage = '/wp-content/uploads/2026/06/hero.jpg';
+    const spec = sectionSpec({
+      headings: ['Native image hero'],
+      bodyText: ['Converted image basename is enough.'],
+      images: [sectionImage(remoteImage)],
+      sectionHtml: [
+        '<section>',
+        '<h2>Native image hero</h2>',
+        '<p>Converted image basename is enough.</p>',
+        `<img src="${remoteImage}" alt="Hero image">`,
+        '</section>',
+      ].join(''),
+    });
+    const nativeBlocks = [
+      '<!-- wp:heading -->',
+      '<h2>Native image hero</h2>',
+      '<!-- /wp:heading -->',
+      '<!-- wp:paragraph -->',
+      '<p>Converted image basename is enough.</p>',
+      '<!-- /wp:paragraph -->',
+      '<!-- wp:image -->',
+      `<figure class="wp-block-image"><img src="${uploadsImage}" alt="Hero image"></figure>`,
+      '<!-- /wp:image -->',
+    ].join('\n');
+
+    const [section] = await reconstruct(
+      [spec],
+      stageCtx(),
+      fakePool(() => nativeBlocks),
+      {},
+      0
+    );
+
+    expect(hasUnmigratedRemoteAsset(nativeBlocks)).toBe(false);
+    expect(section.blocks).toBe(nativeBlocks);
+    expect(section.blocks).not.toContain('lib-coverage-island');
+    expect(section.coverage).toBe(1);
+  });
+
   it('keeps existing onSection coverage-floor gating after fallback', async () => {
     const spec = sectionSpec({
       headings: ['Hooked hero'],
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 4c3defa9..c36df707 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -90,7 +90,7 @@ export type {
 } from './segment.js';
 export type { IslandTier } from './html-fallback.js';
 export { rewriteInternalLinks, rewriteMediaUrls } from './url-rewrite.js';
-export { scanForInjection } from './injection-scan.js';
+export { hasUnmigratedRemoteAsset, scanForInjection } from './injection-scan.js';
 export type { CapturedSectionContent, CoverageResult } from './section-coverage.js';
 export type {
   LocalFontFace,
diff --git a/packages/blocks-engine/src/theme/injection-scan.ts b/packages/blocks-engine/src/theme/injection-scan.ts
index e5d381f3..8c4243a3 100644
--- a/packages/blocks-engine/src/theme/injection-scan.ts
+++ b/packages/blocks-engine/src/theme/injection-scan.ts
@@ -14,3 +14,13 @@ export function scanForInjection(markup: string): string[] {
   }
   return violations;
 }
+
+/** True when markup carries an un-migrated remote asset — a remote <img src> or
+ *  CSS url() that is NOT a /wp-content/uploads/ media-library URL. Shared with the
+ *  blocks reconstructor so it can reject a conversion that would fail this gate. */
+export function hasUnmigratedRemoteAsset(markup: string): boolean {
+  const isMediaLibraryUrl = (u: string): boolean => /\/wp-content\/uploads\//i.test(u);
+  const imgRemote = [...markup.matchAll(/<img\b[^>]*?\bsrc=["']?(https?:\/\/[^"'\s>]+)/gi)].some((m) => !isMediaLibraryUrl(m[1]));
+  const cssRemote = [...markup.matchAll(/url\(\s*['"]?(https?:\/\/[^)'"]+)/gi)].some((m) => !isMediaLibraryUrl(m[1]));
+  return imgRemote || cssRemote;
+}
diff --git a/packages/blocks-engine/src/theme/reconstruct.ts b/packages/blocks-engine/src/theme/reconstruct.ts
index 5c18b1d2..070702ef 100644
--- a/packages/blocks-engine/src/theme/reconstruct.ts
+++ b/packages/blocks-engine/src/theme/reconstruct.ts
@@ -1,13 +1,22 @@
 import { convert } from '../convert.js';
 import { escapeHtmlAttr, escapeHtmlText } from '../escape.js';
 import type { WorkerPool } from '../pool/types.js';
-import { buildCoverageIsland } from './html-fallback.js';
-import { captureSectionContent, measureSectionCoverage } from './section-coverage.js';
+import { buildHtmlFallbackBlock, selectIslandSource, type HtmlFallbackOpts } from './html-fallback.js';
+import { hasUnmigratedRemoteAsset, scanForInjection } from './injection-scan.js';
+import { captureSectionContent, measureConvertedCoverage } from './section-coverage.js';
 import type { SectionSpec, SectionSpecButton, SectionSpecImage } from './section-spec.js';
 import type { SectionBlocks, SiteToThemeHooks, StageCtx } from './types.js';
+import { rewriteMediaUrls } from './url-rewrite.js';
+import type { InternalLinkMap } from './url-rewrite.js';
 
 const BLOCK_COMMENT_RE = /<!--\s+wp:/;
 const HTML_ISLAND_RE = /<!--\s+wp:(?:core\/)?html(?:\s|-->|{)/;
+const UNRESOLVED_PLACEHOLDER_RE = /\{\{[\w -]+\}\}/;
+
+type RewriteCtx = StageCtx & {
+  mediaUrlMap?: Map<string, string>;
+  linkMap?: InternalLinkMap;
+};
 
 function nonEmpty(value: string | null | undefined): string | null {
   const trimmed = value?.trim();
@@ -69,6 +78,33 @@ function skeletonCoverage(blocks: string): number {
   return BLOCK_COMMENT_RE.test(blocks) ? 1 : 0;
 }
 
+function fallbackOptions(ctx: StageCtx): HtmlFallbackOpts {
+  const rewriteCtx = ctx as RewriteCtx;
+  const opts: HtmlFallbackOpts = {};
+  if (rewriteCtx.mediaUrlMap) opts.mediaUrlMap = rewriteCtx.mediaUrlMap;
+  if (rewriteCtx.linkMap) opts.linkMap = rewriteCtx.linkMap;
+  return opts;
+}
+
+function rewriteConvertedMedia(blocks: string, ctx: StageCtx): string {
+  const mediaUrlMap = (ctx as RewriteCtx).mediaUrlMap;
+  return mediaUrlMap && mediaUrlMap.size > 0 ? rewriteMediaUrls(blocks, mediaUrlMap) : blocks;
+}
+
+function convertedOutputLost(spec: SectionSpec, blocks: string): boolean {
+  return (
+    measureConvertedCoverage(captureSectionContent(spec), blocks).lost ||
+    scanForInjection(blocks).length > 0 ||
+    hasUnmigratedRemoteAsset(blocks) ||
+    UNRESOLVED_PLACEHOLDER_RE.test(blocks)
+  );
+}
+
+function buildLossFallback(spec: SectionSpec, ctx: StageCtx): string {
+  const { source } = selectIslandSource(spec);
+  return buildHtmlFallbackBlock(source, fallbackOptions(ctx));
+}
+
 export async function reconstruct(
   specs: SectionSpec[],
   ctx: StageCtx,
@@ -80,11 +116,11 @@ export async function reconstruct(
 
   for (const spec of specs) {
     let blocks = await convert(sectionInputHtml(spec), { url: '' }, { pool });
-    if (
-      !HTML_ISLAND_RE.test(blocks) &&
-      measureSectionCoverage(captureSectionContent(spec), blocks).lost
-    ) {
-      blocks = buildCoverageIsland(spec);
+    if (!HTML_ISLAND_RE.test(blocks)) {
+      blocks = rewriteConvertedMedia(blocks, ctx);
+      if (convertedOutputLost(spec, blocks)) {
+        blocks = buildLossFallback(spec, ctx);
+      }
     }
 
     const section: SectionBlocks = {

From e83b769a788852efc40fab30e5f401c6c183ff0a Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 21:41:38 -0400
Subject: [PATCH 072/113] chore(blocks-engine): freeze form blocks emitter
 surface

---
 packages/blocks-engine/src/theme/form-blocks.ts | 16 ++++++++++++++++
 packages/blocks-engine/src/theme/index.ts       |  2 ++
 2 files changed, 18 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/form-blocks.ts

diff --git a/packages/blocks-engine/src/theme/form-blocks.ts b/packages/blocks-engine/src/theme/form-blocks.ts
new file mode 100644
index 00000000..dd798094
--- /dev/null
+++ b/packages/blocks-engine/src/theme/form-blocks.ts
@@ -0,0 +1,16 @@
+import type { SectionSpecForm, SectionSpecFormField } from './section-spec.js';
+
+export interface FormBlocksResult {
+  /** jetpack/contact-form block markup (wrapper + field blocks + submit button). */
+  markup: string;
+  /** Captured fields that have no in-scope Jetpack equivalent (file, hidden). */
+  skipped: Array<{ kind: SectionSpecFormField['kind']; label: string }>;
+}
+
+/** Field kinds the mapper deliberately does NOT emit (see grammar notes). */
+export const SKIPPED_FIELD_KINDS: ReadonlySet<SectionSpecFormField['kind']> = new Set(['file', 'hidden']);
+
+export function formToBlocks(form: SectionSpecForm): FormBlocksResult {
+  void form;
+  throw new Error('STAGE_STUB formToBlocks');
+}
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index c36df707..eafcd113 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -18,6 +18,7 @@ export {
 export { splitPageChrome } from './chrome-split.js';
 export { segmentPage } from './segment.js';
 export { foundation } from './foundation.js';
+export { formToBlocks, SKIPPED_FIELD_KINDS } from './form-blocks.js';
 export { ingest } from './ingest.js';
 export { planTemplates } from './template-plan.js';
 export {
@@ -98,6 +99,7 @@ export type {
   ThemeFontFamily,
 } from './font-capture.js';
 export type * from './font-faces.js';
+export type { FormBlocksResult } from './form-blocks.js';
 export type { FontFamilyToken } from './page-reconstruct-helpers.js';
 export type { InternalLinkMap } from './url-rewrite.js';
 export type * from './section-spec.js';

From 285820237ccf7f4e4f8958e30383e5c8861574fc Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 21:55:06 -0400
Subject: [PATCH 073/113] feat(blocks-engine): port DLA Jetpack form emitter

---
 .../src/__tests__/theme-contracts.test.ts     | 155 ++++++++++++++++++
 .../blocks-engine/src/theme/form-blocks.ts    | 147 ++++++++++++++++-
 2 files changed, 300 insertions(+), 2 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/theme-contracts.test.ts b/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
index 8159cc42..7bd9e0ed 100644
--- a/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
@@ -3,17 +3,20 @@ import type { WorkerPool } from '../pool/types.js';
 import {
   assemble,
   foundation,
+  formToBlocks,
   ingest,
   planTemplates,
   reconstruct,
   sectionExtract,
   siteToTheme,
+  SKIPPED_FIELD_KINDS,
   writeTheme,
   type AssetFile,
   type AssetInventory,
   type AssetVerdicts,
   type FoundationAggregates,
   type FoundationTokens,
+  type FormBlocksResult,
   type SectionBlocks,
   type SectionSpec,
   type SectionSpecButton,
@@ -306,6 +309,25 @@ type CompileOnlyThemeContractAssignments = {
 
 void (null as never as CompileOnlyThemeContractAssignments);
 
+function formField(
+  partial: Partial<SectionSpecFormField> & Pick<SectionSpecFormField, 'kind' | 'label'>,
+): SectionSpecFormField {
+  return { required: false, ...partial };
+}
+
+function sectionForm(fields: SectionSpecFormField[], submitLabel = 'Send'): SectionSpecForm {
+  return { fields, submitLabel };
+}
+
+function assertBalanced(markup: string): void {
+  const stack: string[] = [];
+  for (const m of markup.matchAll(/<!--\s*(\/)?wp:([a-z0-9/-]+)([^>]*?)(\/)?-->/g)) {
+    if (m[1]) expect(stack.pop()).toBe(m[2]);
+    else if (m[4] !== '/') stack.push(m[2]);
+  }
+  expect(stack).toEqual([]);
+}
+
 describe('theme public contract', () => {
   it('exports runtime stage functions with fixed arity', () => {
     const runtimeStages = [
@@ -324,4 +346,137 @@ describe('theme public contract', () => {
       expect(stage).toHaveLength(expectedArity);
     }
   });
+
+});
+
+describe('formToBlocks DLA parity', () => {
+  it('exports the DLA form-blocks surface and emits jetpack/field-* blocks for every mapped field kind', () => {
+    const formToBlocksType: (form: SectionSpecForm) => FormBlocksResult = formToBlocks;
+    void formToBlocksType;
+
+    expect(formToBlocks).toBeTypeOf('function');
+    expect(SKIPPED_FIELD_KINDS.has('file')).toBe(true);
+    expect(SKIPPED_FIELD_KINDS.has('hidden')).toBe(true);
+
+    const expected: Array<[SectionSpecFormField['kind'], string]> = [
+      ['text', '<!-- wp:jetpack/field-text {"label":"Fictional label"} /-->'],
+      ['name', '<!-- wp:jetpack/field-name {"label":"Fictional label"} /-->'],
+      ['email', '<!-- wp:jetpack/field-email {"label":"Fictional label"} /-->'],
+      ['tel', '<!-- wp:jetpack/field-telephone {"label":"Fictional label"} /-->'],
+      ['url', '<!-- wp:jetpack/field-url {"label":"Fictional label"} /-->'],
+      ['number', '<!-- wp:jetpack/field-number {"label":"Fictional label"} /-->'],
+      ['date', '<!-- wp:jetpack/field-date {"label":"Fictional label"} /-->'],
+      ['textarea', '<!-- wp:jetpack/field-textarea {"label":"Fictional label"} /-->'],
+      ['checkbox', '<!-- wp:jetpack/field-checkbox {"label":"Fictional label"} /-->'],
+      ['consent', '<!-- wp:jetpack/field-consent {"label":"Fictional label","consentType":"implicit"} /-->'],
+    ];
+
+    for (const [kind, golden] of expected) {
+      expect(formToBlocks(sectionForm([formField({ kind, label: 'Fictional label' })])).markup).toContain(golden);
+    }
+  });
+
+  it('keeps authored options in DLA attr grammar for radio, select, and checkbox groups', () => {
+    const radio = formToBlocks(
+      sectionForm([formField({ kind: 'radio', label: 'Size', options: ['Small', 'Large', 'Medium'] })]),
+    );
+    const select = formToBlocks(
+      sectionForm([formField({ kind: 'select', label: 'Topic', options: ['Billing', 'Support', 'Other'] })]),
+    );
+    const checkbox = formToBlocks(
+      sectionForm([formField({ kind: 'checkbox', label: 'Classes', options: ['Yoga', 'Pilates'] })]),
+    );
+
+    expect(radio.markup).toContain(
+      '<!-- wp:jetpack/field-radio {"label":"Size","options":["Small","Large","Medium"]} /-->',
+    );
+    expect(select.markup).toContain(
+      '<!-- wp:jetpack/field-select {"label":"Topic","options":["Billing","Support","Other"]} /-->',
+    );
+    expect(checkbox.markup).toContain(
+      '<!-- wp:jetpack/field-checkbox-multiple {"label":"Classes","options":["Yoga","Pilates"]} /-->',
+    );
+    expect(checkbox.markup).not.toContain('wp:jetpack/field-checkbox {');
+  });
+
+  it('emits the Jetpack wrapper and canonical core/button submit with the label in inner HTML', () => {
+    const result = formToBlocks(sectionForm([formField({ kind: 'email', label: 'Email' })], 'Request a Quote'));
+
+    expect(result.markup.startsWith('<!-- wp:jetpack/contact-form ')).toBe(true);
+    expect(result.markup).toContain('<div class="wp-block-jetpack-contact-form">');
+    expect(result.markup).toContain(
+      '<!-- wp:button {"tagName":"button","type":"submit","lock":{"remove":true},"className":"form-button-submit is-submit","metadata":{"name":"Submit button"}} -->\n' +
+        '<div class="wp-block-button form-button-submit is-submit"><button type="submit" class="wp-block-button__link wp-element-button">Request a Quote</button></div>\n' +
+        '<!-- /wp:button -->',
+    );
+    expect(result.markup).not.toContain('jetpack/button');
+    expect(result.markup).not.toContain('wp:columns');
+    assertBalanced(result.markup);
+  });
+
+  it('matches the DLA multi-field golden, including stable attr order and skipped fields', () => {
+    const result = formToBlocks(
+      sectionForm(
+        [
+          formField({ kind: 'name', label: 'Name', required: true, widthPct: 50 }),
+          formField({ kind: 'email', label: 'Email', required: true, placeholder: 'you@example.com', widthPct: 50 }),
+          formField({ kind: 'select', label: 'Topic', options: ['Billing', 'Support'] }),
+          formField({ kind: 'textarea', label: 'Message', defaultValue: 'Hello' }),
+          formField({ kind: 'consent', label: 'I agree to the privacy policy' }),
+          formField({ kind: 'file', label: 'Resume upload' }),
+          formField({ kind: 'hidden', label: 'Campaign id' }),
+        ],
+        'Send Message',
+      ),
+    );
+
+    expect(result.markup).toBe(
+      '<!-- wp:jetpack/contact-form {"style":{"spacing":{"padding":{"top":"16px","right":"16px","bottom":"16px","left":"16px"}}}} -->\n' +
+        '<div class="wp-block-jetpack-contact-form">\n' +
+        '<!-- wp:jetpack/field-name {"label":"Name","required":true,"width":50} /-->\n' +
+        '<!-- wp:jetpack/field-email {"label":"Email","required":true,"placeholder":"you@example.com","width":50} /-->\n' +
+        '<!-- wp:jetpack/field-select {"label":"Topic","options":["Billing","Support"]} /-->\n' +
+        '<!-- wp:jetpack/field-textarea {"label":"Message","defaultValue":"Hello"} /-->\n' +
+        '<!-- wp:jetpack/field-consent {"label":"I agree to the privacy policy","consentType":"implicit"} /-->\n' +
+        '<!-- wp:button {"tagName":"button","type":"submit","lock":{"remove":true},"className":"form-button-submit is-submit","metadata":{"name":"Submit button"}} -->\n' +
+        '<div class="wp-block-button form-button-submit is-submit"><button type="submit" class="wp-block-button__link wp-element-button">Send Message</button></div>\n' +
+        '<!-- /wp:button -->\n' +
+        '</div>\n' +
+        '<!-- /wp:jetpack/contact-form -->',
+    );
+    expect(result.skipped).toEqual([
+      { kind: 'file', label: 'Resume upload' },
+      { kind: 'hidden', label: 'Campaign id' },
+    ]);
+    expect(result.markup).not.toContain('Resume upload');
+    expect(result.markup).not.toContain('Campaign id');
+  });
+
+  it('matches the DLA zero-field golden and escapes hostile labels like the DLA serializer', () => {
+    const result = formToBlocks(sectionForm([], 'Continue'));
+
+    expect(result.markup).toBe(
+      '<!-- wp:jetpack/contact-form {"style":{"spacing":{"padding":{"top":"16px","right":"16px","bottom":"16px","left":"16px"}}}} -->\n' +
+        '<div class="wp-block-jetpack-contact-form">\n' +
+        '<!-- wp:button {"tagName":"button","type":"submit","lock":{"remove":true},"className":"form-button-submit is-submit","metadata":{"name":"Submit button"}} -->\n' +
+        '<div class="wp-block-button form-button-submit is-submit"><button type="submit" class="wp-block-button__link wp-element-button">Continue</button></div>\n' +
+        '<!-- /wp:button -->\n' +
+        '</div>\n' +
+        '<!-- /wp:jetpack/contact-form -->',
+    );
+    expect(result.markup).not.toContain('wp:jetpack/field-');
+    expect(result.skipped).toEqual([]);
+    assertBalanced(result.markup);
+
+    const escaped = formToBlocks(
+      sectionForm([formField({ kind: 'text', label: 'a --> b & <c> "d"' })], 'Send --> & <go>'),
+    );
+
+    expect(escaped.markup).toContain(
+      '<!-- wp:jetpack/field-text {"label":"a \\u002d\\u002d\\u003e b \\u0026 \\u003cc\\u003e \\u0022d\\u0022"} /-->',
+    );
+    expect(escaped.markup).toContain('>Send --&gt; &amp; &lt;go&gt;</button>');
+    expect(escaped.markup).not.toContain('--\\u003e');
+    assertBalanced(escaped.markup);
+  });
 });
diff --git a/packages/blocks-engine/src/theme/form-blocks.ts b/packages/blocks-engine/src/theme/form-blocks.ts
index dd798094..d9787f62 100644
--- a/packages/blocks-engine/src/theme/form-blocks.ts
+++ b/packages/blocks-engine/src/theme/form-blocks.ts
@@ -1,3 +1,47 @@
+//
+// Form blocks — captured form → jetpack/contact-form markup
+// ==========================================================
+// Pure mapper from a captured `SectionSpecForm` (section-extract.ts) to
+// Jetpack Forms block markup, so a source site's form reconstructs as a LIVE
+// form (submissions land in the local feedback CPT) instead of a dead
+// core/html island posting to the defunct source backend.
+//
+// Grammar notes (verified against current Jetpack, packages/forms/src/blocks):
+//   - The container is `jetpack/contact-form`; its save output wraps inner
+//     blocks in `<div class="wp-block-jetpack-contact-form">`.
+//   - Field blocks are SELF-CLOSING comments (`<!-- wp:jetpack/field-* {...} /-->`);
+//     the blocks are server-rendered, so all data rides in the comment attrs.
+//   - The submit is a `core/button` (`tagName:"button"`, `type:"submit"`,
+//     className `form-button-submit is-submit`) INSIDE the form wrapper — this
+//     is EXACTLY what the current Jetpack form editor inserts (jetpack-forms
+//     dist/blocks/editor.js: `["core/button",{tagName:"button",type:"submit",
+//     className:"form-button-submit is-submit",...}]`; the form-editor's
+//     allowed-blocks list annotates core/button "Used for the submit button"
+//     and jetpack/button "previously"). The label rides in the saved inner
+//     HTML (core/button `text` is HTML-sourced, never a comment attr).
+//     NOT `jetpack/button`: that block lives in Jetpack's connection-gated
+//     extensions loader and is UNREGISTERED on unconnected installs — an
+//     attrs-only self-closing `wp:jetpack/button` then renders to nothing, the
+//     form misses the `wp-block-button` marker, and Contact_Form falls back to
+//     a server-built legacy button labeled "Submit" (the captured label is
+//     lost). Contact_Form::prepare_submit_button wires the interactivity attrs
+//     onto any `<button type="submit">`/`.is-submit`, so the core/button
+//     submit triggers the Jetpack handler. Side-by-side fields use the field
+//     `width` attr (25|50|75|100) — NEVER `wp:columns`.
+//   - `number` → `jetpack/field-number`: the block exists in current Jetpack
+//     (forms blocks README lists it). We auto-install CURRENT Jetpack via
+//     ensurePlugin, so the older-versions gap doesn't apply here.
+//   - A captured `checkbox` WITH `options` is a collapsed same-name checkbox
+//     GROUP (buildSectionForms) — that maps to `jetpack/field-checkbox-multiple`
+//     (Jetpack's checkbox-group block); the single-box `jetpack/field-checkbox`
+//     has no options grammar and would lose the choices.
+//   - `file` is SKIPPED (Jetpack's field-file has paid-plan requirements) and
+//     `hidden` is SKIPPED (no UI; nothing visible to reproduce). Both are
+//     returned in `skipped` so the caller can record provenance flags.
+//   - `radio`/`select` use the long-standing `options` ATTR grammar (the plan's
+//     mapping). Newer Jetpack editors migrate it to inner option blocks on
+//     first edit; the server render accepts the attr form.
+//
 import type { SectionSpecForm, SectionSpecFormField } from './section-spec.js';
 
 export interface FormBlocksResult {
@@ -10,7 +54,106 @@ export interface FormBlocksResult {
 /** Field kinds the mapper deliberately does NOT emit (see grammar notes). */
 export const SKIPPED_FIELD_KINDS: ReadonlySet<SectionSpecFormField['kind']> = new Set(['file', 'hidden']);
 
+/** kind → jetpack block name for the simple (no-options) field kinds. */
+const FIELD_BLOCK_BY_KIND: Partial<Record<SectionSpecFormField['kind'], string>> = {
+  text: 'jetpack/field-text',
+  name: 'jetpack/field-name',
+  email: 'jetpack/field-email',
+  tel: 'jetpack/field-telephone',
+  url: 'jetpack/field-url',
+  number: 'jetpack/field-number',
+  date: 'jetpack/field-date',
+  textarea: 'jetpack/field-textarea',
+  radio: 'jetpack/field-radio',
+  select: 'jetpack/field-select',
+  consent: 'jetpack/field-consent',
+};
+
+/**
+ * Serialize block comment attrs exactly like @wordpress/blocks
+ * `serializeAttributes`: JSON with the characters that could terminate the
+ * comment delimiter (or smuggle markup) unicode-escaped. Keeps a crafted
+ * source label (e.g. containing `-->`) from breaking out of the comment.
+ * Exported for variation-hoist, which rewrites existing comment attrs and must
+ * not lose this escaping (JSON.parse decodes `--` to literal `--`).
+ */
+export function serializeBlockAttrs(attrs: Record<string, unknown>): string {
+  return JSON.stringify(attrs)
+    .replace(/--/g, '\\u002d\\u002d')
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\\"/g, '\\u0022');
+}
+
+/** Escape text for HTML element content (the submit label rides in the
+ *  core/button's saved inner HTML, not in comment attrs). */
+function escapeHtmlText(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function fieldBlock(f: SectionSpecFormField): string {
+  // A captured checkbox carrying options is a collapsed checkbox GROUP.
+  const blockName =
+    f.kind === 'checkbox'
+      ? f.options && f.options.length > 0
+        ? 'jetpack/field-checkbox-multiple'
+        : 'jetpack/field-checkbox'
+      : FIELD_BLOCK_BY_KIND[f.kind];
+  if (!blockName) throw new Error(`formToBlocks: unmapped field kind "${f.kind}"`);
+
+  // Only set keys that have values; stable key order keeps output deterministic.
+  const attrs: Record<string, unknown> = { label: f.label };
+  if (f.required) attrs.required = true;
+  if (f.placeholder) attrs.placeholder = f.placeholder;
+  if (f.defaultValue) attrs.defaultValue = f.defaultValue;
+  if (f.options && f.options.length > 0 && blockName !== 'jetpack/field-checkbox') attrs.options = f.options;
+  // width:100 is the Jetpack default — the editor only serializes width when
+  // changed, so omitting it matches canonical grammar (and keeps markup clean).
+  if (typeof f.widthPct === 'number' && f.widthPct !== 100) attrs.width = f.widthPct;
+  if (f.kind === 'consent') attrs.consentType = 'implicit';
+
+  return `<!-- wp:${blockName} ${serializeBlockAttrs(attrs)} /-->`;
+}
+
+/**
+ * Map one captured form to jetpack/contact-form block markup.
+ *
+ * Determinism: two calls with the same form are byte-identical (no ids, no
+ * randomness — replay-stable per repo conventions).
+ */
 export function formToBlocks(form: SectionSpecForm): FormBlocksResult {
-  void form;
-  throw new Error('STAGE_STUB formToBlocks');
+  const skipped: FormBlocksResult['skipped'] = [];
+  const fieldMarkup: string[] = [];
+  for (const f of form.fields) {
+    if (SKIPPED_FIELD_KINDS.has(f.kind)) {
+      skipped.push({ kind: f.kind, label: f.label });
+      continue;
+    }
+    fieldMarkup.push(fieldBlock(f));
+  }
+
+  // Submit button: canonical core/button save markup (attr order + classes
+  // byte-match @wordpress/blocks serialize(), so the block-fixer round-trip is
+  // a no-op and the editor validates it). See grammar notes above for why this
+  // is core/button and not jetpack/button.
+  const button =
+    '<!-- wp:button {"tagName":"button","type":"submit","lock":{"remove":true},"className":"form-button-submit is-submit","metadata":{"name":"Submit button"}} -->\n' +
+    `<div class="wp-block-button form-button-submit is-submit"><button type="submit" class="wp-block-button__link wp-element-button">${escapeHtmlText(form.submitLabel)}</button></div>\n` +
+    '<!-- /wp:button -->';
+
+  // Wrapper spacing mirrors Jetpack's inserted default (style.spacing only —
+  // the design spec confines wrapper styling to spacing).
+  const wrapperAttrs = serializeBlockAttrs({
+    style: { spacing: { padding: { top: '16px', right: '16px', bottom: '16px', left: '16px' } } },
+  });
+
+  const markup =
+    `<!-- wp:jetpack/contact-form ${wrapperAttrs} -->\n` +
+    `<div class="wp-block-jetpack-contact-form">\n` +
+    [...fieldMarkup, button].join('\n') +
+    `\n</div>\n` +
+    `<!-- /wp:jetpack/contact-form -->`;
+
+  return { markup, skipped };
 }

From e8b4acfd38893580542d0a7673ff8327721e26d0 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 22:01:43 -0400
Subject: [PATCH 074/113] chore(blocks-engine): freeze fallback diagnostic
 surface

---
 .../src/theme/fallback-diagnostic.ts          | 52 +++++++++++++++++++
 packages/blocks-engine/src/theme/index.ts     |  2 +
 2 files changed, 54 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/fallback-diagnostic.ts

diff --git a/packages/blocks-engine/src/theme/fallback-diagnostic.ts b/packages/blocks-engine/src/theme/fallback-diagnostic.ts
new file mode 100644
index 00000000..c710a97a
--- /dev/null
+++ b/packages/blocks-engine/src/theme/fallback-diagnostic.ts
@@ -0,0 +1,52 @@
+import type { CoverageResult } from './section-coverage.js';
+import type { SectionSpec } from './section-spec.js';
+
+export type FallbackReasonCode = 'dropped_images' | 'text_coverage_below_floor' | 'decorative_asset_triaged';
+export type FallbackRepairClass = 'recover_dropped_media' | 'restructure_section_blocks' | 'replace_with_structural_block';
+
+export interface FallbackDiagnostic {
+  id: string;
+  page: string;
+  sectionIndex: number;
+  interactionModel: string;
+  selector: string;
+  severity: 'warning';
+  reasonCode: FallbackReasonCode;
+  /** 'none' = not an island record (decorative_asset_triaged removals). */
+  islandKind: 'verbatim' | 'styled' | 'responsive' | 'none';
+  droppedImages: string[];
+  textCoverage: number;
+  suggestedRepairClass: FallbackRepairClass;
+  sourceHtmlPreview: string;
+  emittedBlockPreview: string;
+}
+
+export interface AssetRemoval {
+  url: string;
+  sectionSelector: string;
+  description: string;
+}
+
+export function buildFallbackDiagnostic(args: {
+  page: string;
+  slug: string;
+  section: SectionSpec;
+  coverage: CoverageResult;
+  islandKind: 'verbatim' | 'styled' | 'responsive';
+  islandMarkup: string;
+}): FallbackDiagnostic {
+  void args;
+  throw new Error('buildFallbackDiagnostic implementation pending');
+}
+
+export function buildTriageRemovalDiagnostic(args: {
+  page: string;
+  slug: string;
+  sectionIndex: number;
+  interactionModel: string;
+  removal: AssetRemoval;
+  ordinal: number;
+}): FallbackDiagnostic {
+  void args;
+  throw new Error('buildTriageRemovalDiagnostic implementation pending');
+}
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index eafcd113..640a1232 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -18,6 +18,7 @@ export {
 export { splitPageChrome } from './chrome-split.js';
 export { segmentPage } from './segment.js';
 export { foundation } from './foundation.js';
+export { buildFallbackDiagnostic, buildTriageRemovalDiagnostic } from './fallback-diagnostic.js';
 export { formToBlocks, SKIPPED_FIELD_KINDS } from './form-blocks.js';
 export { ingest } from './ingest.js';
 export { planTemplates } from './template-plan.js';
@@ -90,6 +91,7 @@ export type {
   SectionRole,
 } from './segment.js';
 export type { IslandTier } from './html-fallback.js';
+export type * from './fallback-diagnostic.js';
 export { rewriteInternalLinks, rewriteMediaUrls } from './url-rewrite.js';
 export { hasUnmigratedRemoteAsset, scanForInjection } from './injection-scan.js';
 export type { CapturedSectionContent, CoverageResult } from './section-coverage.js';

From 90d832965f2343f7d052f752038400240982c9a6 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 24 Jun 2026 22:15:38 -0400
Subject: [PATCH 075/113] feat(blocks-engine): port DLA fallback diagnostics

---
 .../src/__tests__/theme-contracts.test.ts     | 210 ++++++++++++++++++
 .../src/theme/fallback-diagnostic.ts          |  51 ++++-
 2 files changed, 257 insertions(+), 4 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/theme-contracts.test.ts b/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
index 7bd9e0ed..b14a445d 100644
--- a/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
@@ -2,6 +2,8 @@ import { describe, expect, it } from 'vitest';
 import type { WorkerPool } from '../pool/types.js';
 import {
   assemble,
+  buildFallbackDiagnostic,
+  buildTriageRemovalDiagnostic,
   foundation,
   formToBlocks,
   ingest,
@@ -14,6 +16,7 @@ import {
   type AssetFile,
   type AssetInventory,
   type AssetVerdicts,
+  type CoverageResult,
   type FoundationAggregates,
   type FoundationTokens,
   type FormBlocksResult,
@@ -328,6 +331,36 @@ function assertBalanced(markup: string): void {
   expect(stack).toEqual([]);
 }
 
+function diagnosticSection(partial: Partial<SectionSpec> = {}): SectionSpec {
+  return {
+    sectionIndex: 0,
+    interactionModel: 'static',
+    top: 0,
+    height: 100,
+    headings: [],
+    bodyText: [],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 1,
+    backgroundColor: '#ffffff',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: { motionClass: 'none', signals: [], animatedElements: 0 },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: { containerWidth: 960, padding: '0', childLayout: 'stack', columnCount: 1, gap: '0' },
+    cells: [],
+    forms: [],
+    sectionHtml: '<section></section>',
+    ...partial,
+  };
+}
+
+function diagnosticCoverage(partial: Partial<CoverageResult> = {}): CoverageResult {
+  return { textCoverage: 1, missingImages: [], lost: false, ...partial };
+}
+
 describe('theme public contract', () => {
   it('exports runtime stage functions with fixed arity', () => {
     const runtimeStages = [
@@ -349,6 +382,183 @@ describe('theme public contract', () => {
 
 });
 
+describe('fallback diagnostics DLA parity', () => {
+  it('emits dropped_images reasonCode with media-first precedence when text coverage is also below floor', () => {
+    const section = diagnosticSection({
+      sectionIndex: 7,
+      interactionModel: 'media-text',
+      selector: '#hero',
+      sectionHtml: '<section class="hero-source"><h1>Launch faster</h1><p>Proof copy</p></section>',
+      styledHtml: '<section class="hero"><h1>Launch faster</h1><p>Proof copy</p></section>',
+    });
+
+    expect(
+      buildFallbackDiagnostic({
+        page: '/home',
+        slug: 'home',
+        section,
+        coverage: diagnosticCoverage({
+          textCoverage: 0.333,
+          missingImages: ['https://cdn.example.com/hero.jpg'],
+          lost: true,
+        }),
+        islandKind: 'styled',
+        islandMarkup: '<!-- wp:html --><div><p>Launch</p></div><!-- /wp:html -->',
+      }),
+    ).toEqual({
+      id: 'home-s7-dropped_images',
+      page: '/home',
+      sectionIndex: 7,
+      interactionModel: 'media-text',
+      selector: '#hero',
+      severity: 'warning',
+      reasonCode: 'dropped_images',
+      islandKind: 'styled',
+      droppedImages: ['https://cdn.example.com/hero.jpg'],
+      textCoverage: 0.33,
+      suggestedRepairClass: 'recover_dropped_media',
+      sourceHtmlPreview: '<section class="hero"><h1>Launch faster</h1><p>Proof copy</p></section>',
+      emittedBlockPreview: '<!-- wp:html --><div><p>Launch</p></div><!-- /wp:html -->',
+    });
+  });
+
+  it('emits text_coverage_below_floor reasonCode when text is below the DLA floor without dropped media', () => {
+    const section = diagnosticSection({
+      sectionIndex: 3,
+      interactionModel: 'cta',
+      selector: '.cta',
+      sectionHtml: '<section><h2>Book now</h2><p>Schedule a repair.</p></section>',
+    });
+
+    expect(
+      buildFallbackDiagnostic({
+        page: '/service',
+        slug: 'service',
+        section,
+        coverage: diagnosticCoverage({
+          textCoverage: 0.494,
+          lost: true,
+        }),
+        islandKind: 'verbatim',
+        islandMarkup: '<!-- wp:paragraph --><p>Book now</p><!-- /wp:paragraph -->',
+      }),
+    ).toEqual({
+      id: 'service-s3-text_coverage_below_floor',
+      page: '/service',
+      sectionIndex: 3,
+      interactionModel: 'cta',
+      selector: '.cta',
+      severity: 'warning',
+      reasonCode: 'text_coverage_below_floor',
+      islandKind: 'verbatim',
+      droppedImages: [],
+      textCoverage: 0.49,
+      suggestedRepairClass: 'restructure_section_blocks',
+      sourceHtmlPreview: '<section><h2>Book now</h2><p>Schedule a repair.</p></section>',
+      emittedBlockPreview: '<!-- wp:paragraph --><p>Book now</p><!-- /wp:paragraph -->',
+    });
+  });
+
+  it('passes through verbatim, styled, and responsive islandKind classifications', () => {
+    const islandKinds = ['verbatim', 'styled', 'responsive'] as const;
+
+    expect(
+      islandKinds.map((islandKind, index) =>
+        buildFallbackDiagnostic({
+          page: '/landing',
+          slug: 'landing',
+          section: diagnosticSection({
+            sectionIndex: index,
+            interactionModel: 'static',
+            selector: `.section-${index}`,
+            sectionHtml: `<section><p>Section ${index}</p></section>`,
+          }),
+          coverage: diagnosticCoverage({ textCoverage: 0.25, lost: true }),
+          islandKind,
+          islandMarkup: `<p>Island ${index}</p>`,
+        }),
+      ),
+    ).toEqual([
+      {
+        id: 'landing-s0-text_coverage_below_floor',
+        page: '/landing',
+        sectionIndex: 0,
+        interactionModel: 'static',
+        selector: '.section-0',
+        severity: 'warning',
+        reasonCode: 'text_coverage_below_floor',
+        islandKind: 'verbatim',
+        droppedImages: [],
+        textCoverage: 0.25,
+        suggestedRepairClass: 'restructure_section_blocks',
+        sourceHtmlPreview: '<section><p>Section 0</p></section>',
+        emittedBlockPreview: '<p>Island 0</p>',
+      },
+      {
+        id: 'landing-s1-text_coverage_below_floor',
+        page: '/landing',
+        sectionIndex: 1,
+        interactionModel: 'static',
+        selector: '.section-1',
+        severity: 'warning',
+        reasonCode: 'text_coverage_below_floor',
+        islandKind: 'styled',
+        droppedImages: [],
+        textCoverage: 0.25,
+        suggestedRepairClass: 'restructure_section_blocks',
+        sourceHtmlPreview: '<section><p>Section 1</p></section>',
+        emittedBlockPreview: '<p>Island 1</p>',
+      },
+      {
+        id: 'landing-s2-text_coverage_below_floor',
+        page: '/landing',
+        sectionIndex: 2,
+        interactionModel: 'static',
+        selector: '.section-2',
+        severity: 'warning',
+        reasonCode: 'text_coverage_below_floor',
+        islandKind: 'responsive',
+        droppedImages: [],
+        textCoverage: 0.25,
+        suggestedRepairClass: 'restructure_section_blocks',
+        sourceHtmlPreview: '<section><p>Section 2</p></section>',
+        emittedBlockPreview: '<p>Island 2</p>',
+      },
+    ]);
+  });
+
+  it('matches the DLA decorative_asset_triaged diagnostic record shape', () => {
+    expect(
+      buildTriageRemovalDiagnostic({
+        page: '/about',
+        slug: 'about',
+        sectionIndex: 2,
+        interactionModel: 'static',
+        removal: {
+          url: 'https://cdn.example.com/divider.png',
+          sectionSelector: 'section:nth-of-type(3)',
+          description: 'Thin gold divider line between testimonials.',
+        },
+        ordinal: 1,
+      }),
+    ).toEqual({
+      id: 'about-s2-decorative_asset_triaged-1',
+      page: '/about',
+      sectionIndex: 2,
+      interactionModel: 'static',
+      selector: 'section:nth-of-type(3)',
+      severity: 'warning',
+      reasonCode: 'decorative_asset_triaged',
+      islandKind: 'none',
+      droppedImages: ['https://cdn.example.com/divider.png'],
+      textCoverage: 1,
+      suggestedRepairClass: 'replace_with_structural_block',
+      sourceHtmlPreview: 'Thin gold divider line between testimonials.',
+      emittedBlockPreview: '',
+    });
+  });
+});
+
 describe('formToBlocks DLA parity', () => {
   it('exports the DLA form-blocks surface and emits jetpack/field-* blocks for every mapped field kind', () => {
     const formToBlocksType: (form: SectionSpecForm) => FormBlocksResult = formToBlocks;
diff --git a/packages/blocks-engine/src/theme/fallback-diagnostic.ts b/packages/blocks-engine/src/theme/fallback-diagnostic.ts
index c710a97a..edc32597 100644
--- a/packages/blocks-engine/src/theme/fallback-diagnostic.ts
+++ b/packages/blocks-engine/src/theme/fallback-diagnostic.ts
@@ -27,6 +27,8 @@ export interface AssetRemoval {
   description: string;
 }
 
+const PREVIEW = 200; // chars; preview budget — enough for agent triage, small enough not to bloat the JSON
+
 export function buildFallbackDiagnostic(args: {
   page: string;
   slug: string;
@@ -35,10 +37,37 @@ export function buildFallbackDiagnostic(args: {
   islandKind: 'verbatim' | 'styled' | 'responsive';
   islandMarkup: string;
 }): FallbackDiagnostic {
-  void args;
-  throw new Error('buildFallbackDiagnostic implementation pending');
+  const { page, slug, section, coverage, islandKind, islandMarkup } = args;
+  const reasonCode: FallbackReasonCode =
+    coverage.missingImages.length > 0 ? 'dropped_images' : 'text_coverage_below_floor';
+  const suggestedRepairClass: FallbackRepairClass =
+    reasonCode === 'dropped_images' ? 'recover_dropped_media' : 'restructure_section_blocks';
+  const sourceHtmlPreview = ((section.styledHtml ?? section.sectionHtml ?? '') as string).slice(0, PREVIEW);
+  return {
+    id: `${slug}-s${section.sectionIndex}-${reasonCode}`,
+    page,
+    sectionIndex: section.sectionIndex,
+    interactionModel: String(section.interactionModel),
+    selector: section.selector ?? '',
+    severity: 'warning',
+    reasonCode,
+    islandKind,
+    droppedImages: coverage.missingImages,
+    textCoverage: Math.round(coverage.textCoverage * 100) / 100,
+    suggestedRepairClass,
+    sourceHtmlPreview,
+    emittedBlockPreview: islandMarkup.slice(0, PREVIEW),
+  };
 }
 
+/**
+ * Diagnostic record for a triage-removed decorative asset (Neptune #7). Not a
+ * core/html island fallback — a warning-level audit trail: which image was
+ * dropped from which section, plus the vision agent's 1-sentence description
+ * (carried in `sourceHtmlPreview`, the record's free-text channel) so the
+ * structural replacement (wp:separator / parent border / background) can be
+ * chosen from what the visual actually was instead of guessed.
+ */
 export function buildTriageRemovalDiagnostic(args: {
   page: string;
   slug: string;
@@ -47,6 +76,20 @@ export function buildTriageRemovalDiagnostic(args: {
   removal: AssetRemoval;
   ordinal: number;
 }): FallbackDiagnostic {
-  void args;
-  throw new Error('buildTriageRemovalDiagnostic implementation pending');
+  const { page, slug, sectionIndex, interactionModel, removal, ordinal } = args;
+  return {
+    id: `${slug}-s${sectionIndex}-decorative_asset_triaged-${ordinal}`,
+    page,
+    sectionIndex,
+    interactionModel,
+    selector: removal.sectionSelector,
+    severity: 'warning',
+    reasonCode: 'decorative_asset_triaged',
+    islandKind: 'none',
+    droppedImages: [removal.url],
+    textCoverage: 1, // no text impact — the removal is image-only
+    suggestedRepairClass: 'replace_with_structural_block',
+    sourceHtmlPreview: removal.description.slice(0, PREVIEW),
+    emittedBlockPreview: '',
+  };
 }

From 99256f801e233104e60af67e0978d413e2a5c2f9 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 13:33:12 -0400
Subject: [PATCH 076/113] fix(theme): preserve layout offset wrapper class

---
 packages/blocks-engine/src/theme/assemble.ts  |  48 +++++--
 packages/blocks-engine/src/theme/index.ts     |   1 +
 .../src/theme/layout-offset-wrapper.test.ts   |  56 ++++++++
 .../src/theme/layout-offset-wrapper.ts        | 127 ++++++++++++++++++
 .../blocks-engine/src/theme/site-to-theme.ts  |  11 ++
 5 files changed, 235 insertions(+), 8 deletions(-)
 create mode 100644 packages/blocks-engine/src/theme/layout-offset-wrapper.test.ts
 create mode 100644 packages/blocks-engine/src/theme/layout-offset-wrapper.ts

diff --git a/packages/blocks-engine/src/theme/assemble.ts b/packages/blocks-engine/src/theme/assemble.ts
index 2773e2a9..ab992201 100644
--- a/packages/blocks-engine/src/theme/assemble.ts
+++ b/packages/blocks-engine/src/theme/assemble.ts
@@ -20,6 +20,7 @@ type ThemeAssemblyParts = {
   imgRefsByPage?: Record<string, StaticImgRef[]>;
   chromeParts?: Record<string, string>;
   chromeSlugsByPage?: Record<string, ChromeSlugs>;
+  layoutOffsetWrapperClass?: string;
 };
 
 type PaletteEntry = {
@@ -52,10 +53,11 @@ export function assemble(parts: ThemeAssemblyParts): ThemeModel {
         themeSlug,
         parts.chromeParts ?? {},
         parts.chromeSlugsByPage,
-        templatePlan
+        templatePlan,
+        parts.layoutOffsetWrapperClass
       ),
-      'index.html': buildGenericQueriedContentTemplate(parts.chromeParts ?? {}),
-      'page.html': buildGenericQueriedContentTemplate(parts.chromeParts ?? {}),
+      'index.html': buildGenericQueriedContentTemplate(parts.chromeParts ?? {}, parts.layoutOffsetWrapperClass),
+      'page.html': buildGenericQueriedContentTemplate(parts.chromeParts ?? {}, parts.layoutOffsetWrapperClass),
     },
     parts: { ...(parts.chromeParts ?? {}) },
     patterns: {},
@@ -183,15 +185,16 @@ function buildFrontPageTemplate(
   themeSlug: string,
   chromeParts: Record<string, string>,
   chromeSlugsByPage: Record<string, ChromeSlugs> | undefined,
-  templatePlan: TemplatePlan
+  templatePlan: TemplatePlan,
+  layoutOffsetWrapperClass: string | undefined
 ): string {
   const homeSlug = homeSlugFromPlan(site, templatePlan);
   const blocks =
     blocksForPage(homeSlug, pages, imgRefsByPage, themeSlug) ??
     '<!-- wp:paragraph -->\n<p></p>\n<!-- /wp:paragraph -->';
 
-  const mainTemplate = `<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
-<main class="wp-block-group">
+  const mainTemplate = `<!-- wp:group ${mainGroupAttrs(layoutOffsetWrapperClass, { type: 'constrained' })} -->
+<main class="${mainGroupClass(layoutOffsetWrapperClass)}">
 ${blocks}
 </main>
 <!-- /wp:group -->
@@ -214,9 +217,12 @@ ${blocks}
   ].join('\n');
 }
 
-function buildGenericQueriedContentTemplate(chromeParts: Record<string, string>): string {
+function buildGenericQueriedContentTemplate(
+  chromeParts: Record<string, string>,
+  layoutOffsetWrapperClass: string | undefined
+): string {
   const mainTemplate =
-    '<!-- wp:group {"tagName":"main"} --><main class="wp-block-group"><!-- wp:post-content {"layout":{"type":"constrained"}} /--></main><!-- /wp:group -->';
+    `<!-- wp:group ${mainGroupAttrs(layoutOffsetWrapperClass)} --><main class="${mainGroupClass(layoutOffsetWrapperClass)}"><!-- wp:post-content {"layout":{"type":"constrained"}} /--></main><!-- /wp:group -->`;
 
   if (!hasChromePart(chromeParts, 'header') || !hasChromePart(chromeParts, 'footer')) {
     return `${mainTemplate}\n`;
@@ -234,6 +240,24 @@ function hasChromePart(chromeParts: Record<string, string>, slug: string): boole
   return Object.prototype.hasOwnProperty.call(chromeParts, `${slug}.html`);
 }
 
+function mainGroupAttrs(
+  layoutOffsetWrapperClass: string | undefined,
+  layout?: Record<string, unknown>
+): string {
+  return JSON.stringify({
+    tagName: 'main',
+    ...(layoutOffsetWrapperClass ? { className: layoutOffsetWrapperClass } : {}),
+    ...(layout ? { layout } : {}),
+  });
+}
+
+function mainGroupClass(layoutOffsetWrapperClass: string | undefined): string {
+  return ['wp-block-group', layoutOffsetWrapperClass]
+    .filter((value): value is string => Boolean(value))
+    .map(escapeHtmlAttr)
+    .join(' ');
+}
+
 function homeSlugFromPlan(site: SiteModel, templatePlan: TemplatePlan): string {
   const plannedHome = Object.entries(templatePlan.templatesByPage).find(
     ([, template]) => template === 'front-page'
@@ -333,3 +357,11 @@ function slugify(value: string): string {
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '');
 }
+
+function escapeHtmlAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 640a1232..a22fcbd6 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -21,6 +21,7 @@ export { foundation } from './foundation.js';
 export { buildFallbackDiagnostic, buildTriageRemovalDiagnostic } from './fallback-diagnostic.js';
 export { formToBlocks, SKIPPED_FIELD_KINDS } from './form-blocks.js';
 export { ingest } from './ingest.js';
+export { detectLayoutOffsetWrapper } from './layout-offset-wrapper.js';
 export { planTemplates } from './template-plan.js';
 export {
   normalizeCopy,
diff --git a/packages/blocks-engine/src/theme/layout-offset-wrapper.test.ts b/packages/blocks-engine/src/theme/layout-offset-wrapper.test.ts
new file mode 100644
index 00000000..ba5ebf94
--- /dev/null
+++ b/packages/blocks-engine/src/theme/layout-offset-wrapper.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+
+import { detectLayoutOffsetWrapper } from './layout-offset-wrapper.js';
+
+describe('detectLayoutOffsetWrapper', () => {
+  it('returns the offset-bearing main ancestor for a fixed sidebar layout', () => {
+    const html = `
+      <html>
+        <body>
+          <div class="layout">
+            <aside class="sidebar">Docs</aside>
+            <div class="main-area">
+              <main class="content"><h1>Docs</h1></main>
+            </div>
+          </div>
+        </body>
+      </html>
+    `;
+    const css = `
+      .layout { display: flex; }
+      .sidebar { position: fixed; width: 268px; }
+      .main-area { margin-left: 268px; }
+    `;
+
+    expect(detectLayoutOffsetWrapper(html, css)).toBe('main-area');
+  });
+
+  it('returns undefined for constrained layouts even when an ancestor has margin-left', () => {
+    const html = `
+      <body>
+        <div class="page-shell">
+          <main class="content"><h1>About</h1></main>
+        </div>
+      </body>
+    `;
+    const css = '.page-shell { margin-left: 160px; }';
+
+    expect(detectLayoutOffsetWrapper(html, css)).toBeUndefined();
+  });
+
+  it('returns undefined when fixed chrome exists but no ancestor has a horizontal offset', () => {
+    const html = `
+      <body>
+        <div class="page-shell">
+          <main class="content"><h1>About</h1></main>
+        </div>
+      </body>
+    `;
+    const css = `
+      .sidebar { position: sticky; top: 0; }
+      .page-shell { max-width: 900px; }
+    `;
+
+    expect(detectLayoutOffsetWrapper(html, css)).toBeUndefined();
+  });
+});
diff --git a/packages/blocks-engine/src/theme/layout-offset-wrapper.ts b/packages/blocks-engine/src/theme/layout-offset-wrapper.ts
new file mode 100644
index 00000000..28d324e0
--- /dev/null
+++ b/packages/blocks-engine/src/theme/layout-offset-wrapper.ts
@@ -0,0 +1,127 @@
+import * as cheerio from 'cheerio';
+import type { AnyNode, Element } from 'domhandler';
+
+const OUT_OF_FLOW_POSITION_RE = /\bposition\s*:\s*(fixed|absolute|sticky)\b/i;
+const HORIZONTAL_OFFSET_PROPS = ['margin-left', 'margin-right', 'padding-left', 'padding-right'] as const;
+const NON_CONTENT_TAGS = new Set(['header', 'footer', 'nav', 'aside', 'script', 'style', 'template']);
+
+interface CssRule {
+  selector: string;
+  declarations: string;
+}
+
+export function detectLayoutOffsetWrapper(homeHtml: string, css: string): string | undefined {
+  const cleanCss = stripCssComments(css);
+  if (!OUT_OF_FLOW_POSITION_RE.test(cleanCss)) return undefined;
+
+  const $ = cheerio.load(homeHtml);
+  const target = primaryMainContentElement($);
+  if (!target) return undefined;
+
+  const rules = parseCssRules(cleanCss);
+  const rootVars = parseRootVars(rules);
+
+  let current: Element | null = target.includeTarget ? target.element : parentElement(target.element);
+  while (current) {
+    const tag = tagName(current);
+    if (tag === 'html' || tag === 'body') break;
+
+    const classAttr = current.attribs?.class ?? '';
+    for (const token of classAttr.split(/\s+/).filter(Boolean)) {
+      if (classHasHorizontalOffset(token, rules, rootVars)) return token;
+    }
+
+    current = parentElement(current);
+  }
+
+  return undefined;
+}
+
+function primaryMainContentElement($: cheerio.CheerioAPI): { element: Element; includeTarget: boolean } | null {
+  const main = $('main').first().get(0);
+  if (isElement(main)) return { element: main, includeTarget: false };
+
+  const bodyChildren = $('body').children().toArray();
+  const bodyContent = bodyChildren.find(isContentElement);
+  if (isElement(bodyContent)) return { element: bodyContent, includeTarget: true };
+
+  const rootContent = $.root().children().toArray().find(isContentElement);
+  return isElement(rootContent) ? { element: rootContent, includeTarget: true } : null;
+}
+
+function isContentElement(node: AnyNode | undefined): node is Element {
+  return isElement(node) && !NON_CONTENT_TAGS.has(tagName(node));
+}
+
+function isElement(node: AnyNode | undefined): node is Element {
+  return !!node && node.type === 'tag';
+}
+
+function parentElement(node: Element): Element | null {
+  const parent = node.parent as AnyNode | undefined;
+  return isElement(parent) ? parent : null;
+}
+
+function tagName(node: Element): string {
+  return (node.tagName || node.name || '').toLowerCase();
+}
+
+function classHasHorizontalOffset(token: string, rules: CssRule[], rootVars: Map<string, string>): boolean {
+  return rules.some(
+    (rule) => selectorContainsClass(rule.selector, token) && hasNonTrivialHorizontalOffset(rule.declarations, rootVars)
+  );
+}
+
+function hasNonTrivialHorizontalOffset(declarations: string, rootVars: Map<string, string>): boolean {
+  for (const prop of HORIZONTAL_OFFSET_PROPS) {
+    const match = new RegExp(`\\b${prop}\\s*:\\s*([^;]+)`, 'i').exec(declarations);
+    if (!match) continue;
+    if (isNonTrivialOffsetValue(match[1], rootVars)) return true;
+  }
+  return false;
+}
+
+function isNonTrivialOffsetValue(rawValue: string, rootVars: Map<string, string>): boolean {
+  const value = rawValue.trim();
+  const varMatch = /var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,[^)]+)?\)/.exec(value);
+  if (varMatch) {
+    const resolved = rootVars.get(varMatch[1]);
+    return resolved ? isNonTrivialOffsetValue(resolved, rootVars) : true;
+  }
+
+  const pxMatch = /(-?\d+(?:\.\d+)?)px\b/i.exec(value);
+  return pxMatch ? Number.parseFloat(pxMatch[1]) >= 100 : false;
+}
+
+function selectorContainsClass(selector: string, token: string): boolean {
+  return new RegExp(`(^|[^_a-zA-Z0-9-])\\.${escapeRegExp(token)}(?![_a-zA-Z0-9-])`).test(selector);
+}
+
+function parseCssRules(css: string): CssRule[] {
+  const out: CssRule[] = [];
+  const ruleRe = /([^{}]+)\{([^{}]*)\}/g;
+  let match: RegExpExecArray | null;
+  while ((match = ruleRe.exec(css))) {
+    out.push({ selector: match[1].trim(), declarations: match[2] });
+  }
+  return out;
+}
+
+function parseRootVars(rules: CssRule[]): Map<string, string> {
+  const vars = new Map<string, string>();
+  for (const rule of rules) {
+    if (!/(^|,)\s*:root\s*(,|$)/.test(rule.selector)) continue;
+    for (const match of rule.declarations.matchAll(/(--[a-zA-Z0-9_-]+)\s*:\s*([^;]+)/g)) {
+      vars.set(match[1], match[2].trim());
+    }
+  }
+  return vars;
+}
+
+function stripCssComments(css: string): string {
+  return css.replace(/\/\*[\s\S]*?\*\//g, '');
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
diff --git a/packages/blocks-engine/src/theme/site-to-theme.ts b/packages/blocks-engine/src/theme/site-to-theme.ts
index 7014a60d..68fc5f58 100644
--- a/packages/blocks-engine/src/theme/site-to-theme.ts
+++ b/packages/blocks-engine/src/theme/site-to-theme.ts
@@ -6,8 +6,10 @@ import { assets as runAssetsStage } from './assets.js';
 import { chrome } from './chrome.js';
 import { foundation } from './foundation.js';
 import { ingest } from './ingest.js';
+import { detectLayoutOffsetWrapper } from './layout-offset-wrapper.js';
 import { reconstruct } from './reconstruct.js';
 import { sectionExtract } from './section-extract.js';
+import { collectSourceAssets } from './source-assets.js';
 import { writeTheme } from './write-theme.js';
 import type {
   AssetInventory,
@@ -54,6 +56,10 @@ export async function siteToTheme(
     }
 
     const assetStage = await runAssetsStage(ctx, { fetchImpl: options?.fetchImpl });
+    const layoutOffsetWrapperClass = detectLayoutOffsetWrapper(
+      homePage(site)?.html ?? '',
+      collectSourceAssets(site.root, site.pages.map((page) => ({ relPath: page.relPath, html: page.html }))).css
+    );
     const inventory = hooks.onAssets
       ? filterDecorativeAssets(
           assetStage.inventory,
@@ -70,6 +76,7 @@ export async function siteToTheme(
       imgRefsByPage: assetStage.imgRefsByPage,
       chromeParts: chromeRes.parts,
       chromeSlugsByPage: chromeRes.slugsByPage,
+      layoutOffsetWrapperClass,
     });
     const model = hooks.onRefine ? await hooks.onRefine(assembled, ctx) : assembled;
     const written = await writeTheme(model, outDir);
@@ -118,6 +125,10 @@ function normalizeThemeMeta(srcDir: string, meta: Partial<ThemeMeta> | undefined
   };
 }
 
+function homePage(site: { pages: Array<{ slug: string; html: string }> }): { html: string } | undefined {
+  return site.pages.find((page) => page.slug === 'home') ?? site.pages[0];
+}
+
 function titleFromSlug(slug: string): string {
   return slug
     .split('-')

From b567e12c2fc53881aa30957800f521cf0efb0145 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 14:18:56 -0400
Subject: [PATCH 077/113] fix(theme): keep main-sibling layout rail past
 content-landmark gate

A layout rail (aside/nav) that is a grid/flex sibling of <main> under a
shared wrapper was dropped when an outer content-landmark wrapper (e.g.
<section class="section">) enclosed the two-column block: the
content-landmark-ancestor gates in isLayoutChromeCandidate rejected it,
and the body loop then carried only <main>'s children, losing the rail.
Bypass those ancestor gates when findLayoutRailWrapper proves the element
is a main sibling (it returns null for rails nested inside <main>, so
in-content chrome is still rejected). Fixes the library/grant-readiness
right-rail (TOC + related cards) drop; docs-KB left rail and astro
detector path unchanged.
---
 .../__tests__/theme-segment-parity.test.ts    | 27 +++++++++++++++++++
 packages/blocks-engine/src/theme/segment.ts   | 23 +++++++++++++---
 2 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/theme-segment-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-segment-parity.test.ts
index f2109fa0..5c6767f7 100644
--- a/packages/blocks-engine/src/__tests__/theme-segment-parity.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-segment-parity.test.ts
@@ -113,4 +113,31 @@ describe('segmentPage DLA parity', () => {
       },
     ]);
   });
+
+  it('promotes a right rail nested inside an outer content-landmark wrapper', () => {
+    // The library/grant-readiness layout: <section class="section"> wraps the
+    // whole two-column block. The <aside> is a grid SIBLING of <main> (afterMain),
+    // not in-content chrome — the content-landmark-ancestor gate must not drop it.
+    const html =
+      '<body><section class="section"><div class="container"><div class="sidebar-layout"><main class="article-body"><div class="guide-section"><h1>Guide</h1><p>Body copy that is long enough to be a real section.</p></div></main><aside class="sidebar" aria-label="Table of contents"><nav><a href="#a">One</a><a href="#b">Two</a></nav></aside></div></div></section></body>';
+
+    expect(segmentPage(html)).toEqual([
+      {
+        id: 'sidebar',
+        role: 'nav',
+        chromeSource: 'layout-rail',
+        html: '<aside class="sidebar" aria-label="Table of contents"><nav><a href="#a">One</a><a href="#b">Two</a></nav></aside>',
+        classes: ['sidebar'],
+        layoutWrapperTag: 'div',
+        layoutWrapperClasses: ['sidebar-layout'],
+        layoutWrapperRailPosition: 'afterMain',
+      },
+      {
+        id: 'guide',
+        role: 'body',
+        html: '<div class="guide-section"><h1>Guide</h1><p>Body copy that is long enough to be a real section.</p></div>',
+        classes: ['guide-section'],
+      },
+    ]);
+  });
 });
diff --git a/packages/blocks-engine/src/theme/segment.ts b/packages/blocks-engine/src/theme/segment.ts
index 2f827498..fa5916ac 100644
--- a/packages/blocks-engine/src/theme/segment.ts
+++ b/packages/blocks-engine/src/theme/segment.ts
@@ -134,11 +134,26 @@ function isLayoutChromeCandidate($: CheerioAPI, el: Element): boolean {
   const isNav = tag === 'nav' || role === 'navigation';
   const isComplementary = tag === 'aside' || role === 'complementary';
   if (!isNav && !isComplementary) return false;
-  if (hasContentLandmarkAncestor($, el)) return false;
+
+  // A PROVEN layout rail — a grid/flex SIBLING of <main> under a shared wrapper
+  // (findLayoutRailWrapper is non-null ONLY for a main-sibling; a rail nested
+  // INSIDE <main> yields null) — is page-level chrome even when an outer
+  // content-landmark wrapper encloses the whole two-column block, e.g.
+  // <section><div class="cols"><main/><aside/></div></section>. The
+  // content-landmark-ANCESTOR gates below exist to reject chrome nested INSIDE
+  // main/article CONTENT; a main-sibling rail sits BESIDE that content, not in
+  // it, so those gates must not drop it (the library/grant-readiness right-rail
+  // case: an <aside> TOC wrapped in <section class="section">). The
+  // content-landmark-DESCENDANT gate still applies — a rail holding its own
+  // section/article is suspect regardless of where it sits.
+  const isLayoutRailSibling = findLayoutRailWrapper($, el) !== null;
+  if (!isLayoutRailSibling) {
+    if (hasContentLandmarkAncestor($, el)) return false;
+    const nearest = nearestLandmarkAncestor(el);
+    if (nearest && CONTENT_LANDMARK_TAGS.has(nearest)) return false;
+    if (nearest && CHROME_LANDMARK_TAGS.has(nearest)) return false;
+  }
   if (hasContentLandmarkDescendant($, el)) return false;
-  const nearest = nearestLandmarkAncestor(el);
-  if (nearest && CONTENT_LANDMARK_TAGS.has(nearest)) return false;
-  if (nearest && CHROME_LANDMARK_TAGS.has(nearest)) return false;
   return isNav || isActionableComplementary($, el);
 }
 

From 825a6767e96970a6643c9677ff0c1b5d0d74e3c5 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 14:36:12 -0400
Subject: [PATCH 078/113] feat(theme): accommodate the WP admin bar for
 logged-in viewers

Carried source CSS pins chrome (header/sidebar/topbar/TOC) to the viewport
top via position:fixed/sticky. When a logged-in user views the front end,
WordPress's 32px (46px <=782px) admin bar overlays that chrome: WP's html
margin-top bump only shifts document-flow content, not fixed/sticky elements.

Add a deterministic, browser-free pass (admin-bar-accommodation.ts) that scans
the assembled carried CSS for top-anchored fixed/sticky rules and appends
body.admin-bar-scoped overrides shifting each down by a responsive
--wp-admin-bar-h var (32/46px), plus an html:has(body.admin-bar) re-assert of
the document bump. Wired into collectSourceAssets; body.admin-bar <selector>
out-specifies the source rule and carries !important so it wins regardless of
load order. Inactive when logged out (gated on body.admin-bar), so parity and
logged-out rendering are unchanged.

Verified live on the astro fixed-sidebar site: .sidebar top 0->32px (desktop)
and .mobile-nav-toggle 0.75rem->57.25px with --wp-admin-bar-h=46px (<=782px).
---
 .../theme-admin-bar-accommodation.test.ts     |  73 +++++++++
 .../theme-source-assets-parity.test.ts        |  19 ++-
 .../src/theme/admin-bar-accommodation.ts      | 155 ++++++++++++++++++
 packages/blocks-engine/src/theme/index.ts     |   1 +
 .../blocks-engine/src/theme/source-assets.ts  |   9 +-
 5 files changed, 249 insertions(+), 8 deletions(-)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-admin-bar-accommodation.test.ts
 create mode 100644 packages/blocks-engine/src/theme/admin-bar-accommodation.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-admin-bar-accommodation.test.ts b/packages/blocks-engine/src/__tests__/theme-admin-bar-accommodation.test.ts
new file mode 100644
index 00000000..c9c166de
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-admin-bar-accommodation.test.ts
@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { buildAdminBarAccommodationCss } from '../theme/admin-bar-accommodation.js';
+
+describe('buildAdminBarAccommodationCss', () => {
+  it('always emits the responsive bar-height var and document-bump re-assert', () => {
+    const out = buildAdminBarAccommodationCss('');
+    expect(out).toContain('body.admin-bar { --wp-admin-bar-h: 32px; }');
+    expect(out).toContain('@media screen and (max-width: 782px) { body.admin-bar { --wp-admin-bar-h: 46px; } }');
+    expect(out).toContain('html:has(body.admin-bar) { margin-top: 32px !important; }');
+    expect(out).toContain('@media screen and (max-width: 782px) { html:has(body.admin-bar) { margin-top: 46px !important; } }');
+    expect(out.endsWith('\n')).toBe(true);
+  });
+
+  it('shifts a fixed top:0 element by the bar height (bare 0 normalized to 0px)', () => {
+    const out = buildAdminBarAccommodationCss('.sidebar { position: fixed; top: 0; width: 268px; }');
+    expect(out).toContain('body.admin-bar .sidebar { top: calc((0px) + var(--wp-admin-bar-h, 0px)) !important; }');
+  });
+
+  it('shifts a sticky topbar and preserves a calc() / unit top verbatim', () => {
+    const css = [
+      '.topbar { position: sticky; top: 0; }',
+      '.toc { position: sticky; top: calc(var(--topbar-h) + 1rem); }',
+      '.toggle { position: fixed; top: 0.75rem; }',
+    ].join('\n');
+    const out = buildAdminBarAccommodationCss(css);
+    expect(out).toContain('body.admin-bar .topbar { top: calc((0px) + var(--wp-admin-bar-h, 0px)) !important; }');
+    expect(out).toContain('body.admin-bar .toc { top: calc((calc(var(--topbar-h) + 1rem)) + var(--wp-admin-bar-h, 0px)) !important; }');
+    expect(out).toContain('body.admin-bar .toggle { top: calc((0.75rem) + var(--wp-admin-bar-h, 0px)) !important; }');
+  });
+
+  it('drops !important and trailing decls from the source top value', () => {
+    const out = buildAdminBarAccommodationCss('.h { position: fixed; top: 12px !important; z-index: 9; }');
+    expect(out).toContain('body.admin-bar .h { top: calc((12px) + var(--wp-admin-bar-h, 0px)) !important; }');
+    expect(out).not.toContain('!important; z-index');
+  });
+
+  it('ignores fixed/sticky elements with no top anchor or top:auto', () => {
+    const css = [
+      '.grain { position: fixed; inset: 0; }',
+      '.foot { position: fixed; bottom: 0; }',
+      '.x { position: fixed; top: auto; }',
+    ].join('\n');
+    const out = buildAdminBarAccommodationCss(css);
+    expect(out).not.toContain('.grain');
+    expect(out).not.toContain('.foot');
+    expect(out).not.toContain('.x {');
+  });
+
+  it('ignores static/relative/absolute positioned elements', () => {
+    const out = buildAdminBarAccommodationCss('.rel { position: relative; top: 10px; } .abs { position: absolute; top: 0; }');
+    expect(out).not.toContain('.rel');
+    expect(out).not.toContain('.abs');
+  });
+
+  it('scopes an override emitted inside @media to that media block', () => {
+    const css = '@media screen and (max-width: 600px) { .mhdr { position: fixed; top: 0; } }';
+    const out = buildAdminBarAccommodationCss(css);
+    expect(out).toContain('@media screen and (max-width: 600px) {');
+    expect(out).toContain('  body.admin-bar .mhdr { top: calc((0px) + var(--wp-admin-bar-h, 0px)) !important; }');
+  });
+
+  it('splits a comma selector list and skips keyframe steps', () => {
+    const css = [
+      '.a, .b { position: sticky; top: 0; }',
+      '@keyframes slide { from { position: fixed; top: 0; } 50% { top: 10px; } }',
+    ].join('\n');
+    const out = buildAdminBarAccommodationCss(css);
+    expect(out).toContain('body.admin-bar .a { top: calc((0px) + var(--wp-admin-bar-h, 0px)) !important; }');
+    expect(out).toContain('body.admin-bar .b { top: calc((0px) + var(--wp-admin-bar-h, 0px)) !important; }');
+    expect(out).not.toContain('body.admin-bar from');
+    expect(out).not.toContain('body.admin-bar 50%');
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/theme-source-assets-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-source-assets-parity.test.ts
index bd51a61a..ffdf7fb4 100644
--- a/packages/blocks-engine/src/__tests__/theme-source-assets-parity.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-source-assets-parity.test.ts
@@ -274,14 +274,19 @@ describe('source assets DLA parity', () => {
       expect(result.cssFiles).toEqual(['assets/css/base.css', 'assets/css/override.css']);
       expect(result.jsFiles).toEqual(['assets/js/lib.js', 'assets/js/app.js']);
       expect(result.skippedUnlinked).toEqual(['stale.js', 'style.css']);
-      expect(result.css).toBe(
+      const expectedBase =
         DLA_WP_COMPAT_CSS +
-          [
-            '\n.base { background: url(media/bg.png); color: black; }',
-            '.base { color: white; }',
-            '.inline { background: url(media/root-inline.png); }',
-          ].join('\n\n')
-      );
+        [
+          '\n.base { background: url(media/bg.png); color: black; }',
+          '.base { color: white; }',
+          '.inline { background: url(media/root-inline.png); }',
+        ].join('\n\n');
+      // Carried CSS is preserved verbatim as the prefix; the admin-bar
+      // accommodation layer is appended last (no fixed/sticky rules here, so
+      // only the var defs + document-bump re-assert).
+      expect(result.css.startsWith(expectedBase)).toBe(true);
+      expect(result.css).toContain('body.admin-bar { --wp-admin-bar-h: 32px; }');
+      expect(result.css).toContain('html:has(body.admin-bar) { margin-top: 32px !important; }');
       expect(result.css).not.toContain('fonts.googleapis.com');
       expect(result.js).toBe(
         [
diff --git a/packages/blocks-engine/src/theme/admin-bar-accommodation.ts b/packages/blocks-engine/src/theme/admin-bar-accommodation.ts
new file mode 100644
index 00000000..70c59565
--- /dev/null
+++ b/packages/blocks-engine/src/theme/admin-bar-accommodation.ts
@@ -0,0 +1,155 @@
+/**
+ * WP admin-bar accommodation (deterministic, browser-free).
+ *
+ * When a logged-in user views the FRONT END, WordPress prints a fixed 32px
+ * (46px at <=782px) admin bar across the top and bumps the document down with
+ * `html { margin-top: 32px !important }`. That bump only moves DOCUMENT-FLOW
+ * content — `position: fixed`/`sticky` chrome is viewport-relative, so a carried
+ * source header / sidebar / topbar / TOC pinned to `top: 0` (or any top anchor)
+ * sits UNDER the bar and the admin bar overlays the page content.
+ *
+ * This pass scans the assembled carried CSS for top-anchored fixed/sticky rules
+ * and emits `body.admin-bar`-scoped overrides that shift each one down by the bar
+ * height (a responsive custom property), plus a `html:has(body.admin-bar)`
+ * re-assert of the document bump in case carried CSS reset the html/body margin.
+ * The output is appended AFTER the carried CSS; `body.admin-bar <selector>`
+ * (specificity 0,2,1+) out-ranks the source rule (0,1,0) regardless of order, and
+ * the override carries `!important` so it also beats an `!important` source `top`.
+ *
+ * Limitations (documented, not silent): only explicit `top:` anchors are shifted
+ * (a full-viewport `inset: 0` decorative overlay is deliberately left alone); a
+ * `top` first defined inside a nested @media is not tracked across that nesting.
+ */
+
+/** CSS custom property carrying the responsive admin-bar height. */
+const ADMIN_BAR_VAR = '--wp-admin-bar-h';
+
+interface FixedTopRule {
+  /** The @media query text this rule lives under, or null for top level. */
+  media: string | null;
+  selector: string;
+  /** The original `top` value (sans `!important`), e.g. `0`, `0.75rem`, `calc(...)`. */
+  top: string;
+}
+
+/**
+ * Build the admin-bar accommodation stylesheet for a carried CSS bundle. Always
+ * emits the var definitions + document-bump re-assert; adds one shift override
+ * per detected top-anchored fixed/sticky selector. Returns a trailing-newline
+ * string safe to append to the bundle (empty-input safe).
+ */
+export function buildAdminBarAccommodationCss(css: string): string {
+  const rules = scanTopAnchoredFixedRules(css);
+  const lines: string[] = [
+    '/* WP admin-bar accommodation (generated) — shift fixed/sticky top-anchored',
+    '   chrome below the admin bar and re-assert the document bump so the bar',
+    '   never overlaps page content for logged-in viewers. */',
+    `body.admin-bar { ${ADMIN_BAR_VAR}: 32px; }`,
+    `@media screen and (max-width: 782px) { body.admin-bar { ${ADMIN_BAR_VAR}: 46px; } }`,
+    'html:has(body.admin-bar) { margin-top: 32px !important; }',
+    '@media screen and (max-width: 782px) { html:has(body.admin-bar) { margin-top: 46px !important; } }',
+  ];
+
+  for (const r of rules.filter((r) => r.media === null)) {
+    lines.push(overrideLine(r.selector, r.top));
+  }
+
+  const byMedia = new Map<string, FixedTopRule[]>();
+  for (const r of rules) {
+    if (r.media === null) continue;
+    const arr = byMedia.get(r.media) ?? [];
+    arr.push(r);
+    byMedia.set(r.media, arr);
+  }
+  for (const [query, arr] of byMedia) {
+    const inner = arr.map((r) => `  ${overrideLine(r.selector, r.top)}`).join('\n');
+    lines.push(`@media ${query} {\n${inner}\n}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+/** Compose the original top with the bar-height var. Bare `0` is normalized to
+ * `0px` (calc rejects a unitless number added to a length); nested calc is valid. */
+function overrideLine(selector: string, top: string): string {
+  const base = /^[+-]?0$/.test(top.trim()) ? '0px' : top;
+  return `body.admin-bar ${selector} { top: calc((${base}) + var(${ADMIN_BAR_VAR}, 0px)) !important; }`;
+}
+
+function scanTopAnchoredFixedRules(css: string): FixedTopRule[] {
+  const clean = stripCssComments(css);
+  const { topLevel, media } = splitMediaBlocks(clean);
+  const out: FixedTopRule[] = [];
+  collectRegion(topLevel, null, out);
+  for (const m of media) collectRegion(m.inner, m.query, out);
+
+  const seen = new Set<string>();
+  return out.filter((r) => {
+    const key = `${r.media}||${r.selector}||${r.top}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/** Flat rule scan over a single region (top level or one @media's inner body). */
+function collectRegion(region: string, media: string | null, out: FixedTopRule[]): void {
+  const ruleRe = /([^{}]+)\{([^{}]*)\}/g;
+  let match: RegExpExecArray | null;
+  while ((match = ruleRe.exec(region))) {
+    const decls = match[2];
+    if (!/position\s*:\s*(?:fixed|sticky)\b/i.test(decls)) continue;
+    const topMatch = /(?:^|[;{])\s*top\s*:\s*([^;}!]+)/i.exec(decls);
+    if (!topMatch) continue;
+    const top = topMatch[1].trim();
+    if (!top || /^auto$/i.test(top)) continue;
+    for (const sel of match[1].split(',').map((s) => s.trim()).filter(Boolean)) {
+      if (isEmittableSelector(sel)) out.push({ media, selector: sel, top });
+    }
+  }
+}
+
+/** Reject keyframe steps (`0%`, `from`) and at-rule fragments the flat parse can
+ * surface; require at least one usable simple-selector character. */
+function isEmittableSelector(sel: string): boolean {
+  if (sel.startsWith('@')) return false;
+  if (/^(?:from|to|\d+(?:\.\d+)?%)$/i.test(sel)) return false;
+  return /[.#[a-zA-Z*]/.test(sel);
+}
+
+/** Split CSS into the top-level region (with @media blocks removed) and the list
+ * of @media blocks (query + brace-matched inner body). Brace matching tolerates
+ * nested rule braces inside a media block. */
+function splitMediaBlocks(css: string): { topLevel: string; media: Array<{ query: string; inner: string }> } {
+  const media: Array<{ query: string; inner: string }> = [];
+  let topLevel = '';
+  let i = 0;
+  while (i < css.length) {
+    const at = css.toLowerCase().indexOf('@media', i);
+    if (at < 0) {
+      topLevel += css.slice(i);
+      break;
+    }
+    topLevel += css.slice(i, at);
+    const braceOpen = css.indexOf('{', at);
+    if (braceOpen < 0) {
+      topLevel += css.slice(at);
+      break;
+    }
+    const query = css.slice(at + '@media'.length, braceOpen).trim();
+    let depth = 1;
+    let j = braceOpen + 1;
+    for (; j < css.length && depth > 0; j++) {
+      if (css[j] === '{') depth++;
+      else if (css[j] === '}') depth--;
+      if (depth === 0) break;
+    }
+    media.push({ query, inner: css.slice(braceOpen + 1, j) });
+    i = j + 1;
+  }
+  return { topLevel, media };
+}
+
+function stripCssComments(css: string): string {
+  return css.replace(/\/\*[\s\S]*?\*\//g, '');
+}
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index a22fcbd6..e80e2a30 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -22,6 +22,7 @@ export { buildFallbackDiagnostic, buildTriageRemovalDiagnostic } from './fallbac
 export { formToBlocks, SKIPPED_FIELD_KINDS } from './form-blocks.js';
 export { ingest } from './ingest.js';
 export { detectLayoutOffsetWrapper } from './layout-offset-wrapper.js';
+export { buildAdminBarAccommodationCss } from './admin-bar-accommodation.js';
 export { planTemplates } from './template-plan.js';
 export {
   normalizeCopy,
diff --git a/packages/blocks-engine/src/theme/source-assets.ts b/packages/blocks-engine/src/theme/source-assets.ts
index dcac9dec..bcbd6018 100644
--- a/packages/blocks-engine/src/theme/source-assets.ts
+++ b/packages/blocks-engine/src/theme/source-assets.ts
@@ -14,6 +14,7 @@
 //
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, posix } from 'node:path';
+import { buildAdminBarAccommodationCss } from './admin-bar-accommodation.js';
 
 /** Neutralize WP-injected wrappers so source layout selectors keep working.
  * Prepended (lowest precedence) — source rules always win over it. */
@@ -407,7 +408,13 @@ export function collectSourceAssets(
   // dir. Then strip Google-Fonts @imports: WP_COMPAT_CSS contains no @imports so
   // startsWith(WP_COMPAT_CSS) is preserved; Google imports only exist in cssParts.
   const { parts: localizedParts, mediaAssets } = localizeCssImages(cssParts, dir);
-  const css = (WP_COMPAT_CSS + localizedParts.join('\n\n')).replace(GOOGLE_IMPORT_RE, '');
+  const baseCss = (WP_COMPAT_CSS + localizedParts.join('\n\n')).replace(GOOGLE_IMPORT_RE, '');
+  // Append admin-bar accommodation LAST: scan the assembled source CSS for
+  // top-anchored fixed/sticky chrome and shift it below the WP admin bar for
+  // logged-in viewers (the bar otherwise overlays a `position:fixed; top:0`
+  // header/sidebar/topbar). `body.admin-bar <selector>` out-specifies the source
+  // rule, so order is not load-bearing, but appending keeps the layer self-evident.
+  const css = `${baseCss}\n\n${buildAdminBarAccommodationCss(baseCss)}`;
   // Carry HTML <img> assets too (content images the CSS pass never sees).
   const { imgAssets, rewritesByPage: imgRewritesByPage } = collectHtmlImages(pageHtmls, dir);
   return {

From 1972f90b4c71a91fab79f09c99ffa766499fd0c2 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 15:51:31 -0400
Subject: [PATCH 079/113] feat(theme): freeze source CSS carry contract

---
 .../theme-source-css-carry-contract.test.ts   | 28 +++++++++++++++++++
 .../src/theme/source-css-carry.ts             | 28 +++++++++++++++++++
 packages/blocks-engine/src/theme/types.ts     |  3 +-
 3 files changed, 58 insertions(+), 1 deletion(-)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-source-css-carry-contract.test.ts
 create mode 100644 packages/blocks-engine/src/theme/source-css-carry.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-source-css-carry-contract.test.ts b/packages/blocks-engine/src/__tests__/theme-source-css-carry-contract.test.ts
new file mode 100644
index 00000000..b9da42fc
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-source-css-carry-contract.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+
+import type { SiteToThemeOptions } from '../theme/index.js';
+import {
+  appendCarriedSourceCss,
+  hasCarriedSourceCss,
+  shouldCarrySourceCss,
+} from '../theme/source-css-carry.js';
+
+describe('source CSS carry contract', () => {
+  it('carries non-empty source CSS by default and supports an explicit consumer opt-out', () => {
+    const defaultOptions = {} satisfies SiteToThemeOptions;
+    const optOutOptions = { carrySourceCss: false } satisfies SiteToThemeOptions;
+
+    expect(shouldCarrySourceCss('.ftp-sentinel{max-width:960px}', defaultOptions)).toBe(true);
+    expect(shouldCarrySourceCss('.ftp-sentinel{max-width:960px}', optOutOptions)).toBe(false);
+    expect(shouldCarrySourceCss('   ', defaultOptions)).toBe(false);
+  });
+
+  it('preserves carried CSS bytes when appending to the theme stylesheet', () => {
+    const sourceCss = '/* source */\n.ftp-sentinel{max-width:960px}\n';
+
+    expect(hasCarriedSourceCss(sourceCss)).toBe(true);
+    expect(appendCarriedSourceCss('/* theme */\n', sourceCss)).toBe(
+      '/* theme */\n/* source */\n.ftp-sentinel{max-width:960px}\n'
+    );
+  });
+});
diff --git a/packages/blocks-engine/src/theme/source-css-carry.ts b/packages/blocks-engine/src/theme/source-css-carry.ts
new file mode 100644
index 00000000..e992164b
--- /dev/null
+++ b/packages/blocks-engine/src/theme/source-css-carry.ts
@@ -0,0 +1,28 @@
+export interface SourceCssCarryOptions {
+  /**
+   * Source CSS is carried by default. Consumers that already carry the same CSS
+   * through their own compatibility layer can opt out to avoid duplicate output.
+   */
+  carrySourceCss?: boolean;
+}
+
+export interface ThemeAssemblySourceCssInput {
+  sourceCss?: string;
+}
+
+export function hasCarriedSourceCss(sourceCss: string | undefined): boolean {
+  return (sourceCss ?? '').trim().length > 0;
+}
+
+export function shouldCarrySourceCss(
+  sourceCss: string | undefined,
+  options: SourceCssCarryOptions | undefined
+): boolean {
+  return options?.carrySourceCss !== false && hasCarriedSourceCss(sourceCss);
+}
+
+export function appendCarriedSourceCss(styleCss: string, sourceCss: string | undefined): string {
+  if (!hasCarriedSourceCss(sourceCss)) return styleCss;
+  const prefix = styleCss.endsWith('\n') ? styleCss : `${styleCss}\n`;
+  return `${prefix}${sourceCss}`;
+}
diff --git a/packages/blocks-engine/src/theme/types.ts b/packages/blocks-engine/src/theme/types.ts
index a351f7e8..b4c03cec 100644
--- a/packages/blocks-engine/src/theme/types.ts
+++ b/packages/blocks-engine/src/theme/types.ts
@@ -1,5 +1,6 @@
 import type { WorkerPool } from '../pool/types.js';
 import type { SectionSpec } from './section-spec.js';
+import type { SourceCssCarryOptions } from './source-css-carry.js';
 
 export interface SiteModel {
   root: string;
@@ -76,7 +77,7 @@ export interface SiteToThemeHooks {
   onRefine?(theme: ThemeModel, ctx: StageCtx): Promise<ThemeModel>;
 }
 
-export interface SiteToThemeOptions {
+export interface SiteToThemeOptions extends SourceCssCarryOptions {
   outDir?: string;
   pool?: WorkerPool;
   sections?: Record<string, SectionSpec[]>;

From 203668b56dbdc8396ba54b26c5df21fc994079c6 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 16:31:55 -0400
Subject: [PATCH 080/113] feat(theme): carry source css by default

---
 .../src/__tests__/site-to-theme.e2e.test.ts   |  71 ++++++++++++
 packages/blocks-engine/src/theme/assemble.ts  |  31 ++++--
 .../blocks-engine/src/theme/site-to-theme.ts  | 103 +++++++++++++++++-
 packages/blocks-engine/vitest.config.ts       |   1 +
 4 files changed, 193 insertions(+), 13 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
index 8ae27df7..60e51bb5 100644
--- a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
+++ b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
@@ -54,6 +54,18 @@ function copyFixtureSite(dest: string): void {
   cpSync(join(fixtureRoot, 'assets'), join(dest, 'assets'), { recursive: true });
 }
 
+function appendFtpSourceCssSentinel(siteDir: string): void {
+  const imagePath = join(siteDir, 'assets', 'ftp-bg.png');
+  const stylePath = join(siteDir, 'style.css');
+  const sourceCss = readFileSync(stylePath, 'utf8');
+  writeFileSync(imagePath, new Uint8Array([0x89, 0x50, 0x4e, 0x47]));
+  writeFileSync(
+    stylePath,
+    `${sourceCss}\n.ftp-sentinel{max-width:960px;background-image:url("assets/ftp-bg.png")}\n`,
+    'utf8'
+  );
+}
+
 function semanticSpec(sectionIndex = 0): SectionSpec {
   return {
     sectionIndex,
@@ -704,6 +716,65 @@ describe('site-to-theme P0-3 orchestration', () => {
     });
   });
 
+  it('FTP1-engine-acceptance-source-css-carry writes sentinel, admin-bar CSS, and no top-level theme styles', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+
+    await withTempDir('blocks-engine-site-to-theme-ftp1-css-', async (siteDir) => {
+      copyFixtureSite(siteDir);
+      appendFtpSourceCssSentinel(siteDir);
+      const outDir = join(siteDir, 'theme-out');
+
+      await siteToTheme(siteDir, {
+        outDir,
+        pool: p1Pool(),
+        sections: p1Sections(),
+        fetchImpl: mockFontFetch().fetchImpl,
+        themeMeta: themeMeta(),
+      });
+
+      const styleCss = readFileSync(join(outDir, 'style.css'), 'utf8');
+      const themeJson = JSON.parse(readFileSync(join(outDir, 'theme.json'), 'utf8'));
+
+      expect(styleCss).toContain('.ftp-sentinel');
+      expect(styleCss).toContain('url(assets/css/media/ftp-bg.png)');
+      expect(styleCss).not.toContain('url(media/ftp-bg.png)');
+      expect(styleCss).toContain('body.admin-bar');
+      expect(existsSync(join(outDir, 'assets', 'css', 'media', 'ftp-bg.png'))).toBe(true);
+      expect(Object.prototype.hasOwnProperty.call(themeJson, 'styles')).toBe(false);
+    });
+  });
+
+  it('FTP1-engine-acceptance-source-css-carry writes deterministic style.css and theme.json bytes', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+
+    await withTempDir('blocks-engine-site-to-theme-ftp1-determinism-', async (rootDir) => {
+      const siteDir = join(rootDir, 'site');
+      mkdirSync(siteDir);
+      copyFixtureSite(siteDir);
+      appendFtpSourceCssSentinel(siteDir);
+
+      const firstOut = join(rootDir, 'theme-first');
+      const secondOut = join(rootDir, 'theme-second');
+
+      await siteToTheme(siteDir, {
+        outDir: firstOut,
+        pool: p1Pool(),
+        sections: p1Sections(),
+        fetchImpl: mockFontFetch().fetchImpl,
+        themeMeta: themeMeta(),
+      });
+      await siteToTheme(siteDir, {
+        outDir: secondOut,
+        pool: p1Pool(),
+        sections: p1Sections(),
+        fetchImpl: mockFontFetch().fetchImpl,
+        themeMeta: themeMeta(),
+      });
+
+      expectThemesByteIdentical(firstOut, secondOut, ['style.css', 'theme.json']);
+    });
+  });
+
   it('siteToTheme-e2e-hero-survives coverage-gated reconstruct', async () => {
     const { siteToTheme } = await import('../theme/index.js');
     const { fetchImpl } = mockFontFetch();
diff --git a/packages/blocks-engine/src/theme/assemble.ts b/packages/blocks-engine/src/theme/assemble.ts
index ab992201..89dc61c3 100644
--- a/packages/blocks-engine/src/theme/assemble.ts
+++ b/packages/blocks-engine/src/theme/assemble.ts
@@ -1,5 +1,10 @@
 import { rewriteHtmlImageSrcs, type StaticImgRef } from './assets-static.js';
 import type { ChromeSlugs } from './chrome-signature.js';
+import {
+  appendCarriedSourceCss,
+  hasCarriedSourceCss,
+  type ThemeAssemblySourceCssInput,
+} from './source-css-carry.js';
 import { planTemplates, type TemplatePlan } from './template-plan.js';
 import type {
   AssetFile,
@@ -10,7 +15,7 @@ import type {
   ThemeModel,
 } from './types.js';
 
-type ThemeAssemblyParts = {
+type ThemeAssemblyParts = ThemeAssemblySourceCssInput & {
   site: SiteModel;
   tokens: FoundationTokens;
   pages: Record<string, SectionBlocks[]>;
@@ -40,11 +45,14 @@ export function assemble(parts: ThemeAssemblyParts): ThemeModel {
   const palette = buildPalette(parts.tokens);
   const fontFamilies = buildFontFamilies(parts.tokens);
   const styleCss = buildStyleCss(parts.meta, themeSlug);
+  const carriedSourceCss = hasCarriedSourceCss(parts.sourceCss);
   const templatePlan = planTemplates(parts.site);
 
   return {
-    styleCss: appendFontCss(styleCss, parts.fontCss),
-    themeJson: buildThemeJson(parts.tokens, palette, fontFamilies),
+    styleCss: appendCarriedSourceCss(appendFontCss(styleCss, parts.fontCss), parts.sourceCss),
+    themeJson: buildThemeJson(parts.tokens, palette, fontFamilies, {
+      omitStyles: carriedSourceCss,
+    }),
     templates: {
       'front-page.html': buildFrontPageTemplate(
         parts.site,
@@ -91,11 +99,11 @@ function buildThemeHeader(fields: Array<[string, string]>): string {
 function buildThemeJson(
   tokens: FoundationTokens,
   palette: PaletteEntry[],
-  fontFamilies: FontFamilyEntry[]
+  fontFamilies: FontFamilyEntry[],
+  options?: { omitStyles?: boolean }
 ): Record<string, unknown> {
   const bodyFontSlug = fontFamilies[0]?.slug;
-
-  return {
+  const themeJson: Record<string, unknown> = {
     $schema: 'https://schemas.wp.org/trunk/theme.json',
     version: 3,
     settings: {
@@ -119,7 +127,10 @@ function buildThemeJson(
         units: ['px', 'em', 'rem', '%', 'vh', 'vw'],
       },
     },
-    styles: {
+  };
+
+  if (!options?.omitStyles) {
+    themeJson.styles = {
       color: {
         background: colorValueFor(palette, ['surface-base', 'background', 'white'], '#ffffff'),
         text: colorValueFor(palette, ['text-default', 'foreground', 'black'], '#111111'),
@@ -127,8 +138,10 @@ function buildThemeJson(
       ...(bodyFontSlug
         ? { typography: { fontFamily: `var(--wp--preset--font-family--${bodyFontSlug})` } }
         : {}),
-    },
-  };
+    };
+  }
+
+  return themeJson;
 }
 
 function buildPalette(tokens: FoundationTokens): PaletteEntry[] {
diff --git a/packages/blocks-engine/src/theme/site-to-theme.ts b/packages/blocks-engine/src/theme/site-to-theme.ts
index 68fc5f58..593c103a 100644
--- a/packages/blocks-engine/src/theme/site-to-theme.ts
+++ b/packages/blocks-engine/src/theme/site-to-theme.ts
@@ -1,4 +1,4 @@
-import { join } from 'node:path';
+import { basename, extname, join, resolve } from 'node:path';
 
 import { createWorker } from '../pool/pool.js';
 import { assemble } from './assemble.js';
@@ -9,9 +9,11 @@ import { ingest } from './ingest.js';
 import { detectLayoutOffsetWrapper } from './layout-offset-wrapper.js';
 import { reconstruct } from './reconstruct.js';
 import { sectionExtract } from './section-extract.js';
-import { collectSourceAssets } from './source-assets.js';
+import { collectSourceAssets, type MediaAsset } from './source-assets.js';
+import { shouldCarrySourceCss } from './source-css-carry.js';
 import { writeTheme } from './write-theme.js';
 import type {
+  AssetFile,
   AssetInventory,
   AssetVerdicts,
   SectionBlocks,
@@ -56,27 +58,36 @@ export async function siteToTheme(
     }
 
     const assetStage = await runAssetsStage(ctx, { fetchImpl: options?.fetchImpl });
+    const sourceAssets = collectSourceAssets(
+      site.root,
+      site.pages.map((page) => ({ relPath: page.relPath, html: page.html }))
+    );
     const layoutOffsetWrapperClass = detectLayoutOffsetWrapper(
       homePage(site)?.html ?? '',
-      collectSourceAssets(site.root, site.pages.map((page) => ({ relPath: page.relPath, html: page.html }))).css
+      sourceAssets.css
     );
+    const carrySourceCss = shouldCarrySourceCss(sourceAssets.css, options);
     const inventory = hooks.onAssets
       ? filterDecorativeAssets(
           assetStage.inventory,
           await hooks.onAssets(assetStage.inventory, ctx)
         )
       : assetStage.inventory;
+    const sourceCssCarry = carrySourceCss
+      ? prepareSourceCssCarry(sourceAssets.css, sourceAssets.mediaAssets, inventory.assets)
+      : undefined;
     const assembled = assemble({
       site,
       tokens,
       pages,
       meta: themeMeta,
-      assets: inventory.assets,
+      assets: sourceCssCarry?.assets ?? inventory.assets,
       fontCss: assetStage.fontCss,
       imgRefsByPage: assetStage.imgRefsByPage,
       chromeParts: chromeRes.parts,
       chromeSlugsByPage: chromeRes.slugsByPage,
       layoutOffsetWrapperClass,
+      sourceCss: sourceCssCarry?.css,
     });
     const model = hooks.onRefine ? await hooks.onRefine(assembled, ctx) : assembled;
     const written = await writeTheme(model, outDir);
@@ -103,6 +114,90 @@ export async function siteToTheme(
   }
 }
 
+function prepareSourceCssCarry(
+  css: string,
+  mediaAssets: MediaAsset[],
+  inventoryAssets: AssetFile[]
+): { css: string; assets: AssetFile[] } {
+  if (mediaAssets.length === 0) {
+    return { css: rebaseSourceCssMediaUrls(css, []), assets: inventoryAssets };
+  }
+
+  const occupiedByRel = new Map<string, AssetFile>();
+  for (const asset of inventoryAssets) {
+    occupiedByRel.set(asset.relPath, asset);
+  }
+
+  const carriedAssets: AssetFile[] = [];
+  const rewrites: Array<{ from: string; to: string }> = [];
+
+  for (const mediaAsset of mediaAssets) {
+    const targetRel = availableSourceCssMediaRel(mediaAsset, occupiedByRel);
+    rewrites.push({
+      from: `media/${basename(mediaAsset.themeRel)}`,
+      to: targetRel,
+    });
+
+    const existing = occupiedByRel.get(targetRel);
+    if (!existing || !sameSourceAsset(existing, mediaAsset.srcAbs)) {
+      const asset = { relPath: targetRel, sourcePath: mediaAsset.srcAbs };
+      occupiedByRel.set(targetRel, asset);
+      carriedAssets.push(asset);
+    }
+  }
+
+  return {
+    css: rebaseSourceCssMediaUrls(css, rewrites),
+    assets: sortAssetFiles([...inventoryAssets, ...carriedAssets]),
+  };
+}
+
+function availableSourceCssMediaRel(
+  mediaAsset: MediaAsset,
+  occupiedByRel: Map<string, AssetFile>
+): string {
+  const existing = occupiedByRel.get(mediaAsset.themeRel);
+  if (!existing || sameSourceAsset(existing, mediaAsset.srcAbs)) return mediaAsset.themeRel;
+
+  const ext = extname(mediaAsset.themeRel);
+  const base = ext ? mediaAsset.themeRel.slice(0, -ext.length) : mediaAsset.themeRel;
+  let suffix = 2;
+  let candidate = `${base}-${suffix}${ext}`;
+
+  while (
+    occupiedByRel.has(candidate) &&
+    !sameSourceAsset(occupiedByRel.get(candidate), mediaAsset.srcAbs)
+  ) {
+    suffix += 1;
+    candidate = `${base}-${suffix}${ext}`;
+  }
+
+  return candidate;
+}
+
+function sameSourceAsset(asset: AssetFile | undefined, sourcePath: string): boolean {
+  return Boolean(asset?.sourcePath && resolve(asset.sourcePath) === resolve(sourcePath));
+}
+
+function rebaseSourceCssMediaUrls(
+  css: string,
+  rewrites: Array<{ from: string; to: string }>
+): string {
+  let out = css;
+  for (const rewrite of rewrites) {
+    out = out.split(`url(${rewrite.from})`).join(`url(${rewrite.to})`);
+  }
+  return out;
+}
+
+function sortAssetFiles(files: AssetFile[]): AssetFile[] {
+  return [...files].sort((a, b) => {
+    const rel = a.relPath.localeCompare(b.relPath);
+    if (rel !== 0) return rel;
+    return (a.sourcePath ?? '').localeCompare(b.sourcePath ?? '');
+  });
+}
+
 function filterDecorativeAssets(
   inventory: AssetInventory,
   verdicts: AssetVerdicts
diff --git a/packages/blocks-engine/vitest.config.ts b/packages/blocks-engine/vitest.config.ts
index c5529dc0..7fcfe5a5 100644
--- a/packages/blocks-engine/vitest.config.ts
+++ b/packages/blocks-engine/vitest.config.ts
@@ -4,6 +4,7 @@ export default defineConfig({
   test: {
     globals: false,
     environment: 'node',
+    fileParallelism: false,
     testTimeout: 20_000,
   },
 });

From bf0ef6cccc6e6014d5538fa2fa1d6ffa7efeee21 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 17:00:29 -0400
Subject: [PATCH 081/113] docs(theme): map page reconstruct lift

---
 ...26-06-25-ftp2-page-reconstruct-lift-map.md | 434 ++++++++++++++++++
 1 file changed, 434 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-25-ftp2-page-reconstruct-lift-map.md

diff --git a/docs/superpowers/plans/2026-06-25-ftp2-page-reconstruct-lift-map.md b/docs/superpowers/plans/2026-06-25-ftp2-page-reconstruct-lift-map.md
new file mode 100644
index 00000000..157b2217
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-25-ftp2-page-reconstruct-lift-map.md
@@ -0,0 +1,434 @@
+# FTP2a page-reconstruct deterministic-core lift map
+
+Prepared against:
+
+- Engine: `/Users/matt/projects/a8c/blocks-engine`, branch `feature/site-to-theme`, HEAD `203668b5`.
+- DLA: `/Users/matt/projects/a8c/data-liberation-agent`, branch `feature/adopt-blocks-engine`, HEAD `e2f3de7`.
+- Source: `/Users/matt/projects/a8c/data-liberation-agent/src/lib/replicate/page-reconstruct.ts` has 1844 lines.
+
+This map defines how to lift the deterministic native-first reconstruction behavior from DLA into the engine `reconstruct` stage without moving code in this slice.
+
+Classification key:
+
+- `LIFT`: deterministic behavior that should move to `packages/blocks-engine/src/theme/`.
+- `STAY-DLA`: DLA runtime, plugin, capture, adapter, editable-html, Jetpack emit, or post-engine integration behavior.
+- `SHARED`: already engine-owned, contract-shaped, or move-with-care because the current DLA surface combines engine and DLA responsibilities.
+
+Phase 0 disagreements preserved in the handoff:
+
+- The frozen G2 grep counts 46 symbols, but an AST pass finds 57 top-level declarations when local types, constants, sets, and `export { escapeHtml }` are included. This doc classifies all 57 and reports the 46/46 gate explicitly.
+- The Phase 6 phrase "walk the section" does not match the live DLA implementation literally. Live DLA uses a `SectionSpec` renderer, an optional converted native fast path, and coverage-gated fallback. This map describes that live decision chain.
+- Jetpack form emit is currently inside `reconstructPagePattern`; the target boundary moves the emit decision to DLA hooks while keeping the pure mapper shared.
+
+## 1. INVENTORY
+
+Frozen G2 command:
+
+```sh
+cd /Users/matt/projects/a8c/data-liberation-agent && grep -nE "^(export )?(async )?function |^export (const|interface|type) " src/lib/replicate/page-reconstruct.ts | wc -l
+```
+
+Current result: `46`.
+
+Inventory result in this doc:
+
+- G2 symbols classified: `46 / 46`.
+- Top-level declarations classified: `57 / 57`.
+- Extra declarations beyond G2: local type aliases, local interfaces, local constants, dispatch sets, and the `export { escapeHtml }` re-export.
+
+### page-reconstruct.ts top-level declarations
+
+| Symbol | Lines | G2 | Class | Lift note |
+|---|---:|---:|---|---|
+| `FaqPair` | `page-reconstruct.ts:61-64` | yes | SHARED | Same shape as engine `ExtractedFaq`; keep as a section data contract, not DLA runtime. |
+| `SectionSpecWithFaqs` | `page-reconstruct.ts:67` | no | SHARED | Local alias over `SectionSpec`; engine `SectionSpec` already has `faqs`. |
+| `ReconstructOptions` | `page-reconstruct.ts:69-120` | yes | SHARED | Split later: deterministic options move to engine; adapter recipe and PHP/page-pattern options stay DLA. |
+| `ReconstructResult` | `page-reconstruct.ts:122-152` | yes | SHARED | Split later: block markup, diagnostics, assets, and hero signal move; PHP pattern wrapper and page install metadata stay DLA. |
+| `{ escapeHtml }` export | `page-reconstruct.ts:160` | no | SHARED | Engine already has `escapeHtml` in `packages/blocks-engine/src/escape.ts:13-15`; DLA re-export is compatibility surface. |
+| `visibleText` | `page-reconstruct.ts:165` | no | LIFT | Registers visible converted headings/paragraphs into the deterministic provenance corpus. |
+| `MISSING_IMAGE_PLACEHOLDER` | `page-reconstruct.ts:167` | no | LIFT | Deterministic honest placeholder for missing media. |
+| `MIN_LEAD_IMAGE_PX` | `page-reconstruct.ts:176` | no | LIFT | Deterministic lead-image threshold. |
+| `MIN_CELL_IMAGE_PX` | `page-reconstruct.ts:181` | no | LIFT | Deterministic cell/recovery image threshold. |
+| `pickLeadImage` | `page-reconstruct.ts:184-186` | yes | LIFT | Native recipe image selection. |
+| `isWpUrl` | `page-reconstruct.ts:189-191` | yes | LIFT | Deterministic migrated-media predicate; likely rename to `isWpMediaUrl`. |
+| `isTintedSection` | `page-reconstruct.ts:201-208` | yes | LIFT | Layout/color recipe for raised section surfaces. |
+| `BlockOut` | `page-reconstruct.ts:214-222` | no | LIFT | Internal render accumulator for markup, corpus, assets, flags, and icon assets. |
+| `emptyOut` | `page-reconstruct.ts:224-226` | yes | LIFT | Render accumulator initializer. |
+| `recolorSvg` | `page-reconstruct.ts:235-240` | yes | LIFT | Deterministic SVG color normalization after sanitization. |
+| `RenderCtx` | `page-reconstruct.ts:243-252` | no | LIFT | Per-page render context for alternating media, icon ids, palette, and fonts. |
+| `iconImageBlock` | `page-reconstruct.ts:261-289` | yes | LIFT | Native icon asset emission; engine must thread assets through `ThemeModel.assets`. |
+| `resolveImage` | `page-reconstruct.ts:292-306` | yes | LIFT | Honest media fallback and provenance flagging. |
+| `imageBlock` | `page-reconstruct.ts:308-346` | yes | LIFT | Native `core/image` emission with source dimensions. |
+| `responsiveFontSize` | `page-reconstruct.ts:353-358` | yes | LIFT | Deterministic responsive font-size clamp. |
+| `responsiveSpace` | `page-reconstruct.ts:364-370` | yes | LIFT | Deterministic responsive spacing clamp. |
+| `sectionPad` | `page-reconstruct.ts:375-382` | yes | LIFT | Maps captured section padding into block spacing. |
+| `centerOf` | `page-reconstruct.ts:388-390` | yes | LIFT | Text alignment helper with back-compat fallback. |
+| `buttonJustify` | `page-reconstruct.ts:395-397` | yes | LIFT | Button row alignment helper. |
+| `typographyStyle` | `page-reconstruct.ts:403-418` | yes | LIFT | Block typography attr/inline style generation. |
+| `familyHash` | `page-reconstruct.ts:420-423` | yes | LIFT | Font-family matching helper. |
+| `familyMatches` | `page-reconstruct.ts:427-438` | yes | LIFT | Font-family token matching. |
+| `nearestFamily` | `page-reconstruct.ts:449-466` | yes | LIFT | Maps captured computed font-family to theme token slug. |
+| `headingBlock` | `page-reconstruct.ts:468-502` | yes | LIFT | Native heading emitter and expected-text registration. |
+| `paragraphBlock` | `page-reconstruct.ts:504-541` | yes | LIFT | Native paragraph emitter and body-text registration. |
+| `buttonBlock` | `page-reconstruct.ts:543-560` | yes | LIFT | Hrefless fallback CTA block. |
+| `rgbToHex` | `page-reconstruct.ts:563-568` | yes | LIFT | Captured RGB to hex conversion for icon color. |
+| `ctaButton` | `page-reconstruct.ts:577-629` | yes | LIFT | Native CTA block with captured href, colors, and icon. |
+| `sectionButtons` | `page-reconstruct.ts:633-639` | yes | LIFT | Shared CTA selection for renderers. |
+| `renderTextBand` | `page-reconstruct.ts:642-681` | yes | LIFT | Native text-band recipe. |
+| `renderCover` | `page-reconstruct.ts:688-721` | yes | LIFT | Native hero/cover recipe and overlay-header input. |
+| `renderMediaText` | `page-reconstruct.ts:724-758` | yes | LIFT | Native media-text recipe. |
+| `renderCardGrid` | `page-reconstruct.ts:765-789` | yes | LIFT | Native product/project/blog card grid recipe. |
+| `dedupeAdjacent` | `page-reconstruct.ts:792-798` | yes | LIFT | Review/grid copy cleanup. |
+| `renderReviewGrid` | `page-reconstruct.ts:804-876` | yes | LIFT | Native review/testimonial grid recipe. |
+| `galleryBlock` | `page-reconstruct.ts:881-955` | yes | LIFT | Native gallery/scroller emission. |
+| `renderImageRow` | `page-reconstruct.ts:959-968` | yes | LIFT | Native gallery/logo/image-row section recipe. |
+| `renderFaq` | `page-reconstruct.ts:971-1001` | yes | LIFT | Native FAQ/details recipe; engine `SectionSpec` already has `faqs`. |
+| `column` | `page-reconstruct.ts:1005-1013` | yes | LIFT | Low-level columns wrapper. |
+| `columns` | `page-reconstruct.ts:1015-1031` | yes | LIFT | Columns layout wrapper with full-bleed switch. |
+| `wrapSection` | `page-reconstruct.ts:1033-1107` | yes | LIFT | Main native section wrapper, layout, spacing, and background decisions. |
+| `opaqueTintHex` | `page-reconstruct.ts:1116-1140` | yes | LIFT | Deterministic captured-tint normalization. |
+| `isDarkSection` | `page-reconstruct.ts:1143-1145` | yes | LIFT | Inverse text/background predicate. |
+| `renderCellGrid` | `page-reconstruct.ts:1157-1238` | yes | LIFT | Native cell/card grid recipe, including full-bleed card rows. |
+| `cardGroup` | `page-reconstruct.ts:1244-1275` | yes | LIFT | Native styled-card wrapper. |
+| `NON_CELL_GRID_MODELS` | `page-reconstruct.ts:1278-1284` | no | LIFT | Dispatch guard for cell-grid routing. |
+| `FLATTEN_PRONE_MODELS` | `page-reconstruct.ts:1290-1296` | no | LIFT | Dispatch guard for relaxed unflattening. |
+| `MEDIA_LAYOUT_DENY` | `page-reconstruct.ts:1301-1311` | no | LIFT | Dispatch guard for media-layout rerouting. |
+| `renderSection` | `page-reconstruct.ts:1317-1430` | yes | LIFT | Core native recipe dispatch. |
+| `renderSectionForms` | `page-reconstruct.ts:1444-1462` | yes | STAY-DLA | Emits Jetpack/contact-form markup and provenance flags; pure mapper is shared, emit decision stays DLA. |
+| `reconstructPagePattern` | `page-reconstruct.ts:1468-1840` | yes | SHARED | Split: deterministic section normalization, native render, coverage, fallback, diagnostics move; PHP header, adapter recipe, Jetpack emit, and DLA page corpus integration stay DLA. |
+| `dedupe` | `page-reconstruct.ts:1842-1844` | yes | LIFT | Deterministic output de-duplication helper. |
+
+### Key imported helpers
+
+| Imported helper | Import site | Source lines | Class | Lift note |
+|---|---:|---:|---|---|
+| `SectionSpec`, `SectionSpecImage`, `SectionSpecIcon`, `SectionSpecCell` | `page-reconstruct.ts:29` | DLA `section-extract.ts:526-759`; engine `section-spec.ts:35-174` | SHARED | The data contract belongs in engine; Playwright/browser capture that populates it stays DLA. |
+| `nearestToken`, `brightness`, `PaletteToken` | `page-reconstruct.ts:30` | DLA `footer-color.ts:19-123` | LIFT | Pure color/token math used by native recipes; image sampling helpers in the same DLA file stay DLA. |
+| `ExtractedReview` | `page-reconstruct.ts:31` | DLA `review-extract.ts:27`; engine `section-spec.ts:23-28` | SHARED | Data type only; extraction stays DLA. |
+| `cheerio` | `page-reconstruct.ts:32` | external dep; used at `page-reconstruct.ts:1516` | SHARED | Deterministic HTML text decoding is allowed in engine; no browser. |
+| `buildHtmlFallbackBlock`, `selectIslandSource` | `page-reconstruct.ts:33-48` | engine `html-fallback.ts:48-86` | SHARED | Already engine-owned fallback island helpers. |
+| `measureSectionCoverage`, `measureConvertedCoverage`, `foldText` | `page-reconstruct.ts:33-48` | engine `section-coverage.ts:17-107` | SHARED | Already engine-owned coverage primitives. |
+| `formToBlocks`, `SKIPPED_FIELD_KINDS` | `page-reconstruct.ts:33-48` | engine `form-blocks.ts:55-159` | SHARED | Pure HTML-form to Jetpack-block mapper is engine-owned; deciding to emit/activate Jetpack stays DLA. |
+| `buildFallbackDiagnostic`, `FallbackDiagnostic` | `page-reconstruct.ts:33-48` | engine `fallback-diagnostic.ts:4-69` | SHARED | Already engine-owned deterministic diagnostics. |
+| `normalizeCopy`, `sanitizePatternHeaderField`, `stripChrome`, `sanitizeSvgAsset`, `FontFamilyToken` | `page-reconstruct.ts:33-48` | engine `page-reconstruct-helpers.ts:6-123` | SHARED | Already engine-owned page-reconstruct helper subset. |
+| `rewriteMediaUrls` | `page-reconstruct.ts:49` | DLA `media-url-rewrite.ts:45-107`; engine `url-rewrite.ts:3-95` | SHARED | Use engine implementation after lift. |
+| `hasUnmigratedRemoteAsset`, `scanForInjection` | `page-reconstruct.ts:50` | DLA `validate-artifacts.ts:130-195`; engine `injection-scan.ts:1-24` | SHARED | Use engine implementation after lift; full DLA artifact validation stays DLA. |
+| `applyBlockRecipe` | `page-reconstruct.ts:51` | DLA `apply-block-recipe.ts:16-65` | STAY-DLA | Adapter/platform recipe hook; not part of standalone engine core. |
+| `escapeHtml` | `page-reconstruct.ts:159-160` | DLA `html-escape.ts:23-25`; engine `escape.ts:13-15` | SHARED | Use engine escape helper after lift; DLA re-export can remain for compatibility until consumers move. |
+
+### Adjacent deterministic surfaces not top-level in page-reconstruct.ts
+
+- Variation hoisting is named by the Phase 6 spec but is not implemented inside `page-reconstruct.ts`. DLA owns it in `src/lib/replicate/variation-hoist.ts:1-186`; it depends on `serializeBlockAttrs` from DLA `form-blocks.ts:9-13`. Engine has a leaf `serializeBlockAttrs` at `packages/blocks-engine/src/theme/form-blocks.ts:80-86`, but the public barrel currently exports only `formToBlocks` and `SKIPPED_FIELD_KINDS` at `packages/blocks-engine/src/theme/index.ts:22`. Treat variation hoisting as a later dedicated sub-slice, not part of the first page-reconstruct renderer lift.
+- The DLA `dla/editable-html` block plugin is outside `page-reconstruct.ts`; it is built by `src/blocks/editable-html-plugin.ts:4-215`, emitted by `src/lib/replicate/normalize/island-bindings.ts:375-386`, converted by `src/lib/replicate/normalize/make-islands-editable.ts:27-49`, and installed from `convert-local-site.ts:806`. It stays DLA.
+
+## 2. NATIVE-FIRST DESCENT
+
+Live DLA does not contain a generic raw-DOM recursive descent in `page-reconstruct.ts`. The native-first behavior is a decision chain over `SectionSpec` plus optional pre-converted native blocks.
+
+### Decision chain
+
+1. Normalize the section list.
+   - `reconstructPagePattern` strips header/footer chrome with `stripChrome`, resolves captured font families to theme tokens, and removes only verified promoted-heading echoes. See `page-reconstruct.ts:1468-1543`.
+   - This is deterministic and should move, but `patternSlug`, PHP title, and page pattern header concerns should not.
+
+2. Accept pre-converted native blocks when they are safe.
+   - `opts.convertedSections` is checked per `sectionIndex`; accepted only when markup exists, `wpHtmlResidue === 0`, media URLs are rewritten, remote assets are gone, unresolved placeholders are absent, injection scan is clean, and `measureConvertedCoverage` reports no loss. See `page-reconstruct.ts:1558-1602`.
+   - When accepted, DLA registers visible `<h*>` and `<p>` text from the converted markup into provenance and appends captured forms after the converted blocks. See `page-reconstruct.ts:1591-1606`.
+   - Lift target: engine-owned converted-section acceptance. Sever point: form append moves to DLA hook behavior.
+
+3. Suppress form echo before native rendering.
+   - For sections with forms, DLA suppresses recaptured submit labels/buttons and field-label echo cells so the structured renderer does not duplicate dead CTAs or route a form band into the wrong cell grid. See `page-reconstruct.ts:1614-1670`.
+   - This logic is coupled to Jetpack form emit. It should stay DLA unless the engine receives a plugin-free "form remainder" contract.
+
+4. Render native blocks from the spec model.
+   - `renderSection` dispatches by FAQ, cell-grid eligibility, captured `mediaLayout`, and `interactionModel`. See `page-reconstruct.ts:1317-1430`.
+   - The recipe catalog includes text bands, cover heroes, media-text, cards, reviews, galleries, FAQ/details, cell grids, image rows, and layout wrappers. See `page-reconstruct.ts:642-1275`.
+   - Lift target: engine native renderer modules.
+
+5. Recover recoverable image-only loss.
+   - After native render, `measureSectionCoverage` checks captured text and images against emitted markup. If only recoverable WP images are missing, DLA appends image blocks and re-measures. See `page-reconstruct.ts:1717-1757`.
+   - Lift target: engine recovery module using existing engine coverage primitives.
+
+6. Try DLA adapter recipe, then core/html island.
+   - If coverage is still lost, DLA first tries `applyBlockRecipe` only when `adapterBlocks` exists. See `page-reconstruct.ts:1760-1775`.
+   - If no recipe applies, it picks `sectionHtml` or `styledHtml` via `selectIslandSource`, builds a sanitized `core/html` island, records provenance, and creates a fallback diagnostic. See `page-reconstruct.ts:1778-1805`.
+   - Lift target: engine fallback island and diagnostics. Sever point: adapter recipe stays DLA.
+
+7. Return page-level artifacts.
+   - DLA builds a PHP pattern header, body markup, expected text/body/assets, provenance flags, fallback diagnostics, section count, icon assets, and `heroIsCover`. See `page-reconstruct.ts:1815-1840`.
+   - Lift target: body markup, diagnostics, icon assets, and hero signal. DLA keeps PHP pattern file shape and install-time page artifacts.
+
+### Current entanglements to sever
+
+- Jetpack: `renderSectionForms` emits `jetpack/contact-form` blocks and form provenance inside the reconstruct loop at `page-reconstruct.ts:1444-1462`, with call sites at `page-reconstruct.ts:1603-1606` and `page-reconstruct.ts:1671-1702`. The engine must not decide to emit Jetpack or activate modules.
+- Editable HTML: DLA convert defaults `editableIslands` on at `convert-local-site.ts:393-395` and installs the block plugin only when islands are converted at `convert-local-site.ts:806`. Engine must emit plain `core/html` islands.
+- Adapter recipes: `adapterBlocks` in `ReconstructOptions` at `page-reconstruct.ts:95-106` and `applyBlockRecipe` at `page-reconstruct.ts:1760-1775` are platform/adapter aware. Keep them DLA-side.
+- Artifact validation: `scanForInjection` and remote asset predicates are shared primitives, but full DLA artifact validation remains DLA in `validate-artifacts.ts:198-259`.
+- PHP pattern wrapper: `sanitizePatternHeaderField` is shared, but the PHP header in `page-reconstruct.ts:1815-1822` is a DLA pattern file concern.
+
+## 3. ENGINE DECOMPOSITION
+
+Keep the public stage entrypoint centered on the existing engine stage:
+
+- Existing public stage: `packages/blocks-engine/src/theme/reconstruct.ts:111-141`.
+- Existing hook/context types: `SectionBlocks` at `packages/blocks-engine/src/theme/types.ts:45-49`, `StageCtx` at `packages/blocks-engine/src/theme/types.ts:60-65`, and `SiteToThemeHooks` at `packages/blocks-engine/src/theme/types.ts:73-78`.
+- Existing orchestrator: `packages/blocks-engine/src/theme/site-to-theme.ts:46-92`.
+
+The lift should not move the DLA monolith whole. Proposed engine modules:
+
+| Engine file | Responsibility | Frozen interface to expose |
+|---|---|---|
+| `src/theme/reconstruct.ts` | Keep the public stage. Iterate specs, call converted acceptance, native renderer, recovery, fallback, hooks, and return `SectionBlocks[]`. | Existing `reconstruct(specs, ctx, pool, hooks, coverageFloor): Promise<SectionBlocks[]>`. No new public package export required in the first behavior slice. |
+| `src/theme/native-reconstruct-types.ts` | Internal contracts for the lifted renderer: render accumulator, render context, accepted converted result, fallback result, icon asset output. | `NativeRenderOut`, `NativeRenderCtx`, `NativeSectionResult`, `ConvertedSectionInput`, `SectionRenderOptions`. |
+| `src/theme/native-converted-section.ts` | Accept or reject pre-converted native block markup using residue, media rewrite, remote asset, placeholder, injection, and coverage gates. | `acceptConvertedSection(spec, converted, opts): NativeSectionResult | null`. |
+| `src/theme/native-block-builders.ts` | Low-level block emitters for headings, paragraphs, buttons, CTAs, images, icons, galleries, columns, and groups. | `buildHeadingBlock`, `buildParagraphBlock`, `buildImageBlock`, `buildCtaButton`, `buildGalleryBlock`, `wrapNativeSection`. Keep most exports internal to theme tests. |
+| `src/theme/native-layout.ts` | Section layout decisions: spacing clamps, full-bleed/constrained layout, tint/dark/background decisions, button alignment, media alternation. | `resolveSectionLayout(spec, ctx)`, `responsiveSpace`, `responsiveFontSize`, `isTintedSection`, `isDarkSection`. |
+| `src/theme/native-fonts.ts` | Captured font-family to theme font token mapping. | `nearestFamily(computed, tokens): string | null`, `familyMatches`. |
+| `src/theme/native-media.ts` | Lead image selection, migrated-media predicate, SVG sanitization/recolor use, image recovery eligibility, icon asset naming. | `pickLeadImage`, `isWpMediaUrl`, `recoverMissingImages`, `buildIconAssetImage`. |
+| `src/theme/native-section-recipes.ts` | Recipe catalog and dispatch for text band, cover, media-text, cards, reviews, image rows, FAQ/details, cell grids. | `renderNativeSection(spec, ctx): NativeRenderOut`. |
+| `src/theme/native-fallback.ts` | Coverage loss fallback, source selection, `core/html` island build, and fallback diagnostic creation using existing `html-fallback.ts` and `fallback-diagnostic.ts`. | `buildNativeFallback(spec, coverage, opts): NativeSectionResult`. |
+| `src/theme/native-form-remainder.ts` | Plugin-free form boundary. Do not emit Jetpack. Decide whether a form remains a plain `core/html` island or an event for DLA hooks. | `extractFormRemainder(spec): FormRemainder | null`; no Jetpack block names. This interface needs a freeze slice before use. |
+| `src/theme/native-page-render.ts` | Optional pure page renderer for tests and DLA parity harness, without PHP pattern files. | `renderNativePage(sections, opts): NativePageRenderResult` with body, diagnostics, icon assets, hero signal, and provenance corpus. |
+
+Reuse existing modules rather than duplicating:
+
+- `html-fallback.ts` for sanitized `core/html` islands.
+- `section-coverage.ts` for text/image coverage.
+- `fallback-diagnostic.ts` for fallback records.
+- `page-reconstruct-helpers.ts` for copy/header/chrome/SVG helper surface already ported.
+- `url-rewrite.ts` and `injection-scan.ts` for media rewrite and safety gates.
+- `section-spec.ts` for section data contracts.
+- `form-blocks.ts` only as a pure shared mapper; Jetpack emission policy stays outside engine.
+
+Package-barrel rule:
+
+- Do not export every new native helper from `src/theme/index.ts` by default.
+- Export only contracts required by DLA parity/adoption tests. Internal recipe modules can remain leaf-internal until DLA needs them.
+
+## 4. HOOK SEAM
+
+Current hook types:
+
+- `StageCtx` contains `srcDir`, `site`, `themeMeta`, and `warn` at `packages/blocks-engine/src/theme/types.ts:60-65`.
+- `SectionBlocks` contains `spec`, `blocks`, and `coverage` at `packages/blocks-engine/src/theme/types.ts:45-49`.
+- `SiteToThemeHooks` defines `onSection`, `onAssets`, and `onRefine` at `packages/blocks-engine/src/theme/types.ts:73-78`.
+- `siteToTheme` passes hooks to `reconstruct`, applies `onAssets`, then applies `onRefine` before `writeTheme` at `packages/blocks-engine/src/theme/site-to-theme.ts:49-92`.
+
+Current limitation:
+
+- `reconstruct` only invokes `hooks.onSection` when `section.coverage <= coverageFloor` at `packages/blocks-engine/src/theme/reconstruct.ts:126-136`.
+- The behavior is intentionally covered by `theme-reconstruct.test.ts:288-319`, which expects `onSection` to observe only a fallback/coverage-0 section.
+- This is enough for plain `core/html` islands because `skeletonCoverage` returns 0 for html islands at `packages/blocks-engine/src/theme/reconstruct.ts:76-78`.
+- It is not enough to let DLA append Jetpack forms after a fully native form-containing section unless the lifted engine marks form remainder as an island/low-coverage section or a later contract changes the hook policy.
+
+Target seam:
+
+1. Engine deterministic output, hook absent.
+   - Native sections emit core blocks.
+   - Irreducible remainders emit sanitized, plugin-free `core/html` islands through `buildHtmlFallbackBlock`.
+   - Forms do not become Jetpack blocks. If a form cannot be represented with core blocks, it remains a deterministic remainder island or a typed form remainder.
+   - No `dla/editable-html`, no `jetpack/*` activation decision, no Playwright, no vision, no plugin install.
+
+2. DLA `onSection`, hook present.
+   - Input: `SectionBlocks` with original `section.spec` and deterministic engine `blocks`.
+   - Editable-html conversion: replace engine `core/html` island markup with `dla/editable-html` only in DLA. DLA owns the block implementation in `src/blocks/editable-html-plugin.ts:4-215` and the install decision in `convert-local-site.ts:806`.
+   - Jetpack emit: when `section.spec.forms` exists, DLA uses shared `formToBlocks` grammar but decides whether and where to append live `jetpack/contact-form` markup. It also records skipped-field provenance and sets any counters used to decide Jetpack install/module activation.
+   - If the current coverage-gated hook policy is retained, engine must ensure sections needing DLA form/editable processing have `coverage` at or below the floor. The cleaner later contract is an explicit `onSection` policy or typed `SectionBlocks.events`, frozen before implementation.
+
+3. DLA `onRefine`, hook present.
+   - Input: full `ThemeModel` after assemble and before write.
+   - DLA can make final theme-model substitutions that require whole-theme context: replace residual islands in templates/patterns, inject page-local templates, preserve sidecar page content, and align interior chrome. Current DLA already uses `onRefine` in `convert-local-site.ts:760-779`.
+   - DLA still performs post-return plugin packaging/install, `functions.php`, Studio/WP install, Jetpack module activation, safe-svg, parity repair, and editor scoring outside engine. See `convert-local-site.ts:873-991` and `convert-local-site.ts:1014-1683`.
+
+Required contract decision before code lift:
+
+- Either freeze "engine calls `onSection` for every section after deterministic render" or freeze "engine emits typed low-coverage form/editable remainders so current gated `onSection` semantics remain enough." The second option changes less of the existing hook contract, but it forces form sections through a remainder marker when DLA needs Jetpack emit.
+- A third option is to move `onSection` to a pre-finalization section-tail point, where DLA can append Jetpack markup before final coverage/fallback. That is a real contract change because it reverses the current post-fallback expectation in `theme-reconstruct.test.ts:288-319`; freeze it explicitly before any renderer port.
+
+## 5. PARITY PROOF STRATEGY
+
+The safety net must prove deterministic behavior, not only shape. The proof should be layered so each sub-slice catches drift early.
+
+### Golden corpus
+
+Create a DLA-owned fixture corpus from captured `SectionSpec[]` and known `ReconstructOptions` that covers:
+
+- Converted-native acceptance with `convertedSections` and `wpHtmlResidue === 0`.
+- Converted-native rejection on remote assets, unresolved placeholders, injection, and coverage loss.
+- Text band, cover hero, media-text, product/project/blog cards, review grid, gallery/image row, FAQ/details, cell grid, full-bleed card row.
+- Heading echo suppression with decoded HTML entities.
+- Missing image placeholder, recoverable image append, and unrecoverable island fallback.
+- `styledHtml` vs `sectionHtml` island tier selection.
+- Fallback diagnostics.
+- Form sections, but split into deterministic core expectation and DLA hook expectation.
+- Adapter recipe cases kept as DLA-only expectations.
+
+### Byte comparisons
+
+1. DLA-today baseline.
+   - Run current DLA `reconstructPagePattern(sections, opts)` over the corpus.
+   - Save `body`, `expectedText`, `bodyText`, `expectedAssets`, `provenanceFlags`, `fallbackDiagnostics`, `iconAssets`, and `heroIsCover`.
+   - For DLA-only surfaces, save `php` separately so engine is not forced to own PHP pattern headers.
+
+2. Engine deterministic core.
+   - Run the engine lifted renderer over the same injected `SectionSpec[]`, palette tokens, font tokens, media map, and converted-section data.
+   - Compare body markup, diagnostics, assets, icon assets, and hero signal byte-for-byte against the DLA deterministic subset.
+   - Exclude `adapterBlocks`, Jetpack emit, editable-html conversion, and PHP header from this core comparison unless DLA hooks are intentionally enabled.
+
+3. Engine plus DLA hooks.
+   - Run `siteToTheme(srcDir, { sections, foundationAggregates, hooks, coverageFloor, fetchImpl })` with captured specs injected through `SiteToThemeOptions.sections`.
+   - DLA hooks convert islands to `dla/editable-html`, append/replace Jetpack forms, and then DLA performs post-return plugin/module steps.
+   - Compare final DLA-generated theme/page artifacts to DLA-today bytes for the deterministic path. Any allowed difference must be predeclared in the frozen gate.
+
+### Test placement
+
+- Engine tests own pure renderer parity for deterministic helpers and recipes.
+- DLA tests own hook integration, editable-html conversion, Jetpack emission, plugin activation decisions, and byte comparison against DLA-today.
+- No browser, Playwright, WP install, network, AI, time, random, or screenshot dependency belongs in deterministic-core gates.
+
+### Gate style
+
+- Every sub-slice gets a corpus count and byte-diff count.
+- Gates must report both exact command and raw result, for example `cases=12 diffs=0`.
+- If a grep gate is used, it must target module paths or exported symbols, not data/provenance strings. Do not repeat the prior gate-gaming failure mode.
+
+## 6. SUB-SLICE PLAN
+
+### FTP2b - freeze native reconstruct contracts and parity corpus
+
+Scope:
+
+- Add engine contract files for native reconstruct internal result types and form remainder/event shape.
+- Add DLA or shared fixtures that serialize the DLA-today deterministic corpus without changing runtime behavior.
+- Freeze whether `onSection` runs for all sections, runs pre-finalization, or remains low-coverage only with typed remainders.
+
+Out of scope:
+
+- No renderer behavior port.
+- No DLA adoption.
+- No editable-html or Jetpack behavior change.
+
+Parity/acceptance gate:
+
+- Engine typecheck and tests pass.
+- DLA corpus generator/test reports current DLA baseline cases with `diffs=0` against checked-in goldens or freshly frozen snapshots.
+- Contract freeze commit contains only contract/test fixture files; contracts are read-only after this slice.
+
+### FTP2c - port low-level native block builders and layout/media helpers
+
+Scope:
+
+- Port deterministic helpers from `page-reconstruct.ts:165-639` plus low-level wrappers/layout primitives from `page-reconstruct.ts:1005-1145`.
+- Include color token helpers from DLA `footer-color.ts:103-123`.
+- Add unit tests for copy normalization, image placeholder/recovery eligibility, SVG icon asset emission, responsive font/space clamps, tint/dark/full-bleed decisions, and font-family token mapping.
+
+Out of scope:
+
+- No `renderSection` dispatch.
+- No `reconstruct.ts` wiring.
+- No forms, adapter recipe, editable-html, Jetpack, or DLA import changes.
+
+Parity/acceptance gate:
+
+- Engine helper tests compare each ported helper against DLA-today corpus outputs with `diffs=0`.
+- Browser-free grep over new engine theme files prints OK.
+- `git show --name-status HEAD` lists only new/changed engine helper and test files for this slice.
+
+### FTP2d - port native section recipe catalog
+
+Scope:
+
+- Port `renderTextBand`, `renderCover`, `renderMediaText`, `renderCardGrid`, `renderReviewGrid`, `galleryBlock`, `renderImageRow`, `renderFaq`, `renderCellGrid`, `cardGroup`, dispatch sets, and `renderSection`.
+- Use engine `SectionSpec` and engine helper modules.
+- Produce `NativeSectionResult` without PHP header or Jetpack form append.
+
+Out of scope:
+
+- No converted-section fast path.
+- No coverage fallback integration into the public `reconstruct` stage.
+- No DLA adoption.
+
+Parity/acceptance gate:
+
+- Engine recipe corpus covers every `interactionModel` routed by `renderSection` and reports `cases>=10 diffs=0` against DLA deterministic native output with forms disabled or separated.
+- Typecheck, full engine tests, and browser-free grep pass.
+
+### FTP2e - wire converted acceptance, coverage recovery, and core/html fallback into engine reconstruct
+
+Scope:
+
+- Add `native-converted-section.ts` and `native-fallback.ts`.
+- Wire existing `reconstruct.ts` to use injected/precomputed converted sections where available, native recipes otherwise, recover image-only loss, and fall back to engine `core/html` islands with diagnostics.
+- Preserve current `reconstruct(specs, ctx, pool, hooks, coverageFloor)` public signature unless FTP2b froze a change.
+
+Out of scope:
+
+- No DLA editable-html conversion.
+- No Jetpack emit.
+- No adapter recipe port.
+- No PHP pattern generation.
+
+Parity/acceptance gate:
+
+- Engine reconstruct parity corpus reports converted accept/reject, recovery, fallback tier, and diagnostics with `diffs=0` against DLA deterministic subset.
+- Existing site-to-theme e2e fixtures still pass.
+- Hook-absent identity and React-isolation tests remain green.
+
+### FTP2f - DLA hook seam for editable-html and Jetpack forms
+
+Scope:
+
+- In DLA, implement `onSection`/`onRefine` hook behavior that converts engine `core/html` islands to `dla/editable-html` and emits Jetpack forms after engine deterministic output.
+- Keep `buildEditableHtmlPlugin`, plugin install, Jetpack install/module activation, safe-svg, and WP/Studio steps in DLA.
+- Use engine `formToBlocks` as a shared pure mapper; do not move activation decisions.
+
+Out of scope:
+
+- No engine recipe changes except contract fixes required by FTP2b.
+- No Playwright capture changes.
+- No vision asset triage changes.
+- No adapter recipe deletion.
+
+Parity/acceptance gate:
+
+- DLA engine-injected corpus with hooks enabled matches DLA-today deterministic output with `diffs=0`, including form sections and editable islands.
+- Targeted DLA tests for editable-html plugin install decision and Jetpack activation decision pass.
+- No `dla/editable-html` or `jetpack/*` strings are introduced into engine source files outside existing pure form grammar.
+
+### FTP2g - DLA adoption of engine native reconstruct core
+
+Scope:
+
+- Repoint DLA `page-reconstruct.ts` deterministic renderer calls to engine native reconstruct exports or replace the monolith's deterministic body with engine calls.
+- Delete or strip DLA duplicate deterministic helpers only after the parity harness is green.
+- Keep DLA `applyBlockRecipe`, PHP pattern wrapper, editable-html hook, Jetpack hook, plugin activation, artifact validation, and repair/editor flow.
+
+Out of scope:
+
+- No delete of Playwright capture, source extraction, asset triage, adapter recipe, or plugin-aware install modules.
+- No npm publish without user authorization.
+- No broad grep gates that match provenance strings.
+
+Parity/acceptance gate:
+
+- DLA targeted reconstruct tests pass.
+- DLA byte parity corpus reports `diffs=0` for engine-injected deterministic core plus DLA hooks.
+- Deletion/repoint proof shows no DLA production consumer imports removed deterministic helpers from the old DLA module.
+- Hygiene gate lists only intended DLA files and engine dependency/import changes.
+
+### FTP2h - variation hoisting follow-up
+
+Scope:
+
+- Decide whether variation hoisting moves into engine after native reconstruct output is engine-owned.
+- If lifted, expose `serializeBlockAttrs` or an equivalent attr serializer through the engine public theme barrel and port `variation-hoist.ts` deterministically.
+
+Out of scope:
+
+- Not part of the initial page-reconstruct renderer lift.
+- No Jetpack variation behavior changes; current DLA guard that excludes `jetpack/*` from hoisting must survive.
+
+Parity/acceptance gate:
+
+- Variation corpus reports `diffs=0` for hoist decisions and swapped markup.
+- Jetpack and `core/html` exclusion tests remain green.

From 0139f9f048924bb54410dead84ec89a4d39af88c Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 17:24:09 -0400
Subject: [PATCH 082/113] feat(theme): freeze native reconstruct contracts

---
 .../src/theme/native-reconstruct-types.ts     | 53 +++++++++++++++++++
 packages/blocks-engine/src/theme/types.ts     |  2 +
 2 files changed, 55 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/native-reconstruct-types.ts

diff --git a/packages/blocks-engine/src/theme/native-reconstruct-types.ts b/packages/blocks-engine/src/theme/native-reconstruct-types.ts
new file mode 100644
index 00000000..6ccd8347
--- /dev/null
+++ b/packages/blocks-engine/src/theme/native-reconstruct-types.ts
@@ -0,0 +1,53 @@
+import type { FallbackDiagnostic } from './fallback-diagnostic.js';
+import type { FontFamilyToken } from './page-reconstruct-helpers.js';
+import type { CoverageResult } from './section-coverage.js';
+import type { SectionSpec, SectionSpecForm } from './section-spec.js';
+
+export interface FormRemainder {
+  forms: SectionSpecForm[];
+}
+
+export interface NativeRenderOut {
+  markup: string;
+  expectedText: string[];
+  bodyText: string[];
+  assets: string[];
+  flags: string[];
+  iconAssets: Array<{ path: string; svg: string }>;
+  remainder?: FormRemainder;
+}
+
+export interface NativeRenderCtx {
+  mediaTextIndex: number;
+  iconCounter: number;
+  paletteTokens: Array<{ slug: string; hex: string }>;
+  fontFamilies: FontFamilyToken[];
+}
+
+export interface NativeSectionResult {
+  spec: SectionSpec;
+  blocks: string;
+  coverage: CoverageResult;
+  expectedText: string[];
+  bodyText: string[];
+  expectedAssets: string[];
+  provenanceFlags: string[];
+  fallbackDiagnostics: FallbackDiagnostic[];
+  iconAssets: Array<{ path: string; svg: string }>;
+  heroIsCover?: boolean;
+  remainder?: FormRemainder;
+}
+
+export interface ConvertedSectionInput {
+  markup: string | null;
+  wpHtmlResidue: number;
+}
+
+export interface SectionRenderOptions {
+  mediaUrlMap?: Map<string, string>;
+  convertedSections?: Map<number, ConvertedSectionInput>;
+  paletteTokens?: Array<{ slug: string; hex: string }>;
+  fontFamilies?: FontFamilyToken[];
+  sourceUrl?: string;
+  slug?: string;
+}
diff --git a/packages/blocks-engine/src/theme/types.ts b/packages/blocks-engine/src/theme/types.ts
index b4c03cec..c58ddcce 100644
--- a/packages/blocks-engine/src/theme/types.ts
+++ b/packages/blocks-engine/src/theme/types.ts
@@ -1,5 +1,6 @@
 import type { WorkerPool } from '../pool/types.js';
 import type { SectionSpec } from './section-spec.js';
+import type { FormRemainder } from './native-reconstruct-types.js';
 import type { SourceCssCarryOptions } from './source-css-carry.js';
 
 export interface SiteModel {
@@ -46,6 +47,7 @@ export interface SectionBlocks {
   spec: SectionSpec;
   blocks: string;
   coverage: number;
+  remainder?: FormRemainder;
 }
 
 export interface AssetInventory {

From 06922359aa856aebeff3a62df996b7c73dd60f84 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 17:36:06 -0400
Subject: [PATCH 083/113] feat(theme): freeze native low-level helper surface

---
 .../theme-native-low-level-surface.test.ts    | 231 ++++++++++++++++++
 .../src/theme/native-block-builders.ts        | 148 +++++++++++
 .../blocks-engine/src/theme/native-color.ts   |  15 ++
 .../blocks-engine/src/theme/native-fonts.ts   |  13 +
 .../blocks-engine/src/theme/native-layout.ts  |  46 ++++
 .../blocks-engine/src/theme/native-media.ts   |  56 +++++
 6 files changed, 509 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-native-low-level-surface.test.ts
 create mode 100644 packages/blocks-engine/src/theme/native-block-builders.ts
 create mode 100644 packages/blocks-engine/src/theme/native-color.ts
 create mode 100644 packages/blocks-engine/src/theme/native-fonts.ts
 create mode 100644 packages/blocks-engine/src/theme/native-layout.ts
 create mode 100644 packages/blocks-engine/src/theme/native-media.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-native-low-level-surface.test.ts b/packages/blocks-engine/src/__tests__/theme-native-low-level-surface.test.ts
new file mode 100644
index 00000000..17e59552
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-native-low-level-surface.test.ts
@@ -0,0 +1,231 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { brightness, nearestToken, type PaletteToken } from '../theme/native-color.js';
+import { familyMatches, nearestFamily } from '../theme/native-fonts.js';
+import {
+  buttonJustify,
+  centerOf,
+  isDarkSection,
+  isTintedSection,
+  opaqueTintHex,
+  responsiveFontSize,
+  responsiveSpace,
+  sectionPad,
+  type SectionPadding,
+} from '../theme/native-layout.js';
+import {
+  MISSING_IMAGE_PLACEHOLDER,
+  iconImageBlock,
+  isWpMediaUrl,
+  pickLeadImage,
+  recolorSvg,
+  resolveImage,
+  type IconImageBlockOptions,
+  type ResolvedNativeImage,
+} from '../theme/native-media.js';
+import {
+  buttonBlock,
+  column,
+  columns,
+  ctaButton,
+  emptyNativeRenderOut,
+  headingBlock,
+  imageBlock,
+  paragraphBlock,
+  sectionButtons,
+  typographyStyle,
+  visibleText,
+  wrapSection,
+  type HeadingBlockOptions,
+  type ImageBlockOptions,
+  type NativeButtonInput,
+  type ParagraphBlockOptions,
+  type TypographyFragments,
+  type WrapSectionOptions,
+} from '../theme/native-block-builders.js';
+import type { FontFamilyToken } from '../theme/page-reconstruct-helpers.js';
+import type { NativeRenderCtx, NativeRenderOut } from '../theme/native-reconstruct-types.js';
+import type { SectionSpec, SectionSpecIcon, SectionSpecImage } from '../theme/section-spec.js';
+
+describe('native low-level helper frozen surface', () => {
+  it('freezes the helper export names and runtime availability', () => {
+    expect({
+      nearestToken,
+      brightness,
+      familyMatches,
+      nearestFamily,
+      responsiveFontSize,
+      responsiveSpace,
+      sectionPad,
+      centerOf,
+      buttonJustify,
+      isTintedSection,
+      opaqueTintHex,
+      isDarkSection,
+      pickLeadImage,
+      isWpMediaUrl,
+      recolorSvg,
+      resolveImage,
+      iconImageBlock,
+      visibleText,
+      emptyNativeRenderOut,
+      typographyStyle,
+      imageBlock,
+      headingBlock,
+      paragraphBlock,
+      buttonBlock,
+      ctaButton,
+      sectionButtons,
+      column,
+      columns,
+      wrapSection,
+    }).toEqual(
+      expect.objectContaining(
+        Object.fromEntries(
+          [
+            'nearestToken',
+            'brightness',
+            'familyMatches',
+            'nearestFamily',
+            'responsiveFontSize',
+            'responsiveSpace',
+            'sectionPad',
+            'centerOf',
+            'buttonJustify',
+            'isTintedSection',
+            'opaqueTintHex',
+            'isDarkSection',
+            'pickLeadImage',
+            'isWpMediaUrl',
+            'recolorSvg',
+            'resolveImage',
+            'iconImageBlock',
+            'visibleText',
+            'emptyNativeRenderOut',
+            'typographyStyle',
+            'imageBlock',
+            'headingBlock',
+            'paragraphBlock',
+            'buttonBlock',
+            'ctaButton',
+            'sectionButtons',
+            'column',
+            'columns',
+            'wrapSection',
+          ].map((name) => [name, expect.any(Function)])
+        )
+      )
+    );
+    expect(MISSING_IMAGE_PLACEHOLDER).toBe('[image unavailable — not captured]');
+  });
+
+  it('freezes the helper type signatures', () => {
+    expectTypeOf<PaletteToken>().toEqualTypeOf<{ slug: string; hex: string }>();
+    expectTypeOf<SectionPadding>().toEqualTypeOf<{ padTopPx?: number; padBottomPx?: number }>();
+    expectTypeOf<ResolvedNativeImage>().toEqualTypeOf<{ url: string; alt: string; usable: boolean }>();
+    expectTypeOf<IconImageBlockOptions>().toEqualTypeOf<{
+      sizePx?: number;
+      fill?: string;
+      align?: 'left' | 'center' | 'right';
+    }>();
+    expectTypeOf<TypographyFragments>().toEqualTypeOf<{ attr: string; inline: string }>();
+    expectTypeOf<HeadingBlockOptions>().toEqualTypeOf<{
+      level?: number;
+      center?: boolean;
+      muted?: boolean;
+      inverse?: boolean;
+      sizePx?: number;
+      fontFamily?: string | null;
+      lineHeight?: number;
+    }>();
+    expectTypeOf<ParagraphBlockOptions>().toEqualTypeOf<{
+      center?: boolean;
+      muted?: boolean;
+      size?: string;
+      inverse?: boolean;
+      sizePx?: number;
+      fontFamily?: string | null;
+      lineHeight?: number;
+    }>();
+    expectTypeOf<ImageBlockOptions>().toEqualTypeOf<{ rounded?: boolean; align?: 'center' | null }>();
+    expectTypeOf<NativeButtonInput>().toEqualTypeOf<{
+      label: string;
+      href?: string;
+      background?: string | null;
+      color?: string | null;
+      icon?: SectionSpecIcon | null;
+      iconAfter?: boolean;
+    }>();
+    expectTypeOf<WrapSectionOptions>().toEqualTypeOf<{
+      constrained?: string;
+      wide?: string;
+      center?: boolean;
+      raised?: boolean;
+      inverse?: boolean;
+      bgColor?: string;
+      padTopPx?: number;
+      padBottomPx?: number;
+      fullBleed?: boolean;
+    }>();
+
+    expectTypeOf(nearestToken).toEqualTypeOf<(hex: string, tokens: PaletteToken[]) => string | null>();
+    expectTypeOf(brightness).toEqualTypeOf<(hex: string) => number>();
+    expectTypeOf(familyMatches).toEqualTypeOf<(computed: string, token: FontFamilyToken) => boolean>();
+    expectTypeOf(nearestFamily).toEqualTypeOf<
+      (computed: string | undefined, tokens: FontFamilyToken[]) => string | null
+    >();
+    expectTypeOf(responsiveFontSize).toEqualTypeOf<(px: number | undefined) => string>();
+    expectTypeOf(responsiveSpace).toEqualTypeOf<(px: number) => string>();
+    expectTypeOf(sectionPad).toEqualTypeOf<(section: SectionSpec) => SectionPadding>();
+    expectTypeOf(centerOf).toEqualTypeOf<(section: SectionSpec) => boolean>();
+    expectTypeOf(buttonJustify).toEqualTypeOf<(section: SectionSpec) => 'left' | 'center'>();
+    expectTypeOf(isTintedSection).toEqualTypeOf<(section: SectionSpec) => boolean>();
+    expectTypeOf(opaqueTintHex).toEqualTypeOf<(color: string | null | undefined) => string | null>();
+    expectTypeOf(isDarkSection).toEqualTypeOf<(section: SectionSpec) => boolean>();
+    expectTypeOf(pickLeadImage).toEqualTypeOf<(images: SectionSpecImage[]) => SectionSpecImage | undefined>();
+    expectTypeOf(isWpMediaUrl).toEqualTypeOf<(url: string) => boolean>();
+    expectTypeOf(recolorSvg).toEqualTypeOf<(svg: string, hex: string) => string>();
+    expectTypeOf(resolveImage).toEqualTypeOf<
+      (image: SectionSpecImage | undefined, out: NativeRenderOut, context: string) => ResolvedNativeImage
+    >();
+    expectTypeOf(iconImageBlock).toEqualTypeOf<
+      (
+        icon: SectionSpecIcon,
+        out: NativeRenderOut,
+        ctx: NativeRenderCtx,
+        opts?: IconImageBlockOptions,
+      ) => string
+    >();
+    expectTypeOf(visibleText).toEqualTypeOf<(html: string) => string>();
+    expectTypeOf(emptyNativeRenderOut).toEqualTypeOf<() => NativeRenderOut>();
+    expectTypeOf(typographyStyle).toEqualTypeOf<
+      (fontCss: string, lineHeight?: number) => TypographyFragments
+    >();
+    expectTypeOf(imageBlock).toEqualTypeOf<
+      (
+        image: SectionSpecImage | undefined,
+        out: NativeRenderOut,
+        context: string,
+        opts?: ImageBlockOptions,
+      ) => string
+    >();
+    expectTypeOf(headingBlock).toEqualTypeOf<
+      (text: string, out: NativeRenderOut, opts?: HeadingBlockOptions) => string
+    >();
+    expectTypeOf(paragraphBlock).toEqualTypeOf<
+      (text: string, out: NativeRenderOut, opts?: ParagraphBlockOptions) => string
+    >();
+    expectTypeOf(buttonBlock).toEqualTypeOf<
+      (label: string, out: NativeRenderOut, opts?: { align?: 'left' | 'center' | 'right' }) => string
+    >();
+    expectTypeOf(ctaButton).toEqualTypeOf<
+      (out: NativeRenderOut, ctx: NativeRenderCtx, button: NativeButtonInput, opts?: { align?: 'left' | 'center' }) => string
+    >();
+    expectTypeOf(sectionButtons).toEqualTypeOf<
+      (section: SectionSpec, out: NativeRenderOut, ctx: NativeRenderCtx) => string[]
+    >();
+    expectTypeOf(column).toEqualTypeOf<(parts: string[], width?: string) => string>();
+    expectTypeOf(columns).toEqualTypeOf<(cols: string[], opts?: { fullBleed?: boolean }) => string>();
+    expectTypeOf(wrapSection).toEqualTypeOf<(parts: string[], opts: WrapSectionOptions) => string>();
+  });
+});
diff --git a/packages/blocks-engine/src/theme/native-block-builders.ts b/packages/blocks-engine/src/theme/native-block-builders.ts
new file mode 100644
index 00000000..8ea1370a
--- /dev/null
+++ b/packages/blocks-engine/src/theme/native-block-builders.ts
@@ -0,0 +1,148 @@
+import type { NativeRenderCtx, NativeRenderOut } from './native-reconstruct-types.js';
+import type { SectionSpec, SectionSpecIcon, SectionSpecImage } from './section-spec.js';
+
+export interface TypographyFragments {
+  attr: string;
+  inline: string;
+}
+
+export interface HeadingBlockOptions {
+  level?: number;
+  center?: boolean;
+  muted?: boolean;
+  inverse?: boolean;
+  sizePx?: number;
+  fontFamily?: string | null;
+  lineHeight?: number;
+}
+
+export interface ParagraphBlockOptions {
+  center?: boolean;
+  muted?: boolean;
+  size?: string;
+  inverse?: boolean;
+  sizePx?: number;
+  fontFamily?: string | null;
+  lineHeight?: number;
+}
+
+export interface ImageBlockOptions {
+  rounded?: boolean;
+  align?: 'center' | null;
+}
+
+export interface NativeButtonInput {
+  label: string;
+  href?: string;
+  background?: string | null;
+  color?: string | null;
+  icon?: SectionSpecIcon | null;
+  iconAfter?: boolean;
+}
+
+export interface CtaButtonOptions {
+  align?: 'left' | 'center';
+}
+
+export interface WrapSectionOptions {
+  constrained?: string;
+  wide?: string;
+  center?: boolean;
+  raised?: boolean;
+  inverse?: boolean;
+  bgColor?: string;
+  padTopPx?: number;
+  padBottomPx?: number;
+  fullBleed?: boolean;
+}
+
+export function visibleText(html: string): string {
+  void html;
+  throw new Error('native-block-builders visibleText is not implemented');
+}
+
+export function emptyNativeRenderOut(): NativeRenderOut {
+  throw new Error('native-block-builders emptyNativeRenderOut is not implemented');
+}
+
+export function typographyStyle(fontCss: string, lineHeight?: number): TypographyFragments {
+  void fontCss;
+  void lineHeight;
+  throw new Error('native-block-builders typographyStyle is not implemented');
+}
+
+export function imageBlock(
+  image: SectionSpecImage | undefined,
+  out: NativeRenderOut,
+  context: string,
+  opts?: ImageBlockOptions,
+): string {
+  void image;
+  void out;
+  void context;
+  void opts;
+  throw new Error('native-block-builders imageBlock is not implemented');
+}
+
+export function headingBlock(text: string, out: NativeRenderOut, opts?: HeadingBlockOptions): string {
+  void text;
+  void out;
+  void opts;
+  throw new Error('native-block-builders headingBlock is not implemented');
+}
+
+export function paragraphBlock(text: string, out: NativeRenderOut, opts?: ParagraphBlockOptions): string {
+  void text;
+  void out;
+  void opts;
+  throw new Error('native-block-builders paragraphBlock is not implemented');
+}
+
+export function buttonBlock(
+  label: string,
+  out: NativeRenderOut,
+  opts?: { align?: 'left' | 'center' | 'right' },
+): string {
+  void label;
+  void out;
+  void opts;
+  throw new Error('native-block-builders buttonBlock is not implemented');
+}
+
+export function ctaButton(
+  out: NativeRenderOut,
+  ctx: NativeRenderCtx,
+  button: NativeButtonInput,
+  opts?: CtaButtonOptions,
+): string {
+  void out;
+  void ctx;
+  void button;
+  void opts;
+  throw new Error('native-block-builders ctaButton is not implemented');
+}
+
+export function sectionButtons(section: SectionSpec, out: NativeRenderOut, ctx: NativeRenderCtx): string[] {
+  void section;
+  void out;
+  void ctx;
+  throw new Error('native-block-builders sectionButtons is not implemented');
+}
+
+export function column(parts: string[], width?: string): string {
+  void parts;
+  void width;
+  throw new Error('native-block-builders column is not implemented');
+}
+
+export function columns(cols: string[], opts?: { fullBleed?: boolean }): string {
+  void cols;
+  void opts;
+  throw new Error('native-block-builders columns is not implemented');
+}
+
+export function wrapSection(parts: string[], opts: WrapSectionOptions): string {
+  void parts;
+  void opts;
+  throw new Error('native-block-builders wrapSection is not implemented');
+}
diff --git a/packages/blocks-engine/src/theme/native-color.ts b/packages/blocks-engine/src/theme/native-color.ts
new file mode 100644
index 00000000..e7a0f00e
--- /dev/null
+++ b/packages/blocks-engine/src/theme/native-color.ts
@@ -0,0 +1,15 @@
+export interface PaletteToken {
+  slug: string;
+  hex: string;
+}
+
+export function nearestToken(hex: string, tokens: PaletteToken[]): string | null {
+  void hex;
+  void tokens;
+  throw new Error('native-color nearestToken is not implemented');
+}
+
+export function brightness(hex: string): number {
+  void hex;
+  throw new Error('native-color brightness is not implemented');
+}
diff --git a/packages/blocks-engine/src/theme/native-fonts.ts b/packages/blocks-engine/src/theme/native-fonts.ts
new file mode 100644
index 00000000..8d0f14c3
--- /dev/null
+++ b/packages/blocks-engine/src/theme/native-fonts.ts
@@ -0,0 +1,13 @@
+import type { FontFamilyToken } from './page-reconstruct-helpers.js';
+
+export function familyMatches(computed: string, token: FontFamilyToken): boolean {
+  void computed;
+  void token;
+  throw new Error('native-fonts familyMatches is not implemented');
+}
+
+export function nearestFamily(computed: string | undefined, tokens: FontFamilyToken[]): string | null {
+  void computed;
+  void tokens;
+  throw new Error('native-fonts nearestFamily is not implemented');
+}
diff --git a/packages/blocks-engine/src/theme/native-layout.ts b/packages/blocks-engine/src/theme/native-layout.ts
new file mode 100644
index 00000000..1895b513
--- /dev/null
+++ b/packages/blocks-engine/src/theme/native-layout.ts
@@ -0,0 +1,46 @@
+import type { SectionSpec } from './section-spec.js';
+
+export interface SectionPadding {
+  padTopPx?: number;
+  padBottomPx?: number;
+}
+
+export function responsiveFontSize(px: number | undefined): string {
+  void px;
+  throw new Error('native-layout responsiveFontSize is not implemented');
+}
+
+export function responsiveSpace(px: number): string {
+  void px;
+  throw new Error('native-layout responsiveSpace is not implemented');
+}
+
+export function sectionPad(section: SectionSpec): SectionPadding {
+  void section;
+  throw new Error('native-layout sectionPad is not implemented');
+}
+
+export function centerOf(section: SectionSpec): boolean {
+  void section;
+  throw new Error('native-layout centerOf is not implemented');
+}
+
+export function buttonJustify(section: SectionSpec): 'left' | 'center' {
+  void section;
+  throw new Error('native-layout buttonJustify is not implemented');
+}
+
+export function isTintedSection(section: SectionSpec): boolean {
+  void section;
+  throw new Error('native-layout isTintedSection is not implemented');
+}
+
+export function opaqueTintHex(color: string | null | undefined): string | null {
+  void color;
+  throw new Error('native-layout opaqueTintHex is not implemented');
+}
+
+export function isDarkSection(section: SectionSpec): boolean {
+  void section;
+  throw new Error('native-layout isDarkSection is not implemented');
+}
diff --git a/packages/blocks-engine/src/theme/native-media.ts b/packages/blocks-engine/src/theme/native-media.ts
new file mode 100644
index 00000000..f75bad93
--- /dev/null
+++ b/packages/blocks-engine/src/theme/native-media.ts
@@ -0,0 +1,56 @@
+import type { NativeRenderCtx, NativeRenderOut } from './native-reconstruct-types.js';
+import type { SectionSpecIcon, SectionSpecImage } from './section-spec.js';
+
+export const MISSING_IMAGE_PLACEHOLDER = '[image unavailable — not captured]';
+
+export interface ResolvedNativeImage {
+  url: string;
+  alt: string;
+  usable: boolean;
+}
+
+export interface IconImageBlockOptions {
+  sizePx?: number;
+  fill?: string;
+  align?: 'left' | 'center' | 'right';
+}
+
+export function pickLeadImage(images: SectionSpecImage[]): SectionSpecImage | undefined {
+  void images;
+  throw new Error('native-media pickLeadImage is not implemented');
+}
+
+export function isWpMediaUrl(url: string): boolean {
+  void url;
+  throw new Error('native-media isWpMediaUrl is not implemented');
+}
+
+export function recolorSvg(svg: string, hex: string): string {
+  void svg;
+  void hex;
+  throw new Error('native-media recolorSvg is not implemented');
+}
+
+export function resolveImage(
+  image: SectionSpecImage | undefined,
+  out: NativeRenderOut,
+  context: string,
+): ResolvedNativeImage {
+  void image;
+  void out;
+  void context;
+  throw new Error('native-media resolveImage is not implemented');
+}
+
+export function iconImageBlock(
+  icon: SectionSpecIcon,
+  out: NativeRenderOut,
+  ctx: NativeRenderCtx,
+  opts?: IconImageBlockOptions,
+): string {
+  void icon;
+  void out;
+  void ctx;
+  void opts;
+  throw new Error('native-media iconImageBlock is not implemented');
+}

From bfbe622d9b9cd8341522a549e00eda299b64337f Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 17:46:54 -0400
Subject: [PATCH 084/113] feat(theme): port native low-level helpers

---
 .../native-low-level-dla-goldens.json         | 873 ++++++++++++++++++
 .../native-low-level-helper-cases.ts          | 422 +++++++++
 .../theme-native-low-level-parity.test.ts     | 118 +++
 .../src/theme/native-block-builders.ts        | 254 ++++-
 .../blocks-engine/src/theme/native-color.ts   |  33 +-
 .../blocks-engine/src/theme/native-fonts.ts   |  30 +-
 .../blocks-engine/src/theme/native-layout.ts  |  64 +-
 .../blocks-engine/src/theme/native-media.ts   |  49 +-
 8 files changed, 1759 insertions(+), 84 deletions(-)
 create mode 100644 packages/blocks-engine/src/__fixtures__/native-low-level-dla-goldens.json
 create mode 100644 packages/blocks-engine/src/__fixtures__/native-low-level-helper-cases.ts
 create mode 100644 packages/blocks-engine/src/__tests__/theme-native-low-level-parity.test.ts

diff --git a/packages/blocks-engine/src/__fixtures__/native-low-level-dla-goldens.json b/packages/blocks-engine/src/__fixtures__/native-low-level-dla-goldens.json
new file mode 100644
index 00000000..fb7c535b
--- /dev/null
+++ b/packages/blocks-engine/src/__fixtures__/native-low-level-dla-goldens.json
@@ -0,0 +1,873 @@
+{
+  "version": 1,
+  "derivation": "Mechanically generated from DLA page-reconstruct.ts low-level helpers and footer-color.ts color helpers at DLA commit 1e393c5.",
+  "helpers": {
+    "MISSING_IMAGE_PLACEHOLDER": [
+      {
+        "id": "constant",
+        "output": "[image unavailable — not captured]"
+      }
+    ],
+    "visibleText": [
+      {
+        "id": "tags-and-whitespace",
+        "output": "Hello there Again"
+      }
+    ],
+    "nearestToken": [
+      {
+        "id": "nearest-hex",
+        "output": "accent-primary"
+      },
+      {
+        "id": "nearest-rgb",
+        "output": "text-inverse"
+      },
+      {
+        "id": "invalid-color",
+        "output": null
+      }
+    ],
+    "brightness": [
+      {
+        "id": "hex",
+        "output": 86
+      },
+      {
+        "id": "rgb",
+        "output": 29
+      },
+      {
+        "id": "invalid",
+        "output": 255
+      }
+    ],
+    "familyMatches": [
+      {
+        "id": "exact-body",
+        "output": true
+      },
+      {
+        "id": "hash-overlap",
+        "output": true
+      },
+      {
+        "id": "substring",
+        "output": true
+      },
+      {
+        "id": "miss",
+        "output": false
+      }
+    ],
+    "nearestFamily": [
+      {
+        "id": "body-priority",
+        "output": "body"
+      },
+      {
+        "id": "display",
+        "output": "body"
+      },
+      {
+        "id": "unknown-falls-body",
+        "output": "body"
+      },
+      {
+        "id": "generic-null",
+        "output": null
+      }
+    ],
+    "responsiveFontSize": [
+      {
+        "id": "missing",
+        "output": ""
+      },
+      {
+        "id": "hero",
+        "output": "clamp(46px, 6.4vw, 92px)"
+      },
+      {
+        "id": "small",
+        "output": "clamp(12px, 0.8vw, 12px)"
+      }
+    ],
+    "responsiveSpace": [
+      {
+        "id": "negative",
+        "output": "0px"
+      },
+      {
+        "id": "small",
+        "output": "16px"
+      },
+      {
+        "id": "large",
+        "output": "clamp(43px, 6.67vw, 96px)"
+      }
+    ],
+    "sectionPad": [
+      {
+        "id": "none",
+        "output": {}
+      },
+      {
+        "id": "top-bottom",
+        "output": {
+          "padTopPx": 48,
+          "padBottomPx": 80
+        }
+      }
+    ],
+    "centerOf": [
+      {
+        "id": "default-center",
+        "output": true
+      },
+      {
+        "id": "left",
+        "output": false
+      }
+    ],
+    "buttonJustify": [
+      {
+        "id": "center",
+        "output": "center"
+      },
+      {
+        "id": "left-for-right-source",
+        "output": "left"
+      }
+    ],
+    "isTintedSection": [
+      {
+        "id": "saturated-light",
+        "output": false
+      },
+      {
+        "id": "near-white",
+        "output": false
+      },
+      {
+        "id": "dark",
+        "output": false
+      }
+    ],
+    "opaqueTintHex": [
+      {
+        "id": "rgb-tint",
+        "output": "#e8eff1"
+      },
+      {
+        "id": "rgba-faint",
+        "output": null
+      },
+      {
+        "id": "near-white",
+        "output": null
+      },
+      {
+        "id": "light-neutral",
+        "output": null
+      }
+    ],
+    "isDarkSection": [
+      {
+        "id": "dark",
+        "output": true
+      },
+      {
+        "id": "light",
+        "output": false
+      }
+    ],
+    "pickLeadImage": [
+      {
+        "id": "skips-small",
+        "output": {
+          "url": "http://localhost:8883/wp-content/uploads/2026/05/lead.jpg",
+          "sourceUrl": "https://cdn.example.test/assets/lead.jpg",
+          "alt": "Lead alt",
+          "kind": "img",
+          "width": 640,
+          "height": 480
+        }
+      },
+      {
+        "id": "none",
+        "output": {
+          "__type": "undefined"
+        }
+      }
+    ],
+    "isWpMediaUrl": [
+      {
+        "id": "wp",
+        "output": true
+      },
+      {
+        "id": "remote",
+        "output": false
+      }
+    ],
+    "recolorSvg": [
+      {
+        "id": "replace-fill-stroke",
+        "output": "<svg fill=\"#ffffff\" viewBox=\"0 0 10 10\"><path d=\"M1 1h8v8H1z\"/></svg>"
+      },
+      {
+        "id": "preserve-none",
+        "output": "<svg fill=\"#ffffff\"><path fill=\"none\" stroke=\"none\" d=\"M1 1h2\"/></svg>"
+      }
+    ],
+    "resolveImage": [
+      {
+        "id": "missing",
+        "output": {
+          "returnValue": {
+            "url": "",
+            "alt": "[image unavailable — not captured]",
+            "usable": false
+          },
+          "out": {
+            "markup": "",
+            "expectedText": [],
+            "bodyText": [],
+            "assets": [],
+            "flags": [
+              "hero#1: no image in spec — placeholder emitted"
+            ],
+            "iconAssets": []
+          }
+        }
+      },
+      {
+        "id": "remote",
+        "output": {
+          "returnValue": {
+            "url": "",
+            "alt": "[image unavailable — not captured]",
+            "usable": false
+          },
+          "out": {
+            "markup": "",
+            "expectedText": [],
+            "bodyText": [],
+            "assets": [],
+            "flags": [
+              "hero#2: image not in WP library (https://cdn.example.test/assets/remote.jpg) — placeholder emitted"
+            ],
+            "iconAssets": []
+          }
+        }
+      },
+      {
+        "id": "wp",
+        "output": {
+          "returnValue": {
+            "url": "http://localhost:8883/wp-content/uploads/2026/05/lead.jpg",
+            "alt": "Lead alt",
+            "usable": true
+          },
+          "out": {
+            "markup": "",
+            "expectedText": [],
+            "bodyText": [],
+            "assets": [],
+            "flags": [],
+            "iconAssets": []
+          }
+        }
+      }
+    ],
+    "iconImageBlock": [
+      {
+        "id": "center-fill",
+        "output": {
+          "returnValue": "<!-- wp:image {\"width\":\"32px\",\"height\":\"32px\",\"sizeSlug\":\"full\",\"align\":\"center\"} -->\n<figure class=\"wp-block-image aligncenter size-full is-resized\"><img src=\"<?php echo esc_url(get_theme_file_uri('assets/icon-0.svg')); ?>\" alt=\"\" style=\"width:32px;height:32px\"/></figure>\n<!-- /wp:image -->",
+          "out": {
+            "markup": "",
+            "expectedText": [],
+            "bodyText": [],
+            "assets": [],
+            "flags": [],
+            "iconAssets": [
+              {
+                "path": "assets/icon-0.svg",
+                "svg": "<svg fill=\"#ffffff\" viewBox=\"0 0 10 10\"><path d=\"M2 2h6v6H2z\"/></svg>"
+              }
+            ]
+          },
+          "ctx": {
+            "mediaTextIndex": 0,
+            "iconCounter": 1,
+            "paletteTokens": [
+              {
+                "slug": "text-default",
+                "hex": "#102030"
+              },
+              {
+                "slug": "text-inverse",
+                "hex": "#f8fafc"
+              },
+              {
+                "slug": "accent-primary",
+                "hex": "#008060"
+              },
+              {
+                "slug": "surface-raised",
+                "hex": "#e8eff1"
+              }
+            ],
+            "fontFamilies": [
+              {
+                "slug": "display",
+                "family": "Caldera Display, serif"
+              },
+              {
+                "slug": "body",
+                "family": "Caldera, sans-serif"
+              },
+              {
+                "slug": "wix",
+                "family": "wf_5499e3d4abcd, sans-serif"
+              }
+            ]
+          }
+        }
+      },
+      {
+        "id": "left-no-fill",
+        "output": {
+          "returnValue": "<!-- wp:image {\"width\":\"48px\",\"height\":\"48px\",\"sizeSlug\":\"full\"} -->\n<figure class=\"wp-block-image size-full is-resized\"><img src=\"<?php echo esc_url(get_theme_file_uri('assets/icon-0.svg')); ?>\" alt=\"\" style=\"width:48px;height:48px\"/></figure>\n<!-- /wp:image -->",
+          "out": {
+            "markup": "",
+            "expectedText": [],
+            "bodyText": [],
+            "assets": [],
+            "flags": [],
+            "iconAssets": [
+              {
+                "path": "assets/icon-0.svg",
+                "svg": "<svg viewBox=\"0 0 10 10\"><path fill=\"#111\" stroke=\"#222\" d=\"M1 1h8v8H1z\"/></svg>"
+              }
+            ]
+          },
+          "ctx": {
+            "mediaTextIndex": 0,
+            "iconCounter": 1,
+            "paletteTokens": [
+              {
+                "slug": "text-default",
+                "hex": "#102030"
+              },
+              {
+                "slug": "text-inverse",
+                "hex": "#f8fafc"
+              },
+              {
+                "slug": "accent-primary",
+                "hex": "#008060"
+              },
+              {
+                "slug": "surface-raised",
+                "hex": "#e8eff1"
+              }
+            ],
+            "fontFamilies": [
+              {
+                "slug": "display",
+                "family": "Caldera Display, serif"
+              },
+              {
+                "slug": "body",
+                "family": "Caldera, sans-serif"
+              },
+              {
+                "slug": "wix",
+                "family": "wf_5499e3d4abcd, sans-serif"
+              }
+            ]
+          }
+        }
+      },
+      {
+        "id": "glyph-empty",
+        "output": {
+          "returnValue": "",
+          "out": {
+            "markup": "",
+            "expectedText": [],
+            "bodyText": [],
+            "assets": [],
+            "flags": [],
+            "iconAssets": []
+          },
+          "ctx": {
+            "mediaTextIndex": 0,
+            "iconCounter": 0,
+            "paletteTokens": [
+              {
+                "slug": "text-default",
+                "hex": "#102030"
+              },
+              {
+                "slug": "text-inverse",
+                "hex": "#f8fafc"
+              },
+              {
+                "slug": "accent-primary",
+                "hex": "#008060"
+              },
+              {
+                "slug": "surface-raised",
+                "hex": "#e8eff1"
+              }
+            ],
+            "fontFamilies": [
+              {
+                "slug": "display",
+                "family": "Caldera Display, serif"
+              },
+              {
+                "slug": "body",
+                "family": "Caldera, sans-serif"
+              },
+              {
+                "slug": "wix",
+                "family": "wf_5499e3d4abcd, sans-serif"
+              }
+            ]
+          }
+        }
+      }
+    ],
+    "emptyNativeRenderOut": [
+      {
+        "id": "empty",
+        "output": {
+          "markup": "",
+          "expectedText": [],
+          "bodyText": [],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      }
+    ],
+    "typographyStyle": [
+      {
+        "id": "font-and-line-height",
+        "output": {
+          "attr": "\"style\":{\"typography\":{\"fontSize\":\"clamp(20px, 4.0vw, 60px)\",\"lineHeight\":\"1.1\"}},",
+          "inline": " style=\"font-size:clamp(20px, 4.0vw, 60px);line-height:1.1\""
+        }
+      },
+      {
+        "id": "invalid-line-height",
+        "output": {
+          "attr": "\"style\":{\"typography\":{\"fontSize\":\"16px\"}},",
+          "inline": " style=\"font-size:16px\""
+        }
+      }
+    ],
+    "imageBlock": [
+      {
+        "id": "wp-rounded-center",
+        "output": {
+          "returnValue": "<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"640px\",\"align\":\"center\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image aligncenter size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/lead.jpg\" alt=\"Lead alt\" style=\"width:640px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->",
+          "out": {
+            "markup": "",
+            "expectedText": [],
+            "bodyText": [],
+            "assets": [
+              "http://localhost:8883/wp-content/uploads/2026/05/lead.jpg"
+            ],
+            "flags": [],
+            "iconAssets": []
+          }
+        }
+      },
+      {
+        "id": "remote-placeholder",
+        "output": {
+          "returnValue": "<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-subtle\",\"fontSize\":\"small\"} -->\n<p class=\"has-text-align-center has-text-subtle-color has-text-color has-small-font-size\">[image unavailable — not captured]</p>\n<!-- /wp:paragraph -->",
+          "out": {
+            "markup": "",
+            "expectedText": [],
+            "bodyText": [],
+            "assets": [],
+            "flags": [
+              "image#2: image not in WP library (https://cdn.example.test/assets/remote.jpg) — placeholder emitted"
+            ],
+            "iconAssets": []
+          }
+        }
+      }
+    ],
+    "headingBlock": [
+      {
+        "id": "heading-rich",
+        "output": {
+          "returnValue": "<!-- wp:heading {\"textAlign\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(32px, 4.4vw, 64px)\",\"lineHeight\":\"1.05\"}},\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-inverse\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family\" style=\"font-size:clamp(32px, 4.4vw, 64px);line-height:1.05\">Launch &lt;Now&gt;</h1>\n<!-- /wp:heading -->",
+          "out": {
+            "markup": "",
+            "expectedText": [
+              "Launch <Now>"
+            ],
+            "bodyText": [],
+            "assets": [],
+            "flags": [],
+            "iconAssets": []
+          }
+        }
+      },
+      {
+        "id": "empty",
+        "output": {
+          "returnValue": "",
+          "out": {
+            "markup": "",
+            "expectedText": [],
+            "bodyText": [],
+            "assets": [],
+            "flags": [],
+            "iconAssets": []
+          }
+        }
+      }
+    ],
+    "paragraphBlock": [
+      {
+        "id": "paragraph-rich",
+        "output": {
+          "returnValue": "<!-- wp:paragraph {\"align\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 1.3vw, 18px)\",\"lineHeight\":\"1.5\"}},\"fontFamily\":\"body\",\"textColor\":\"text-default\"} -->\n<p class=\"has-text-align-center has-text-default-color has-text-color has-body-font-family\" style=\"font-size:clamp(16px, 1.3vw, 18px);line-height:1.5\">Body &amp; copy</p>\n<!-- /wp:paragraph -->",
+          "out": {
+            "markup": "",
+            "expectedText": [],
+            "bodyText": [
+              "Body & copy"
+            ],
+            "assets": [],
+            "flags": [],
+            "iconAssets": []
+          }
+        }
+      },
+      {
+        "id": "size-slug",
+        "output": {
+          "returnValue": "<!-- wp:paragraph {\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color has-small-font-size\">Small copy</p>\n<!-- /wp:paragraph -->",
+          "out": {
+            "markup": "",
+            "expectedText": [],
+            "bodyText": [
+              "Small copy"
+            ],
+            "assets": [],
+            "flags": [],
+            "iconAssets": []
+          }
+        }
+      }
+    ],
+    "buttonBlock": [
+      {
+        "id": "default",
+        "output": {
+          "returnValue": "<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Buy &lt;Now&gt;</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->",
+          "out": {
+            "markup": "",
+            "expectedText": [
+              "Buy <Now>"
+            ],
+            "bodyText": [],
+            "assets": [],
+            "flags": [],
+            "iconAssets": []
+          }
+        }
+      },
+      {
+        "id": "left",
+        "output": {
+          "returnValue": "<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"left\"}} -->\n<div class=\"wp-block-buttons is-content-justification-left\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Learn</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->",
+          "out": {
+            "markup": "",
+            "expectedText": [
+              "Learn"
+            ],
+            "bodyText": [],
+            "assets": [],
+            "flags": [],
+            "iconAssets": []
+          }
+        }
+      }
+    ],
+    "ctaButton": [
+      {
+        "id": "colored-link-icon-after",
+        "output": {
+          "returnValue": "<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"left\"}} -->\n<div class=\"wp-block-buttons is-content-justification-left\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\" href=\"/shop\">Shop<img src=\"<?php echo esc_url(get_theme_file_uri('assets/icon-0.svg')); ?>\" alt=\"\" style=\"width:18px;height:18px;vertical-align:middle;margin-left:8px\"/></a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->",
+          "out": {
+            "markup": "",
+            "expectedText": [
+              "Shop"
+            ],
+            "bodyText": [],
+            "assets": [],
+            "flags": [],
+            "iconAssets": [
+              {
+                "path": "assets/icon-0.svg",
+                "svg": "<svg fill=\"#f8fafc\" viewBox=\"0 0 10 10\"><path d=\"M2 2h6v6H2z\"/></svg>"
+              }
+            ]
+          },
+          "ctx": {
+            "mediaTextIndex": 0,
+            "iconCounter": 1,
+            "paletteTokens": [
+              {
+                "slug": "text-default",
+                "hex": "#102030"
+              },
+              {
+                "slug": "text-inverse",
+                "hex": "#f8fafc"
+              },
+              {
+                "slug": "accent-primary",
+                "hex": "#008060"
+              },
+              {
+                "slug": "surface-raised",
+                "hex": "#e8eff1"
+              }
+            ],
+            "fontFamilies": [
+              {
+                "slug": "display",
+                "family": "Caldera Display, serif"
+              },
+              {
+                "slug": "body",
+                "family": "Caldera, sans-serif"
+              },
+              {
+                "slug": "wix",
+                "family": "wf_5499e3d4abcd, sans-serif"
+              }
+            ]
+          }
+        }
+      },
+      {
+        "id": "icon-only",
+        "output": {
+          "returnValue": "<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\"><img src=\"<?php echo esc_url(get_theme_file_uri('assets/icon-0.svg')); ?>\" alt=\"\" style=\"width:18px;height:18px;vertical-align:middle;margin-right:8px\"/></a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->",
+          "out": {
+            "markup": "",
+            "expectedText": [],
+            "bodyText": [],
+            "assets": [],
+            "flags": [],
+            "iconAssets": [
+              {
+                "path": "assets/icon-0.svg",
+                "svg": "<svg viewBox=\"0 0 10 10\"><path d=\"M2 2h6v6H2z\"/></svg>"
+              }
+            ]
+          },
+          "ctx": {
+            "mediaTextIndex": 0,
+            "iconCounter": 1,
+            "paletteTokens": [
+              {
+                "slug": "text-default",
+                "hex": "#102030"
+              },
+              {
+                "slug": "text-inverse",
+                "hex": "#f8fafc"
+              },
+              {
+                "slug": "accent-primary",
+                "hex": "#008060"
+              },
+              {
+                "slug": "surface-raised",
+                "hex": "#e8eff1"
+              }
+            ],
+            "fontFamilies": [
+              {
+                "slug": "display",
+                "family": "Caldera Display, serif"
+              },
+              {
+                "slug": "body",
+                "family": "Caldera, sans-serif"
+              },
+              {
+                "slug": "wix",
+                "family": "wf_5499e3d4abcd, sans-serif"
+              }
+            ]
+          }
+        }
+      }
+    ],
+    "sectionButtons": [
+      {
+        "id": "structured",
+        "output": {
+          "returnValue": [
+            "<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"left\"}} -->\n<div class=\"wp-block-buttons is-content-justification-left\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\" href=\"/contact\">Contact</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->"
+          ],
+          "out": {
+            "markup": "",
+            "expectedText": [
+              "Contact"
+            ],
+            "bodyText": [],
+            "assets": [],
+            "flags": [],
+            "iconAssets": []
+          },
+          "ctx": {
+            "mediaTextIndex": 0,
+            "iconCounter": 0,
+            "paletteTokens": [
+              {
+                "slug": "text-default",
+                "hex": "#102030"
+              },
+              {
+                "slug": "text-inverse",
+                "hex": "#f8fafc"
+              },
+              {
+                "slug": "accent-primary",
+                "hex": "#008060"
+              },
+              {
+                "slug": "surface-raised",
+                "hex": "#e8eff1"
+              }
+            ],
+            "fontFamilies": [
+              {
+                "slug": "display",
+                "family": "Caldera Display, serif"
+              },
+              {
+                "slug": "body",
+                "family": "Caldera, sans-serif"
+              },
+              {
+                "slug": "wix",
+                "family": "wf_5499e3d4abcd, sans-serif"
+              }
+            ]
+          }
+        }
+      },
+      {
+        "id": "labels",
+        "output": {
+          "returnValue": [
+            "<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Alpha</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->",
+            "<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Beta</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->"
+          ],
+          "out": {
+            "markup": "",
+            "expectedText": [
+              "Alpha",
+              "Beta"
+            ],
+            "bodyText": [],
+            "assets": [],
+            "flags": [],
+            "iconAssets": []
+          },
+          "ctx": {
+            "mediaTextIndex": 0,
+            "iconCounter": 0,
+            "paletteTokens": [
+              {
+                "slug": "text-default",
+                "hex": "#102030"
+              },
+              {
+                "slug": "text-inverse",
+                "hex": "#f8fafc"
+              },
+              {
+                "slug": "accent-primary",
+                "hex": "#008060"
+              },
+              {
+                "slug": "surface-raised",
+                "hex": "#e8eff1"
+              }
+            ],
+            "fontFamilies": [
+              {
+                "slug": "display",
+                "family": "Caldera Display, serif"
+              },
+              {
+                "slug": "body",
+                "family": "Caldera, sans-serif"
+              },
+              {
+                "slug": "wix",
+                "family": "wf_5499e3d4abcd, sans-serif"
+              }
+            ]
+          }
+        }
+      }
+    ],
+    "column": [
+      {
+        "id": "auto",
+        "output": "<!-- wp:column  -->\n<div class=\"wp-block-column\">\nA\nB\n</div>\n<!-- /wp:column -->"
+      },
+      {
+        "id": "width",
+        "output": "<!-- wp:column {\"width\":\"33.33%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:33.33%\">\nA\n</div>\n<!-- /wp:column -->"
+      }
+    ],
+    "columns": [
+      {
+        "id": "empty",
+        "output": ""
+      },
+      {
+        "id": "standard",
+        "output": "<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<p>A</p>\n<p>B</p>\n</div>\n<!-- /wp:columns -->"
+      },
+      {
+        "id": "full-bleed",
+        "output": "<!-- wp:columns {\"verticalAlignment\":\"center\",\"align\":\"full\",\"style\":{\"spacing\":{\"blockGap\":\"0\"}}} -->\n<div class=\"wp-block-columns alignfull are-vertically-aligned-center\">\n<p>A</p>\n</div>\n<!-- /wp:columns -->"
+      }
+    ],
+    "wrapSection": [
+      {
+        "id": "empty",
+        "output": ""
+      },
+      {
+        "id": "raised-constrained",
+        "output": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"color\":{\"background\":\"#e8eff1\"},\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(22px, 3.33vw, 48px)\",\"bottom\":\"clamp(29px, 4.44vw, 64px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull has-background\" style=\"margin-top:0;margin-bottom:0;background-color:#e8eff1;padding-top:clamp(22px, 3.33vw, 48px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(29px, 4.44vw, 64px);padding-left:var(--wp--preset--spacing--40)\">\n<p>Body</p>\n</section>\n<!-- /wp:group -->"
+      },
+      {
+        "id": "inverse-full-bleed",
+        "output": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"backgroundColor\":\"surface-inverse\",\"textColor\":\"text-inverse\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"12px\",\"bottom\":\"12px\",\"left\":\"0\",\"right\":\"0\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"default\"}} -->\n<section class=\"wp-block-group alignfull has-surface-inverse-background-color has-text-inverse-color has-text-color has-background\" style=\"margin-top:0;margin-bottom:0;padding-top:12px;padding-right:0px;padding-bottom:12px;padding-left:0px\">\n<p>Inverse</p>\n</section>\n<!-- /wp:group -->"
+      }
+    ]
+  }
+}
diff --git a/packages/blocks-engine/src/__fixtures__/native-low-level-helper-cases.ts b/packages/blocks-engine/src/__fixtures__/native-low-level-helper-cases.ts
new file mode 100644
index 00000000..8aac14e3
--- /dev/null
+++ b/packages/blocks-engine/src/__fixtures__/native-low-level-helper-cases.ts
@@ -0,0 +1,422 @@
+import type {
+  HeadingBlockOptions,
+  ImageBlockOptions,
+  NativeButtonInput,
+  ParagraphBlockOptions,
+  TypographyFragments,
+  WrapSectionOptions,
+} from '../theme/native-block-builders.js';
+import type { PaletteToken } from '../theme/native-color.js';
+import type { IconImageBlockOptions } from '../theme/native-media.js';
+import type { FontFamilyToken } from '../theme/page-reconstruct-helpers.js';
+import type { NativeRenderCtx, NativeRenderOut } from '../theme/native-reconstruct-types.js';
+import type { SectionSpec, SectionSpecIcon, SectionSpecImage } from '../theme/section-spec.js';
+
+export interface NativeLowLevelImpl {
+  MISSING_IMAGE_PLACEHOLDER: string;
+  nearestToken(hex: string, tokens: PaletteToken[]): string | null;
+  brightness(hex: string): number;
+  familyMatches(computed: string, token: FontFamilyToken): boolean;
+  nearestFamily(computed: string | undefined, tokens: FontFamilyToken[]): string | null;
+  responsiveFontSize(px: number | undefined): string;
+  responsiveSpace(px: number): string;
+  sectionPad(section: SectionSpec): { padTopPx?: number; padBottomPx?: number };
+  centerOf(section: SectionSpec): boolean;
+  buttonJustify(section: SectionSpec): 'left' | 'center';
+  isTintedSection(section: SectionSpec): boolean;
+  opaqueTintHex(color: string | null | undefined): string | null;
+  isDarkSection(section: SectionSpec): boolean;
+  pickLeadImage(images: SectionSpecImage[]): SectionSpecImage | undefined;
+  isWpMediaUrl(url: string): boolean;
+  recolorSvg(svg: string, hex: string): string;
+  resolveImage(image: SectionSpecImage | undefined, out: NativeRenderOut, context: string): {
+    url: string;
+    alt: string;
+    usable: boolean;
+  };
+  iconImageBlock(
+    icon: SectionSpecIcon,
+    out: NativeRenderOut,
+    ctx: NativeRenderCtx,
+    opts?: IconImageBlockOptions,
+  ): string;
+  visibleText(html: string): string;
+  emptyNativeRenderOut(): NativeRenderOut;
+  typographyStyle(fontCss: string, lineHeight?: number): TypographyFragments;
+  imageBlock(
+    image: SectionSpecImage | undefined,
+    out: NativeRenderOut,
+    context: string,
+    opts?: ImageBlockOptions,
+  ): string;
+  headingBlock(text: string, out: NativeRenderOut, opts?: HeadingBlockOptions): string;
+  paragraphBlock(text: string, out: NativeRenderOut, opts?: ParagraphBlockOptions): string;
+  buttonBlock(label: string, out: NativeRenderOut, opts?: { align?: 'left' | 'center' | 'right' }): string;
+  ctaButton(
+    out: NativeRenderOut,
+    ctx: NativeRenderCtx,
+    button: NativeButtonInput,
+    opts?: { align?: 'left' | 'center' },
+  ): string;
+  sectionButtons(section: SectionSpec, out: NativeRenderOut, ctx: NativeRenderCtx): string[];
+  column(parts: string[], width?: string): string;
+  columns(cols: string[], opts?: { fullBleed?: boolean }): string;
+  wrapSection(parts: string[], opts: WrapSectionOptions): string;
+}
+
+export interface NativeLowLevelCase {
+  id: string;
+  output: unknown;
+}
+
+export interface NativeLowLevelParityFile {
+  version: 1;
+  derivation: string;
+  helpers: Record<string, NativeLowLevelCase[]>;
+}
+
+const WP = 'http://localhost:8883/wp-content/uploads/2026/05/';
+const CDN = 'https://cdn.example.test/assets/';
+
+function nativeOut(): NativeRenderOut {
+  return { markup: '', expectedText: [], bodyText: [], assets: [], flags: [], iconAssets: [] };
+}
+
+function nativeCtx(): NativeRenderCtx {
+  return {
+    mediaTextIndex: 0,
+    iconCounter: 0,
+    paletteTokens: [
+      { slug: 'text-default', hex: '#102030' },
+      { slug: 'text-inverse', hex: '#f8fafc' },
+      { slug: 'accent-primary', hex: '#008060' },
+      { slug: 'surface-raised', hex: '#e8eff1' },
+    ],
+    fontFamilies: [
+      { slug: 'display', family: 'Caldera Display, serif' },
+      { slug: 'body', family: 'Caldera, sans-serif' },
+      { slug: 'wix', family: 'wf_5499e3d4abcd, sans-serif' },
+    ],
+  };
+}
+
+function image(name: string, width = 800, height = 600, alt = name): SectionSpecImage {
+  return {
+    url: `${WP}${name}`,
+    sourceUrl: `${CDN}${name}`,
+    alt,
+    kind: 'img',
+    width,
+    height,
+  };
+}
+
+function remoteImage(name: string, width = 800, height = 600): SectionSpecImage {
+  return {
+    url: `${CDN}${name}`,
+    sourceUrl: `${CDN}${name}`,
+    alt: name,
+    kind: 'img',
+    width,
+    height,
+  };
+}
+
+function svgIcon(markup: string): SectionSpecIcon {
+  return {
+    kind: 'svg',
+    markup,
+    width: 24,
+    height: 24,
+  };
+}
+
+function section(partial: Partial<SectionSpec> = {}): SectionSpec {
+  return {
+    sectionIndex: 7,
+    interactionModel: 'static',
+    top: 0,
+    height: 420,
+    headings: ['Source Heading'],
+    bodyText: ['Source body'],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 255,
+    backgroundColor: 'rgb(255, 255, 255)',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: { motionClass: 'none', signals: [], animatedElements: 0 },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: {
+      containerWidth: 1200,
+      padding: '0',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '24px',
+    },
+    ...partial,
+  };
+}
+
+function freeze(value: unknown): unknown {
+  if (value === undefined) return { __type: 'undefined' };
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(freeze);
+  return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, freeze(nested)]));
+}
+
+function capture(id: string, run: () => unknown): NativeLowLevelCase {
+  return { id, output: freeze(run()) };
+}
+
+function withOut(run: (out: NativeRenderOut) => unknown): { returnValue: unknown; out: NativeRenderOut } {
+  const out = nativeOut();
+  return { returnValue: run(out), out };
+}
+
+function withOutAndCtx(
+  run: (out: NativeRenderOut, ctx: NativeRenderCtx) => unknown,
+): { returnValue: unknown; out: NativeRenderOut; ctx: NativeRenderCtx } {
+  const out = nativeOut();
+  const ctx = nativeCtx();
+  return { returnValue: run(out, ctx), out, ctx };
+}
+
+export function runNativeLowLevelParity(impl: NativeLowLevelImpl): NativeLowLevelParityFile {
+  const lead = image('lead.jpg', 640, 480, 'Lead alt');
+  const remote = remoteImage('remote.jpg', 640, 480);
+  const small = image('badge.svg', 48, 48, 'Tiny badge');
+  const icon = svgIcon('<svg viewBox="0 0 10 10"><path fill="#111" stroke="#222" d="M1 1h8v8H1z"/></svg>');
+  const iconNoFill = svgIcon('<svg viewBox="0 0 10 10"><path d="M2 2h6v6H2z"/></svg>');
+  const palette = nativeCtx().paletteTokens;
+  const fonts = nativeCtx().fontFamilies;
+
+  return {
+    version: 1,
+    derivation:
+      'Mechanically generated from DLA page-reconstruct.ts low-level helpers and footer-color.ts color helpers at DLA commit 1e393c5.',
+    helpers: {
+      MISSING_IMAGE_PLACEHOLDER: [capture('constant', () => impl.MISSING_IMAGE_PLACEHOLDER)],
+      visibleText: [
+        capture('tags-and-whitespace', () => impl.visibleText('<h2> Hello <em>there</em></h2>\n<p>Again</p>')),
+      ],
+      nearestToken: [
+        capture('nearest-hex', () => impl.nearestToken('#00815f', palette)),
+        capture('nearest-rgb', () => impl.nearestToken('rgb(246, 248, 250)', palette)),
+        capture('invalid-color', () => impl.nearestToken('not-a-color', palette)),
+      ],
+      brightness: [
+        capture('hex', () => impl.brightness('#008060')),
+        capture('rgb', () => impl.brightness('rgb(16, 32, 48)')),
+        capture('invalid', () => impl.brightness('currentColor')),
+      ],
+      familyMatches: [
+        capture('exact-body', () => impl.familyMatches('caldera', fonts[1])),
+        capture('hash-overlap', () => impl.familyMatches('wfont_abc_5499e3d4abcd', fonts[2])),
+        capture('substring', () => impl.familyMatches('caldera display', fonts[0])),
+        capture('miss', () => impl.familyMatches('unrelated', fonts[0])),
+      ],
+      nearestFamily: [
+        capture('body-priority', () => impl.nearestFamily('"Caldera"', fonts)),
+        capture('display', () => impl.nearestFamily('Caldera Display', fonts)),
+        capture('unknown-falls-body', () => impl.nearestFamily('wix-obfuscated-handle', fonts)),
+        capture('generic-null', () => impl.nearestFamily('serif', fonts)),
+      ],
+      responsiveFontSize: [
+        capture('missing', () => impl.responsiveFontSize(undefined)),
+        capture('hero', () => impl.responsiveFontSize(92)),
+        capture('small', () => impl.responsiveFontSize(12)),
+      ],
+      responsiveSpace: [
+        capture('negative', () => impl.responsiveSpace(-10)),
+        capture('small', () => impl.responsiveSpace(16)),
+        capture('large', () => impl.responsiveSpace(96)),
+      ],
+      sectionPad: [
+        capture('none', () => impl.sectionPad(section())),
+        capture('top-bottom', () =>
+          impl.sectionPad(section({ layout: { ...section().layout, padTopPx: 48, padBottomPx: 80 } })),
+        ),
+      ],
+      centerOf: [
+        capture('default-center', () => impl.centerOf(section())),
+        capture('left', () => impl.centerOf(section({ textAlign: 'left' }))),
+      ],
+      buttonJustify: [
+        capture('center', () => impl.buttonJustify(section({ textAlign: 'center' }))),
+        capture('left-for-right-source', () => impl.buttonJustify(section({ textAlign: 'right' }))),
+      ],
+      isTintedSection: [
+        capture('saturated-light', () =>
+          impl.isTintedSection(section({ backgroundBrightness: 220, backgroundColor: 'rgb(232, 239, 241)' })),
+        ),
+        capture('near-white', () =>
+          impl.isTintedSection(section({ backgroundBrightness: 248, backgroundColor: 'rgb(250, 250, 250)' })),
+        ),
+        capture('dark', () =>
+          impl.isTintedSection(section({ backgroundBrightness: 80, backgroundColor: 'rgb(20, 80, 100)' })),
+        ),
+      ],
+      opaqueTintHex: [
+        capture('rgb-tint', () => impl.opaqueTintHex('rgb(232, 239, 241)')),
+        capture('rgba-faint', () => impl.opaqueTintHex('rgba(232, 239, 241, 0.4)')),
+        capture('near-white', () => impl.opaqueTintHex('#ffffff')),
+        capture('light-neutral', () => impl.opaqueTintHex('#eeeeec')),
+      ],
+      isDarkSection: [
+        capture('dark', () => impl.isDarkSection(section({ backgroundBrightness: 40 }))),
+        capture('light', () => impl.isDarkSection(section({ backgroundBrightness: 180 }))),
+      ],
+      pickLeadImage: [
+        capture('skips-small', () => impl.pickLeadImage([small, lead])),
+        capture('none', () => impl.pickLeadImage([small])),
+      ],
+      isWpMediaUrl: [
+        capture('wp', () => impl.isWpMediaUrl(`${WP}hero.jpg`)),
+        capture('remote', () => impl.isWpMediaUrl(`${CDN}hero.jpg`)),
+      ],
+      recolorSvg: [
+        capture('replace-fill-stroke', () => impl.recolorSvg(icon.markup ?? '', '#ffffff')),
+        capture('preserve-none', () =>
+          impl.recolorSvg('<svg><path fill="none" stroke="none" d="M1 1h2"/></svg>', '#ffffff'),
+        ),
+      ],
+      resolveImage: [
+        capture('missing', () => withOut((out) => impl.resolveImage(undefined, out, 'hero#1'))),
+        capture('remote', () => withOut((out) => impl.resolveImage(remote, out, 'hero#2'))),
+        capture('wp', () => withOut((out) => impl.resolveImage(lead, out, 'hero#3'))),
+      ],
+      iconImageBlock: [
+        capture('center-fill', () =>
+          withOutAndCtx((out, ctx) => impl.iconImageBlock(iconNoFill, out, ctx, { sizePx: 32, fill: '#ffffff' })),
+        ),
+        capture('left-no-fill', () =>
+          withOutAndCtx((out, ctx) => impl.iconImageBlock(icon, out, ctx, { align: 'left' })),
+        ),
+        capture('glyph-empty', () =>
+          withOutAndCtx((out, ctx) =>
+            impl.iconImageBlock({ kind: 'glyph', glyph: '*', width: 16, height: 16 }, out, ctx),
+          ),
+        ),
+      ],
+      emptyNativeRenderOut: [capture('empty', () => impl.emptyNativeRenderOut())],
+      typographyStyle: [
+        capture('font-and-line-height', () => impl.typographyStyle('clamp(20px, 4.0vw, 60px)', 1.1)),
+        capture('invalid-line-height', () => impl.typographyStyle('16px', 3)),
+      ],
+      imageBlock: [
+        capture('wp-rounded-center', () =>
+          withOut((out) => impl.imageBlock(lead, out, 'image#1', { rounded: true, align: 'center' })),
+        ),
+        capture('remote-placeholder', () =>
+          withOut((out) => impl.imageBlock(remote, out, 'image#2', { rounded: true })),
+        ),
+      ],
+      headingBlock: [
+        capture('heading-rich', () =>
+          withOut((out) =>
+            impl.headingBlock('  Launch  <Now> ', out, {
+              level: 1,
+              center: true,
+              inverse: true,
+              sizePx: 64,
+              fontFamily: 'display',
+              lineHeight: 1.05,
+            }),
+          ),
+        ),
+        capture('empty', () => withOut((out) => impl.headingBlock('   ', out))),
+      ],
+      paragraphBlock: [
+        capture('paragraph-rich', () =>
+          withOut((out) =>
+            impl.paragraphBlock(' Body & copy ', out, {
+              center: true,
+              muted: false,
+              sizePx: 18,
+              fontFamily: 'body',
+              lineHeight: 1.5,
+            }),
+          ),
+        ),
+        capture('size-slug', () => withOut((out) => impl.paragraphBlock('Small copy', out, { size: 'small' }))),
+      ],
+      buttonBlock: [
+        capture('default', () => withOut((out) => impl.buttonBlock(' Buy <Now> ', out))),
+        capture('left', () => withOut((out) => impl.buttonBlock('Learn', out, { align: 'left' }))),
+      ],
+      ctaButton: [
+        capture('colored-link-icon-after', () =>
+          withOutAndCtx((out, ctx) =>
+            impl.ctaButton(
+              out,
+              ctx,
+              {
+                label: 'Shop',
+                href: '/shop',
+                background: 'rgb(0, 128, 96)',
+                color: 'rgb(248, 250, 252)',
+                icon: iconNoFill,
+                iconAfter: true,
+              },
+              { align: 'left' },
+            ),
+          ),
+        ),
+        capture('icon-only', () =>
+          withOutAndCtx((out, ctx) => impl.ctaButton(out, ctx, { label: '', icon: iconNoFill })),
+        ),
+      ],
+      sectionButtons: [
+        capture('structured', () =>
+          withOutAndCtx((out, ctx) =>
+            impl.sectionButtons(
+              section({
+                textAlign: 'left',
+                buttons: [{ label: 'Contact', href: '/contact', background: '#008060', color: '#f8fafc' }],
+              }),
+              out,
+              ctx,
+            ),
+          ),
+        ),
+        capture('labels', () =>
+          withOutAndCtx((out, ctx) =>
+            impl.sectionButtons(section({ buttonLabels: ['Alpha', 'Beta'], textAlign: 'center' }), out, ctx),
+          ),
+        ),
+      ],
+      column: [
+        capture('auto', () => impl.column(['A', 'B'])),
+        capture('width', () => impl.column(['A'], '33.33%')),
+      ],
+      columns: [
+        capture('empty', () => impl.columns([])),
+        capture('standard', () => impl.columns(['<p>A</p>', '<p>B</p>'])),
+        capture('full-bleed', () => impl.columns(['<p>A</p>'], { fullBleed: true })),
+      ],
+      wrapSection: [
+        capture('empty', () => impl.wrapSection([], {})),
+        capture('raised-constrained', () =>
+          impl.wrapSection(['<p>Body</p>'], {
+            constrained: '760px',
+            raised: true,
+            bgColor: 'rgb(232, 239, 241)',
+            padTopPx: 48,
+            padBottomPx: 64,
+          }),
+        ),
+        capture('inverse-full-bleed', () =>
+          impl.wrapSection(['<p>Inverse</p>'], {
+            inverse: true,
+            fullBleed: true,
+            padTopPx: 12,
+            padBottomPx: 12,
+          }),
+        ),
+      ],
+    },
+  };
+}
diff --git a/packages/blocks-engine/src/__tests__/theme-native-low-level-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-native-low-level-parity.test.ts
new file mode 100644
index 00000000..a5f16551
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-native-low-level-parity.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+
+import expectedGoldens from '../__fixtures__/native-low-level-dla-goldens.json' with { type: 'json' };
+import {
+  runNativeLowLevelParity,
+  type NativeLowLevelImpl,
+  type NativeLowLevelParityFile,
+} from '../__fixtures__/native-low-level-helper-cases.js';
+import {
+  buttonBlock,
+  column,
+  columns,
+  ctaButton,
+  emptyNativeRenderOut,
+  headingBlock,
+  imageBlock,
+  paragraphBlock,
+  sectionButtons,
+  typographyStyle,
+  visibleText,
+  wrapSection,
+} from '../theme/native-block-builders.js';
+import { brightness, nearestToken } from '../theme/native-color.js';
+import { familyMatches, nearestFamily } from '../theme/native-fonts.js';
+import {
+  buttonJustify,
+  centerOf,
+  isDarkSection,
+  isTintedSection,
+  opaqueTintHex,
+  responsiveFontSize,
+  responsiveSpace,
+  sectionPad,
+} from '../theme/native-layout.js';
+import {
+  MISSING_IMAGE_PLACEHOLDER,
+  iconImageBlock,
+  isWpMediaUrl,
+  pickLeadImage,
+  recolorSvg,
+  resolveImage,
+} from '../theme/native-media.js';
+
+const EXPECTED_HELPERS = 30;
+
+const engineImpl: NativeLowLevelImpl = {
+  MISSING_IMAGE_PLACEHOLDER,
+  nearestToken,
+  brightness,
+  familyMatches,
+  nearestFamily,
+  responsiveFontSize,
+  responsiveSpace,
+  sectionPad,
+  centerOf,
+  buttonJustify,
+  isTintedSection,
+  opaqueTintHex,
+  isDarkSection,
+  pickLeadImage,
+  isWpMediaUrl,
+  recolorSvg,
+  resolveImage,
+  iconImageBlock,
+  visibleText,
+  emptyNativeRenderOut,
+  typographyStyle,
+  imageBlock,
+  headingBlock,
+  paragraphBlock,
+  buttonBlock,
+  ctaButton,
+  sectionButtons,
+  column,
+  columns,
+  wrapSection,
+};
+
+function stableJson(value: unknown): string {
+  return JSON.stringify(value, null, 2);
+}
+
+function collectDiffs(actual: NativeLowLevelParityFile, expected: NativeLowLevelParityFile): string[] {
+  const diffs: string[] = [];
+  if (actual.version !== expected.version) diffs.push(`version: expected ${expected.version}, got ${actual.version}`);
+
+  const actualHelpers = Object.keys(actual.helpers).sort();
+  const expectedHelpers = Object.keys(expected.helpers).sort();
+  if (stableJson(actualHelpers) !== stableJson(expectedHelpers)) {
+    diffs.push(`helper keys: expected ${expectedHelpers.join(',')}, got ${actualHelpers.join(',')}`);
+  }
+
+  for (const helper of expectedHelpers) {
+    const actualCases = actual.helpers[helper];
+    const expectedCases = expected.helpers[helper];
+    if (!actualCases) continue;
+    if (stableJson(actualCases) !== stableJson(expectedCases)) {
+      diffs.push(`${helper}: output changed`);
+    }
+  }
+  return diffs;
+}
+
+describe('native low-level helper DLA-today parity', () => {
+  it('matches mechanically derived DLA helper outputs byte-for-byte and is stable on rerun', () => {
+    const first = runNativeLowLevelParity(engineImpl);
+    const second = runNativeLowLevelParity(engineImpl);
+    expect(stableJson(first)).toBe(stableJson(second));
+
+    const expected = expectedGoldens as NativeLowLevelParityFile;
+    const helperCount = Object.keys(expected.helpers).length;
+    const diffs = collectDiffs(first, expected);
+    console.info(`native low-level helper parity: helpers=${helperCount} diffs=${diffs.length}`);
+
+    expect(helperCount).toBe(EXPECTED_HELPERS);
+    expect(diffs).toEqual([]);
+  });
+});
diff --git a/packages/blocks-engine/src/theme/native-block-builders.ts b/packages/blocks-engine/src/theme/native-block-builders.ts
index 8ea1370a..80b545ca 100644
--- a/packages/blocks-engine/src/theme/native-block-builders.ts
+++ b/packages/blocks-engine/src/theme/native-block-builders.ts
@@ -1,5 +1,10 @@
 import type { NativeRenderCtx, NativeRenderOut } from './native-reconstruct-types.js';
 import type { SectionSpec, SectionSpecIcon, SectionSpecImage } from './section-spec.js';
+import { escapeHtml } from '../escape.js';
+import { normalizeCopy, sanitizeSvgAsset } from './page-reconstruct-helpers.js';
+import { brightness, nearestToken } from './native-color.js';
+import { buttonJustify, opaqueTintHex, responsiveFontSize, responsiveSpace } from './native-layout.js';
+import { MISSING_IMAGE_PLACEHOLDER, recolorSvg, resolveImage } from './native-media.js';
 
 export interface TypographyFragments {
   attr: string;
@@ -57,18 +62,28 @@ export interface WrapSectionOptions {
 }
 
 export function visibleText(html: string): string {
-  void html;
-  throw new Error('native-block-builders visibleText is not implemented');
+  return html.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
 }
 
 export function emptyNativeRenderOut(): NativeRenderOut {
-  throw new Error('native-block-builders emptyNativeRenderOut is not implemented');
+  return { markup: '', expectedText: [], bodyText: [], assets: [], flags: [], iconAssets: [] };
 }
 
 export function typographyStyle(fontCss: string, lineHeight?: number): TypographyFragments {
-  void fontCss;
-  void lineHeight;
-  throw new Error('native-block-builders typographyStyle is not implemented');
+  const attrParts: string[] = [];
+  const inlineParts: string[] = [];
+  if (fontCss) {
+    attrParts.push(`"fontSize":"${fontCss}"`);
+    inlineParts.push(`font-size:${fontCss}`);
+  }
+  if (typeof lineHeight === 'number' && lineHeight >= 0.8 && lineHeight <= 2.4) {
+    attrParts.push(`"lineHeight":"${lineHeight}"`);
+    inlineParts.push(`line-height:${lineHeight}`);
+  }
+  return {
+    attr: attrParts.length ? `"style":{"typography":{${attrParts.join(',')}}},` : '',
+    inline: inlineParts.length ? ` style="${inlineParts.join(';')}"` : '',
+  };
 }
 
 export function imageBlock(
@@ -77,25 +92,77 @@ export function imageBlock(
   context: string,
   opts?: ImageBlockOptions,
 ): string {
-  void image;
-  void out;
-  void context;
-  void opts;
-  throw new Error('native-block-builders imageBlock is not implemented');
+  const options = opts ?? {};
+  const resolved = resolveImage(image, out, context);
+  const roundStyle = options.rounded ? ',"style":{"border":{"radius":"12px"}}' : '';
+  const roundClass = options.rounded ? ' has-custom-border' : '';
+  const alignAttr = options.align === 'center' ? ',"align":"center"' : '';
+  const alignClass = options.align === 'center' ? ' aligncenter' : '';
+  if (!resolved.usable) {
+    return (
+      `<!-- wp:paragraph {"align":"center","textColor":"text-subtle","fontSize":"small"} -->\n` +
+      `<p class="has-text-align-center has-text-subtle-color has-text-color has-small-font-size">${escapeHtml(
+        MISSING_IMAGE_PLACEHOLDER,
+      )}</p>\n<!-- /wp:paragraph -->`
+    );
+  }
+  out.assets.push(resolved.url);
+  const width = image && image.width && image.height ? Math.round(image.width) : 0;
+  const widthAttr = width ? `,"width":"${width}px"` : '';
+  const resizedClass = width ? ' is-resized' : '';
+  const dimStyle = width ? `width:${width}px;max-width:100%;height:auto;` : '';
+  const borderStyle = options.rounded ? 'border-radius:12px;' : '';
+  const imgStyle = dimStyle || borderStyle ? ` style="${dimStyle}${borderStyle}"` : '';
+  return (
+    `<!-- wp:image {"sizeSlug":"large"${widthAttr}${alignAttr}${roundStyle}} -->\n` +
+    `<figure class="wp-block-image${alignClass} size-large${roundClass}${resizedClass}"><img src="${escapeHtml(
+      resolved.url,
+    )}" alt="${escapeHtml(resolved.alt)}"${imgStyle}/></figure>\n` +
+    `<!-- /wp:image -->`
+  );
 }
 
 export function headingBlock(text: string, out: NativeRenderOut, opts?: HeadingBlockOptions): string {
-  void text;
-  void out;
-  void opts;
-  throw new Error('native-block-builders headingBlock is not implemented');
+  const options = opts ?? {};
+  const normalized = normalizeCopy(text);
+  if (!normalized) return '';
+  out.expectedText.push(normalized);
+  const level = options.level ?? 2;
+  const centerAttr = options.center ? '"textAlign":"center",' : '';
+  const centerClass = options.center ? ' has-text-align-center' : '';
+  const colorSlug = options.inverse ? 'text-inverse' : options.muted ? 'text-muted' : 'text-default';
+  const fontCss = responsiveFontSize(options.sizePx);
+  const typography = typographyStyle(fontCss, options.lineHeight);
+  const familySlug = options.fontFamily || 'display';
+  return (
+    `<!-- wp:heading {${centerAttr}${typography.attr}"level":${level},"fontFamily":"${familySlug}","textColor":"${colorSlug}"} -->\n` +
+    `<h${level} class="wp-block-heading${centerClass} has-${colorSlug}-color has-text-color has-${familySlug}-font-family"${typography.inline}>${escapeHtml(
+      normalized,
+    )}</h${level}>\n<!-- /wp:heading -->`
+  );
 }
 
 export function paragraphBlock(text: string, out: NativeRenderOut, opts?: ParagraphBlockOptions): string {
-  void text;
-  void out;
-  void opts;
-  throw new Error('native-block-builders paragraphBlock is not implemented');
+  const options = opts ?? {};
+  const normalized = normalizeCopy(text);
+  if (!normalized) return '';
+  out.bodyText.push(normalized);
+  const centerAttr = options.center ? '"align":"center",' : '';
+  const centerClass = options.center ? 'has-text-align-center ' : '';
+  const colorSlug = options.inverse ? 'text-inverse' : options.muted === false ? 'text-default' : 'text-muted';
+  const px = options.sizePx && options.sizePx >= 11 && options.sizePx <= 32 ? options.sizePx : 0;
+  const fontCss = responsiveFontSize(px);
+  const typography = typographyStyle(fontCss, options.lineHeight);
+  const sizeAttr = !fontCss && options.size ? `"fontSize":"${options.size}",` : '';
+  const sizeClass = !fontCss && options.size ? ` has-${options.size}-font-size` : '';
+  const familyAttr = options.fontFamily ? `"fontFamily":"${options.fontFamily}",` : '';
+  const familyClass = options.fontFamily ? ` has-${options.fontFamily}-font-family` : '';
+  return (
+    `<!-- wp:paragraph {${centerAttr}${typography.attr}${sizeAttr}${familyAttr}"textColor":"${colorSlug}"} -->\n` +
+    `<p class="${centerClass}has-${colorSlug}-color has-text-color${sizeClass}${familyClass}"${typography.inline}>${escapeHtml(
+      normalized,
+    )}</p>\n<!-- /wp:paragraph -->`
+  );
 }
 
 export function buttonBlock(
@@ -103,10 +170,20 @@ export function buttonBlock(
   out: NativeRenderOut,
   opts?: { align?: 'left' | 'center' | 'right' },
 ): string {
-  void label;
-  void out;
-  void opts;
-  throw new Error('native-block-builders buttonBlock is not implemented');
+  const normalized = normalizeCopy(label);
+  if (!normalized) return '';
+  out.expectedText.push(normalized);
+  const justify = opts?.align ?? 'center';
+  const justifyClass = ` is-content-justification-${justify}`;
+  return (
+    `<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"${justify}"}} -->\n` +
+    `<div class="wp-block-buttons${justifyClass}">\n` +
+    `<!-- wp:button {"backgroundColor":"accent-primary","textColor":"text-inverse"} -->\n` +
+    `<div class="wp-block-button"><a class="wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button">${escapeHtml(
+      normalized,
+    )}</a></div>\n` +
+    `<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->`
+  );
 }
 
 export function ctaButton(
@@ -115,34 +192,129 @@ export function ctaButton(
   button: NativeButtonInput,
   opts?: CtaButtonOptions,
 ): string {
-  void out;
-  void ctx;
-  void button;
-  void opts;
-  throw new Error('native-block-builders ctaButton is not implemented');
+  const normalized = normalizeCopy(button.label);
+  if (!normalized && !button.icon) return '';
+  if (normalized) out.expectedText.push(normalized);
+  const justify = opts?.align ?? 'center';
+  const justifyClass = ` is-content-justification-${justify}`;
+  const bgToken = button.background ? nearestToken(button.background, ctx.paletteTokens) : null;
+  const textToken = button.color ? nearestToken(button.color, ctx.paletteTokens) : null;
+  const bg = bgToken ?? 'accent-primary';
+  let textColor: string;
+  if (textToken) {
+    textColor = textToken;
+  } else {
+    const bgHex = ctx.paletteTokens.find((token) => token.slug === bg)?.hex;
+    textColor = bgHex && brightness(bgHex) >= 140 ? 'text-default' : 'text-inverse';
+  }
+
+  let iconImg = '';
+  if (button.icon && button.icon.kind === 'svg' && button.icon.markup) {
+    let svg = sanitizeSvgAsset(button.icon.markup);
+    if (svg && /<svg[\s>]/i.test(svg)) {
+      const fillHex = button.color ? rgbToHex(button.color) : null;
+      if (fillHex) svg = recolorSvg(svg, fillHex);
+      const path = `assets/icon-${ctx.iconCounter++}.svg`;
+      out.iconAssets.push({ path, svg });
+      const src = `<?php echo esc_url(get_theme_file_uri('${path}')); ?>`;
+      const margin = button.iconAfter ? 'margin-left:8px' : 'margin-right:8px';
+      iconImg = `<img src="${src}" alt="" style="width:18px;height:18px;vertical-align:middle;${margin}"/>`;
+    }
+  }
+  const href = button.href ? ` href="${escapeHtml(button.href)}"` : '';
+  const inner = button.iconAfter ? `${escapeHtml(normalized)}${iconImg}` : `${iconImg}${escapeHtml(normalized)}`;
+  return (
+    `<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"${justify}"}} -->\n` +
+    `<div class="wp-block-buttons${justifyClass}">\n` +
+    `<!-- wp:button {"backgroundColor":"${bg}","textColor":"${textColor}"} -->\n` +
+    `<div class="wp-block-button"><a class="wp-block-button__link has-${textColor}-color has-${bg}-background-color has-text-color has-background wp-element-button"${href}>${inner}</a></div>\n` +
+    `<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->`
+  );
 }
 
 export function sectionButtons(section: SectionSpec, out: NativeRenderOut, ctx: NativeRenderCtx): string[] {
-  void section;
-  void out;
-  void ctx;
-  throw new Error('native-block-builders sectionButtons is not implemented');
+  const align = buttonJustify(section);
+  if (section.buttons && section.buttons.length) {
+    return section.buttons.map((button) => ctaButton(out, ctx, button, { align })).filter(Boolean);
+  }
+  return section.buttonLabels.map((label) => ctaButton(out, ctx, { label }, { align })).filter(Boolean);
 }
 
 export function column(parts: string[], width?: string): string {
-  void parts;
-  void width;
-  throw new Error('native-block-builders column is not implemented');
+  const widthAttr = width ? `{"width":"${width}"}` : '';
+  const widthStyle = width ? ` style="flex-basis:${width}"` : '';
+  return (
+    `<!-- wp:column ${widthAttr} -->\n` +
+    `<div class="wp-block-column"${widthStyle}>\n${parts.join('\n')}\n</div>\n` +
+    `<!-- /wp:column -->`
+  );
 }
 
 export function columns(cols: string[], opts?: { fullBleed?: boolean }): string {
-  void cols;
-  void opts;
-  throw new Error('native-block-builders columns is not implemented');
+  const options = opts ?? {};
+  if (cols.length === 0) return '';
+  const attr = options.fullBleed
+    ? `"verticalAlignment":"center","align":"full","style":{"spacing":{"blockGap":"0"}}`
+    : `"verticalAlignment":"center"`;
+  const cls = options.fullBleed
+    ? 'wp-block-columns alignfull are-vertically-aligned-center'
+    : 'wp-block-columns are-vertically-aligned-center';
+  return (
+    `<!-- wp:columns {${attr}} -->\n` +
+    `<div class="${cls}">\n${cols.join('\n')}\n</div>\n` +
+    `<!-- /wp:columns -->`
+  );
 }
 
 export function wrapSection(parts: string[], opts: WrapSectionOptions): string {
-  void parts;
-  void opts;
-  throw new Error('native-block-builders wrapSection is not implemented');
+  const body = parts.filter(Boolean).join('\n');
+  if (!body) return '';
+  const layout = opts.fullBleed
+    ? `"layout":{"type":"default"}`
+    : opts.constrained
+      ? `"layout":{"type":"constrained","contentSize":"${opts.constrained}"}`
+      : opts.wide
+        ? `"layout":{"type":"constrained","wideSize":"${opts.wide}"}`
+        : `"layout":{"type":"constrained"}`;
+  const hpadJson = opts.fullBleed
+    ? `"left":"0","right":"0"`
+    : `"left":"var:preset|spacing|40","right":"var:preset|spacing|40"`;
+  const hpadL = opts.fullBleed ? '0px' : 'var(--wp--preset--spacing--40)';
+  const hpadR = hpadL;
+  const customBg = !opts.inverse ? opaqueTintHex(opts.bgColor) : null;
+  const colorAttr = opts.inverse
+    ? '"backgroundColor":"surface-inverse","textColor":"text-inverse",'
+    : customBg
+      ? ''
+      : opts.raised
+        ? '"backgroundColor":"surface-raised",'
+        : '';
+  const styleColor = !opts.inverse && customBg ? `"color":{"background":"${customBg}"},` : '';
+  const bgClass = opts.inverse
+    ? ' has-surface-inverse-background-color has-text-inverse-color has-text-color has-background'
+    : customBg
+      ? ' has-background'
+      : opts.raised
+        ? ' has-surface-raised-background-color has-background'
+        : '';
+  const bgInlineStyle = !opts.inverse && customBg ? `background-color:${customBg};` : '';
+  const topVal = typeof opts.padTopPx === 'number' ? responsiveSpace(opts.padTopPx) : 'var:preset|spacing|60';
+  const botVal =
+    typeof opts.padBottomPx === 'number' ? responsiveSpace(opts.padBottomPx) : 'var:preset|spacing|60';
+  const cssLen = (value: string): string =>
+    value.startsWith('var:preset|spacing|') ? `var(--wp--preset--spacing--${value.split('|').pop()})` : value;
+  return (
+    `<!-- wp:group {"tagName":"section","align":"full",${colorAttr}"style":{${styleColor}"spacing":{"margin":{"top":"0","bottom":"0"},"padding":{"top":"${topVal}","bottom":"${botVal}",${hpadJson}},"blockGap":"var:preset|spacing|40"}},${layout}} -->\n` +
+    `<section class="wp-block-group alignfull${bgClass}" style="margin-top:0;margin-bottom:0;${bgInlineStyle}padding-top:${cssLen(topVal)};padding-right:${hpadR};padding-bottom:${cssLen(botVal)};padding-left:${hpadL}">\n` +
+    `${body}\n` +
+    `</section>\n<!-- /wp:group -->`
+  );
+}
+
+function rgbToHex(rgb: string): string | null {
+  const match = rgb.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
+  if (!match) return null;
+  const h = (value: string): string =>
+    Math.max(0, Math.min(255, parseInt(value, 10))).toString(16).padStart(2, '0');
+  return `#${h(match[1])}${h(match[2])}${h(match[3])}`;
 }
diff --git a/packages/blocks-engine/src/theme/native-color.ts b/packages/blocks-engine/src/theme/native-color.ts
index e7a0f00e..55814b5f 100644
--- a/packages/blocks-engine/src/theme/native-color.ts
+++ b/packages/blocks-engine/src/theme/native-color.ts
@@ -3,13 +3,36 @@ export interface PaletteToken {
   hex: string;
 }
 
+function parseHex(color: string): [number, number, number] | null {
+  const s = color.trim();
+  const rgb = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/i.exec(s);
+  if (rgb) return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])];
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(s);
+  if (!m) return null;
+  let h = m[1];
+  if (h.length === 3) h = h.split('').map((c) => c + c).join('');
+  return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+}
+
 export function nearestToken(hex: string, tokens: PaletteToken[]): string | null {
-  void hex;
-  void tokens;
-  throw new Error('native-color nearestToken is not implemented');
+  const c = parseHex(hex);
+  if (!c) return null;
+  let best: string | null = null;
+  let bestD = Infinity;
+  for (const t of tokens) {
+    const tc = parseHex(t.hex);
+    if (!tc) continue;
+    const d = (c[0] - tc[0]) ** 2 + (c[1] - tc[1]) ** 2 + (c[2] - tc[2]) ** 2;
+    if (d < bestD) {
+      bestD = d;
+      best = t.slug;
+    }
+  }
+  return best;
 }
 
 export function brightness(hex: string): number {
-  void hex;
-  throw new Error('native-color brightness is not implemented');
+  const c = parseHex(hex);
+  if (!c) return 255;
+  return Math.round(0.299 * c[0] + 0.587 * c[1] + 0.114 * c[2]);
 }
diff --git a/packages/blocks-engine/src/theme/native-fonts.ts b/packages/blocks-engine/src/theme/native-fonts.ts
index 8d0f14c3..c8939b01 100644
--- a/packages/blocks-engine/src/theme/native-fonts.ts
+++ b/packages/blocks-engine/src/theme/native-fonts.ts
@@ -1,13 +1,31 @@
 import type { FontFamilyToken } from './page-reconstruct-helpers.js';
 
+function familyHash(s: string): string | null {
+  const m = s.match(/[0-9a-f]{10,}/i);
+  return m ? m[0].toLowerCase() : null;
+}
+
 export function familyMatches(computed: string, token: FontFamilyToken): boolean {
-  void computed;
-  void token;
-  throw new Error('native-fonts familyMatches is not implemented');
+  const first = (token.family || '').split(',')[0].replace(/["']/g, '').trim().toLowerCase();
+  const slug = (token.slug || '').toLowerCase();
+  if (first && first === computed) return true;
+  const ch = familyHash(computed);
+  if (ch) {
+    const th = familyHash(token.family) || familyHash(slug);
+    if (th && (th.includes(ch) || ch.includes(th))) return true;
+  }
+  if (first && first.length >= 4 && (computed.includes(first) || first.includes(computed))) return true;
+  return false;
 }
 
 export function nearestFamily(computed: string | undefined, tokens: FontFamilyToken[]): string | null {
-  void computed;
-  void tokens;
-  throw new Error('native-fonts nearestFamily is not implemented');
+  if (!computed || tokens.length === 0) return null;
+  const c = computed.replace(/["']/g, '').trim().toLowerCase();
+  if (!c || c === 'inherit' || c === 'sans-serif' || c === 'serif') return null;
+  const display = tokens.find((t) => t.slug === 'display');
+  const body = tokens.find((t) => t.slug === 'body');
+  if (body && familyMatches(c, body)) return 'body';
+  if (display && familyMatches(c, display)) return 'display';
+  if (body) return 'body';
+  return null;
 }
diff --git a/packages/blocks-engine/src/theme/native-layout.ts b/packages/blocks-engine/src/theme/native-layout.ts
index 1895b513..bfe1520a 100644
--- a/packages/blocks-engine/src/theme/native-layout.ts
+++ b/packages/blocks-engine/src/theme/native-layout.ts
@@ -5,42 +5,74 @@ export interface SectionPadding {
   padBottomPx?: number;
 }
 
+/**
+ * A responsive font size that equals the captured px at a 1440px viewport and
+ * scales down on mobile.
+ */
 export function responsiveFontSize(px: number | undefined): string {
-  void px;
-  throw new Error('native-layout responsiveFontSize is not implemented');
+  if (!px || px <= 0) return '';
+  const floor = Math.min(px, Math.max(16, Math.round(px * 0.5)));
+  const vw = (px / 14.4).toFixed(1);
+  return `clamp(${floor}px, ${vw}vw, ${px}px)`;
 }
 
 export function responsiveSpace(px: number): string {
-  void px;
-  throw new Error('native-layout responsiveSpace is not implemented');
+  const p = Math.max(0, Math.round(px));
+  if (p < 24) return `${p}px`;
+  const floor = Math.max(16, Math.round(p * 0.45));
+  const vw = (p / 14.4).toFixed(2);
+  return `clamp(${floor}px, ${vw}vw, ${p}px)`;
 }
 
 export function sectionPad(section: SectionSpec): SectionPadding {
-  void section;
-  throw new Error('native-layout sectionPad is not implemented');
+  const t = section.layout?.padTopPx;
+  const b = section.layout?.padBottomPx;
+  return {
+    ...(typeof t === 'number' ? { padTopPx: t } : {}),
+    ...(typeof b === 'number' ? { padBottomPx: b } : {}),
+  };
 }
 
 export function centerOf(section: SectionSpec): boolean {
-  void section;
-  throw new Error('native-layout centerOf is not implemented');
+  return section.textAlign == null ? true : section.textAlign === 'center';
 }
 
 export function buttonJustify(section: SectionSpec): 'left' | 'center' {
-  void section;
-  throw new Error('native-layout buttonJustify is not implemented');
+  return centerOf(section) ? 'center' : 'left';
 }
 
 export function isTintedSection(section: SectionSpec): boolean {
-  void section;
-  throw new Error('native-layout isTintedSection is not implemented');
+  const b = section.backgroundBrightness;
+  if (b >= 245 || b < 100) return false;
+  const m = /rgba?\((\d+),\s*(\d+),\s*(\d+)/.exec(section.backgroundColor || '');
+  if (!m) return false;
+  const sat = Math.max(+m[1], +m[2], +m[3]) - Math.min(+m[1], +m[2], +m[3]);
+  return sat >= 25;
 }
 
 export function opaqueTintHex(color: string | null | undefined): string | null {
-  void color;
-  throw new Error('native-layout opaqueTintHex is not implemented');
+  if (!color) return null;
+  const s = color.trim();
+  const rgba = /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)(?:\s*,\s*([\d.]+))?\s*\)/.exec(s);
+  let r: number, g: number, b: number;
+  if (rgba) {
+    const alpha = rgba[4] === undefined ? 1 : Number(rgba[4]);
+    if (alpha < 0.6) return null;
+    [r, g, b] = [Number(rgba[1]), Number(rgba[2]), Number(rgba[3])];
+  } else {
+    const hex = /^#?([0-9a-f]{6})$/i.exec(s);
+    if (!hex) return null;
+    r = parseInt(hex[1].slice(0, 2), 16);
+    g = parseInt(hex[1].slice(2, 4), 16);
+    b = parseInt(hex[1].slice(4, 6), 16);
+  }
+  const bright = (r + g + b) / 3;
+  if (bright >= 248) return null;
+  const spread = Math.max(r, g, b) - Math.min(r, g, b);
+  if (spread <= 6 && bright >= 230) return null;
+  return '#' + [r, g, b].map((n) => n.toString(16).padStart(2, '0')).join('');
 }
 
 export function isDarkSection(section: SectionSpec): boolean {
-  void section;
-  throw new Error('native-layout isDarkSection is not implemented');
+  return section.backgroundBrightness < 100;
 }
diff --git a/packages/blocks-engine/src/theme/native-media.ts b/packages/blocks-engine/src/theme/native-media.ts
index f75bad93..2aac699e 100644
--- a/packages/blocks-engine/src/theme/native-media.ts
+++ b/packages/blocks-engine/src/theme/native-media.ts
@@ -1,7 +1,9 @@
 import type { NativeRenderCtx, NativeRenderOut } from './native-reconstruct-types.js';
+import { sanitizeSvgAsset } from './page-reconstruct-helpers.js';
 import type { SectionSpecIcon, SectionSpecImage } from './section-spec.js';
 
 export const MISSING_IMAGE_PLACEHOLDER = '[image unavailable — not captured]';
+const MIN_LEAD_IMAGE_PX = 200;
 
 export interface ResolvedNativeImage {
   url: string;
@@ -16,19 +18,18 @@ export interface IconImageBlockOptions {
 }
 
 export function pickLeadImage(images: SectionSpecImage[]): SectionSpecImage | undefined {
-  void images;
-  throw new Error('native-media pickLeadImage is not implemented');
+  return images.find((image) => Math.min(image.width || 0, image.height || 0) >= MIN_LEAD_IMAGE_PX);
 }
 
 export function isWpMediaUrl(url: string): boolean {
-  void url;
-  throw new Error('native-media isWpMediaUrl is not implemented');
+  return /\/wp-content\/uploads\//i.test(url);
 }
 
 export function recolorSvg(svg: string, hex: string): string {
-  void svg;
-  void hex;
-  throw new Error('native-media recolorSvg is not implemented');
+  const stripped = svg
+    .replace(/\sfill="(?!none")[^"]*"/gi, '')
+    .replace(/\sstroke="(?!none")[^"]*"/gi, '');
+  return stripped.replace(/<svg\b/i, `<svg fill="${hex}"`);
 }
 
 export function resolveImage(
@@ -36,10 +37,15 @@ export function resolveImage(
   out: NativeRenderOut,
   context: string,
 ): ResolvedNativeImage {
-  void image;
-  void out;
-  void context;
-  throw new Error('native-media resolveImage is not implemented');
+  if (!image) {
+    out.flags.push(`${context}: no image in spec — placeholder emitted`);
+    return { url: '', alt: MISSING_IMAGE_PLACEHOLDER, usable: false };
+  }
+  if (!isWpMediaUrl(image.url)) {
+    out.flags.push(`${context}: image not in WP library (${image.sourceUrl}) — placeholder emitted`);
+    return { url: '', alt: MISSING_IMAGE_PLACEHOLDER, usable: false };
+  }
+  return { url: image.url, alt: image.alt || '', usable: true };
 }
 
 export function iconImageBlock(
@@ -48,9 +54,20 @@ export function iconImageBlock(
   ctx: NativeRenderCtx,
   opts?: IconImageBlockOptions,
 ): string {
-  void icon;
-  void out;
-  void ctx;
-  void opts;
-  throw new Error('native-media iconImageBlock is not implemented');
+  const sizePx = opts?.sizePx ?? 48;
+  if (icon.kind !== 'svg' || !icon.markup) return '';
+  let svg = sanitizeSvgAsset(icon.markup);
+  if (!svg || !/<svg[\s>]/i.test(svg)) return '';
+  if (opts?.fill) svg = recolorSvg(svg, opts.fill);
+  const path = `assets/icon-${ctx.iconCounter++}.svg`;
+  out.iconAssets.push({ path, svg });
+  const src = `<?php echo esc_url(get_theme_file_uri('${path}')); ?>`;
+  const align = opts?.align ?? 'center';
+  const alignAttr = align === 'center' ? ',"align":"center"' : align === 'right' ? ',"align":"right"' : '';
+  const alignClass = align === 'center' ? ' aligncenter' : align === 'right' ? ' alignright' : '';
+  return (
+    `<!-- wp:image {"width":"${sizePx}px","height":"${sizePx}px","sizeSlug":"full"${alignAttr}} -->\n` +
+    `<figure class="wp-block-image${alignClass} size-full is-resized"><img src="${src}" alt="" style="width:${sizePx}px;height:${sizePx}px"/></figure>\n` +
+    `<!-- /wp:image -->`
+  );
 }

From 9d0973ccea1ebf999ddaa50264540cd57d3df46a Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 19:07:24 -0400
Subject: [PATCH 085/113] feat(theme): freeze native text renderer surface

---
 ...heme-native-renderers-text-surface.test.ts | 45 +++++++++++++++++++
 .../src/theme/native-renderers-text.ts        | 37 +++++++++++++++
 2 files changed, 82 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-native-renderers-text-surface.test.ts
 create mode 100644 packages/blocks-engine/src/theme/native-renderers-text.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-native-renderers-text-surface.test.ts b/packages/blocks-engine/src/__tests__/theme-native-renderers-text-surface.test.ts
new file mode 100644
index 00000000..08704b04
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-native-renderers-text-surface.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import {
+  galleryBlock,
+  renderCover,
+  renderMediaText,
+  renderTextBand,
+  type GalleryBlockOptions,
+} from '../theme/native-renderers-text.js';
+import type { NativeRenderCtx, NativeRenderOut } from '../theme/native-reconstruct-types.js';
+import type { SectionSpec, SectionSpecImage } from '../theme/section-spec.js';
+
+describe('native text renderer frozen surface', () => {
+  it('freezes the renderer export names and runtime availability', () => {
+    expect({
+      galleryBlock,
+      renderCover,
+      renderMediaText,
+      renderTextBand,
+    }).toEqual(
+      expect.objectContaining({
+        galleryBlock: expect.any(Function),
+        renderCover: expect.any(Function),
+        renderMediaText: expect.any(Function),
+        renderTextBand: expect.any(Function),
+      })
+    );
+  });
+
+  it('freezes the renderer type signatures', () => {
+    expectTypeOf<GalleryBlockOptions>().toEqualTypeOf<{ sectionHeight?: number }>();
+    expectTypeOf(renderTextBand).toEqualTypeOf<
+      (section: SectionSpec, ctx: NativeRenderCtx) => NativeRenderOut
+    >();
+    expectTypeOf(renderCover).toEqualTypeOf<
+      (section: SectionSpec, ctx: NativeRenderCtx) => NativeRenderOut
+    >();
+    expectTypeOf(renderMediaText).toEqualTypeOf<
+      (section: SectionSpec, flip: boolean, ctx: NativeRenderCtx) => NativeRenderOut
+    >();
+    expectTypeOf(galleryBlock).toEqualTypeOf<
+      (images: SectionSpecImage[], out: NativeRenderOut, opts?: GalleryBlockOptions) => string
+    >();
+  });
+});
diff --git a/packages/blocks-engine/src/theme/native-renderers-text.ts b/packages/blocks-engine/src/theme/native-renderers-text.ts
new file mode 100644
index 00000000..65ae0dce
--- /dev/null
+++ b/packages/blocks-engine/src/theme/native-renderers-text.ts
@@ -0,0 +1,37 @@
+import { emptyNativeRenderOut } from './native-block-builders.js';
+import type { NativeRenderCtx, NativeRenderOut } from './native-reconstruct-types.js';
+import type { SectionSpec, SectionSpecImage } from './section-spec.js';
+
+export interface GalleryBlockOptions {
+  sectionHeight?: number;
+}
+
+export function renderTextBand(section: SectionSpec, ctx: NativeRenderCtx): NativeRenderOut {
+  void section;
+  void ctx;
+  return emptyNativeRenderOut();
+}
+
+export function renderCover(section: SectionSpec, ctx: NativeRenderCtx): NativeRenderOut {
+  void section;
+  void ctx;
+  return emptyNativeRenderOut();
+}
+
+export function renderMediaText(section: SectionSpec, flip: boolean, ctx: NativeRenderCtx): NativeRenderOut {
+  void section;
+  void flip;
+  void ctx;
+  return emptyNativeRenderOut();
+}
+
+export function galleryBlock(
+  images: SectionSpecImage[],
+  out: NativeRenderOut,
+  opts?: GalleryBlockOptions,
+): string {
+  void images;
+  void out;
+  void opts;
+  return '';
+}

From f9f8861527962b51abb24eb29b11d88b18da8556 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 19:20:13 -0400
Subject: [PATCH 086/113] feat(theme): port native text renderers

---
 .../capture-native-text-renderer-goldens.mjs  | 155 +++++++++
 .../native-text-renderer-cases.ts             | 327 ++++++++++++++++++
 .../native-text-renderer-dla-goldens.json     | 128 +++++++
 ...theme-native-renderers-text-parity.test.ts |  72 ++++
 .../src/theme/native-renderers-text.ts        | 229 +++++++++++-
 5 files changed, 896 insertions(+), 15 deletions(-)
 create mode 100644 packages/blocks-engine/scripts/capture-native-text-renderer-goldens.mjs
 create mode 100644 packages/blocks-engine/src/__fixtures__/native-text-renderer-cases.ts
 create mode 100644 packages/blocks-engine/src/__fixtures__/native-text-renderer-dla-goldens.json
 create mode 100644 packages/blocks-engine/src/__tests__/theme-native-renderers-text-parity.test.ts

diff --git a/packages/blocks-engine/scripts/capture-native-text-renderer-goldens.mjs b/packages/blocks-engine/scripts/capture-native-text-renderer-goldens.mjs
new file mode 100644
index 00000000..ace44982
--- /dev/null
+++ b/packages/blocks-engine/scripts/capture-native-text-renderer-goldens.mjs
@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const DLA_COMMIT = '1e393c535850ee1a9482f83459f779d0e225b027';
+const DEFAULT_DLA_ROOT = '/Users/matt/projects/a8c/data-liberation-agent';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+const fixtureUrl = pathToFileURL(path.join(packageRoot, 'src/__fixtures__/native-text-renderer-cases.ts')).href;
+const outputPath = path.join(packageRoot, 'src/__fixtures__/native-text-renderer-dla-goldens.json');
+
+const args = new Set(process.argv.slice(2));
+const shouldWrite = args.has('--write');
+const shouldCheck = args.has('--check');
+const shouldStdout = args.has('--stdout') || (!shouldWrite && !shouldCheck);
+const dlaRoot = process.env.DLA_ROOT || DEFAULT_DLA_ROOT;
+
+function git(args) {
+  return execFileSync('git', ['-C', dlaRoot, ...args], { encoding: 'utf8' }).trim();
+}
+
+function stableJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function stripFinalBodyNewline(markup) {
+  return markup.endsWith('\n') ? markup.slice(0, -1) : markup;
+}
+
+function extractGallery(markup) {
+  const match = markup.match(/<!-- wp:gallery\b[\s\S]*?<!-- \/wp:gallery -->/);
+  if (!match) throw new Error('DLA reconstruct output did not contain a wp:gallery block');
+  return match[0];
+}
+
+function emptyOut() {
+  return { markup: '', expectedText: [], bodyText: [], assets: [], flags: [], iconAssets: [] };
+}
+
+function capture(id, output) {
+  return { id, output };
+}
+
+function reconstructOptions() {
+  return {
+    patternSlug: 'native-text-renderer-parity/single-section',
+    title: 'Native Text Renderer Parity',
+    paletteTokens: [
+      { slug: 'text-default', hex: '#102030' },
+      { slug: 'text-inverse', hex: '#f8fafc' },
+      { slug: 'text-muted', hex: '#4b5563' },
+      { slug: 'text-subtle', hex: '#6b7280' },
+      { slug: 'accent-primary', hex: '#008060' },
+      { slug: 'surface-base', hex: '#ffffff' },
+      { slug: 'surface-raised', hex: '#e8eff1' },
+      { slug: 'surface-inverse', hex: '#111827' },
+    ],
+    fontFamilies: [
+      { slug: 'display', family: 'Caldera Display, serif' },
+      { slug: 'body', family: 'Caldera, sans-serif' },
+    ],
+    sourceUrl: 'https://example.test/native-text-renderer-parity',
+    slug: 'native-text-renderer-parity',
+  };
+}
+
+function renderOutFromResult(result) {
+  if (result.sectionsRendered !== 1) {
+    throw new Error(`Expected exactly one rendered section, got ${result.sectionsRendered}`);
+  }
+  if (result.fallbackDiagnostics.length > 0) {
+    throw new Error(`Expected native renderer output, got fallback diagnostics: ${JSON.stringify(result.fallbackDiagnostics)}`);
+  }
+  return {
+    markup: stripFinalBodyNewline(result.body),
+    expectedText: result.expectedText,
+    bodyText: result.bodyText,
+    assets: result.expectedAssets,
+    flags: result.provenanceFlags,
+    iconAssets: result.iconAssets,
+  };
+}
+
+const currentCommit = git(['rev-parse', 'HEAD']);
+if (currentCommit !== DLA_COMMIT) {
+  throw new Error(`DLA checkout must be at ${DLA_COMMIT}; got ${currentCommit}`);
+}
+
+const { nativeTextRendererCaseGroups, NATIVE_TEXT_RENDERER_DERIVATION } = await import(fixtureUrl);
+const { reconstructPagePattern } = await import(
+  pathToFileURL(path.join(dlaRoot, 'src/lib/replicate/page-reconstruct.ts')).href
+);
+
+const cases = nativeTextRendererCaseGroups();
+const renderSectionCase = (entry) =>
+  capture(entry.id, renderOutFromResult(reconstructPagePattern([entry.section], reconstructOptions())));
+
+const renderGalleryCase = (entry) => {
+  const section = {
+    sectionIndex: 90,
+    interactionModel: 'gallery',
+    top: 0,
+    height: entry.opts?.sectionHeight ?? 240,
+    headings: [],
+    bodyText: [],
+    buttonLabels: [],
+    images: entry.images,
+    icons: [],
+    backgroundBrightness: 255,
+    backgroundColor: 'rgb(255, 255, 255)',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: { motionClass: 'none', signals: [], animatedElements: 0 },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: {
+      containerWidth: 1100,
+      padding: '0px',
+      childLayout: 'grid',
+      columnCount: 4,
+      gap: '16px',
+    },
+  };
+  const result = reconstructPagePattern([section], reconstructOptions());
+  return capture(entry.id, {
+    returnValue: extractGallery(stripFinalBodyNewline(result.body)),
+    out: { ...emptyOut(), assets: result.expectedAssets },
+  });
+};
+
+const parityFile = {
+  version: 1,
+  derivation: NATIVE_TEXT_RENDERER_DERIVATION,
+  renderers: {
+    renderTextBand: cases.renderTextBand.map(renderSectionCase),
+    renderCover: cases.renderCover.map(renderSectionCase),
+    renderMediaText: cases.renderMediaText.map(renderSectionCase),
+    galleryBlock: cases.galleryBlock.map(renderGalleryCase),
+  },
+};
+
+const json = stableJson(parityFile);
+
+if (shouldCheck) {
+  const existing = readFileSync(outputPath, 'utf8');
+  if (existing !== json) {
+    throw new Error(`${outputPath} is out of date with DLA ${DLA_COMMIT}`);
+  }
+}
+
+if (shouldWrite) writeFileSync(outputPath, json);
+if (shouldStdout) process.stdout.write(json);
diff --git a/packages/blocks-engine/src/__fixtures__/native-text-renderer-cases.ts b/packages/blocks-engine/src/__fixtures__/native-text-renderer-cases.ts
new file mode 100644
index 00000000..39184a98
--- /dev/null
+++ b/packages/blocks-engine/src/__fixtures__/native-text-renderer-cases.ts
@@ -0,0 +1,327 @@
+import type { GalleryBlockOptions } from '../theme/native-renderers-text.js';
+import type { NativeRenderCtx, NativeRenderOut } from '../theme/native-reconstruct-types.js';
+import type { SectionSpec, SectionSpecImage } from '../theme/section-spec.js';
+
+export const NATIVE_TEXT_RENDERER_DERIVATION =
+  'Mechanically generated from DLA src/lib/replicate/page-reconstruct.ts reconstructPagePattern at DLA commit 1e393c5; section renderer markup strips the final reconstruct body newline, and direct galleryBlock outputs extract the nested wp:gallery block.';
+
+export interface NativeTextRendererImpl {
+  renderTextBand(section: SectionSpec, ctx: NativeRenderCtx): NativeRenderOut;
+  renderCover(section: SectionSpec, ctx: NativeRenderCtx): NativeRenderOut;
+  renderMediaText(section: SectionSpec, flip: boolean, ctx: NativeRenderCtx): NativeRenderOut;
+  galleryBlock(images: SectionSpecImage[], out: NativeRenderOut, opts?: GalleryBlockOptions): string;
+}
+
+export interface NativeSectionRendererCase {
+  id: string;
+  section: SectionSpec;
+}
+
+export interface NativeMediaTextRendererCase extends NativeSectionRendererCase {
+  flip: boolean;
+}
+
+export interface NativeGalleryBlockCase {
+  id: string;
+  images: SectionSpecImage[];
+  opts?: GalleryBlockOptions;
+}
+
+export interface NativeTextRendererCaseGroups {
+  renderTextBand: NativeSectionRendererCase[];
+  renderCover: NativeSectionRendererCase[];
+  renderMediaText: NativeMediaTextRendererCase[];
+  galleryBlock: NativeGalleryBlockCase[];
+}
+
+export interface NativeTextRendererOutputCase {
+  id: string;
+  output: unknown;
+}
+
+export interface NativeTextRendererParityFile {
+  version: 1;
+  derivation: string;
+  renderers: Record<keyof NativeTextRendererCaseGroups, NativeTextRendererOutputCase[]>;
+}
+
+const WP = 'http://localhost:8883/wp-content/uploads/2026/05/';
+const CDN = 'https://cdn.example.test/native-text/';
+
+export function nativeRenderOut(): NativeRenderOut {
+  return { markup: '', expectedText: [], bodyText: [], assets: [], flags: [], iconAssets: [] };
+}
+
+export function nativeRenderCtx(): NativeRenderCtx {
+  return {
+    mediaTextIndex: 0,
+    iconCounter: 0,
+    paletteTokens: [
+      { slug: 'text-default', hex: '#102030' },
+      { slug: 'text-inverse', hex: '#f8fafc' },
+      { slug: 'text-muted', hex: '#4b5563' },
+      { slug: 'text-subtle', hex: '#6b7280' },
+      { slug: 'accent-primary', hex: '#008060' },
+      { slug: 'surface-base', hex: '#ffffff' },
+      { slug: 'surface-raised', hex: '#e8eff1' },
+      { slug: 'surface-inverse', hex: '#111827' },
+    ],
+    fontFamilies: [
+      { slug: 'display', family: 'Caldera Display, serif' },
+      { slug: 'body', family: 'Caldera, sans-serif' },
+    ],
+  };
+}
+
+function image(name: string, width = 800, height = 600, alt = name): SectionSpecImage {
+  return {
+    url: `${WP}${name}`,
+    sourceUrl: `${CDN}${name}`,
+    alt,
+    kind: 'img',
+    width,
+    height,
+  };
+}
+
+function backgroundImage(name: string, width = 1440, height = 900, alt = name): SectionSpecImage {
+  return {
+    ...image(name, width, height, alt),
+    kind: 'background',
+  };
+}
+
+function section(partial: Partial<SectionSpec> = {}): SectionSpec {
+  return {
+    sectionIndex: 1,
+    interactionModel: 'static',
+    top: 0,
+    height: 480,
+    headings: [],
+    bodyText: [],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 255,
+    backgroundColor: 'rgb(255, 255, 255)',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: { motionClass: 'none', signals: [], animatedElements: 0 },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: {
+      containerWidth: 1180,
+      padding: '0px',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '24px',
+    },
+    ...partial,
+  };
+}
+
+export function nativeTextRendererCaseGroups(): NativeTextRendererCaseGroups {
+  const textBand = section({
+    sectionIndex: 21,
+    interactionModel: 'static',
+    height: 560,
+    headings: ['Build calmer block themes', 'Without losing source copy'],
+    headingSizes: [58, 24],
+    headingLineHeights: [1.05, 1.25],
+    textAlign: 'center',
+    bodyText: ['Every heading, paragraph, button, and media asset traces back to capture.'],
+    bodyTextSizes: [18],
+    bodyLineHeights: [1.55],
+    buttonLabels: ['See the demo'],
+    buttons: [
+      {
+        label: 'See the demo',
+        href: '/demo',
+        background: 'rgb(0, 128, 96)',
+        color: 'rgb(248, 250, 252)',
+      },
+    ],
+    images: [image('theme-preview.jpg', 720, 480, 'Theme preview')],
+    backgroundBrightness: 35,
+    backgroundColor: 'rgb(16, 32, 48)',
+    layout: {
+      containerWidth: 1180,
+      padding: '0px',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '28px',
+      padTopPx: 72,
+      padBottomPx: 80,
+    },
+  });
+
+  const cover = section({
+    sectionIndex: 22,
+    interactionModel: 'cover-with-headline',
+    height: 733,
+    fullBleed: true,
+    headings: ['A native cover from captured hero media'],
+    headingSizes: [68],
+    headingLineHeights: [1.02],
+    textAlign: 'center',
+    bodyText: ['The headline and CTA stay over the migrated background image.'],
+    bodyTextSizes: [20],
+    bodyLineHeights: [1.5],
+    buttonLabels: ['Explore patterns'],
+    buttons: [
+      {
+        label: 'Explore patterns',
+        href: '/patterns',
+        background: 'rgb(255, 255, 255)',
+        color: 'rgb(16, 32, 48)',
+      },
+    ],
+    images: [backgroundImage('hero-cover.jpg', 1440, 900, 'Workspace with block patterns')],
+    backgroundBrightness: 42,
+    backgroundColor: 'rgb(18, 28, 42)',
+  });
+
+  const mediaTextRight = section({
+    sectionIndex: 23,
+    interactionModel: 'media-text',
+    height: 560,
+    headings: ['Media beside structured copy'],
+    headingSizes: [40],
+    headingLineHeights: [1.15],
+    textAlign: 'left',
+    bodyText: ['A two-up row carries the main product image and preserves the sample strip below it.'],
+    bodyTextSizes: [17],
+    bodyLineHeights: [1.6],
+    buttonLabels: ['Compare specs'],
+    buttons: [
+      {
+        label: 'Compare specs',
+        href: '/compare',
+        background: 'rgb(0, 128, 96)',
+        color: 'rgb(248, 250, 252)',
+      },
+    ],
+    images: [
+      image('media-primary.jpg', 720, 520, 'Primary product'),
+      image('sample-oak.jpg', 320, 180, 'Oak sample'),
+      image('sample-walnut.jpg', 300, 180, 'Walnut sample'),
+      image('sample-maple.jpg', 280, 180, 'Maple sample'),
+    ],
+    backgroundBrightness: 236,
+    backgroundColor: 'rgb(232, 239, 241)',
+    layout: {
+      containerWidth: 1100,
+      padding: '0px',
+      childLayout: 'flex-row',
+      columnCount: 2,
+      gap: '36px',
+      padTopPx: 64,
+      padBottomPx: 64,
+    },
+  });
+
+  const mediaTextLeft = section({
+    sectionIndex: 24,
+    interactionModel: 'static',
+    mediaLayout: 'image-left',
+    height: 520,
+    headings: ['Image-led story row'],
+    headingSizes: [36],
+    headingLineHeights: [1.16],
+    textAlign: 'left',
+    bodyText: ['When the source puts media first, the parity corpus fixes the column order.'],
+    bodyTextSizes: [16],
+    bodyLineHeights: [1.55],
+    images: [
+      image('story-portrait.jpg', 520, 640, 'Portrait crop'),
+      image('story-detail.jpg', 360, 260, 'Detail crop'),
+    ],
+    backgroundBrightness: 255,
+    backgroundColor: 'rgb(255, 255, 255)',
+    layout: {
+      containerWidth: 1080,
+      padding: '0px',
+      childLayout: 'flex-row',
+      columnCount: 2,
+      gap: '32px',
+      padTopPx: 48,
+      padBottomPx: 56,
+    },
+  });
+
+  return {
+    renderTextBand: [{ id: 'dark-band-cta-lead-image', section: textBand }],
+    renderCover: [{ id: 'full-bleed-hero-cover', section: cover }],
+    renderMediaText: [
+      { id: 'image-right-with-gallery-strip', section: mediaTextRight, flip: false },
+      { id: 'image-left-with-stacked-extra', section: mediaTextLeft, flip: true },
+    ],
+    galleryBlock: [
+      {
+        id: 'scroller-landscape-strip',
+        images: [
+          image('gallery-wide-1.jpg', 900, 420, 'Wide one'),
+          image('gallery-wide-2.jpg', 780, 420, 'Wide two'),
+          image('gallery-tall.jpg', 360, 540, 'Tall item'),
+          image('gallery-wide-3.jpg', 640, 360, 'Wide three'),
+        ],
+        opts: { sectionHeight: 240 },
+      },
+      {
+        id: 'multi-row-cropped-grid',
+        images: [
+          image('gallery-grid-1.jpg', 320, 320, 'Grid one'),
+          image('gallery-grid-2.jpg', 320, 320, 'Grid two'),
+          image('gallery-grid-3.jpg', 320, 320, 'Grid three'),
+          image('gallery-grid-4.jpg', 320, 320, 'Grid four'),
+        ],
+        opts: { sectionHeight: 760 },
+      },
+    ],
+  };
+}
+
+function clone<T>(value: T): T {
+  if (value === undefined) return value;
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function freeze(value: unknown): unknown {
+  if (value === undefined) return { __type: 'undefined' };
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(freeze);
+  return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, freeze(nested)]));
+}
+
+function capture(id: string, run: () => unknown): NativeTextRendererOutputCase {
+  return { id, output: freeze(run()) };
+}
+
+export function runNativeTextRendererParity(impl: NativeTextRendererImpl): NativeTextRendererParityFile {
+  const cases = nativeTextRendererCaseGroups();
+
+  return {
+    version: 1,
+    derivation: NATIVE_TEXT_RENDERER_DERIVATION,
+    renderers: {
+      renderTextBand: cases.renderTextBand.map((entry) =>
+        capture(entry.id, () => impl.renderTextBand(clone(entry.section), nativeRenderCtx())),
+      ),
+      renderCover: cases.renderCover.map((entry) =>
+        capture(entry.id, () => impl.renderCover(clone(entry.section), nativeRenderCtx())),
+      ),
+      renderMediaText: cases.renderMediaText.map((entry) =>
+        capture(entry.id, () => impl.renderMediaText(clone(entry.section), entry.flip, nativeRenderCtx())),
+      ),
+      galleryBlock: cases.galleryBlock.map((entry) =>
+        capture(entry.id, () => {
+          const out = nativeRenderOut();
+          return {
+            returnValue: impl.galleryBlock(clone(entry.images), out, clone(entry.opts)),
+            out,
+          };
+        }),
+      ),
+    },
+  };
+}
diff --git a/packages/blocks-engine/src/__fixtures__/native-text-renderer-dla-goldens.json b/packages/blocks-engine/src/__fixtures__/native-text-renderer-dla-goldens.json
new file mode 100644
index 00000000..d5ab4843
--- /dev/null
+++ b/packages/blocks-engine/src/__fixtures__/native-text-renderer-dla-goldens.json
@@ -0,0 +1,128 @@
+{
+  "version": 1,
+  "derivation": "Mechanically generated from DLA src/lib/replicate/page-reconstruct.ts reconstructPagePattern at DLA commit 1e393c5; section renderer markup strips the final reconstruct body newline, and direct galleryBlock outputs extract the nested wp:gallery block.",
+  "renderers": {
+    "renderTextBand": [
+      {
+        "id": "dark-band-cta-lead-image",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"backgroundColor\":\"surface-inverse\",\"textColor\":\"text-inverse\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(32px, 5.00vw, 72px)\",\"bottom\":\"clamp(36px, 5.56vw, 80px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull has-surface-inverse-background-color has-text-inverse-color has-text-color has-background\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(32px, 5.00vw, 72px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(36px, 5.56vw, 80px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(29px, 4.0vw, 58px)\",\"lineHeight\":\"1.05\"}},\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-inverse\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family\" style=\"font-size:clamp(29px, 4.0vw, 58px);line-height:1.05\">Build calmer block themes</h1>\n<!-- /wp:heading -->\n<!-- wp:heading {\"textAlign\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 1.7vw, 24px)\",\"lineHeight\":\"1.25\"}},\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-inverse\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family\" style=\"font-size:clamp(16px, 1.7vw, 24px);line-height:1.25\">Without losing source copy</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 1.3vw, 18px)\",\"lineHeight\":\"1.55\"}},\"textColor\":\"text-inverse\"} -->\n<p class=\"has-text-align-center has-text-inverse-color has-text-color\" style=\"font-size:clamp(16px, 1.3vw, 18px);line-height:1.55\">Every heading, paragraph, button, and media asset traces back to capture.</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\" href=\"/demo\">See the demo</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"720px\",\"align\":\"center\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image aligncenter size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/theme-preview.jpg\" alt=\"Theme preview\" style=\"width:720px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Build calmer block themes",
+            "Without losing source copy",
+            "See the demo"
+          ],
+          "bodyText": [
+            "Every heading, paragraph, button, and media asset traces back to capture."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/theme-preview.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      }
+    ],
+    "renderCover": [
+      {
+        "id": "full-bleed-hero-cover",
+        "output": {
+          "markup": "<!-- wp:cover {\"url\":\"http://localhost:8883/wp-content/uploads/2026/05/hero-cover.jpg\",\"dimRatio\":40,\"overlayColor\":\"surface-inverse\",\"isUserOverlayColor\":true,\"minHeight\":50.9,\"minHeightUnit\":\"vw\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0px\"}}},\"layout\":{\"type\":\"constrained\"}} -->\n<div class=\"wp-block-cover alignfull\" style=\"margin-top:0px;min-height:50.9vw\"><img class=\"wp-block-cover__image-background\" src=\"http://localhost:8883/wp-content/uploads/2026/05/hero-cover.jpg\" alt=\"Workspace with block patterns\" data-object-fit=\"cover\"/><span aria-hidden=\"true\" class=\"wp-block-cover__background has-surface-inverse-background-color has-background-dim-40 has-background-dim\"></span>\n<div class=\"wp-block-cover__inner-container\">\n<!-- wp:heading {\"textAlign\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(34px, 4.7vw, 68px)\",\"lineHeight\":\"1.02\"}},\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-inverse\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family\" style=\"font-size:clamp(34px, 4.7vw, 68px);line-height:1.02\">A native cover from captured hero media</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 1.4vw, 20px)\",\"lineHeight\":\"1.5\"}},\"textColor\":\"text-inverse\"} -->\n<p class=\"has-text-align-center has-text-inverse-color has-text-color\" style=\"font-size:clamp(16px, 1.4vw, 20px);line-height:1.5\">The headline and CTA stay over the migrated background image.</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"surface-base\",\"textColor\":\"text-default\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-default-color has-surface-base-background-color has-text-color has-background wp-element-button\" href=\"/patterns\">Explore patterns</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</div>\n</div>\n<!-- /wp:cover -->",
+          "expectedText": [
+            "A native cover from captured hero media",
+            "Explore patterns"
+          ],
+          "bodyText": [
+            "The headline and CTA stay over the migrated background image."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/hero-cover.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      }
+    ],
+    "renderMediaText": [
+      {
+        "id": "image-right-with-gallery-strip",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"color\":{\"background\":\"#e8eff1\"},\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(29px, 4.44vw, 64px)\",\"bottom\":\"clamp(29px, 4.44vw, 64px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull has-background\" style=\"margin-top:0;margin-bottom:0;background-color:#e8eff1;padding-top:clamp(29px, 4.44vw, 64px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(29px, 4.44vw, 64px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column {\"width\":\"55%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:55%\">\n<!-- wp:heading {\"style\":{\"typography\":{\"fontSize\":\"clamp(20px, 2.8vw, 40px)\",\"lineHeight\":\"1.15\"}},\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-default-color has-text-color has-display-font-family\" style=\"font-size:clamp(20px, 2.8vw, 40px);line-height:1.15\">Media beside structured copy</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 1.2vw, 17px)\",\"lineHeight\":\"1.6\"}},\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\" style=\"font-size:clamp(16px, 1.2vw, 17px);line-height:1.6\">A two-up row carries the main product image and preserves the sample strip below it.</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"left\"}} -->\n<div class=\"wp-block-buttons is-content-justification-left\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\" href=\"/compare\">Compare specs</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column {\"width\":\"45%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:45%\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"720px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/media-primary.jpg\" alt=\"Primary product\" style=\"width:720px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n<!-- wp:gallery {\"columns\":3,\"imageCrop\":false,\"linkTo\":\"none\",\"sizeSlug\":\"large\",\"className\":\"is-gallery-scroller\"} -->\n<figure class=\"wp-block-gallery has-nested-images columns-3 is-gallery-scroller\">\n<!-- wp:image {\"width\":\"320px\",\"height\":\"180px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/sample-oak.jpg\" alt=\"Oak sample\" style=\"width:320px;height:180px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"300px\",\"height\":\"180px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/sample-walnut.jpg\" alt=\"Walnut sample\" style=\"width:300px;height:180px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"280px\",\"height\":\"180px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/sample-maple.jpg\" alt=\"Maple sample\" style=\"width:280px;height:180px\"/></figure>\n<!-- /wp:image -->\n</figure>\n<!-- /wp:gallery -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Media beside structured copy",
+            "Compare specs"
+          ],
+          "bodyText": [
+            "A two-up row carries the main product image and preserves the sample strip below it."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/media-primary.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/sample-oak.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/sample-walnut.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/sample-maple.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "image-left-with-stacked-extra",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(22px, 3.33vw, 48px)\",\"bottom\":\"clamp(25px, 3.89vw, 56px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(22px, 3.33vw, 48px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(25px, 3.89vw, 56px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column {\"width\":\"45%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:45%\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"520px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/story-portrait.jpg\" alt=\"Portrait crop\" style=\"width:520px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column {\"width\":\"55%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:55%\">\n<!-- wp:heading {\"style\":{\"typography\":{\"fontSize\":\"clamp(18px, 2.5vw, 36px)\",\"lineHeight\":\"1.16\"}},\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-default-color has-text-color has-display-font-family\" style=\"font-size:clamp(18px, 2.5vw, 36px);line-height:1.16\">Image-led story row</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 1.1vw, 16px)\",\"lineHeight\":\"1.55\"}},\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\" style=\"font-size:clamp(16px, 1.1vw, 16px);line-height:1.55\">When the source puts media first, the parity corpus fixes the column order.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"360px\",\"align\":\"center\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image aligncenter size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/story-detail.jpg\" alt=\"Detail crop\" style=\"width:360px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Image-led story row"
+          ],
+          "bodyText": [
+            "When the source puts media first, the parity corpus fixes the column order."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/story-portrait.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/story-detail.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      }
+    ],
+    "galleryBlock": [
+      {
+        "id": "scroller-landscape-strip",
+        "output": {
+          "returnValue": "<!-- wp:gallery {\"columns\":4,\"imageCrop\":false,\"linkTo\":\"none\",\"sizeSlug\":\"large\",\"className\":\"is-gallery-scroller\"} -->\n<figure class=\"wp-block-gallery has-nested-images columns-4 is-gallery-scroller\">\n<!-- wp:image {\"width\":\"647px\",\"height\":\"302px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/gallery-wide-1.jpg\" alt=\"Wide one\" style=\"width:647px;height:302px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"561px\",\"height\":\"302px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/gallery-wide-2.jpg\" alt=\"Wide two\" style=\"width:561px;height:302px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"201px\",\"height\":\"302px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/gallery-tall.jpg\" alt=\"Tall item\" style=\"width:201px;height:302px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"537px\",\"height\":\"302px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/gallery-wide-3.jpg\" alt=\"Wide three\" style=\"width:537px;height:302px\"/></figure>\n<!-- /wp:image -->\n</figure>\n<!-- /wp:gallery -->",
+          "out": {
+            "markup": "",
+            "expectedText": [],
+            "bodyText": [],
+            "assets": [
+              "http://localhost:8883/wp-content/uploads/2026/05/gallery-wide-1.jpg",
+              "http://localhost:8883/wp-content/uploads/2026/05/gallery-wide-2.jpg",
+              "http://localhost:8883/wp-content/uploads/2026/05/gallery-tall.jpg",
+              "http://localhost:8883/wp-content/uploads/2026/05/gallery-wide-3.jpg"
+            ],
+            "flags": [],
+            "iconAssets": []
+          }
+        }
+      },
+      {
+        "id": "multi-row-cropped-grid",
+        "output": {
+          "returnValue": "<!-- wp:gallery {\"columns\":4,\"imageCrop\":true,\"linkTo\":\"none\",\"sizeSlug\":\"large\"} -->\n<figure class=\"wp-block-gallery has-nested-images columns-4 is-cropped\">\n<!-- wp:image {\"width\":\"320px\",\"height\":\"320px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/gallery-grid-1.jpg\" alt=\"Grid one\" style=\"width:320px;height:320px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"320px\",\"height\":\"320px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/gallery-grid-2.jpg\" alt=\"Grid two\" style=\"width:320px;height:320px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"320px\",\"height\":\"320px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/gallery-grid-3.jpg\" alt=\"Grid three\" style=\"width:320px;height:320px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"320px\",\"height\":\"320px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/gallery-grid-4.jpg\" alt=\"Grid four\" style=\"width:320px;height:320px\"/></figure>\n<!-- /wp:image -->\n</figure>\n<!-- /wp:gallery -->",
+          "out": {
+            "markup": "",
+            "expectedText": [],
+            "bodyText": [],
+            "assets": [
+              "http://localhost:8883/wp-content/uploads/2026/05/gallery-grid-1.jpg",
+              "http://localhost:8883/wp-content/uploads/2026/05/gallery-grid-2.jpg",
+              "http://localhost:8883/wp-content/uploads/2026/05/gallery-grid-3.jpg",
+              "http://localhost:8883/wp-content/uploads/2026/05/gallery-grid-4.jpg"
+            ],
+            "flags": [],
+            "iconAssets": []
+          }
+        }
+      }
+    ]
+  }
+}
diff --git a/packages/blocks-engine/src/__tests__/theme-native-renderers-text-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-native-renderers-text-parity.test.ts
new file mode 100644
index 00000000..15ba4666
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-native-renderers-text-parity.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+
+import expectedGoldens from '../__fixtures__/native-text-renderer-dla-goldens.json' with { type: 'json' };
+import {
+  runNativeTextRendererParity,
+  type NativeTextRendererImpl,
+  type NativeTextRendererParityFile,
+} from '../__fixtures__/native-text-renderer-cases.js';
+import {
+  galleryBlock,
+  renderCover,
+  renderMediaText,
+  renderTextBand,
+} from '../theme/native-renderers-text.js';
+
+const EXPECTED_RENDERERS = 4;
+const EXPECTED_CASES = 6;
+
+const engineImpl: NativeTextRendererImpl = {
+  renderTextBand,
+  renderCover,
+  renderMediaText,
+  galleryBlock,
+};
+
+function stableJson(value: unknown): string {
+  return JSON.stringify(value, null, 2);
+}
+
+function rendererCaseCount(file: NativeTextRendererParityFile): number {
+  return Object.values(file.renderers).reduce((sum, cases) => sum + cases.length, 0);
+}
+
+function collectDiffs(actual: NativeTextRendererParityFile, expected: NativeTextRendererParityFile): string[] {
+  const diffs: string[] = [];
+  if (actual.version !== expected.version) diffs.push(`version: expected ${expected.version}, got ${actual.version}`);
+  if (actual.derivation !== expected.derivation) diffs.push('derivation: changed');
+
+  const actualRenderers = Object.keys(actual.renderers).sort();
+  const expectedRenderers = Object.keys(expected.renderers).sort();
+  if (stableJson(actualRenderers) !== stableJson(expectedRenderers)) {
+    diffs.push(`renderer keys: expected ${expectedRenderers.join(',')}, got ${actualRenderers.join(',')}`);
+  }
+
+  for (const renderer of expectedRenderers) {
+    const actualCases = actual.renderers[renderer as keyof NativeTextRendererParityFile['renderers']];
+    const expectedCases = expected.renderers[renderer as keyof NativeTextRendererParityFile['renderers']];
+    if (!actualCases) continue;
+    if (stableJson(actualCases) !== stableJson(expectedCases)) {
+      diffs.push(`${renderer}: output changed`);
+    }
+  }
+  return diffs;
+}
+
+describe('native text renderer DLA-today parity', () => {
+  it('matches mechanically derived DLA renderer outputs byte-for-byte and is stable on rerun', () => {
+    const first = runNativeTextRendererParity(engineImpl);
+    const second = runNativeTextRendererParity(engineImpl);
+    expect(stableJson(first)).toBe(stableJson(second));
+
+    const expected = expectedGoldens as NativeTextRendererParityFile;
+    const rendererCount = Object.keys(expected.renderers).length;
+    const caseCount = rendererCaseCount(expected);
+    const diffs = collectDiffs(first, expected);
+    console.info(`native text renderer parity: renderers=${rendererCount} cases=${caseCount} diffs=${diffs.length}`);
+
+    expect(rendererCount).toBe(EXPECTED_RENDERERS);
+    expect(caseCount).toBe(EXPECTED_CASES);
+    expect(diffs).toEqual([]);
+  });
+});
diff --git a/packages/blocks-engine/src/theme/native-renderers-text.ts b/packages/blocks-engine/src/theme/native-renderers-text.ts
index 65ae0dce..f1ec8165 100644
--- a/packages/blocks-engine/src/theme/native-renderers-text.ts
+++ b/packages/blocks-engine/src/theme/native-renderers-text.ts
@@ -1,4 +1,16 @@
-import { emptyNativeRenderOut } from './native-block-builders.js';
+import { escapeHtml } from '../escape.js';
+import {
+  column,
+  columns,
+  emptyNativeRenderOut,
+  headingBlock,
+  imageBlock,
+  paragraphBlock,
+  sectionButtons,
+  wrapSection,
+} from './native-block-builders.js';
+import { centerOf, isDarkSection, isTintedSection, sectionPad } from './native-layout.js';
+import { isWpMediaUrl, pickLeadImage } from './native-media.js';
 import type { NativeRenderCtx, NativeRenderOut } from './native-reconstruct-types.js';
 import type { SectionSpec, SectionSpecImage } from './section-spec.js';
 
@@ -7,22 +19,172 @@ export interface GalleryBlockOptions {
 }
 
 export function renderTextBand(section: SectionSpec, ctx: NativeRenderCtx): NativeRenderOut {
-  void section;
-  void ctx;
-  return emptyNativeRenderOut();
+  const out = emptyNativeRenderOut();
+  const parts: string[] = [];
+  const dark = isDarkSection(section);
+  section.headings.forEach((heading, index) =>
+    parts.push(
+      headingBlock(heading, out, {
+        level: index === 0 ? 1 : 2,
+        center: centerOf(section),
+        inverse: dark,
+        sizePx: section.headingSizes?.[index],
+        fontFamily: section.headingFamilies?.[index] || undefined,
+        lineHeight: section.headingLineHeights?.[index],
+      }),
+    ),
+  );
+  (section.bodyText ?? []).forEach((body, index) =>
+    parts.push(
+      paragraphBlock(body, out, {
+        center: centerOf(section),
+        inverse: dark,
+        sizePx: section.bodyTextSizes?.[index],
+        fontFamily: section.bodyFamilies?.[index] || undefined,
+        lineHeight: section.bodyLineHeights?.[index],
+      }),
+    ),
+  );
+  parts.push(...sectionButtons(section, out, ctx));
+
+  const lead = pickLeadImage(section.images);
+  if (lead) {
+    parts.push(
+      imageBlock(lead, out, `${section.interactionModel}#${section.sectionIndex}`, {
+        align: centerOf(section) ? 'center' : null,
+        rounded: true,
+      }),
+    );
+  }
+
+  const extra = section.images.filter(
+    (image) =>
+      image.url !== lead?.url &&
+      isWpMediaUrl(image.url) &&
+      Math.min(image.width || 0, image.height || 0) >= 90,
+  );
+  if (extra.length >= 3) {
+    const gallery = galleryBlock(extra, out);
+    if (gallery) parts.push(gallery);
+  } else {
+    for (const image of extra.filter((candidate) => pickLeadImage([candidate]) === candidate)) {
+      parts.push(
+        imageBlock(image, out, `${section.interactionModel}#${section.sectionIndex}.extra`, {
+          align: centerOf(section) ? 'center' : null,
+          rounded: true,
+        }),
+      );
+    }
+  }
+
+  out.markup = wrapSection(parts.filter(Boolean), {
+    constrained: '760px',
+    center: centerOf(section),
+    inverse: dark,
+    raised: isTintedSection(section),
+    bgColor: section.backgroundColor,
+    ...sectionPad(section),
+  });
+  return out;
 }
 
 export function renderCover(section: SectionSpec, ctx: NativeRenderCtx): NativeRenderOut {
-  void section;
-  void ctx;
-  return emptyNativeRenderOut();
+  const lead = pickLeadImage(section.images);
+  if (!lead || !isWpMediaUrl(lead.url)) return renderTextBand(section, ctx);
+  const out = emptyNativeRenderOut();
+  out.assets.push(lead.url);
+  const inner: string[] = [];
+  section.headings.forEach((heading, index) =>
+    inner.push(
+      headingBlock(heading, out, {
+        level: index === 0 ? 1 : 2,
+        center: centerOf(section),
+        inverse: true,
+        sizePx: section.headingSizes?.[index],
+        fontFamily: section.headingFamilies?.[index] || undefined,
+        lineHeight: section.headingLineHeights?.[index],
+      }),
+    ),
+  );
+  (section.bodyText ?? []).forEach((body, index) =>
+    inner.push(
+      paragraphBlock(body, out, {
+        center: centerOf(section),
+        inverse: true,
+        sizePx: section.bodyTextSizes?.[index],
+        fontFamily: section.bodyFamilies?.[index] || undefined,
+        lineHeight: section.bodyLineHeights?.[index],
+      }),
+    ),
+  );
+  inner.push(...sectionButtons(section, out, ctx));
+  const innerMarkup = inner.filter(Boolean).join('\n');
+  const url = escapeHtml(lead.url);
+  const minHpx = Math.max(480, Math.min(Math.round(section.height || 520), 1000));
+  const minVw = Math.round((minHpx / 1440) * 1000) / 10;
+  out.markup =
+    `<!-- wp:cover {"url":"${url}","dimRatio":40,"overlayColor":"surface-inverse","isUserOverlayColor":true,"minHeight":${minVw},"minHeightUnit":"vw","align":"full","style":{"spacing":{"margin":{"top":"0px"}}},"layout":{"type":"constrained"}} -->\n` +
+    `<div class="wp-block-cover alignfull" style="margin-top:0px;min-height:${minVw}vw">` +
+    `<img class="wp-block-cover__image-background" src="${url}" alt="${escapeHtml(lead.alt || '')}" data-object-fit="cover"/>` +
+    `<span aria-hidden="true" class="wp-block-cover__background has-surface-inverse-background-color has-background-dim-40 has-background-dim"></span>\n` +
+    `<div class="wp-block-cover__inner-container">\n${innerMarkup}\n</div>\n` +
+    `</div>\n<!-- /wp:cover -->`;
+  return out;
 }
 
 export function renderMediaText(section: SectionSpec, flip: boolean, ctx: NativeRenderCtx): NativeRenderOut {
-  void section;
-  void flip;
-  void ctx;
-  return emptyNativeRenderOut();
+  const out = emptyNativeRenderOut();
+  const textParts: string[] = [];
+  section.headings.forEach((heading, index) =>
+    textParts.push(
+      headingBlock(heading, out, {
+        level: 2,
+        sizePx: section.headingSizes?.[index],
+        fontFamily: section.headingFamilies?.[index] || undefined,
+        lineHeight: section.headingLineHeights?.[index],
+      }),
+    ),
+  );
+  (section.bodyText ?? []).forEach((body, index) =>
+    textParts.push(
+      paragraphBlock(body, out, {
+        sizePx: section.bodyTextSizes?.[index],
+        fontFamily: section.bodyFamilies?.[index] || undefined,
+        lineHeight: section.bodyLineHeights?.[index],
+      }),
+    ),
+  );
+  textParts.push(...sectionButtons(section, out, ctx));
+
+  const lead = pickLeadImage(section.images) ?? section.images[0];
+  const imageMarkup = imageBlock(lead, out, `media-text#${section.sectionIndex}`, { rounded: true });
+  const textColumn = column(textParts.filter(Boolean), '55%');
+  const imageColumn = column([imageMarkup], '45%');
+  const columnBlocks = flip ? [imageColumn, textColumn] : [textColumn, imageColumn];
+  const blocks: string[] = [columns(columnBlocks)];
+
+  const extra = section.images.filter(
+    (image) =>
+      image.url !== lead?.url &&
+      isWpMediaUrl(image.url) &&
+      Math.min(image.width || 0, image.height || 0) >= 90,
+  );
+  if (extra.length >= 3) {
+    const gallery = galleryBlock(extra, out);
+    if (gallery) blocks.push(gallery);
+  } else {
+    for (const image of extra.filter((candidate) => pickLeadImage([candidate]) === candidate)) {
+      blocks.push(imageBlock(image, out, `media-text#${section.sectionIndex}.extra`, { align: 'center', rounded: true }));
+    }
+  }
+
+  out.markup = wrapSection(blocks, {
+    wide: '1100px',
+    raised: isTintedSection(section),
+    bgColor: section.backgroundColor,
+    ...sectionPad(section),
+  });
+  return out;
 }
 
 export function galleryBlock(
@@ -30,8 +192,45 @@ export function galleryBlock(
   out: NativeRenderOut,
   opts?: GalleryBlockOptions,
 ): string {
-  void images;
-  void out;
-  void opts;
-  return '';
+  const usable = images.filter((image) => isWpMediaUrl(image.url));
+  if (usable.length === 0) return '';
+  const columnsCount = Math.min(4, usable.length);
+  const sized = usable.filter((image) => image.width && image.height);
+  const landscape = sized.filter((image) => image.width >= image.height);
+  const basis = (landscape.length ? landscape : sized).map(
+    (image) => (image.height * Math.min(560, image.width)) / image.width,
+  );
+  const sortedHeights = basis.slice().sort((a, b) => a - b);
+  const rowHeight = sortedHeights.length
+    ? Math.max(140, Math.min(460, Math.round(sortedHeights[Math.floor(sortedHeights.length / 2)])))
+    : 0;
+  const figures = usable.map((image) => {
+    out.assets.push(image.url);
+    if (image.width && image.height && rowHeight) {
+      const width = Math.max(80, Math.min(900, Math.round((rowHeight * image.width) / image.height)));
+      return (
+        `<!-- wp:image {"width":"${width}px","height":"${rowHeight}px","sizeSlug":"large","linkDestination":"none"} -->\n` +
+        `<figure class="wp-block-image size-large is-resized"><img src="${escapeHtml(image.url)}" alt="${escapeHtml(image.alt || '')}" style="width:${width}px;height:${rowHeight}px"/></figure>\n` +
+        `<!-- /wp:image -->`
+      );
+    }
+    return (
+      `<!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->\n` +
+      `<figure class="wp-block-image size-large"><img src="${escapeHtml(image.url)}" alt="${escapeHtml(image.alt || '')}"/></figure>\n` +
+      `<!-- /wp:image -->`
+    );
+  });
+  const multiRow = !!(opts?.sectionHeight && rowHeight && opts.sectionHeight >= rowHeight * 2);
+  if (multiRow) {
+    return (
+      `<!-- wp:gallery {"columns":${columnsCount},"imageCrop":true,"linkTo":"none","sizeSlug":"large"} -->\n` +
+      `<figure class="wp-block-gallery has-nested-images columns-${columnsCount} is-cropped">\n${figures.join('\n')}\n</figure>\n` +
+      `<!-- /wp:gallery -->`
+    );
+  }
+  return (
+    `<!-- wp:gallery {"columns":${columnsCount},"imageCrop":false,"linkTo":"none","sizeSlug":"large","className":"is-gallery-scroller"} -->\n` +
+    `<figure class="wp-block-gallery has-nested-images columns-${columnsCount} is-gallery-scroller">\n${figures.join('\n')}\n</figure>\n` +
+    `<!-- /wp:gallery -->`
+  );
 }

From 542ebf46360552fe9280e0efb91a2f77cfbda723 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 19:28:38 -0400
Subject: [PATCH 087/113] feat(theme): freeze native section renderer surface

---
 ...e-native-renderers-section-surface.test.ts | 24 +++++++++++++++++++
 .../src/theme/native-renderers-section.ts     | 13 ++++++++++
 2 files changed, 37 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-native-renderers-section-surface.test.ts
 create mode 100644 packages/blocks-engine/src/theme/native-renderers-section.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-native-renderers-section-surface.test.ts b/packages/blocks-engine/src/__tests__/theme-native-renderers-section-surface.test.ts
new file mode 100644
index 00000000..13b81521
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-native-renderers-section-surface.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { renderImageRow, renderReviewGrid } from '../theme/native-renderers-section.js';
+import type { NativeRenderOut } from '../theme/native-reconstruct-types.js';
+import type { SectionSpec } from '../theme/section-spec.js';
+
+describe('native section renderer frozen surface', () => {
+  it('freezes the renderer export names and runtime availability', () => {
+    expect({
+      renderImageRow,
+      renderReviewGrid,
+    }).toEqual(
+      expect.objectContaining({
+        renderImageRow: expect.any(Function),
+        renderReviewGrid: expect.any(Function),
+      })
+    );
+  });
+
+  it('freezes the renderer type signatures', () => {
+    expectTypeOf(renderReviewGrid).toEqualTypeOf<(section: SectionSpec) => NativeRenderOut>();
+    expectTypeOf(renderImageRow).toEqualTypeOf<(section: SectionSpec) => NativeRenderOut>();
+  });
+});
diff --git a/packages/blocks-engine/src/theme/native-renderers-section.ts b/packages/blocks-engine/src/theme/native-renderers-section.ts
new file mode 100644
index 00000000..72505ffb
--- /dev/null
+++ b/packages/blocks-engine/src/theme/native-renderers-section.ts
@@ -0,0 +1,13 @@
+import { emptyNativeRenderOut } from './native-block-builders.js';
+import type { NativeRenderOut } from './native-reconstruct-types.js';
+import type { SectionSpec } from './section-spec.js';
+
+export function renderReviewGrid(section: SectionSpec): NativeRenderOut {
+  void section;
+  return emptyNativeRenderOut();
+}
+
+export function renderImageRow(section: SectionSpec): NativeRenderOut {
+  void section;
+  return emptyNativeRenderOut();
+}

From 413d96b4ee95212e6a5b28bf3bba3bcc263f3752 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 19:37:14 -0400
Subject: [PATCH 088/113] feat(theme): port native section renderers

---
 ...apture-native-section-renderer-goldens.mjs | 138 ++++++++++
 .../native-section-renderer-cases.ts          | 258 ++++++++++++++++++
 .../native-section-renderer-dla-goldens.json  |  98 +++++++
 ...me-native-renderers-section-parity.test.ts |  65 +++++
 .../src/theme/native-renderers-section.ts     | 124 ++++++++-
 5 files changed, 677 insertions(+), 6 deletions(-)
 create mode 100644 packages/blocks-engine/scripts/capture-native-section-renderer-goldens.mjs
 create mode 100644 packages/blocks-engine/src/__fixtures__/native-section-renderer-cases.ts
 create mode 100644 packages/blocks-engine/src/__fixtures__/native-section-renderer-dla-goldens.json
 create mode 100644 packages/blocks-engine/src/__tests__/theme-native-renderers-section-parity.test.ts

diff --git a/packages/blocks-engine/scripts/capture-native-section-renderer-goldens.mjs b/packages/blocks-engine/scripts/capture-native-section-renderer-goldens.mjs
new file mode 100644
index 00000000..cad93047
--- /dev/null
+++ b/packages/blocks-engine/scripts/capture-native-section-renderer-goldens.mjs
@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import { execFileSync, spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const DLA_COMMIT = '1e393c535850ee1a9482f83459f779d0e225b027';
+const DEFAULT_DLA_ROOT = '/Users/matt/projects/a8c/data-liberation-agent';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+const fixtureUrl = pathToFileURL(path.join(packageRoot, 'src/__fixtures__/native-section-renderer-cases.ts')).href;
+const outputPath = path.join(packageRoot, 'src/__fixtures__/native-section-renderer-dla-goldens.json');
+const TSX_BOOTSTRAP_ENV = 'BLOCKS_ENGINE_NATIVE_SECTION_GOLDENS_TSX';
+
+function hasTsxLoader() {
+  return process.execArgv.some((arg, index, argv) => {
+    if (arg === '--import') return argv[index + 1]?.includes('tsx');
+    return arg.startsWith('--import=') && arg.includes('tsx');
+  });
+}
+
+if (!process.env[TSX_BOOTSTRAP_ENV] && !hasTsxLoader()) {
+  const result = spawnSync(process.execPath, ['--import', 'tsx', fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+    cwd: packageRoot,
+    env: { ...process.env, [TSX_BOOTSTRAP_ENV]: '1' },
+    stdio: 'inherit',
+  });
+  if (result.error) throw result.error;
+  process.exit(result.status ?? 1);
+}
+
+const args = new Set(process.argv.slice(2));
+const shouldWrite = args.has('--write');
+const shouldCheck = args.has('--check');
+const shouldStdout = args.has('--stdout') || (!shouldWrite && !shouldCheck);
+const dlaRoot = process.env.DLA_ROOT || DEFAULT_DLA_ROOT;
+
+function git(args) {
+  return execFileSync('git', ['-C', dlaRoot, ...args], { encoding: 'utf8' }).trim();
+}
+
+function stableJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function clone(value) {
+  if (value === undefined) return value;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function stripFinalBodyNewline(markup) {
+  return markup.endsWith('\n') ? markup.slice(0, -1) : markup;
+}
+
+function capture(id, output) {
+  return { id, output };
+}
+
+function reconstructOptions() {
+  return {
+    patternSlug: 'native-section-renderer-parity/single-section',
+    title: 'Native Section Renderer Parity',
+    paletteTokens: [
+      { slug: 'text-default', hex: '#102030' },
+      { slug: 'text-inverse', hex: '#f8fafc' },
+      { slug: 'text-muted', hex: '#4b5563' },
+      { slug: 'text-subtle', hex: '#6b7280' },
+      { slug: 'accent-primary', hex: '#008060' },
+      { slug: 'surface-base', hex: '#ffffff' },
+      { slug: 'surface-raised', hex: '#e8eff1' },
+      { slug: 'surface-inverse', hex: '#111827' },
+    ],
+    fontFamilies: [
+      { slug: 'display', family: 'Caldera Display, serif' },
+      { slug: 'body', family: 'Caldera, sans-serif' },
+    ],
+    sourceUrl: 'https://example.test/native-section-renderer-parity',
+    slug: 'native-section-renderer-parity',
+  };
+}
+
+function renderOutFromResult(result) {
+  if (result.sectionsRendered !== 1) {
+    throw new Error(`Expected exactly one rendered section, got ${result.sectionsRendered}`);
+  }
+  if (result.fallbackDiagnostics.length > 0) {
+    throw new Error(`Expected native renderer output, got fallback diagnostics: ${JSON.stringify(result.fallbackDiagnostics)}`);
+  }
+  return {
+    markup: stripFinalBodyNewline(result.body),
+    expectedText: result.expectedText,
+    bodyText: result.bodyText,
+    assets: result.expectedAssets,
+    flags: result.provenanceFlags,
+    iconAssets: result.iconAssets,
+  };
+}
+
+const currentCommit = git(['rev-parse', 'HEAD']);
+if (currentCommit !== DLA_COMMIT) {
+  throw new Error(`DLA checkout must be at ${DLA_COMMIT}; got ${currentCommit}`);
+}
+
+const dirty = git(['status', '--porcelain']);
+if (dirty) {
+  throw new Error(`DLA checkout must be clean at ${DLA_COMMIT}; status:\n${dirty}`);
+}
+
+const { nativeSectionRendererCaseGroups, NATIVE_SECTION_RENDERER_DERIVATION } = await import(fixtureUrl);
+const { reconstructPagePattern } = await import(
+  pathToFileURL(path.join(dlaRoot, 'src/lib/replicate/page-reconstruct.ts')).href
+);
+
+const cases = nativeSectionRendererCaseGroups();
+const renderSectionCase = (entry) =>
+  capture(entry.id, renderOutFromResult(reconstructPagePattern([clone(entry.section)], reconstructOptions())));
+
+const parityFile = {
+  version: 1,
+  derivation: NATIVE_SECTION_RENDERER_DERIVATION,
+  renderers: {
+    renderReviewGrid: cases.renderReviewGrid.map(renderSectionCase),
+    renderImageRow: cases.renderImageRow.map(renderSectionCase),
+  },
+};
+
+const json = stableJson(parityFile);
+
+if (shouldCheck) {
+  const existing = readFileSync(outputPath, 'utf8');
+  if (existing !== json) {
+    throw new Error(`${outputPath} is out of date with DLA ${DLA_COMMIT}`);
+  }
+}
+
+if (shouldWrite) writeFileSync(outputPath, json);
+if (shouldStdout) process.stdout.write(json);
diff --git a/packages/blocks-engine/src/__fixtures__/native-section-renderer-cases.ts b/packages/blocks-engine/src/__fixtures__/native-section-renderer-cases.ts
new file mode 100644
index 00000000..6bd84655
--- /dev/null
+++ b/packages/blocks-engine/src/__fixtures__/native-section-renderer-cases.ts
@@ -0,0 +1,258 @@
+import type { NativeRenderOut } from '../theme/native-reconstruct-types.js';
+import type { SectionSpec, SectionSpecImage } from '../theme/section-spec.js';
+
+export const NATIVE_SECTION_RENDERER_DERIVATION =
+  'Mechanically generated from DLA src/lib/replicate/page-reconstruct.ts reconstructPagePattern at DLA commit 1e393c5; section renderer markup strips the final reconstruct body newline.';
+
+export interface NativeSectionRendererImpl {
+  renderReviewGrid(section: SectionSpec): NativeRenderOut;
+  renderImageRow(section: SectionSpec): NativeRenderOut;
+}
+
+export interface NativeSectionRendererCase {
+  id: string;
+  section: SectionSpec;
+}
+
+export interface NativeSectionRendererCaseGroups {
+  renderReviewGrid: NativeSectionRendererCase[];
+  renderImageRow: NativeSectionRendererCase[];
+}
+
+export interface NativeSectionRendererOutputCase {
+  id: string;
+  output: unknown;
+}
+
+export interface NativeSectionRendererParityFile {
+  version: 1;
+  derivation: string;
+  renderers: Record<keyof NativeSectionRendererCaseGroups, NativeSectionRendererOutputCase[]>;
+}
+
+const WP = 'http://localhost:8883/wp-content/uploads/2026/05/';
+const CDN = 'https://cdn.example.test/native-section/';
+
+function image(name: string, width = 800, height = 600, alt = name): SectionSpecImage {
+  return {
+    url: `${WP}${name}`,
+    sourceUrl: `${CDN}${name}`,
+    alt,
+    kind: 'img',
+    width,
+    height,
+  };
+}
+
+function section(partial: Partial<SectionSpec> = {}): SectionSpec {
+  return {
+    sectionIndex: 1,
+    interactionModel: 'static',
+    top: 0,
+    height: 480,
+    headings: [],
+    bodyText: [],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 255,
+    backgroundColor: 'rgb(255, 255, 255)',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: { motionClass: 'none', signals: [], animatedElements: 0 },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: {
+      containerWidth: 1100,
+      padding: '0px',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '24px',
+    },
+    ...partial,
+  };
+}
+
+export function nativeSectionRendererCaseGroups(): NativeSectionRendererCaseGroups {
+  const structuredReviews = section({
+    sectionIndex: 41,
+    interactionModel: 'review-grid',
+    height: 520,
+    headings: ['Loved by studio teams', '- mobile duplicate'],
+    headingSizes: [36, 36],
+    headingLineHeights: [1.15, 1.15],
+    textAlign: 'center',
+    reviews: [
+      {
+        category: 'studio',
+        stars: 5,
+        quote: 'The sample wall finally matches how clients actually shop.',
+        author: 'Mara Lee',
+      },
+      {
+        category: 'contractor',
+        stars: 4.6,
+        quote: 'Clean ordering, clear photography, and no extra showroom calls.',
+        author: 'Jules Park',
+      },
+    ],
+    backgroundBrightness: 28,
+    backgroundColor: 'rgb(13, 31, 52)',
+    layout: {
+      containerWidth: 1100,
+      padding: '0px',
+      childLayout: 'grid',
+      columnCount: 2,
+      gap: '28px',
+      padTopPx: 72,
+      padBottomPx: 76,
+    },
+  });
+
+  const bodyTextFallbackReviews = section({
+    sectionIndex: 42,
+    interactionModel: 'review-grid',
+    height: 460,
+    headings: ['Customer notes'],
+    headingSizes: [32],
+    headingLineHeights: [1.18],
+    textAlign: 'center',
+    bodyText: ['4.8 / 5 rating', 'Installers understood the choices before they arrived.', 'Avery Stone'],
+    bodyTextSizes: [15, 18, 14],
+    bodyLineHeights: [1.35, 1.55, 1.35],
+    backgroundBrightness: 244,
+    backgroundColor: 'rgb(239, 248, 245)',
+    layout: {
+      containerWidth: 980,
+      padding: '0px',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '22px',
+      padTopPx: 56,
+      padBottomPx: 58,
+    },
+  });
+
+  const placeholderReviewGap = section({
+    sectionIndex: 43,
+    interactionModel: 'review-grid',
+    height: 360,
+    headings: ['Reviews from homeowners'],
+    headingSizes: [30],
+    headingLineHeights: [1.2],
+    textAlign: 'center',
+    backgroundBrightness: 248,
+    backgroundColor: 'rgb(255, 255, 255)',
+    layout: {
+      containerWidth: 900,
+      padding: '0px',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '20px',
+      padTopPx: 48,
+      padBottomPx: 52,
+    },
+  });
+
+  const imageScroller = section({
+    sectionIndex: 51,
+    interactionModel: 'gallery',
+    height: 246,
+    headings: ['Recent installs'],
+    headingSizes: [34],
+    headingLineHeights: [1.16],
+    textAlign: 'center',
+    bodyText: ['A compact single-row strip keeps mixed aspect ratios intact.'],
+    bodyTextSizes: [17],
+    bodyLineHeights: [1.55],
+    images: [
+      image('install-wide-1.jpg', 900, 420, 'Wide install one'),
+      image('install-wide-2.jpg', 780, 420, 'Wide install two'),
+      image('install-tall.jpg', 360, 540, 'Tall install'),
+      image('install-wide-3.jpg', 640, 360, 'Wide install three'),
+    ],
+    backgroundBrightness: 255,
+    backgroundColor: 'rgb(255, 255, 255)',
+    layout: {
+      containerWidth: 1100,
+      padding: '0px',
+      childLayout: 'grid',
+      columnCount: 4,
+      gap: '16px',
+      padTopPx: 44,
+      padBottomPx: 48,
+    },
+  });
+
+  const imageWrappingGrid = section({
+    sectionIndex: 52,
+    interactionModel: 'color-block-grid',
+    height: 760,
+    headings: ['Finish palette'],
+    headingSizes: [32],
+    headingLineHeights: [1.18],
+    textAlign: 'center',
+    images: [
+      image('finish-oak.jpg', 320, 320, 'Oak finish'),
+      image('finish-walnut.jpg', 320, 320, 'Walnut finish'),
+      image('finish-maple.jpg', 320, 320, 'Maple finish'),
+      image('finish-ash.jpg', 320, 320, 'Ash finish'),
+    ],
+    backgroundBrightness: 232,
+    backgroundColor: 'rgb(232, 239, 241)',
+    layout: {
+      containerWidth: 1100,
+      padding: '0px',
+      childLayout: 'grid',
+      columnCount: 4,
+      gap: '18px',
+      padTopPx: 60,
+      padBottomPx: 64,
+    },
+  });
+
+  return {
+    renderReviewGrid: [
+      { id: 'structured-review-cards-dark-band', section: structuredReviews },
+      { id: 'body-text-fallback-without-structured-reviews', section: bodyTextFallbackReviews },
+      { id: 'placeholder-review-gap', section: placeholderReviewGap },
+    ],
+    renderImageRow: [
+      { id: 'gallery-scroller-mixed-aspect-strip', section: imageScroller },
+      { id: 'color-block-grid-wrapping-gallery', section: imageWrappingGrid },
+    ],
+  };
+}
+
+function clone<T>(value: T): T {
+  if (value === undefined) return value;
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function freeze(value: unknown): unknown {
+  if (value === undefined) return { __type: 'undefined' };
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(freeze);
+  return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, freeze(nested)]));
+}
+
+function capture(id: string, run: () => unknown): NativeSectionRendererOutputCase {
+  return { id, output: freeze(run()) };
+}
+
+export function runNativeSectionRendererParity(impl: NativeSectionRendererImpl): NativeSectionRendererParityFile {
+  const cases = nativeSectionRendererCaseGroups();
+
+  return {
+    version: 1,
+    derivation: NATIVE_SECTION_RENDERER_DERIVATION,
+    renderers: {
+      renderReviewGrid: cases.renderReviewGrid.map((entry) =>
+        capture(entry.id, () => impl.renderReviewGrid(clone(entry.section))),
+      ),
+      renderImageRow: cases.renderImageRow.map((entry) =>
+        capture(entry.id, () => impl.renderImageRow(clone(entry.section))),
+      ),
+    },
+  };
+}
diff --git a/packages/blocks-engine/src/__fixtures__/native-section-renderer-dla-goldens.json b/packages/blocks-engine/src/__fixtures__/native-section-renderer-dla-goldens.json
new file mode 100644
index 00000000..4999cbe2
--- /dev/null
+++ b/packages/blocks-engine/src/__fixtures__/native-section-renderer-dla-goldens.json
@@ -0,0 +1,98 @@
+{
+  "version": 1,
+  "derivation": "Mechanically generated from DLA src/lib/replicate/page-reconstruct.ts reconstructPagePattern at DLA commit 1e393c5; section renderer markup strips the final reconstruct body newline.",
+  "renderers": {
+    "renderReviewGrid": [
+      {
+        "id": "structured-review-cards-dark-band",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"backgroundColor\":\"surface-inverse\",\"textColor\":\"text-inverse\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(32px, 5.00vw, 72px)\",\"bottom\":\"clamp(34px, 5.28vw, 76px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull has-surface-inverse-background-color has-text-inverse-color has-text-color has-background\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(32px, 5.00vw, 72px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(34px, 5.28vw, 76px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(18px, 2.5vw, 36px)\",\"lineHeight\":\"1.15\"}},\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-inverse\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family\" style=\"font-size:clamp(18px, 2.5vw, 36px);line-height:1.15\">Loved by studio teams</h2>\n<!-- /wp:heading -->\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"accent-primary\"} -->\n<p class=\"has-text-align-center has-accent-primary-color has-text-color\">★★★★★</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-inverse\"} -->\n<p class=\"has-text-align-center has-text-inverse-color has-text-color\">The sample wall finally matches how clients actually shop.</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-inverse\",\"fontSize\":\"small\"} -->\n<p class=\"has-text-align-center has-text-inverse-color has-text-color has-small-font-size\">Mara Lee</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"accent-primary\"} -->\n<p class=\"has-text-align-center has-accent-primary-color has-text-color\">★★★★★</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-inverse\"} -->\n<p class=\"has-text-align-center has-text-inverse-color has-text-color\">Clean ordering, clear photography, and no extra showroom calls.</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-inverse\",\"fontSize\":\"small\"} -->\n<p class=\"has-text-align-center has-text-inverse-color has-text-color has-small-font-size\">Jules Park</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Loved by studio teams"
+          ],
+          "bodyText": [
+            "The sample wall finally matches how clients actually shop.",
+            "Mara Lee",
+            "Clean ordering, clear photography, and no extra showroom calls.",
+            "Jules Park"
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "body-text-fallback-without-structured-reviews",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"color\":{\"background\":\"#eff8f5\"},\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(25px, 3.89vw, 56px)\",\"bottom\":\"clamp(26px, 4.03vw, 58px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull has-background\" style=\"margin-top:0;margin-bottom:0;background-color:#eff8f5;padding-top:clamp(25px, 3.89vw, 56px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(26px, 4.03vw, 58px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 2.2vw, 32px)\",\"lineHeight\":\"1.18\"}},\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\" style=\"font-size:clamp(16px, 2.2vw, 32px);line-height:1.18\">Customer notes</h2>\n<!-- /wp:heading -->\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\",\"fontSize\":\"small\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">4.8 / 5 rating</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-default\"} -->\n<p class=\"has-text-align-center has-text-default-color has-text-color\">Installers understood the choices before they arrived.</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-default\"} -->\n<p class=\"has-text-align-center has-text-default-color has-text-color\">Avery Stone</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Customer notes"
+          ],
+          "bodyText": [
+            "4.8 / 5 rating",
+            "Installers understood the choices before they arrived.",
+            "Avery Stone"
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "placeholder-review-gap",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"backgroundColor\":\"surface-raised\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(22px, 3.33vw, 48px)\",\"bottom\":\"clamp(23px, 3.61vw, 52px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull has-surface-raised-background-color has-background\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(22px, 3.33vw, 48px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(23px, 3.61vw, 52px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 2.1vw, 30px)\",\"lineHeight\":\"1.2\"}},\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\" style=\"font-size:clamp(16px, 2.1vw, 30px);line-height:1.2\">Reviews from homeowners</h2>\n<!-- /wp:heading -->\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-subtle\"} -->\n<p class=\"has-text-align-center has-text-subtle-color has-text-color\">[reviews not captured]</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Reviews from homeowners"
+          ],
+          "bodyText": [],
+          "assets": [],
+          "flags": [
+            "review-grid#43: review band detected but no verbatim reviews captured — placeholder emitted"
+          ],
+          "iconAssets": []
+        }
+      }
+    ],
+    "renderImageRow": [
+      {
+        "id": "gallery-scroller-mixed-aspect-strip",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(22px, 3.33vw, 48px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(22px, 3.33vw, 48px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(17px, 2.4vw, 34px)\",\"lineHeight\":\"1.16\"}},\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\" style=\"font-size:clamp(17px, 2.4vw, 34px);line-height:1.16\">Recent installs</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 1.2vw, 17px)\",\"lineHeight\":\"1.55\"}},\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\" style=\"font-size:clamp(16px, 1.2vw, 17px);line-height:1.55\">A compact single-row strip keeps mixed aspect ratios intact.</p>\n<!-- /wp:paragraph -->\n<!-- wp:gallery {\"columns\":4,\"imageCrop\":false,\"linkTo\":\"none\",\"sizeSlug\":\"large\",\"className\":\"is-gallery-scroller\"} -->\n<figure class=\"wp-block-gallery has-nested-images columns-4 is-gallery-scroller\">\n<!-- wp:image {\"width\":\"647px\",\"height\":\"302px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/install-wide-1.jpg\" alt=\"Wide install one\" style=\"width:647px;height:302px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"561px\",\"height\":\"302px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/install-wide-2.jpg\" alt=\"Wide install two\" style=\"width:561px;height:302px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"201px\",\"height\":\"302px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/install-tall.jpg\" alt=\"Tall install\" style=\"width:201px;height:302px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"537px\",\"height\":\"302px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/install-wide-3.jpg\" alt=\"Wide install three\" style=\"width:537px;height:302px\"/></figure>\n<!-- /wp:image -->\n</figure>\n<!-- /wp:gallery -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Recent installs"
+          ],
+          "bodyText": [
+            "A compact single-row strip keeps mixed aspect ratios intact."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/install-wide-1.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/install-wide-2.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/install-tall.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/install-wide-3.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "color-block-grid-wrapping-gallery",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"color\":{\"background\":\"#e8eff1\"},\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(27px, 4.17vw, 60px)\",\"bottom\":\"clamp(29px, 4.44vw, 64px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull has-background\" style=\"margin-top:0;margin-bottom:0;background-color:#e8eff1;padding-top:clamp(27px, 4.17vw, 60px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(29px, 4.44vw, 64px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 2.2vw, 32px)\",\"lineHeight\":\"1.18\"}},\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\" style=\"font-size:clamp(16px, 2.2vw, 32px);line-height:1.18\">Finish palette</h2>\n<!-- /wp:heading -->\n<!-- wp:gallery {\"columns\":4,\"imageCrop\":true,\"linkTo\":\"none\",\"sizeSlug\":\"large\"} -->\n<figure class=\"wp-block-gallery has-nested-images columns-4 is-cropped\">\n<!-- wp:image {\"width\":\"320px\",\"height\":\"320px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/finish-oak.jpg\" alt=\"Oak finish\" style=\"width:320px;height:320px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"320px\",\"height\":\"320px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/finish-walnut.jpg\" alt=\"Walnut finish\" style=\"width:320px;height:320px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"320px\",\"height\":\"320px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/finish-maple.jpg\" alt=\"Maple finish\" style=\"width:320px;height:320px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"320px\",\"height\":\"320px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/finish-ash.jpg\" alt=\"Ash finish\" style=\"width:320px;height:320px\"/></figure>\n<!-- /wp:image -->\n</figure>\n<!-- /wp:gallery -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Finish palette"
+          ],
+          "bodyText": [],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/finish-oak.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/finish-walnut.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/finish-maple.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/finish-ash.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      }
+    ]
+  }
+}
diff --git a/packages/blocks-engine/src/__tests__/theme-native-renderers-section-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-native-renderers-section-parity.test.ts
new file mode 100644
index 00000000..6326514b
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-native-renderers-section-parity.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+
+import expectedGoldens from '../__fixtures__/native-section-renderer-dla-goldens.json' with { type: 'json' };
+import {
+  runNativeSectionRendererParity,
+  type NativeSectionRendererImpl,
+  type NativeSectionRendererParityFile,
+} from '../__fixtures__/native-section-renderer-cases.js';
+import { renderImageRow, renderReviewGrid } from '../theme/native-renderers-section.js';
+
+const EXPECTED_RENDERERS = 2;
+const EXPECTED_CASES = 5;
+
+const engineImpl: NativeSectionRendererImpl = {
+  renderReviewGrid,
+  renderImageRow,
+};
+
+function stableJson(value: unknown): string {
+  return JSON.stringify(value, null, 2);
+}
+
+function rendererCaseCount(file: NativeSectionRendererParityFile): number {
+  return Object.values(file.renderers).reduce((sum, cases) => sum + cases.length, 0);
+}
+
+function collectDiffs(actual: NativeSectionRendererParityFile, expected: NativeSectionRendererParityFile): string[] {
+  const diffs: string[] = [];
+  if (actual.version !== expected.version) diffs.push(`version: expected ${expected.version}, got ${actual.version}`);
+  if (actual.derivation !== expected.derivation) diffs.push('derivation: changed');
+
+  const actualRenderers = Object.keys(actual.renderers).sort();
+  const expectedRenderers = Object.keys(expected.renderers).sort();
+  if (stableJson(actualRenderers) !== stableJson(expectedRenderers)) {
+    diffs.push(`renderer keys: expected ${expectedRenderers.join(',')}, got ${actualRenderers.join(',')}`);
+  }
+
+  for (const renderer of expectedRenderers) {
+    const actualCases = actual.renderers[renderer as keyof NativeSectionRendererParityFile['renderers']];
+    const expectedCases = expected.renderers[renderer as keyof NativeSectionRendererParityFile['renderers']];
+    if (!actualCases) continue;
+    if (stableJson(actualCases) !== stableJson(expectedCases)) {
+      diffs.push(`${renderer}: output changed`);
+    }
+  }
+  return diffs;
+}
+
+describe('native section renderer DLA-today parity', () => {
+  it('matches mechanically derived DLA renderer outputs byte-for-byte and is stable on rerun', () => {
+    const first = runNativeSectionRendererParity(engineImpl);
+    const second = runNativeSectionRendererParity(engineImpl);
+    expect(stableJson(first)).toBe(stableJson(second));
+
+    const expected = expectedGoldens as NativeSectionRendererParityFile;
+    const rendererCount = Object.keys(expected.renderers).length;
+    const caseCount = rendererCaseCount(expected);
+    const diffs = collectDiffs(first, expected);
+    console.info(`native section renderer parity: renderers=${rendererCount} cases=${caseCount} diffs=${diffs.length}`);
+
+    expect(rendererCount).toBe(EXPECTED_RENDERERS);
+    expect(caseCount).toBe(EXPECTED_CASES);
+    expect(diffs).toEqual([]);
+  });
+});
diff --git a/packages/blocks-engine/src/theme/native-renderers-section.ts b/packages/blocks-engine/src/theme/native-renderers-section.ts
index 72505ffb..423b1e84 100644
--- a/packages/blocks-engine/src/theme/native-renderers-section.ts
+++ b/packages/blocks-engine/src/theme/native-renderers-section.ts
@@ -1,13 +1,125 @@
-import { emptyNativeRenderOut } from './native-block-builders.js';
+import { escapeHtml } from '../escape.js';
+import {
+  column,
+  columns,
+  emptyNativeRenderOut,
+  headingBlock,
+  paragraphBlock,
+  wrapSection,
+} from './native-block-builders.js';
+import { centerOf, isDarkSection, isTintedSection, sectionPad } from './native-layout.js';
+import { normalizeCopy } from './page-reconstruct-helpers.js';
+import { galleryBlock } from './native-renderers-text.js';
 import type { NativeRenderOut } from './native-reconstruct-types.js';
-import type { SectionSpec } from './section-spec.js';
+import type { ExtractedReview, SectionSpec } from './section-spec.js';
 
 export function renderReviewGrid(section: SectionSpec): NativeRenderOut {
-  void section;
-  return emptyNativeRenderOut();
+  const out = emptyNativeRenderOut();
+  const dark = isDarkSection(section);
+  const bodyColor = dark ? 'text-inverse' : 'text-default';
+  const mutedColor = dark ? 'text-inverse' : 'text-muted';
+  const reviewP = (text: string, slug: string, small = false): string =>
+    `<!-- wp:paragraph {"align":"center","textColor":"${slug}"${small ? ',"fontSize":"small"' : ''}} -->\n` +
+    `<p class="has-text-align-center has-${slug}-color has-text-color${small ? ' has-small-font-size' : ''}">${escapeHtml(
+      text,
+    )}</p>\n<!-- /wp:paragraph -->`;
+
+  const intro: string[] = [];
+  section.headings
+    .map((heading, originalIndex) => ({ heading, originalIndex }))
+    .filter(({ heading }) => !/^\s*-/.test(heading))
+    .slice(0, 1)
+    .forEach(({ heading, originalIndex }) =>
+      intro.push(
+        headingBlock(heading, out, {
+          level: 2,
+          center: centerOf(section),
+          inverse: dark,
+          sizePx: section.headingSizes?.[originalIndex],
+          fontFamily: section.headingFamilies?.[originalIndex] || undefined,
+          lineHeight: section.headingLineHeights?.[originalIndex],
+        }),
+      ),
+    );
+
+  const reviews: ExtractedReview[] = section.reviews ?? [];
+  const cards: string[] = [];
+  if (reviews.length === 0) {
+    const captured = (section.bodyText ?? []).map((body) => normalizeCopy(body)).filter(Boolean);
+    if (captured.length > 0) {
+      const parts: string[] = [];
+      for (const line of captured) {
+        out.bodyText.push(line);
+        const isRating = /\d(?:\.\d)?\s*\/\s*5|rating|\breviews?\b/i.test(line) && line.length < 60;
+        parts.push(reviewP(line, isRating ? mutedColor : bodyColor, isRating));
+      }
+      cards.push(column(parts.filter(Boolean)));
+    } else {
+      out.flags.push(
+        `review-grid#${section.sectionIndex}: review band detected but no verbatim reviews captured — placeholder emitted`,
+      );
+      cards.push(column([reviewP('[reviews not captured]', dark ? 'text-inverse' : 'text-subtle')]));
+    }
+  } else {
+    for (const review of reviews) {
+      const parts: string[] = [];
+      const starCount = Math.max(0, Math.min(5, Math.round(review.stars || 0)));
+      if (starCount > 0) parts.push(reviewP('★'.repeat(starCount), 'accent-primary'));
+      const quote = normalizeCopy(review.quote);
+      if (quote) {
+        out.bodyText.push(quote);
+        parts.push(reviewP(quote, bodyColor));
+      }
+      if (review.author) {
+        const author = normalizeCopy(review.author);
+        out.bodyText.push(author);
+        parts.push(reviewP(author, mutedColor, true));
+      }
+      cards.push(column(parts.filter(Boolean)));
+    }
+  }
+
+  out.markup = wrapSection([...intro.filter(Boolean), columns(cards)], {
+    wide: '1100px',
+    inverse: dark,
+    raised: !dark,
+    bgColor: section.backgroundColor,
+    ...sectionPad(section),
+  });
+  return out;
 }
 
 export function renderImageRow(section: SectionSpec): NativeRenderOut {
-  void section;
-  return emptyNativeRenderOut();
+  const out = emptyNativeRenderOut();
+  const parts: string[] = [];
+  section.headings.forEach((heading, index) =>
+    parts.push(
+      headingBlock(heading, out, {
+        level: 2,
+        center: centerOf(section),
+        sizePx: section.headingSizes?.[index],
+        fontFamily: section.headingFamilies?.[index] || undefined,
+        lineHeight: section.headingLineHeights?.[index],
+      }),
+    ),
+  );
+  (section.bodyText ?? []).forEach((body, index) =>
+    parts.push(
+      paragraphBlock(body, out, {
+        center: centerOf(section),
+        sizePx: section.bodyTextSizes?.[index],
+        fontFamily: section.bodyFamilies?.[index] || undefined,
+        lineHeight: section.bodyLineHeights?.[index],
+      }),
+    ),
+  );
+  const gallery = galleryBlock(section.images, out, { sectionHeight: section.height });
+  if (gallery) parts.push(gallery);
+  out.markup = wrapSection(parts.filter(Boolean), {
+    wide: '1100px',
+    raised: isTintedSection(section),
+    bgColor: section.backgroundColor,
+    ...sectionPad(section),
+  });
+  return out;
 }

From 0fa82911e83dd4f13eeb18a1daed2c8a9a6a0512 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 19:46:11 -0400
Subject: [PATCH 089/113] feat(theme): freeze native renderer dispatcher
 surface

---
 ...-native-renderers-dispatch-surface.test.ts | 68 +++++++++++++++++++
 .../src/theme/native-renderers-dispatch.ts    | 37 ++++++++++
 .../src/theme/native-renderers-grid.ts        | 44 ++++++++++++
 3 files changed, 149 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-native-renderers-dispatch-surface.test.ts
 create mode 100644 packages/blocks-engine/src/theme/native-renderers-dispatch.ts
 create mode 100644 packages/blocks-engine/src/theme/native-renderers-grid.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-native-renderers-dispatch-surface.test.ts b/packages/blocks-engine/src/__tests__/theme-native-renderers-dispatch-surface.test.ts
new file mode 100644
index 00000000..83a76b84
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-native-renderers-dispatch-surface.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import {
+  FLATTEN_PRONE_MODELS,
+  MEDIA_LAYOUT_DENY,
+  NON_CELL_GRID_MODELS,
+  renderSection,
+} from '../theme/native-renderers-dispatch.js';
+import {
+  cardGroup,
+  renderCardGrid,
+  renderCellGrid,
+  renderFaq,
+  type CardGroupPadding,
+} from '../theme/native-renderers-grid.js';
+import type { NativeRenderCtx, NativeRenderOut } from '../theme/native-reconstruct-types.js';
+import type { InteractionModel, SectionSpec } from '../theme/section-spec.js';
+
+describe('native renderer dispatcher frozen surface', () => {
+  it('freezes the renderer export names and runtime availability', () => {
+    expect({
+      FLATTEN_PRONE_MODELS,
+      MEDIA_LAYOUT_DENY,
+      NON_CELL_GRID_MODELS,
+      cardGroup,
+      renderCardGrid,
+      renderCellGrid,
+      renderFaq,
+      renderSection,
+    }).toEqual(
+      expect.objectContaining({
+        FLATTEN_PRONE_MODELS: expect.any(Set),
+        MEDIA_LAYOUT_DENY: expect.any(Set),
+        NON_CELL_GRID_MODELS: expect.any(Set),
+        cardGroup: expect.any(Function),
+        renderCardGrid: expect.any(Function),
+        renderCellGrid: expect.any(Function),
+        renderFaq: expect.any(Function),
+        renderSection: expect.any(Function),
+      }),
+    );
+  });
+
+  it('freezes the renderer type signatures', () => {
+    expectTypeOf<CardGroupPadding>().toEqualTypeOf<{
+      top: number;
+      right: number;
+      bottom: number;
+      left: number;
+    }>();
+    expectTypeOf(NON_CELL_GRID_MODELS).toEqualTypeOf<ReadonlySet<InteractionModel>>();
+    expectTypeOf(FLATTEN_PRONE_MODELS).toEqualTypeOf<ReadonlySet<InteractionModel>>();
+    expectTypeOf(MEDIA_LAYOUT_DENY).toEqualTypeOf<ReadonlySet<InteractionModel>>();
+    expectTypeOf(renderCardGrid).toEqualTypeOf<
+      (section: SectionSpec, withButtons: boolean) => NativeRenderOut
+    >();
+    expectTypeOf(renderFaq).toEqualTypeOf<(section: SectionSpec) => NativeRenderOut>();
+    expectTypeOf(renderCellGrid).toEqualTypeOf<
+      (section: SectionSpec, ctx: NativeRenderCtx) => NativeRenderOut
+    >();
+    expectTypeOf(cardGroup).toEqualTypeOf<
+      (parts: string[], bgToken: string, dark: boolean, radius: number, padding: CardGroupPadding | null) => string
+    >();
+    expectTypeOf(renderSection).toEqualTypeOf<
+      (section: SectionSpec, ctx: NativeRenderCtx) => NativeRenderOut
+    >();
+  });
+});
diff --git a/packages/blocks-engine/src/theme/native-renderers-dispatch.ts b/packages/blocks-engine/src/theme/native-renderers-dispatch.ts
new file mode 100644
index 00000000..c95c0050
--- /dev/null
+++ b/packages/blocks-engine/src/theme/native-renderers-dispatch.ts
@@ -0,0 +1,37 @@
+import { emptyNativeRenderOut } from './native-block-builders.js';
+import type { NativeRenderCtx, NativeRenderOut } from './native-reconstruct-types.js';
+import type { InteractionModel, SectionSpec } from './section-spec.js';
+
+export const NON_CELL_GRID_MODELS: ReadonlySet<InteractionModel> = new Set([
+  'product-card-row',
+  'project-card-grid',
+  'blog-card-grid',
+  'review-grid',
+  'testimonial',
+]);
+
+export const FLATTEN_PRONE_MODELS: ReadonlySet<InteractionModel> = new Set([
+  'static',
+  'cta',
+  'price-list',
+  'app-download',
+  'horizontal-showcase',
+]);
+
+export const MEDIA_LAYOUT_DENY: ReadonlySet<InteractionModel> = new Set([
+  'gallery',
+  'logo-strip',
+  'color-block-grid',
+  'marquee-strip',
+  'product-card-row',
+  'project-card-grid',
+  'blog-card-grid',
+  'review-grid',
+  'testimonial',
+]);
+
+export function renderSection(section: SectionSpec, ctx: NativeRenderCtx): NativeRenderOut {
+  void section;
+  void ctx;
+  return emptyNativeRenderOut();
+}
diff --git a/packages/blocks-engine/src/theme/native-renderers-grid.ts b/packages/blocks-engine/src/theme/native-renderers-grid.ts
new file mode 100644
index 00000000..27ac9f13
--- /dev/null
+++ b/packages/blocks-engine/src/theme/native-renderers-grid.ts
@@ -0,0 +1,44 @@
+import {
+  emptyNativeRenderOut,
+} from './native-block-builders.js';
+import type { NativeRenderCtx, NativeRenderOut } from './native-reconstruct-types.js';
+import type { SectionSpec } from './section-spec.js';
+
+export interface CardGroupPadding {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export function renderCardGrid(section: SectionSpec, withButtons: boolean): NativeRenderOut {
+  void section;
+  void withButtons;
+  return emptyNativeRenderOut();
+}
+
+export function renderFaq(section: SectionSpec): NativeRenderOut {
+  void section;
+  return emptyNativeRenderOut();
+}
+
+export function renderCellGrid(section: SectionSpec, ctx: NativeRenderCtx): NativeRenderOut {
+  void section;
+  void ctx;
+  return emptyNativeRenderOut();
+}
+
+export function cardGroup(
+  parts: string[],
+  bgToken: string,
+  dark: boolean,
+  radius: number,
+  padding: CardGroupPadding | null,
+): string {
+  void parts;
+  void bgToken;
+  void dark;
+  void radius;
+  void padding;
+  return '';
+}

From 85ea74e700c44e7364828ebe5ecc0de39d31d3db Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 19:53:25 -0400
Subject: [PATCH 090/113] feat(theme): port native renderer dispatcher

---
 ...pture-native-dispatch-renderer-goldens.mjs | 234 +++++++
 .../native-dispatch-renderer-cases.ts         | 600 ++++++++++++++++
 .../native-dispatch-renderer-dla-goldens.json | 648 ++++++++++++++++++
 ...e-native-renderers-dispatch-parity.test.ts | 135 ++++
 .../src/theme/native-renderers-dispatch.ts    | 122 +++-
 .../src/theme/native-renderers-grid.ts        | 225 +++++-
 6 files changed, 1945 insertions(+), 19 deletions(-)
 create mode 100644 packages/blocks-engine/scripts/capture-native-dispatch-renderer-goldens.mjs
 create mode 100644 packages/blocks-engine/src/__fixtures__/native-dispatch-renderer-cases.ts
 create mode 100644 packages/blocks-engine/src/__fixtures__/native-dispatch-renderer-dla-goldens.json
 create mode 100644 packages/blocks-engine/src/__tests__/theme-native-renderers-dispatch-parity.test.ts

diff --git a/packages/blocks-engine/scripts/capture-native-dispatch-renderer-goldens.mjs b/packages/blocks-engine/scripts/capture-native-dispatch-renderer-goldens.mjs
new file mode 100644
index 00000000..a1cf787e
--- /dev/null
+++ b/packages/blocks-engine/scripts/capture-native-dispatch-renderer-goldens.mjs
@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+import { execFileSync, spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const DLA_COMMIT = '1e393c535850ee1a9482f83459f779d0e225b027';
+const DEFAULT_DLA_ROOT = '/Users/matt/projects/a8c/data-liberation-agent';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+const fixtureUrl = pathToFileURL(path.join(packageRoot, 'src/__fixtures__/native-dispatch-renderer-cases.ts')).href;
+const outputPath = path.join(packageRoot, 'src/__fixtures__/native-dispatch-renderer-dla-goldens.json');
+const TSX_BOOTSTRAP_ENV = 'BLOCKS_ENGINE_NATIVE_DISPATCH_GOLDENS_TSX';
+
+function hasTsxLoader() {
+  return process.execArgv.some((arg, index, argv) => {
+    if (arg === '--import') return argv[index + 1]?.includes('tsx');
+    return arg.startsWith('--import=') && arg.includes('tsx');
+  });
+}
+
+if (!process.env[TSX_BOOTSTRAP_ENV] && !hasTsxLoader()) {
+  const result = spawnSync(process.execPath, ['--import', 'tsx', fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+    cwd: packageRoot,
+    env: { ...process.env, [TSX_BOOTSTRAP_ENV]: '1' },
+    stdio: 'inherit',
+  });
+  if (result.error) throw result.error;
+  process.exit(result.status ?? 1);
+}
+
+const args = new Set(process.argv.slice(2));
+const shouldWrite = args.has('--write');
+const shouldCheck = args.has('--check');
+const shouldStdout = args.has('--stdout') || (!shouldWrite && !shouldCheck);
+const dlaRoot = process.env.DLA_ROOT || DEFAULT_DLA_ROOT;
+
+function git(args) {
+  return execFileSync('git', ['-C', dlaRoot, ...args], { encoding: 'utf8' }).trim();
+}
+
+function stableJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function clone(value) {
+  if (value === undefined) return value;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function stripFinalBodyNewline(markup) {
+  return markup.endsWith('\n') ? markup.slice(0, -1) : markup;
+}
+
+function capture(id, output) {
+  return { id, output };
+}
+
+function normalizeCopy(value) {
+  return String(value ?? '')
+    .replace(/­/g, '')
+    .replace(/[​-‍]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function reconstructOptions() {
+  return {
+    patternSlug: 'native-dispatch-renderer-parity/single-section',
+    title: 'Native Dispatch Renderer Parity',
+    paletteTokens: [
+      { slug: 'text-default', hex: '#102030' },
+      { slug: 'text-inverse', hex: '#f8fafc' },
+      { slug: 'text-muted', hex: '#4b5563' },
+      { slug: 'text-subtle', hex: '#6b7280' },
+      { slug: 'accent-primary', hex: '#008060' },
+      { slug: 'surface-base', hex: '#ffffff' },
+      { slug: 'surface-raised', hex: '#e8eff1' },
+      { slug: 'surface-inverse', hex: '#111827' },
+    ],
+    fontFamilies: [
+      { slug: 'display', family: 'Caldera Display, serif' },
+      { slug: 'body', family: 'Caldera, sans-serif' },
+    ],
+    sourceUrl: 'https://example.test/native-dispatch-renderer-parity',
+    slug: 'native-dispatch-renderer-parity',
+  };
+}
+
+function renderOutFromResult(result) {
+  if (result.sectionsRendered !== 1) {
+    throw new Error(`Expected exactly one rendered section, got ${result.sectionsRendered}`);
+  }
+  if (result.fallbackDiagnostics.length > 0) {
+    throw new Error(`Expected native renderer output, got fallback diagnostics: ${JSON.stringify(result.fallbackDiagnostics)}`);
+  }
+  return {
+    markup: stripFinalBodyNewline(result.body),
+    expectedText: result.expectedText,
+    bodyText: result.bodyText,
+    assets: result.expectedAssets,
+    flags: result.provenanceFlags,
+    iconAssets: result.iconAssets,
+  };
+}
+
+function sentinelSection(sectionIndex, label) {
+  return {
+    sectionIndex,
+    interactionModel: 'static',
+    top: sectionIndex * 100,
+    height: 360,
+    headings: [`${label} sentinel heading`],
+    bodyText: [`${label} sentinel body`],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 255,
+    backgroundColor: 'rgb(255, 255, 255)',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: { motionClass: 'none', signals: [], animatedElements: 0 },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: { containerWidth: 900, padding: '0px', childLayout: 'stack', columnCount: 1, gap: '20px' },
+  };
+}
+
+function extractSectionGroup(markup, marker) {
+  const groups = markup.match(/<!-- wp:group \{"tagName":"section"[\s\S]*?<\/section>\n<!-- \/wp:group -->/g) ?? [];
+  const found = groups.find((group) => group.includes(marker));
+  if (!found) throw new Error(`Could not find sandwiched section group containing ${marker}`);
+  return found;
+}
+
+function countFilter(values, wanted) {
+  const budget = new Map();
+  for (const value of wanted.map(normalizeCopy).filter(Boolean)) {
+    budget.set(value, (budget.get(value) ?? 0) + 1);
+  }
+  const out = [];
+  for (const value of values) {
+    const key = normalizeCopy(value);
+    const left = budget.get(key) ?? 0;
+    if (left > 0) {
+      out.push(value);
+      budget.set(key, left - 1);
+    }
+  }
+  return out;
+}
+
+function sandwichedRenderOut(section, result) {
+  if (result.sectionsRendered !== 3) {
+    throw new Error(`Expected three rendered sections for chrome-sandwich case, got ${result.sectionsRendered}`);
+  }
+  if (result.fallbackDiagnostics.length > 0) {
+    throw new Error(`Expected native renderer output, got fallback diagnostics: ${JSON.stringify(result.fallbackDiagnostics)}`);
+  }
+  const marker = section.headings[0] || section.bodyText[0] || String(section.sectionIndex);
+  return {
+    markup: extractSectionGroup(stripFinalBodyNewline(result.body), marker),
+    expectedText: countFilter(result.expectedText, [...section.headings, ...(section.buttonLabels ?? [])]),
+    bodyText: countFilter(result.bodyText, section.bodyText ?? []),
+    assets: countFilter(result.expectedAssets, (section.images ?? []).map((image) => image.url)),
+    flags: result.provenanceFlags.filter((flag) => flag.includes(`#${section.sectionIndex}`)),
+    iconAssets: result.iconAssets.filter((asset) => asset.path.includes(`icon-${section.sectionIndex}`)),
+  };
+}
+
+function extractCardGroup(markup) {
+  const match = /<!-- wp:group \{"className":"is-replica-card"[\s\S]*?<!-- \/wp:group -->/.exec(markup);
+  if (!match) throw new Error('Could not extract is-replica-card group from DLA output');
+  return match[0];
+}
+
+const currentCommit = git(['rev-parse', 'HEAD']);
+if (currentCommit !== DLA_COMMIT) {
+  throw new Error(`DLA checkout must be at ${DLA_COMMIT}; got ${currentCommit}`);
+}
+
+const dirty = git(['status', '--porcelain']);
+if (dirty) {
+  throw new Error(`DLA checkout must be clean at ${DLA_COMMIT}; status:\n${dirty}`);
+}
+
+const { nativeDispatchRendererCaseGroups, NATIVE_DISPATCH_RENDERER_DERIVATION } = await import(fixtureUrl);
+const { reconstructPagePattern } = await import(
+  pathToFileURL(path.join(dlaRoot, 'src/lib/replicate/page-reconstruct.ts')).href
+);
+
+const cases = nativeDispatchRendererCaseGroups();
+const renderSectionCase = (entry) => {
+  const section = clone(entry.section);
+  if (entry.chromeSandwich) {
+    const result = reconstructPagePattern(
+      [sentinelSection(9001, 'before'), section, sentinelSection(9002, 'after')],
+      reconstructOptions(),
+    );
+    return capture(entry.id, sandwichedRenderOut(section, result));
+  }
+  return capture(entry.id, renderOutFromResult(reconstructPagePattern([section], reconstructOptions())));
+};
+const renderCardGroupCase = (entry) => {
+  const result = reconstructPagePattern([clone(entry.dlaSection)], reconstructOptions());
+  return capture(entry.id, {
+    returnValue: extractCardGroup(stripFinalBodyNewline(result.body)),
+  });
+};
+
+const parityFile = {
+  version: 1,
+  derivation: NATIVE_DISPATCH_RENDERER_DERIVATION,
+  renderers: {
+    renderCardGrid: cases.renderCardGrid.map(renderSectionCase),
+    renderFaq: cases.renderFaq.map(renderSectionCase),
+    renderCellGrid: cases.renderCellGrid.map(renderSectionCase),
+    cardGroup: cases.cardGroup.map(renderCardGroupCase),
+    renderSection: cases.renderSection.map(renderSectionCase),
+  },
+};
+
+const json = stableJson(parityFile);
+
+if (shouldCheck) {
+  const existing = readFileSync(outputPath, 'utf8');
+  if (existing !== json) {
+    throw new Error(`${outputPath} is out of date with DLA ${DLA_COMMIT}`);
+  }
+}
+
+if (shouldWrite) writeFileSync(outputPath, json);
+if (shouldStdout) process.stdout.write(json);
diff --git a/packages/blocks-engine/src/__fixtures__/native-dispatch-renderer-cases.ts b/packages/blocks-engine/src/__fixtures__/native-dispatch-renderer-cases.ts
new file mode 100644
index 00000000..32a0cc4d
--- /dev/null
+++ b/packages/blocks-engine/src/__fixtures__/native-dispatch-renderer-cases.ts
@@ -0,0 +1,600 @@
+import type { NativeRenderCtx, NativeRenderOut } from '../theme/native-reconstruct-types.js';
+import type {
+  InteractionModel,
+  SectionSpec,
+  SectionSpecCell,
+  SectionSpecIcon,
+  SectionSpecImage,
+} from '../theme/section-spec.js';
+import type { CardGroupPadding } from '../theme/native-renderers-grid.js';
+
+export const NATIVE_DISPATCH_RENDERER_DERIVATION =
+  'Mechanically generated from DLA src/lib/replicate/page-reconstruct.ts reconstructPagePattern at DLA commit 1e393c5; renderer markup strips the final reconstruct body newline, and footer/nav renderSection cases are sandwiched between non-chrome sentinels so DLA stripChrome does not remove them before dispatch.';
+
+export const ALL_RENDER_SECTION_INTERACTION_MODELS: InteractionModel[] = [
+  'static',
+  'cover-with-headline',
+  'animated-cover',
+  'media-text',
+  'columns',
+  'gallery',
+  'logo-strip',
+  'testimonial',
+  'cta',
+  'blog-card-grid',
+  'project-card-grid',
+  'price-list',
+  'product-card-row',
+  'review-grid',
+  'app-download',
+  'color-block-grid',
+  'marquee-strip',
+  'horizontal-showcase',
+  'footer',
+  'nav',
+];
+
+export type DispatchRendererName =
+  | 'renderTextBand'
+  | 'renderCover'
+  | 'renderMediaText'
+  | 'renderCardGrid'
+  | 'renderReviewGrid'
+  | 'renderImageRow'
+  | 'renderFaq'
+  | 'renderCellGrid';
+
+export interface NativeDispatchRendererImpl {
+  renderCardGrid(section: SectionSpec, withButtons: boolean): NativeRenderOut;
+  renderFaq(section: SectionSpec): NativeRenderOut;
+  renderCellGrid(section: SectionSpec, ctx: NativeRenderCtx): NativeRenderOut;
+  cardGroup(parts: string[], bgToken: string, dark: boolean, radius: number, padding: CardGroupPadding | null): string;
+  renderSection(section: SectionSpec, ctx: NativeRenderCtx): NativeRenderOut;
+}
+
+export interface NativeRendererSectionCase {
+  id: string;
+  section: SectionSpec;
+}
+
+export interface NativeCardGridRendererCase extends NativeRendererSectionCase {
+  withButtons: boolean;
+}
+
+export interface NativeCardGroupRendererCase {
+  id: string;
+  parts: string[];
+  bgToken: string;
+  dark: boolean;
+  radius: number;
+  padding: CardGroupPadding | null;
+  dlaSection: SectionSpec;
+}
+
+export interface NativeRenderSectionCase extends NativeRendererSectionCase {
+  expectedRenderer: DispatchRendererName;
+  expectedFlip?: boolean;
+  chromeSandwich?: boolean;
+}
+
+export interface NativeDispatchRendererCaseGroups {
+  renderCardGrid: NativeCardGridRendererCase[];
+  renderFaq: NativeRendererSectionCase[];
+  renderCellGrid: NativeRendererSectionCase[];
+  cardGroup: NativeCardGroupRendererCase[];
+  renderSection: NativeRenderSectionCase[];
+}
+
+export interface NativeDispatchRendererOutputCase {
+  id: string;
+  output: unknown;
+}
+
+export interface NativeDispatchRendererParityFile {
+  version: 1;
+  derivation: string;
+  renderers: Record<keyof NativeDispatchRendererCaseGroups, NativeDispatchRendererOutputCase[]>;
+}
+
+const WP = 'http://localhost:8883/wp-content/uploads/2026/05/';
+const CDN = 'https://cdn.example.test/native-dispatch/';
+
+export function nativeDispatchRenderCtx(): NativeRenderCtx {
+  return {
+    mediaTextIndex: 0,
+    iconCounter: 0,
+    paletteTokens: [
+      { slug: 'text-default', hex: '#102030' },
+      { slug: 'text-inverse', hex: '#f8fafc' },
+      { slug: 'text-muted', hex: '#4b5563' },
+      { slug: 'text-subtle', hex: '#6b7280' },
+      { slug: 'accent-primary', hex: '#008060' },
+      { slug: 'surface-base', hex: '#ffffff' },
+      { slug: 'surface-raised', hex: '#e8eff1' },
+      { slug: 'surface-inverse', hex: '#111827' },
+    ],
+    fontFamilies: [
+      { slug: 'display', family: 'Caldera Display, serif' },
+      { slug: 'body', family: 'Caldera, sans-serif' },
+    ],
+  };
+}
+
+function image(name: string, width = 800, height = 600, alt = name): SectionSpecImage {
+  return {
+    url: `${WP}${name}`,
+    sourceUrl: `${CDN}${name}`,
+    alt,
+    kind: 'img',
+    width,
+    height,
+  };
+}
+
+function backgroundImage(name: string, width = 1440, height = 900, alt = name): SectionSpecImage {
+  return {
+    ...image(name, width, height, alt),
+    kind: 'background',
+  };
+}
+
+function icon(markup = '<svg viewBox="0 0 20 20"><path d="M2 10h16v2H2z"/></svg>'): SectionSpecIcon {
+  return {
+    kind: 'svg',
+    markup,
+    width: 20,
+    height: 20,
+  };
+}
+
+function cell(partial: Partial<SectionSpecCell>): SectionSpecCell {
+  return {
+    heading: null,
+    body: [],
+    image: null,
+    icon: null,
+    button: null,
+    ...partial,
+  };
+}
+
+function section(partial: Partial<SectionSpec> = {}): SectionSpec {
+  return {
+    sectionIndex: 1,
+    interactionModel: 'static',
+    top: 0,
+    height: 480,
+    headings: [],
+    bodyText: [],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 255,
+    backgroundColor: 'rgb(255, 255, 255)',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: { motionClass: 'none', signals: [], animatedElements: 0 },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: {
+      containerWidth: 1100,
+      padding: '0px',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '24px',
+    },
+    ...partial,
+  };
+}
+
+function basicSection(index: number, interactionModel: InteractionModel, label: string): SectionSpec {
+  return section({
+    sectionIndex: index,
+    interactionModel,
+    headings: [`${label} headline`],
+    bodyText: [`${label} body copy`],
+    buttonLabels: [`${label} action`],
+    height: 420,
+    layout: {
+      containerWidth: 1000,
+      padding: '0px',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '24px',
+      padTopPx: 44,
+      padBottomPx: 46,
+    },
+  });
+}
+
+const cardIntro = section({
+  sectionIndex: 61,
+  interactionModel: 'product-card-row',
+  headings: ['Sleep essentials'],
+  bodyText: ['Choose the pieces that fit your room.'],
+  buttonLabels: ['Shop bundle', 'Shop lamp'],
+  images: [image('bundle.jpg', 640, 420, 'Bundle'), image('lamp.jpg', 620, 420, 'Lamp')],
+  layout: { containerWidth: 1120, padding: '0px', childLayout: 'grid', columnCount: 2, gap: '24px' },
+});
+
+const projectCards = section({
+  sectionIndex: 62,
+  interactionModel: 'project-card-grid',
+  headings: ['Cabin refresh', 'Studio wall'],
+  bodyText: ['Warm oak across the room.', 'A quiet wall for display.'],
+  images: [image('cabin.jpg', 600, 430, 'Cabin'), image('studio.jpg', 610, 430, 'Studio')],
+  layout: { containerWidth: 1120, padding: '0px', childLayout: 'grid', columnCount: 2, gap: '24px' },
+});
+
+const faqComplete = section({
+  sectionIndex: 63,
+  interactionModel: 'static',
+  headings: ['Frequently Asked Questions'],
+  faqs: [
+    { question: 'Can I install it myself?', answer: 'Yes, the kit includes a measured guide.' },
+    { question: 'How fast does it ship?', answer: 'Most orders leave the studio in two days.' },
+  ],
+  layout: { containerWidth: 760, padding: '0px', childLayout: 'stack', columnCount: 1, gap: '18px' },
+});
+
+const faqMissingAnswer = section({
+  sectionIndex: 64,
+  interactionModel: 'cta',
+  headings: ['Questions before ordering'],
+  faqs: [{ question: 'Is commercial pricing available?', answer: '' }],
+  backgroundBrightness: 238,
+  backgroundColor: 'rgb(232, 239, 241)',
+});
+
+const styledCells = section({
+  sectionIndex: 65,
+  interactionModel: 'static',
+  headings: ['Three bedtime essentials.'],
+  cells: [
+    cell({
+      heading: 'Quiet motor',
+      body: ['A low-hum motor keeps the room calm.'],
+      icon: icon(),
+      background: 'rgb(17, 24, 39)',
+      radius: 24,
+      padding: { top: 24, right: 32, bottom: 28, left: 32 },
+      headingSize: 28,
+      headingLineHeight: 1.15,
+      bodyLineHeight: 1.45,
+      align: 'center',
+      iconAlign: 'center',
+    }),
+    cell({
+      heading: 'Warm light',
+      body: ['A dimmable surface light replaces harsh lamps.'],
+      image: image('warm-light.jpg', 360, 260, 'Warm light'),
+      background: 'rgb(232, 239, 241)',
+      radius: 12,
+      padding: { top: 20, right: 24, bottom: 20, left: 24 },
+      headingSize: 24,
+      headingLineHeight: 1.18,
+      bodyLineHeight: 1.45,
+      align: 'left',
+      iconAlign: 'left',
+    }),
+  ],
+  layout: { containerWidth: 1100, padding: '0px', childLayout: 'grid', columnCount: 2, gap: '28px' },
+});
+
+const cellWithSectionImage = section({
+  sectionIndex: 66,
+  interactionModel: 'price-list',
+  headings: ['Compare the setups'],
+  cells: [
+    cell({ heading: 'Starter', body: ['A simple bedside setup.'] }),
+    cell({ heading: 'Studio', body: ['A deeper package with samples.'] }),
+  ],
+  images: [image('comparison-photo.jpg', 480, 320, 'Comparison photo')],
+  layout: { containerWidth: 1100, padding: '0px', childLayout: 'grid', columnCount: 3, gap: '24px' },
+});
+
+const fullBleedCells = section({
+  sectionIndex: 67,
+  interactionModel: 'horizontal-showcase',
+  cells: [
+    cell({ heading: 'Left edge', body: ['The first card reaches the viewport edge.'] }),
+    cell({ heading: 'Right edge', body: ['The last card follows the source rail.'] }),
+  ],
+  layout: { containerWidth: 1440, padding: '0px', childLayout: 'grid', columnCount: 2, gap: '0px' },
+});
+
+const cardGroupDlaSection = section({
+  sectionIndex: 68,
+  interactionModel: 'static',
+  cells: [
+    cell({
+      heading: 'Quiet card',
+      body: ['Padded copy'],
+      background: 'rgb(17, 24, 39)',
+      radius: 24,
+      padding: { top: 24, right: 32, bottom: 28, left: 32 },
+      headingSize: 28,
+      headingLineHeight: 1.15,
+      bodyLineHeight: 1.45,
+      align: 'center',
+    }),
+    cell({ heading: 'Second card', body: ['Keeps the cell-grid route active.'] }),
+  ],
+  layout: { containerWidth: 1100, padding: '0px', childLayout: 'grid', columnCount: 2, gap: '24px' },
+});
+
+const cardGroupParts = [
+  '<!-- wp:heading {"textAlign":"center","style":{"typography":{"fontSize":"clamp(16px, 1.9vw, 28px)","lineHeight":"1.15"}},"level":3,"fontFamily":"display","textColor":"text-inverse"} -->\n<h3 class="wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family" style="font-size:clamp(16px, 1.9vw, 28px);line-height:1.15">Quiet card</h3>\n<!-- /wp:heading -->',
+  '<!-- wp:paragraph {"align":"center","style":{"typography":{"lineHeight":"1.45"}},"fontSize":"small","textColor":"text-inverse"} -->\n<p class="has-text-align-center has-text-inverse-color has-text-color has-small-font-size" style="line-height:1.45">Padded copy</p>\n<!-- /wp:paragraph -->',
+];
+
+function renderSectionCases(): NativeRenderSectionCase[] {
+  const cases: NativeRenderSectionCase[] = [
+    {
+      id: 'faq-override-before-model-switch',
+      section: faqComplete,
+      expectedRenderer: 'renderFaq',
+    },
+    {
+      id: 'cell-grid-override-for-flatten-prone-model',
+      section: styledCells,
+      expectedRenderer: 'renderCellGrid',
+    },
+    {
+      id: 'media-layout-override-image-left',
+      section: section({
+        sectionIndex: 81,
+        interactionModel: 'static',
+        mediaLayout: 'image-left',
+        headings: ['Image-led story row'],
+        bodyText: ['The source puts media before the copy.'],
+        images: [image('story.jpg', 640, 520, 'Story')],
+        layout: { containerWidth: 1100, padding: '0px', childLayout: 'flex-row', columnCount: 2, gap: '32px' },
+      }),
+      expectedRenderer: 'renderMediaText',
+      expectedFlip: true,
+    },
+    {
+      id: 'columns-single-image-media-text',
+      section: section({
+        sectionIndex: 82,
+        interactionModel: 'columns',
+        headings: ['Columns become media text'],
+        bodyText: ['One image and copy is a two-up row.'],
+        images: [image('columns.jpg', 640, 480, 'Columns')],
+        layout: { containerWidth: 1100, padding: '0px', childLayout: 'flex-row', columnCount: 2, gap: '28px' },
+      }),
+      expectedRenderer: 'renderMediaText',
+      expectedFlip: false,
+    },
+    {
+      id: 'columns-without-image-text-band',
+      section: basicSection(83, 'columns', 'Columns default'),
+      expectedRenderer: 'renderTextBand',
+    },
+    {
+      id: 'cover-full-bleed-wide-image',
+      section: section({
+        sectionIndex: 84,
+        interactionModel: 'cover-with-headline',
+        fullBleed: true,
+        height: 720,
+        headings: ['Cover headline'],
+        bodyText: ['Copy sits over the captured background image.'],
+        images: [backgroundImage('cover-wide.jpg', 1440, 900, 'Cover')],
+        backgroundBrightness: 32,
+        backgroundColor: 'rgb(16, 32, 48)',
+      }),
+      expectedRenderer: 'renderCover',
+    },
+    {
+      id: 'cover-non-full-bleed-media-text',
+      section: section({
+        sectionIndex: 85,
+        interactionModel: 'cover-with-headline',
+        fullBleed: false,
+        headings: ['Cover falls to media text'],
+        bodyText: ['A contained photo belongs beside the copy.'],
+        images: [image('cover-contained.jpg', 640, 520, 'Contained cover')],
+      }),
+      expectedRenderer: 'renderMediaText',
+      expectedFlip: false,
+    },
+    {
+      id: 'cover-without-image-text-band',
+      section: basicSection(86, 'cover-with-headline', 'Cover text'),
+      expectedRenderer: 'renderTextBand',
+    },
+    {
+      id: 'animated-cover-wide-image',
+      section: section({
+        sectionIndex: 87,
+        interactionModel: 'animated-cover',
+        height: 680,
+        headings: ['Animated cover'],
+        bodyText: ['Wide media uses the cover renderer.'],
+        images: [backgroundImage('animated-wide.jpg', 1320, 820, 'Animated')],
+        backgroundBrightness: 40,
+        backgroundColor: 'rgb(18, 28, 42)',
+      }),
+      expectedRenderer: 'renderCover',
+    },
+    {
+      id: 'animated-cover-contained-media-text',
+      section: section({
+        sectionIndex: 88,
+        interactionModel: 'animated-cover',
+        headings: ['Animated contained'],
+        bodyText: ['A smaller captured photo uses media text.'],
+        images: [image('animated-contained.jpg', 620, 480, 'Contained')],
+      }),
+      expectedRenderer: 'renderMediaText',
+      expectedFlip: false,
+    },
+    {
+      id: 'animated-cover-without-image-text-band',
+      section: basicSection(89, 'animated-cover', 'Animated text'),
+      expectedRenderer: 'renderTextBand',
+    },
+    {
+      id: 'media-text-model',
+      section: section({
+        sectionIndex: 90,
+        interactionModel: 'media-text',
+        headings: ['Media text section'],
+        bodyText: ['The explicit model uses media-text.'],
+        images: [image('media-text.jpg', 640, 480, 'Media')],
+      }),
+      expectedRenderer: 'renderMediaText',
+      expectedFlip: false,
+    },
+    { id: 'product-card-row-model', section: cardIntro, expectedRenderer: 'renderCardGrid' },
+    { id: 'project-card-grid-model', section: projectCards, expectedRenderer: 'renderCardGrid' },
+    {
+      id: 'blog-card-grid-model',
+      section: { ...projectCards, sectionIndex: 91, interactionModel: 'blog-card-grid' },
+      expectedRenderer: 'renderCardGrid',
+    },
+    {
+      id: 'review-grid-model',
+      section: {
+        ...basicSection(92, 'review-grid', 'Review grid'),
+        reviews: [{ category: null, stars: 5, quote: 'The review copy stays verbatim.', author: 'Lee' }],
+      },
+      expectedRenderer: 'renderReviewGrid',
+    },
+    {
+      id: 'testimonial-model',
+      section: {
+        ...basicSection(93, 'testimonial', 'Testimonial'),
+        reviews: [{ category: null, stars: 4.8, quote: 'A compact testimonial quote.', author: 'Avery' }],
+      },
+      expectedRenderer: 'renderReviewGrid',
+    },
+    {
+      id: 'gallery-model',
+      section: {
+        ...basicSection(94, 'gallery', 'Gallery'),
+        images: [image('gallery-1.jpg', 520, 360), image('gallery-2.jpg', 520, 360), image('gallery-3.jpg', 520, 360)],
+      },
+      expectedRenderer: 'renderImageRow',
+    },
+    {
+      id: 'logo-strip-model',
+      section: {
+        ...basicSection(95, 'logo-strip', 'Logo strip'),
+        images: [image('logo-1.png', 240, 120), image('logo-2.png', 240, 120), image('logo-3.png', 240, 120)],
+      },
+      expectedRenderer: 'renderImageRow',
+    },
+    {
+      id: 'color-block-grid-model',
+      section: {
+        ...basicSection(96, 'color-block-grid', 'Color grid'),
+        images: [image('color-1.jpg', 320, 320), image('color-2.jpg', 320, 320), image('color-3.jpg', 320, 320)],
+      },
+      expectedRenderer: 'renderImageRow',
+    },
+    {
+      id: 'marquee-strip-model',
+      section: {
+        ...basicSection(97, 'marquee-strip', 'Marquee strip'),
+        images: [image('marquee-1.jpg', 520, 300), image('marquee-2.jpg', 520, 300), image('marquee-3.jpg', 520, 300)],
+      },
+      expectedRenderer: 'renderImageRow',
+    },
+  ];
+
+  const defaultTextModels: InteractionModel[] = [
+    'static',
+    'cta',
+    'price-list',
+    'app-download',
+    'horizontal-showcase',
+    'footer',
+    'nav',
+  ];
+  for (const model of defaultTextModels) {
+    const chromeSandwich = model === 'footer' || model === 'nav';
+    cases.push({
+      id: `${model}-default-text-band`,
+      section: basicSection(100 + cases.length, model, model),
+      expectedRenderer: 'renderTextBand',
+      chromeSandwich,
+    });
+  }
+
+  return cases;
+}
+
+export function nativeDispatchRendererCaseGroups(): NativeDispatchRendererCaseGroups {
+  return {
+    renderCardGrid: [
+      { id: 'product-card-row-with-buttons', section: cardIntro, withButtons: true },
+      { id: 'project-card-grid-without-buttons', section: projectCards, withButtons: false },
+    ],
+    renderFaq: [
+      { id: 'faq-complete-answers', section: faqComplete },
+      { id: 'faq-missing-answer-placeholder', section: faqMissingAnswer },
+    ],
+    renderCellGrid: [
+      { id: 'styled-cell-grid-with-icon-and-card', section: styledCells },
+      { id: 'cell-grid-recovers-section-image-column', section: cellWithSectionImage },
+      { id: 'full-bleed-cell-grid', section: fullBleedCells },
+    ],
+    cardGroup: [
+      {
+        id: 'dark-card-group-with-captured-padding',
+        parts: cardGroupParts,
+        bgToken: 'surface-inverse',
+        dark: true,
+        radius: 24,
+        padding: { top: 24, right: 32, bottom: 28, left: 32 },
+        dlaSection: cardGroupDlaSection,
+      },
+    ],
+    renderSection: renderSectionCases(),
+  };
+}
+
+function clone<T>(value: T): T {
+  if (value === undefined) return value;
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function freeze(value: unknown): unknown {
+  if (value === undefined) return { __type: 'undefined' };
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(freeze);
+  return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, freeze(nested)]));
+}
+
+function capture(id: string, run: () => unknown): NativeDispatchRendererOutputCase {
+  return { id, output: freeze(run()) };
+}
+
+export function runNativeDispatchRendererParity(impl: NativeDispatchRendererImpl): NativeDispatchRendererParityFile {
+  const cases = nativeDispatchRendererCaseGroups();
+
+  return {
+    version: 1,
+    derivation: NATIVE_DISPATCH_RENDERER_DERIVATION,
+    renderers: {
+      renderCardGrid: cases.renderCardGrid.map((entry) =>
+        capture(entry.id, () => impl.renderCardGrid(clone(entry.section), entry.withButtons)),
+      ),
+      renderFaq: cases.renderFaq.map((entry) => capture(entry.id, () => impl.renderFaq(clone(entry.section)))),
+      renderCellGrid: cases.renderCellGrid.map((entry) =>
+        capture(entry.id, () => impl.renderCellGrid(clone(entry.section), nativeDispatchRenderCtx())),
+      ),
+      cardGroup: cases.cardGroup.map((entry) =>
+        capture(entry.id, () => ({
+          returnValue: impl.cardGroup(clone(entry.parts), entry.bgToken, entry.dark, entry.radius, clone(entry.padding)),
+        })),
+      ),
+      renderSection: cases.renderSection.map((entry) =>
+        capture(entry.id, () => impl.renderSection(clone(entry.section), nativeDispatchRenderCtx())),
+      ),
+    },
+  };
+}
diff --git a/packages/blocks-engine/src/__fixtures__/native-dispatch-renderer-dla-goldens.json b/packages/blocks-engine/src/__fixtures__/native-dispatch-renderer-dla-goldens.json
new file mode 100644
index 00000000..7b472270
--- /dev/null
+++ b/packages/blocks-engine/src/__fixtures__/native-dispatch-renderer-dla-goldens.json
@@ -0,0 +1,648 @@
+{
+  "version": 1,
+  "derivation": "Mechanically generated from DLA src/lib/replicate/page-reconstruct.ts reconstructPagePattern at DLA commit 1e393c5; renderer markup strips the final reconstruct body newline, and footer/nav renderSection cases are sandwiched between non-chrome sentinels so DLA stripChrome does not remove them before dispatch.",
+  "renderers": {
+    "renderCardGrid": [
+      {
+        "id": "product-card-row-with-buttons",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"640px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/bundle.jpg\" alt=\"Bundle\" style=\"width:640px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Sleep essentials</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Choose the pieces that fit your room.</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Shop bundle</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"620px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/lamp.jpg\" alt=\"Lamp\" style=\"width:620px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Shop lamp</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Sleep essentials",
+            "Shop bundle",
+            "Shop lamp"
+          ],
+          "bodyText": [
+            "Choose the pieces that fit your room."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/bundle.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/lamp.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "project-card-grid-without-buttons",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"600px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/cabin.jpg\" alt=\"Cabin\" style=\"width:600px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Cabin refresh</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Warm oak across the room.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"610px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/studio.jpg\" alt=\"Studio\" style=\"width:610px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Studio wall</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">A quiet wall for display.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Cabin refresh",
+            "Studio wall"
+          ],
+          "bodyText": [
+            "Warm oak across the room.",
+            "A quiet wall for display."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/cabin.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/studio.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      }
+    ],
+    "renderFaq": [
+      {
+        "id": "faq-complete-answers",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Frequently Asked Questions</h2>\n<!-- /wp:heading -->\n<!-- wp:details -->\n<details class=\"wp-block-details\"><summary>Can I install it myself?</summary>\n<!-- wp:paragraph {\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\">Yes, the kit includes a measured guide.</p>\n<!-- /wp:paragraph -->\n</details>\n<!-- /wp:details -->\n<!-- wp:details -->\n<details class=\"wp-block-details\"><summary>How fast does it ship?</summary>\n<!-- wp:paragraph {\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\">Most orders leave the studio in two days.</p>\n<!-- /wp:paragraph -->\n</details>\n<!-- /wp:details -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Frequently Asked Questions",
+            "Can I install it myself?",
+            "How fast does it ship?"
+          ],
+          "bodyText": [
+            "Yes, the kit includes a measured guide.",
+            "Most orders leave the studio in two days."
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "faq-missing-answer-placeholder",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"color\":{\"background\":\"#e8eff1\"},\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull has-background\" style=\"margin-top:0;margin-bottom:0;background-color:#e8eff1;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Questions before ordering</h2>\n<!-- /wp:heading -->\n<!-- wp:details -->\n<details class=\"wp-block-details\"><summary>Is commercial pricing available?</summary>\n<!-- wp:paragraph {\"textColor\":\"text-subtle\"} -->\n<p class=\"has-text-subtle-color has-text-color\">[answer not captured]</p>\n<!-- /wp:paragraph -->\n</details>\n<!-- /wp:details -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Questions before ordering",
+            "Is commercial pricing available?"
+          ],
+          "bodyText": [],
+          "assets": [],
+          "flags": [
+            "faq#64: answer for \"Is commercial pricing available?\" not captured — placeholder emitted"
+          ],
+          "iconAssets": []
+        }
+      }
+    ],
+    "renderCellGrid": [
+      {
+        "id": "styled-cell-grid-with-icon-and-card",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Three bedtime essentials.</h2>\n<!-- /wp:heading -->\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:group {\"className\":\"is-replica-card\",\"style\":{\"spacing\":{\"padding\":{\"top\":\"clamp(16px, 1.67vw, 24px)\",\"bottom\":\"clamp(16px, 1.94vw, 28px)\",\"left\":\"clamp(16px, 2.22vw, 32px)\",\"right\":\"clamp(16px, 2.22vw, 32px)\"}},\"border\":{\"radius\":\"24px\"}},\"backgroundColor\":\"surface-inverse\",\"textColor\":\"text-inverse\",\"layout\":{\"type\":\"constrained\"}} -->\n<div class=\"wp-block-group is-replica-card has-text-inverse-color has-surface-inverse-background-color has-text-color has-background\" style=\"border-radius:24px;padding-top:clamp(16px, 1.67vw, 24px);padding-right:clamp(16px, 2.22vw, 32px);padding-bottom:clamp(16px, 1.94vw, 28px);padding-left:clamp(16px, 2.22vw, 32px)\">\n<!-- wp:image {\"width\":\"48px\",\"height\":\"48px\",\"sizeSlug\":\"full\",\"align\":\"center\"} -->\n<figure class=\"wp-block-image aligncenter size-full is-resized\"><img src=\"<?php echo esc_url(get_theme_file_uri('assets/icon-0.svg')); ?>\" alt=\"\" style=\"width:48px;height:48px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 1.9vw, 28px)\",\"lineHeight\":\"1.15\"}},\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-inverse\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family\" style=\"font-size:clamp(16px, 1.9vw, 28px);line-height:1.15\">Quiet motor</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"style\":{\"typography\":{\"lineHeight\":\"1.45\"}},\"fontSize\":\"small\",\"textColor\":\"text-inverse\"} -->\n<p class=\"has-text-align-center has-text-inverse-color has-text-color has-small-font-size\" style=\"line-height:1.45\">A low-hum motor keeps the room calm.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:group -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:group {\"className\":\"is-replica-card\",\"style\":{\"spacing\":{\"padding\":{\"top\":\"20px\",\"bottom\":\"20px\",\"left\":\"clamp(16px, 1.67vw, 24px)\",\"right\":\"clamp(16px, 1.67vw, 24px)\"}},\"border\":{\"radius\":\"12px\"}},\"backgroundColor\":\"surface-raised\",\"textColor\":\"text-default\",\"layout\":{\"type\":\"constrained\"}} -->\n<div class=\"wp-block-group is-replica-card has-text-default-color has-surface-raised-background-color has-text-color has-background\" style=\"border-radius:12px;padding-top:20px;padding-right:clamp(16px, 1.67vw, 24px);padding-bottom:20px;padding-left:clamp(16px, 1.67vw, 24px)\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"360px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/warm-light.jpg\" alt=\"Warm light\" style=\"width:360px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 1.7vw, 24px)\",\"lineHeight\":\"1.18\"}},\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-default-color has-text-color has-display-font-family\" style=\"font-size:clamp(16px, 1.7vw, 24px);line-height:1.18\">Warm light</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"style\":{\"typography\":{\"lineHeight\":\"1.45\"}},\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color has-small-font-size\" style=\"line-height:1.45\">A dimmable surface light replaces harsh lamps.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:group -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Three bedtime essentials.",
+            "Quiet motor",
+            "Warm light"
+          ],
+          "bodyText": [
+            "A low-hum motor keeps the room calm.",
+            "A dimmable surface light replaces harsh lamps."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/warm-light.jpg"
+          ],
+          "flags": [],
+          "iconAssets": [
+            {
+              "path": "assets/icon-0.svg",
+              "svg": "<svg fill=\"#ffffff\" viewBox=\"0 0 20 20\"><path d=\"M2 10h16v2H2z\"/></svg>"
+            }
+          ]
+        }
+      },
+      {
+        "id": "cell-grid-recovers-section-image-column",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Compare the setups</h2>\n<!-- /wp:heading -->\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Starter</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">A simple bedside setup.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Studio</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">A deeper package with samples.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"480px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/comparison-photo.jpg\" alt=\"Comparison photo\" style=\"width:480px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Compare the setups",
+            "Starter",
+            "Studio"
+          ],
+          "bodyText": [
+            "A simple bedside setup.",
+            "A deeper package with samples."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/comparison-photo.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "full-bleed-cell-grid",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"0\",\"right\":\"0\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"default\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:0px;padding-bottom:var(--wp--preset--spacing--60);padding-left:0px\">\n<!-- wp:columns {\"verticalAlignment\":\"center\",\"align\":\"full\",\"style\":{\"spacing\":{\"blockGap\":\"0\"}}} -->\n<div class=\"wp-block-columns alignfull are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Left edge</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">The first card reaches the viewport edge.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Right edge</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">The last card follows the source rail.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Left edge",
+            "Right edge"
+          ],
+          "bodyText": [
+            "The first card reaches the viewport edge.",
+            "The last card follows the source rail."
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      }
+    ],
+    "cardGroup": [
+      {
+        "id": "dark-card-group-with-captured-padding",
+        "output": {
+          "returnValue": "<!-- wp:group {\"className\":\"is-replica-card\",\"style\":{\"spacing\":{\"padding\":{\"top\":\"clamp(16px, 1.67vw, 24px)\",\"bottom\":\"clamp(16px, 1.94vw, 28px)\",\"left\":\"clamp(16px, 2.22vw, 32px)\",\"right\":\"clamp(16px, 2.22vw, 32px)\"}},\"border\":{\"radius\":\"24px\"}},\"backgroundColor\":\"surface-inverse\",\"textColor\":\"text-inverse\",\"layout\":{\"type\":\"constrained\"}} -->\n<div class=\"wp-block-group is-replica-card has-text-inverse-color has-surface-inverse-background-color has-text-color has-background\" style=\"border-radius:24px;padding-top:clamp(16px, 1.67vw, 24px);padding-right:clamp(16px, 2.22vw, 32px);padding-bottom:clamp(16px, 1.94vw, 28px);padding-left:clamp(16px, 2.22vw, 32px)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 1.9vw, 28px)\",\"lineHeight\":\"1.15\"}},\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-inverse\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family\" style=\"font-size:clamp(16px, 1.9vw, 28px);line-height:1.15\">Quiet card</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"style\":{\"typography\":{\"lineHeight\":\"1.45\"}},\"fontSize\":\"small\",\"textColor\":\"text-inverse\"} -->\n<p class=\"has-text-align-center has-text-inverse-color has-text-color has-small-font-size\" style=\"line-height:1.45\">Padded copy</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:group -->"
+        }
+      }
+    ],
+    "renderSection": [
+      {
+        "id": "faq-override-before-model-switch",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Frequently Asked Questions</h2>\n<!-- /wp:heading -->\n<!-- wp:details -->\n<details class=\"wp-block-details\"><summary>Can I install it myself?</summary>\n<!-- wp:paragraph {\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\">Yes, the kit includes a measured guide.</p>\n<!-- /wp:paragraph -->\n</details>\n<!-- /wp:details -->\n<!-- wp:details -->\n<details class=\"wp-block-details\"><summary>How fast does it ship?</summary>\n<!-- wp:paragraph {\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\">Most orders leave the studio in two days.</p>\n<!-- /wp:paragraph -->\n</details>\n<!-- /wp:details -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Frequently Asked Questions",
+            "Can I install it myself?",
+            "How fast does it ship?"
+          ],
+          "bodyText": [
+            "Yes, the kit includes a measured guide.",
+            "Most orders leave the studio in two days."
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "cell-grid-override-for-flatten-prone-model",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Three bedtime essentials.</h2>\n<!-- /wp:heading -->\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:group {\"className\":\"is-replica-card\",\"style\":{\"spacing\":{\"padding\":{\"top\":\"clamp(16px, 1.67vw, 24px)\",\"bottom\":\"clamp(16px, 1.94vw, 28px)\",\"left\":\"clamp(16px, 2.22vw, 32px)\",\"right\":\"clamp(16px, 2.22vw, 32px)\"}},\"border\":{\"radius\":\"24px\"}},\"backgroundColor\":\"surface-inverse\",\"textColor\":\"text-inverse\",\"layout\":{\"type\":\"constrained\"}} -->\n<div class=\"wp-block-group is-replica-card has-text-inverse-color has-surface-inverse-background-color has-text-color has-background\" style=\"border-radius:24px;padding-top:clamp(16px, 1.67vw, 24px);padding-right:clamp(16px, 2.22vw, 32px);padding-bottom:clamp(16px, 1.94vw, 28px);padding-left:clamp(16px, 2.22vw, 32px)\">\n<!-- wp:image {\"width\":\"48px\",\"height\":\"48px\",\"sizeSlug\":\"full\",\"align\":\"center\"} -->\n<figure class=\"wp-block-image aligncenter size-full is-resized\"><img src=\"<?php echo esc_url(get_theme_file_uri('assets/icon-0.svg')); ?>\" alt=\"\" style=\"width:48px;height:48px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 1.9vw, 28px)\",\"lineHeight\":\"1.15\"}},\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-inverse\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family\" style=\"font-size:clamp(16px, 1.9vw, 28px);line-height:1.15\">Quiet motor</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"style\":{\"typography\":{\"lineHeight\":\"1.45\"}},\"fontSize\":\"small\",\"textColor\":\"text-inverse\"} -->\n<p class=\"has-text-align-center has-text-inverse-color has-text-color has-small-font-size\" style=\"line-height:1.45\">A low-hum motor keeps the room calm.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:group -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:group {\"className\":\"is-replica-card\",\"style\":{\"spacing\":{\"padding\":{\"top\":\"20px\",\"bottom\":\"20px\",\"left\":\"clamp(16px, 1.67vw, 24px)\",\"right\":\"clamp(16px, 1.67vw, 24px)\"}},\"border\":{\"radius\":\"12px\"}},\"backgroundColor\":\"surface-raised\",\"textColor\":\"text-default\",\"layout\":{\"type\":\"constrained\"}} -->\n<div class=\"wp-block-group is-replica-card has-text-default-color has-surface-raised-background-color has-text-color has-background\" style=\"border-radius:12px;padding-top:20px;padding-right:clamp(16px, 1.67vw, 24px);padding-bottom:20px;padding-left:clamp(16px, 1.67vw, 24px)\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"360px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/warm-light.jpg\" alt=\"Warm light\" style=\"width:360px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"style\":{\"typography\":{\"fontSize\":\"clamp(16px, 1.7vw, 24px)\",\"lineHeight\":\"1.18\"}},\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-default-color has-text-color has-display-font-family\" style=\"font-size:clamp(16px, 1.7vw, 24px);line-height:1.18\">Warm light</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"style\":{\"typography\":{\"lineHeight\":\"1.45\"}},\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color has-small-font-size\" style=\"line-height:1.45\">A dimmable surface light replaces harsh lamps.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:group -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Three bedtime essentials.",
+            "Quiet motor",
+            "Warm light"
+          ],
+          "bodyText": [
+            "A low-hum motor keeps the room calm.",
+            "A dimmable surface light replaces harsh lamps."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/warm-light.jpg"
+          ],
+          "flags": [],
+          "iconAssets": [
+            {
+              "path": "assets/icon-0.svg",
+              "svg": "<svg fill=\"#ffffff\" viewBox=\"0 0 20 20\"><path d=\"M2 10h16v2H2z\"/></svg>"
+            }
+          ]
+        }
+      },
+      {
+        "id": "media-layout-override-image-left",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column {\"width\":\"45%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:45%\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"640px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/story.jpg\" alt=\"Story\" style=\"width:640px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column {\"width\":\"55%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:55%\">\n<!-- wp:heading {\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-default-color has-text-color has-display-font-family\">Image-led story row</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\">The source puts media before the copy.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Image-led story row"
+          ],
+          "bodyText": [
+            "The source puts media before the copy."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/story.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "columns-single-image-media-text",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column {\"width\":\"55%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:55%\">\n<!-- wp:heading {\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-default-color has-text-color has-display-font-family\">Columns become media text</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\">One image and copy is a two-up row.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column {\"width\":\"45%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:45%\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"640px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/columns.jpg\" alt=\"Columns\" style=\"width:640px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Columns become media text"
+          ],
+          "bodyText": [
+            "One image and copy is a two-up row."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/columns.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "columns-without-image-text-band",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Columns default headline</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Columns default body copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Columns default action</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Columns default headline",
+            "Columns default action"
+          ],
+          "bodyText": [
+            "Columns default body copy"
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "cover-full-bleed-wide-image",
+        "output": {
+          "markup": "<!-- wp:cover {\"url\":\"http://localhost:8883/wp-content/uploads/2026/05/cover-wide.jpg\",\"dimRatio\":40,\"overlayColor\":\"surface-inverse\",\"isUserOverlayColor\":true,\"minHeight\":50,\"minHeightUnit\":\"vw\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0px\"}}},\"layout\":{\"type\":\"constrained\"}} -->\n<div class=\"wp-block-cover alignfull\" style=\"margin-top:0px;min-height:50vw\"><img class=\"wp-block-cover__image-background\" src=\"http://localhost:8883/wp-content/uploads/2026/05/cover-wide.jpg\" alt=\"Cover\" data-object-fit=\"cover\"/><span aria-hidden=\"true\" class=\"wp-block-cover__background has-surface-inverse-background-color has-background-dim-40 has-background-dim\"></span>\n<div class=\"wp-block-cover__inner-container\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-inverse\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family\">Cover headline</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-inverse\"} -->\n<p class=\"has-text-align-center has-text-inverse-color has-text-color\">Copy sits over the captured background image.</p>\n<!-- /wp:paragraph -->\n</div>\n</div>\n<!-- /wp:cover -->",
+          "expectedText": [
+            "Cover headline"
+          ],
+          "bodyText": [
+            "Copy sits over the captured background image."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/cover-wide.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "cover-non-full-bleed-media-text",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column {\"width\":\"55%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:55%\">\n<!-- wp:heading {\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-default-color has-text-color has-display-font-family\">Cover falls to media text</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\">A contained photo belongs beside the copy.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column {\"width\":\"45%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:45%\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"640px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/cover-contained.jpg\" alt=\"Contained cover\" style=\"width:640px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Cover falls to media text"
+          ],
+          "bodyText": [
+            "A contained photo belongs beside the copy."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/cover-contained.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "cover-without-image-text-band",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Cover text headline</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Cover text body copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Cover text action</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Cover text headline",
+            "Cover text action"
+          ],
+          "bodyText": [
+            "Cover text body copy"
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "animated-cover-wide-image",
+        "output": {
+          "markup": "<!-- wp:cover {\"url\":\"http://localhost:8883/wp-content/uploads/2026/05/animated-wide.jpg\",\"dimRatio\":40,\"overlayColor\":\"surface-inverse\",\"isUserOverlayColor\":true,\"minHeight\":47.2,\"minHeightUnit\":\"vw\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0px\"}}},\"layout\":{\"type\":\"constrained\"}} -->\n<div class=\"wp-block-cover alignfull\" style=\"margin-top:0px;min-height:47.2vw\"><img class=\"wp-block-cover__image-background\" src=\"http://localhost:8883/wp-content/uploads/2026/05/animated-wide.jpg\" alt=\"Animated\" data-object-fit=\"cover\"/><span aria-hidden=\"true\" class=\"wp-block-cover__background has-surface-inverse-background-color has-background-dim-40 has-background-dim\"></span>\n<div class=\"wp-block-cover__inner-container\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-inverse\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family\">Animated cover</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-inverse\"} -->\n<p class=\"has-text-align-center has-text-inverse-color has-text-color\">Wide media uses the cover renderer.</p>\n<!-- /wp:paragraph -->\n</div>\n</div>\n<!-- /wp:cover -->",
+          "expectedText": [
+            "Animated cover"
+          ],
+          "bodyText": [
+            "Wide media uses the cover renderer."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/animated-wide.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "animated-cover-contained-media-text",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column {\"width\":\"55%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:55%\">\n<!-- wp:heading {\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-default-color has-text-color has-display-font-family\">Animated contained</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\">A smaller captured photo uses media text.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column {\"width\":\"45%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:45%\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"620px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/animated-contained.jpg\" alt=\"Contained\" style=\"width:620px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Animated contained"
+          ],
+          "bodyText": [
+            "A smaller captured photo uses media text."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/animated-contained.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "animated-cover-without-image-text-band",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Animated text headline</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Animated text body copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Animated text action</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Animated text headline",
+            "Animated text action"
+          ],
+          "bodyText": [
+            "Animated text body copy"
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "media-text-model",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column {\"width\":\"55%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:55%\">\n<!-- wp:heading {\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-default-color has-text-color has-display-font-family\">Media text section</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\">The explicit model uses media-text.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column {\"width\":\"45%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:45%\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"640px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/media-text.jpg\" alt=\"Media\" style=\"width:640px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Media text section"
+          ],
+          "bodyText": [
+            "The explicit model uses media-text."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/media-text.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "product-card-row-model",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"640px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/bundle.jpg\" alt=\"Bundle\" style=\"width:640px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Sleep essentials</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Choose the pieces that fit your room.</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Shop bundle</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"620px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/lamp.jpg\" alt=\"Lamp\" style=\"width:620px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Shop lamp</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Sleep essentials",
+            "Shop bundle",
+            "Shop lamp"
+          ],
+          "bodyText": [
+            "Choose the pieces that fit your room."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/bundle.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/lamp.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "project-card-grid-model",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"600px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/cabin.jpg\" alt=\"Cabin\" style=\"width:600px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Cabin refresh</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Warm oak across the room.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"610px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/studio.jpg\" alt=\"Studio\" style=\"width:610px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Studio wall</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">A quiet wall for display.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Cabin refresh",
+            "Studio wall"
+          ],
+          "bodyText": [
+            "Warm oak across the room.",
+            "A quiet wall for display."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/cabin.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/studio.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "blog-card-grid-model",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"600px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/cabin.jpg\" alt=\"Cabin\" style=\"width:600px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Cabin refresh</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Warm oak across the room.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"610px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/studio.jpg\" alt=\"Studio\" style=\"width:610px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Studio wall</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">A quiet wall for display.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Cabin refresh",
+            "Studio wall"
+          ],
+          "bodyText": [
+            "Warm oak across the room.",
+            "A quiet wall for display."
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/cabin.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/studio.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "review-grid-model",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"backgroundColor\":\"surface-raised\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull has-surface-raised-background-color has-background\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Review grid headline</h2>\n<!-- /wp:heading -->\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"accent-primary\"} -->\n<p class=\"has-text-align-center has-accent-primary-color has-text-color\">★★★★★</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-default\"} -->\n<p class=\"has-text-align-center has-text-default-color has-text-color\">The review copy stays verbatim.</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\",\"fontSize\":\"small\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Lee</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Review grid headline"
+          ],
+          "bodyText": [
+            "The review copy stays verbatim.",
+            "Lee"
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "testimonial-model",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"backgroundColor\":\"surface-raised\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull has-surface-raised-background-color has-background\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Testimonial headline</h2>\n<!-- /wp:heading -->\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"accent-primary\"} -->\n<p class=\"has-text-align-center has-accent-primary-color has-text-color\">★★★★★</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-default\"} -->\n<p class=\"has-text-align-center has-text-default-color has-text-color\">A compact testimonial quote.</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\",\"fontSize\":\"small\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Avery</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Testimonial headline"
+          ],
+          "bodyText": [
+            "A compact testimonial quote.",
+            "Avery"
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "gallery-model",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Gallery headline</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Gallery body copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:gallery {\"columns\":3,\"imageCrop\":false,\"linkTo\":\"none\",\"sizeSlug\":\"large\",\"className\":\"is-gallery-scroller\"} -->\n<figure class=\"wp-block-gallery has-nested-images columns-3 is-gallery-scroller\">\n<!-- wp:image {\"width\":\"520px\",\"height\":\"360px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/gallery-1.jpg\" alt=\"gallery-1.jpg\" style=\"width:520px;height:360px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"520px\",\"height\":\"360px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/gallery-2.jpg\" alt=\"gallery-2.jpg\" style=\"width:520px;height:360px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"520px\",\"height\":\"360px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/gallery-3.jpg\" alt=\"gallery-3.jpg\" style=\"width:520px;height:360px\"/></figure>\n<!-- /wp:image -->\n</figure>\n<!-- /wp:gallery -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Gallery headline"
+          ],
+          "bodyText": [
+            "Gallery body copy"
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/gallery-1.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/gallery-2.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/gallery-3.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "logo-strip-model",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Logo strip headline</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Logo strip body copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:gallery {\"columns\":3,\"imageCrop\":true,\"linkTo\":\"none\",\"sizeSlug\":\"large\"} -->\n<figure class=\"wp-block-gallery has-nested-images columns-3 is-cropped\">\n<!-- wp:image {\"width\":\"280px\",\"height\":\"140px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/logo-1.png\" alt=\"logo-1.png\" style=\"width:280px;height:140px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"280px\",\"height\":\"140px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/logo-2.png\" alt=\"logo-2.png\" style=\"width:280px;height:140px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"280px\",\"height\":\"140px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/logo-3.png\" alt=\"logo-3.png\" style=\"width:280px;height:140px\"/></figure>\n<!-- /wp:image -->\n</figure>\n<!-- /wp:gallery -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Logo strip headline"
+          ],
+          "bodyText": [
+            "Logo strip body copy"
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/logo-1.png",
+            "http://localhost:8883/wp-content/uploads/2026/05/logo-2.png",
+            "http://localhost:8883/wp-content/uploads/2026/05/logo-3.png"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "color-block-grid-model",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Color grid headline</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Color grid body copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:gallery {\"columns\":3,\"imageCrop\":false,\"linkTo\":\"none\",\"sizeSlug\":\"large\",\"className\":\"is-gallery-scroller\"} -->\n<figure class=\"wp-block-gallery has-nested-images columns-3 is-gallery-scroller\">\n<!-- wp:image {\"width\":\"320px\",\"height\":\"320px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/color-1.jpg\" alt=\"color-1.jpg\" style=\"width:320px;height:320px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"320px\",\"height\":\"320px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/color-2.jpg\" alt=\"color-2.jpg\" style=\"width:320px;height:320px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"320px\",\"height\":\"320px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/color-3.jpg\" alt=\"color-3.jpg\" style=\"width:320px;height:320px\"/></figure>\n<!-- /wp:image -->\n</figure>\n<!-- /wp:gallery -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Color grid headline"
+          ],
+          "bodyText": [
+            "Color grid body copy"
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/color-1.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/color-2.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/color-3.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "marquee-strip-model",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Marquee strip headline</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Marquee strip body copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:gallery {\"columns\":3,\"imageCrop\":false,\"linkTo\":\"none\",\"sizeSlug\":\"large\",\"className\":\"is-gallery-scroller\"} -->\n<figure class=\"wp-block-gallery has-nested-images columns-3 is-gallery-scroller\">\n<!-- wp:image {\"width\":\"520px\",\"height\":\"300px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/marquee-1.jpg\" alt=\"marquee-1.jpg\" style=\"width:520px;height:300px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"520px\",\"height\":\"300px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/marquee-2.jpg\" alt=\"marquee-2.jpg\" style=\"width:520px;height:300px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"520px\",\"height\":\"300px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/marquee-3.jpg\" alt=\"marquee-3.jpg\" style=\"width:520px;height:300px\"/></figure>\n<!-- /wp:image -->\n</figure>\n<!-- /wp:gallery -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "Marquee strip headline"
+          ],
+          "bodyText": [
+            "Marquee strip body copy"
+          ],
+          "assets": [
+            "http://localhost:8883/wp-content/uploads/2026/05/marquee-1.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/marquee-2.jpg",
+            "http://localhost:8883/wp-content/uploads/2026/05/marquee-3.jpg"
+          ],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "static-default-text-band",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">static headline</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">static body copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">static action</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "static headline",
+            "static action"
+          ],
+          "bodyText": [
+            "static body copy"
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "cta-default-text-band",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">cta headline</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">cta body copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">cta action</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "cta headline",
+            "cta action"
+          ],
+          "bodyText": [
+            "cta body copy"
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "price-list-default-text-band",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">price-list headline</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">price-list body copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">price-list action</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "price-list headline",
+            "price-list action"
+          ],
+          "bodyText": [
+            "price-list body copy"
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "app-download-default-text-band",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">app-download headline</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">app-download body copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">app-download action</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "app-download headline",
+            "app-download action"
+          ],
+          "bodyText": [
+            "app-download body copy"
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "horizontal-showcase-default-text-band",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">horizontal-showcase headline</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">horizontal-showcase body copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">horizontal-showcase action</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "horizontal-showcase headline",
+            "horizontal-showcase action"
+          ],
+          "bodyText": [
+            "horizontal-showcase body copy"
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "footer-default-text-band",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">footer headline</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">footer body copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">footer action</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "footer headline",
+            "footer action"
+          ],
+          "bodyText": [
+            "footer body copy"
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      },
+      {
+        "id": "nav-default-text-band",
+        "output": {
+          "markup": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"clamp(20px, 3.06vw, 44px)\",\"bottom\":\"clamp(21px, 3.19vw, 46px)\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:clamp(20px, 3.06vw, 44px);padding-right:var(--wp--preset--spacing--40);padding-bottom:clamp(21px, 3.19vw, 46px);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">nav headline</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">nav body copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">nav action</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</section>\n<!-- /wp:group -->",
+          "expectedText": [
+            "nav headline",
+            "nav action"
+          ],
+          "bodyText": [
+            "nav body copy"
+          ],
+          "assets": [],
+          "flags": [],
+          "iconAssets": []
+        }
+      }
+    ]
+  }
+}
diff --git a/packages/blocks-engine/src/__tests__/theme-native-renderers-dispatch-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-native-renderers-dispatch-parity.test.ts
new file mode 100644
index 00000000..6e1e71f1
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-native-renderers-dispatch-parity.test.ts
@@ -0,0 +1,135 @@
+import { describe, expect, it } from 'vitest';
+
+import expectedGoldens from '../__fixtures__/native-dispatch-renderer-dla-goldens.json' with { type: 'json' };
+import {
+  ALL_RENDER_SECTION_INTERACTION_MODELS,
+  nativeDispatchRenderCtx,
+  nativeDispatchRendererCaseGroups,
+  runNativeDispatchRendererParity,
+  type DispatchRendererName,
+  type NativeDispatchRendererImpl,
+  type NativeDispatchRendererParityFile,
+  type NativeRenderSectionCase,
+} from '../__fixtures__/native-dispatch-renderer-cases.js';
+import { renderImageRow, renderReviewGrid } from '../theme/native-renderers-section.js';
+import { renderCover, renderMediaText, renderTextBand } from '../theme/native-renderers-text.js';
+import { cardGroup, renderCardGrid, renderCellGrid, renderFaq } from '../theme/native-renderers-grid.js';
+import { renderSection } from '../theme/native-renderers-dispatch.js';
+import type { NativeRenderOut } from '../theme/native-reconstruct-types.js';
+import type { SectionSpec } from '../theme/section-spec.js';
+
+const EXPECTED_RENDERERS = 5;
+const EXPECTED_CASES = 36;
+const PORTED_DISPATCH_TARGETS: DispatchRendererName[] = [
+  'renderTextBand',
+  'renderCover',
+  'renderMediaText',
+  'renderCardGrid',
+  'renderReviewGrid',
+  'renderImageRow',
+  'renderFaq',
+  'renderCellGrid',
+];
+
+const engineImpl: NativeDispatchRendererImpl = {
+  renderCardGrid,
+  renderFaq,
+  renderCellGrid,
+  cardGroup,
+  renderSection,
+};
+
+function stableJson(value: unknown): string {
+  return JSON.stringify(value, null, 2);
+}
+
+function clone<T>(value: T): T {
+  if (value === undefined) return value;
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function rendererCaseCount(file: NativeDispatchRendererParityFile): number {
+  return Object.values(file.renderers).reduce((sum, cases) => sum + cases.length, 0);
+}
+
+function collectDiffs(actual: NativeDispatchRendererParityFile, expected: NativeDispatchRendererParityFile): string[] {
+  const diffs: string[] = [];
+  if (actual.version !== expected.version) diffs.push(`version: expected ${expected.version}, got ${actual.version}`);
+  if (actual.derivation !== expected.derivation) diffs.push('derivation: changed');
+
+  const actualRenderers = Object.keys(actual.renderers).sort();
+  const expectedRenderers = Object.keys(expected.renderers).sort();
+  if (stableJson(actualRenderers) !== stableJson(expectedRenderers)) {
+    diffs.push(`renderer keys: expected ${expectedRenderers.join(',')}, got ${actualRenderers.join(',')}`);
+  }
+
+  for (const renderer of expectedRenderers) {
+    const actualCases = actual.renderers[renderer as keyof NativeDispatchRendererParityFile['renderers']];
+    const expectedCases = expected.renderers[renderer as keyof NativeDispatchRendererParityFile['renderers']];
+    if (!actualCases) continue;
+    if (stableJson(actualCases) !== stableJson(expectedCases)) {
+      diffs.push(`${renderer}: output changed`);
+    }
+  }
+  return diffs;
+}
+
+function renderDirectTarget(entry: NativeRenderSectionCase): NativeRenderOut {
+  const section = clone(entry.section);
+  const ctx = nativeDispatchRenderCtx();
+  switch (entry.expectedRenderer) {
+    case 'renderTextBand':
+      return renderTextBand(section, ctx);
+    case 'renderCover':
+      return renderCover(section, ctx);
+    case 'renderMediaText':
+      return renderMediaText(section, entry.expectedFlip ?? false, ctx);
+    case 'renderCardGrid':
+      return renderCardGrid(section, section.interactionModel === 'product-card-row');
+    case 'renderReviewGrid':
+      return renderReviewGrid(section);
+    case 'renderImageRow':
+      return renderImageRow(section);
+    case 'renderFaq':
+      return renderFaq(section);
+    case 'renderCellGrid':
+      return renderCellGrid(section, ctx);
+  }
+}
+
+describe('native dispatch renderer DLA-today parity', () => {
+  it('matches mechanically derived DLA renderer outputs byte-for-byte and is stable on rerun', () => {
+    const first = runNativeDispatchRendererParity(engineImpl);
+    const second = runNativeDispatchRendererParity(engineImpl);
+    expect(stableJson(first)).toBe(stableJson(second));
+
+    const expected = expectedGoldens as NativeDispatchRendererParityFile;
+    const rendererCount = Object.keys(expected.renderers).length;
+    const caseCount = rendererCaseCount(expected);
+    const diffs = collectDiffs(first, expected);
+    console.info(`native dispatch renderer parity: renderers=${rendererCount} cases=${caseCount} diffs=${diffs.length}`);
+
+    expect(rendererCount).toBe(EXPECTED_RENDERERS);
+    expect(caseCount).toBe(EXPECTED_CASES);
+    expect(diffs).toEqual([]);
+  });
+
+  it('dispatches every interactionModel to a ported engine renderer', () => {
+    const cases = nativeDispatchRendererCaseGroups().renderSection;
+    const coveredModels = [...new Set(cases.map((entry) => entry.section.interactionModel))].sort();
+    expect(coveredModels).toEqual([...ALL_RENDER_SECTION_INTERACTION_MODELS].sort());
+
+    for (const entry of cases) {
+      expect(PORTED_DISPATCH_TARGETS).toContain(entry.expectedRenderer);
+      const actual = renderSection(clone(entry.section), nativeDispatchRenderCtx());
+      const direct = renderDirectTarget(entry);
+      expect(stableJson(actual), `${entry.id} should dispatch to ${entry.expectedRenderer}`).toBe(stableJson(direct));
+    }
+  });
+
+  it('keeps renderSection cases free of out-of-scope form and converted wiring', () => {
+    const cases = nativeDispatchRendererCaseGroups().renderSection;
+    expect(cases.every((entry) => !(entry.section as SectionSpec).forms?.length)).toBe(true);
+    expect(cases.every((entry) => !entry.section.sectionHtml && !entry.section.styledHtml)).toBe(true);
+  });
+});
diff --git a/packages/blocks-engine/src/theme/native-renderers-dispatch.ts b/packages/blocks-engine/src/theme/native-renderers-dispatch.ts
index c95c0050..3837ce18 100644
--- a/packages/blocks-engine/src/theme/native-renderers-dispatch.ts
+++ b/packages/blocks-engine/src/theme/native-renderers-dispatch.ts
@@ -1,6 +1,9 @@
-import { emptyNativeRenderOut } from './native-block-builders.js';
+import { pickLeadImage, isWpMediaUrl } from './native-media.js';
+import { renderCardGrid, renderCellGrid, renderFaq } from './native-renderers-grid.js';
+import { renderImageRow, renderReviewGrid } from './native-renderers-section.js';
+import { renderCover, renderMediaText, renderTextBand } from './native-renderers-text.js';
 import type { NativeRenderCtx, NativeRenderOut } from './native-reconstruct-types.js';
-import type { InteractionModel, SectionSpec } from './section-spec.js';
+import type { InteractionModel, SectionSpec, SectionSpecCell } from './section-spec.js';
 
 export const NON_CELL_GRID_MODELS: ReadonlySet<InteractionModel> = new Set([
   'product-card-row',
@@ -31,7 +34,116 @@ export const MEDIA_LAYOUT_DENY: ReadonlySet<InteractionModel> = new Set([
 ]);
 
 export function renderSection(section: SectionSpec, ctx: NativeRenderCtx): NativeRenderOut {
-  void section;
-  void ctx;
-  return emptyNativeRenderOut();
+  // A section carrying re-captured FAQ pairs renders as an accordion regardless
+  // of its geometric interaction model.
+  if (section.faqs && section.faqs.length) return renderFaq(section);
+  // A uniform multi-cell content grid: >=2 cells each carrying BOTH a title and
+  // body (a genuine feature/column grid, not a hero's text|image split or a
+  // single CTA). Card grids / reviews keep their specialized paths.
+  // A uniform multi-cell content grid. The base trigger needs cells carrying BOTH a
+  // heading and body (an unambiguous feature grid). RELAXED un-flatten: when the source
+  // reported >=2 columns AND the model would otherwise flatten to a centered text band,
+  // >=2 cells carrying ANY content (heading/body/image/icon/button) is enough — so a
+  // numbered-card band whose cells are heading-only stops collapsing into one column. The
+  // relaxed path is gated to FLATTEN_PRONE_MODELS so heroes/covers/media-text (which run
+  // their own checks after this) are never swept into a card grid by column count alone.
+  const cellHasHeadingAndBody = (cell: SectionSpecCell) => !!(cell.heading && cell.body.length > 0);
+  const cellHasAnyContent = (cell: SectionSpecCell) =>
+    !!(cell.heading || cell.body.length > 0 || cell.image || cell.icon || cell.button);
+  if (
+    section.cells &&
+    !NON_CELL_GRID_MODELS.has(section.interactionModel) &&
+    (section.cells.filter(cellHasHeadingAndBody).length >= 2 ||
+      (FLATTEN_PRONE_MODELS.has(section.interactionModel) &&
+        section.layout.columnCount >= 2 &&
+        section.cells.filter(cellHasAnyContent).length >= 2))
+  ) {
+    return renderCellGrid(section, ctx);
+  }
+  // The source places a large image BESIDE the text (a 2-up media row) — render
+  // media-text with the captured side, regardless of the geometric model, so the
+  // arrangement isn't stacked. Skipped for gallery/card/review models (their
+  // multi-image layouts own their rendering) and when there's no lead image or
+  // text to pair. This is what makes a flat-Wix content tile (e.g. a product
+  // page's photo|description row) reproduce its real two-column layout.
+  if (
+    section.mediaLayout &&
+    !MEDIA_LAYOUT_DENY.has(section.interactionModel) &&
+    pickLeadImage(section.images) &&
+    (section.headings.length > 0 || (section.bodyText ?? []).length > 0)
+  ) {
+    ctx.mediaTextIndex++;
+    return renderMediaText(section, section.mediaLayout === 'image-left', ctx);
+  }
+  switch (section.interactionModel) {
+    case 'media-text': {
+      const flip = ctx.mediaTextIndex % 2 === 1;
+      ctx.mediaTextIndex++;
+      return renderMediaText(section, flip, ctx);
+    }
+    case 'product-card-row':
+      return renderCardGrid(section, true);
+    case 'project-card-grid':
+    case 'blog-card-grid':
+      return renderCardGrid(section, false);
+    case 'review-grid':
+    case 'testimonial':
+      return renderReviewGrid(section);
+    case 'color-block-grid':
+    case 'logo-strip':
+    case 'gallery':
+    case 'marquee-strip':
+      return renderImageRow(section);
+    case 'columns':
+      // A two-up columns band: if it has both copy and one image, treat as media-text;
+      // otherwise a centered text band.
+      if (section.images.length === 1 && (section.headings.length || (section.bodyText ?? []).length)) {
+        return renderMediaText(section, false, ctx);
+      }
+      return renderTextBand(section, ctx);
+    case 'cover-with-headline': {
+      const coverLead = pickLeadImage(section.images);
+      // A FULL-BLEED hero with a wide background photo (≥1000px) is a
+      // text-OVER-photo cover (the title sits on the image) — render it as a
+      // wp:cover, not a side-by-side. Routing it to media-text produced the
+      // common failure where the hero became a flat dark band with a dark
+      // (often invisible) heading beside a shrunken photo. Mirrors the
+      // animated-cover branch. Generic: keyed on the captured fullBleed flag +
+      // image width, not any one site.
+      if (coverLead && isWpMediaUrl(coverLead.url) && section.fullBleed && (coverLead.width || 0) >= 1000) {
+        return renderCover(section, ctx);
+      }
+      // A non-full-bleed hero with a REAL lead photo renders as a 2-column
+      // media-text (text | image). Without a photo it's a centered band.
+      if (coverLead && (section.headings.length || (section.bodyText ?? []).length)) {
+        const flip = ctx.mediaTextIndex % 2 === 1;
+        ctx.mediaTextIndex++;
+        return renderMediaText(section, flip, ctx);
+      }
+      return renderTextBand(section, ctx);
+    }
+    case 'animated-cover': {
+      // A full-bleed hero cover needs a WIDE background photo (≥1000px). A
+      // smaller content image is a media band (a mid-page story section), not a
+      // cover — render it as media-text so it isn't turned into a full-bleed
+      // text-over-photo band.
+      const coverLead = pickLeadImage(section.images);
+      if (coverLead && isWpMediaUrl(coverLead.url) && (coverLead.width || 0) >= 1000) {
+        return renderCover(section, ctx);
+      }
+      if (coverLead && (section.headings.length || (section.bodyText ?? []).length)) {
+        const flip = ctx.mediaTextIndex % 2 === 1;
+        ctx.mediaTextIndex++;
+        return renderMediaText(section, flip, ctx);
+      }
+      return renderTextBand(section, ctx);
+    }
+    case 'static':
+    case 'cta':
+    case 'price-list':
+    case 'app-download':
+    case 'horizontal-showcase':
+    default:
+      return renderTextBand(section, ctx);
+  }
 }
diff --git a/packages/blocks-engine/src/theme/native-renderers-grid.ts b/packages/blocks-engine/src/theme/native-renderers-grid.ts
index 27ac9f13..b62cf6f4 100644
--- a/packages/blocks-engine/src/theme/native-renderers-grid.ts
+++ b/packages/blocks-engine/src/theme/native-renderers-grid.ts
@@ -1,9 +1,24 @@
 import {
+  buttonBlock,
+  column,
+  columns,
   emptyNativeRenderOut,
+  headingBlock,
+  imageBlock,
+  paragraphBlock,
+  wrapSection,
 } from './native-block-builders.js';
+import { brightness, nearestToken } from './native-color.js';
+import { nearestFamily } from './native-fonts.js';
+import { buttonJustify, centerOf, isTintedSection, responsiveSpace, sectionPad } from './native-layout.js';
+import { iconImageBlock, isWpMediaUrl } from './native-media.js';
 import type { NativeRenderCtx, NativeRenderOut } from './native-reconstruct-types.js';
+import { escapeHtml } from '../escape.js';
+import { normalizeCopy } from './page-reconstruct-helpers.js';
 import type { SectionSpec } from './section-spec.js';
 
+const MIN_CELL_IMAGE_PX = 90;
+
 export interface CardGroupPadding {
   top: number;
   right: number;
@@ -12,20 +27,185 @@ export interface CardGroupPadding {
 }
 
 export function renderCardGrid(section: SectionSpec, withButtons: boolean): NativeRenderOut {
-  void section;
-  void withButtons;
-  return emptyNativeRenderOut();
+  const out = emptyNativeRenderOut();
+  const headings = dedupeAdjacent(section.headings);
+  const bodyText = section.bodyText ?? [];
+  const cardCount =
+    section.images.length > 0 ? section.images.length : Math.min(headings.length, bodyText.length || headings.length);
+  const cards: string[] = [];
+  for (let i = 0; i < cardCount; i++) {
+    const cardParts: string[] = [];
+    if (section.images.length > 0) {
+      cardParts.push(
+        imageBlock(section.images[i], out, `${section.interactionModel}#${section.sectionIndex}.card${i}`, {
+          rounded: true,
+        }),
+      );
+    }
+    if (headings[i]) {
+      cardParts.push(
+        headingBlock(headings[i], out, {
+          level: 3,
+          center: centerOf(section),
+          sizePx: section.headingSizes?.[i],
+          fontFamily: section.headingFamilies?.[i] || undefined,
+          lineHeight: section.headingLineHeights?.[i],
+        }),
+      );
+    }
+    if (bodyText[i]) {
+      cardParts.push(
+        paragraphBlock(bodyText[i], out, {
+          center: centerOf(section),
+          size: 'small',
+          sizePx: section.bodyTextSizes?.[i],
+          fontFamily: section.bodyFamilies?.[i] || undefined,
+          lineHeight: section.bodyLineHeights?.[i],
+        }),
+      );
+    }
+    if (withButtons && section.buttonLabels[i]) {
+      cardParts.push(buttonBlock(section.buttonLabels[i], out, { align: buttonJustify(section) }));
+    }
+    if (cardParts.filter(Boolean).length) cards.push(column(cardParts.filter(Boolean)));
+  }
+  const extra: string[] = [];
+  for (let i = cardCount; i < bodyText.length; i++) {
+    extra.push(paragraphBlock(bodyText[i], out, { center: centerOf(section) }));
+  }
+  out.markup = wrapSection([...extra.filter(Boolean), columns(cards)], {
+    wide: '1100px',
+    raised: isTintedSection(section),
+    bgColor: section.backgroundColor,
+    ...sectionPad(section),
+  });
+  return out;
 }
 
 export function renderFaq(section: SectionSpec): NativeRenderOut {
-  void section;
-  return emptyNativeRenderOut();
+  const out = emptyNativeRenderOut();
+  const parts: string[] = [];
+  section.headings.slice(0, 1).forEach((heading, i) =>
+    parts.push(
+      headingBlock(heading, out, {
+        level: 2,
+        center: centerOf(section),
+        sizePx: section.headingSizes?.[i],
+        fontFamily: section.headingFamilies?.[i] || undefined,
+        lineHeight: section.headingLineHeights?.[i],
+      }),
+    ),
+  );
+  const faqs = section.faqs ?? [];
+  for (const faq of faqs) {
+    const question = normalizeCopy(faq.question);
+    if (!question) continue;
+    out.expectedText.push(question);
+    const answer = normalizeCopy(faq.answer);
+    let answerBlock: string;
+    if (answer) {
+      out.bodyText.push(answer);
+      answerBlock =
+        `<!-- wp:paragraph {"textColor":"text-muted"} -->\n` +
+        `<p class="has-text-muted-color has-text-color">${escapeHtml(answer)}</p>\n<!-- /wp:paragraph -->`;
+    } else {
+      out.flags.push(`faq#${section.sectionIndex}: answer for "${question}" not captured — placeholder emitted`);
+      answerBlock =
+        `<!-- wp:paragraph {"textColor":"text-subtle"} -->\n` +
+        `<p class="has-text-subtle-color has-text-color">[answer not captured]</p>\n<!-- /wp:paragraph -->`;
+    }
+    parts.push(
+      `<!-- wp:details -->\n<details class="wp-block-details"><summary>${escapeHtml(question)}</summary>\n` +
+        `${answerBlock}\n</details>\n<!-- /wp:details -->`,
+    );
+  }
+  out.markup = wrapSection(parts.filter(Boolean), {
+    constrained: '760px',
+    raised: isTintedSection(section),
+    bgColor: section.backgroundColor,
+    ...sectionPad(section),
+  });
+  return out;
 }
 
 export function renderCellGrid(section: SectionSpec, ctx: NativeRenderCtx): NativeRenderOut {
-  void section;
-  void ctx;
-  return emptyNativeRenderOut();
+  const out = emptyNativeRenderOut();
+  const cells = section.cells ?? [];
+  const cellHeadSet = new Set(cells.map((cell) => normalizeCopy(cell.heading ?? '')).filter(Boolean));
+  const intro: string[] = [];
+  section.headings.forEach((heading, i) => {
+    if (cellHeadSet.has(normalizeCopy(heading))) return;
+    intro.push(
+      headingBlock(heading, out, {
+        level: i === 0 ? 2 : 3,
+        center: centerOf(section),
+        sizePx: section.headingSizes?.[i],
+        fontFamily: section.headingFamilies?.[i] || undefined,
+        lineHeight: section.headingLineHeights?.[i],
+      }),
+    );
+  });
+  const cols: string[] = [];
+  for (const cell of cells) {
+    const cardToken = cell.background ? nearestToken(cell.background, ctx.paletteTokens) : null;
+    const cardDark = cell.background ? brightness(cell.background) < 140 : false;
+    const cellCenter = cell.align ? cell.align === 'center' : centerOf(section);
+    const iconAlign = cell.iconAlign ?? (cellCenter ? 'center' : 'left');
+    const parts: string[] = [];
+    if (cell.icon) {
+      parts.push(iconImageBlock(cell.icon, out, ctx, { align: iconAlign, ...(cardDark ? { fill: '#ffffff' } : {}) }));
+    }
+    if (
+      cell.image &&
+      isWpMediaUrl(cell.image.url) &&
+      Math.min(cell.image.width || 0, cell.image.height || 0) >= MIN_CELL_IMAGE_PX
+    ) {
+      parts.push(imageBlock(cell.image, out, `cell#${section.sectionIndex}`, { rounded: true }));
+    }
+    const cellHeadFamily = nearestFamily(cell.headingFamily, ctx.fontFamilies) || undefined;
+    const cellBodyFamily = nearestFamily(cell.bodyFamily, ctx.fontFamilies) || undefined;
+    if (cell.heading) {
+      parts.push(
+        headingBlock(cell.heading, out, {
+          level: 3,
+          center: cellCenter,
+          inverse: cardDark,
+          sizePx: cell.headingSize,
+          fontFamily: cellHeadFamily,
+          lineHeight: cell.headingLineHeight,
+        }),
+      );
+    }
+    for (const body of cell.body) {
+      parts.push(
+        paragraphBlock(body, out, {
+          center: cellCenter,
+          size: 'small',
+          inverse: cardDark,
+          fontFamily: cellBodyFamily,
+          lineHeight: cell.bodyLineHeight,
+        }),
+      );
+    }
+    if (cell.button) parts.push(buttonBlock(cell.button, out, { align: cellCenter ? 'center' : 'left' }));
+    const kept = parts.filter(Boolean);
+    if (!kept.length) continue;
+    cols.push(column(cardToken ? [cardGroup(kept, cardToken, cardDark, cell.radius ?? 0, cell.padding ?? null)] : kept));
+  }
+  const claimedImageUrls = new Set(cells.map((cell) => cell.image?.url).filter(Boolean));
+  for (const image of section.images ?? []) {
+    if (claimedImageUrls.has(image.url)) continue;
+    if (!isWpMediaUrl(image.url) || Math.min(image.width || 0, image.height || 0) < MIN_CELL_IMAGE_PX) continue;
+    cols.push(column([imageBlock(image, out, `cell-media#${section.sectionIndex}`, { rounded: true })]));
+  }
+  const fullBleed = (section.layout?.containerWidth ?? 0) >= 1380;
+  out.markup = wrapSection([...intro.filter(Boolean), columns(cols, { fullBleed })], {
+    ...(fullBleed ? { fullBleed: true } : { wide: '1100px' }),
+    raised: isTintedSection(section),
+    bgColor: section.backgroundColor,
+    ...sectionPad(section),
+  });
+  return out;
 }
 
 export function cardGroup(
@@ -35,10 +215,27 @@ export function cardGroup(
   radius: number,
   padding: CardGroupPadding | null,
 ): string {
-  void parts;
-  void bgToken;
-  void dark;
-  void radius;
-  void padding;
-  return '';
+  const textToken = dark ? 'text-inverse' : 'text-default';
+  const r = radius > 0 ? Math.min(radius, 32) : 0;
+  const cssLen = (value: string): string =>
+    value.startsWith('var:preset|spacing|') ? `var(--wp--preset--spacing--${value.split('|').pop()})` : value;
+  const side = (px: number | undefined): string =>
+    typeof px === 'number' ? responsiveSpace(Math.max(8, Math.min(96, px))) : 'var:preset|spacing|40';
+  const pt = side(padding?.top);
+  const pr = side(padding?.right);
+  const pb = side(padding?.bottom);
+  const pl = side(padding?.left);
+  return (
+    `<!-- wp:group {"className":"is-replica-card","style":{"spacing":{"padding":{"top":"${pt}","bottom":"${pb}","left":"${pl}","right":"${pr}"}},"border":{"radius":"${r}px"}},"backgroundColor":"${bgToken}","textColor":"${textToken}","layout":{"type":"constrained"}} -->\n` +
+    `<div class="wp-block-group is-replica-card has-${textToken}-color has-${bgToken}-background-color has-text-color has-background" style="border-radius:${r}px;padding-top:${cssLen(pt)};padding-right:${cssLen(pr)};padding-bottom:${cssLen(pb)};padding-left:${cssLen(pl)}">\n${parts.join('\n')}\n</div>\n` +
+    `<!-- /wp:group -->`
+  );
+}
+
+function dedupeAdjacent(arr: string[]): string[] {
+  const out: string[] = [];
+  for (const value of arr) {
+    if (out.length === 0 || normalizeCopy(out[out.length - 1]) !== normalizeCopy(value)) out.push(value);
+  }
+  return out;
 }

From 5a8720b793d36c8324e3f956caab95684c13f54c Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 20:48:47 -0400
Subject: [PATCH 091/113] feat(theme): freeze native reconstruct contract

---
 .../theme-native-reconstruct-contract.test.ts | 70 +++++++++++++++++++
 .../src/theme/native-reconstruct-types.ts     | 18 +++++
 2 files changed, 88 insertions(+)
 create mode 100644 packages/blocks-engine/src/__tests__/theme-native-reconstruct-contract.test.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-native-reconstruct-contract.test.ts b/packages/blocks-engine/src/__tests__/theme-native-reconstruct-contract.test.ts
new file mode 100644
index 00000000..03c2d16e
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-native-reconstruct-contract.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import type { WorkerPool } from '../pool/types.js';
+import { reconstruct, type SectionBlocks, type SiteToThemeHooks, type StageCtx } from '../theme/index.js';
+import type { FallbackDiagnostic } from '../theme/fallback-diagnostic.js';
+import type {
+  FormRemainder,
+  NativeReconstructAggregate,
+  NativeSectionDecision,
+  NativeSectionDecisionKind,
+} from '../theme/native-reconstruct-types.js';
+import type { CoverageResult } from '../theme/section-coverage.js';
+import type { SectionSpec } from '../theme/section-spec.js';
+
+describe('native reconstruct frozen internal contract', () => {
+  it('freezes the section decision and aggregate types', () => {
+    expect(['converted', 'native', 'fallback']).toEqual([
+      'converted',
+      'native',
+      'fallback',
+    ] satisfies NativeSectionDecisionKind[]);
+
+    expectTypeOf<NativeSectionDecision>().toEqualTypeOf<{
+      spec: SectionSpec;
+      blocks: string;
+      coverage: CoverageResult;
+      expectedText: string[];
+      bodyText: string[];
+      expectedAssets: string[];
+      provenanceFlags: string[];
+      fallbackDiagnostics: FallbackDiagnostic[];
+      iconAssets: Array<{ path: string; svg: string }>;
+      heroIsCover?: boolean;
+      remainder?: FormRemainder;
+      decision: NativeSectionDecisionKind;
+    }>();
+
+    expectTypeOf<NativeReconstructAggregate>().toEqualTypeOf<{
+      sections: NativeSectionDecision[];
+      sectionMarkup: string[];
+      expectedText: string[];
+      bodyText: string[];
+      expectedAssets: string[];
+      provenanceFlags: string[];
+      fallbackDiagnostics: FallbackDiagnostic[];
+      iconAssets: Array<{ path: string; svg: string }>;
+      heroIsCover: boolean;
+    }>();
+  });
+
+  it('keeps the public reconstruct hook-stage surface stable', () => {
+    expect(reconstruct).toHaveLength(5);
+    expectTypeOf(reconstruct).toEqualTypeOf<
+      (
+        specs: SectionSpec[],
+        ctx: StageCtx,
+        pool: WorkerPool,
+        hooks: SiteToThemeHooks,
+        coverageFloor: number,
+      ) => Promise<SectionBlocks[]>
+    >();
+
+    expectTypeOf<SectionBlocks>().toEqualTypeOf<{
+      spec: SectionSpec;
+      blocks: string;
+      coverage: number;
+      remainder?: FormRemainder;
+    }>();
+  });
+});
diff --git a/packages/blocks-engine/src/theme/native-reconstruct-types.ts b/packages/blocks-engine/src/theme/native-reconstruct-types.ts
index 6ccd8347..1af0dc1c 100644
--- a/packages/blocks-engine/src/theme/native-reconstruct-types.ts
+++ b/packages/blocks-engine/src/theme/native-reconstruct-types.ts
@@ -38,6 +38,24 @@ export interface NativeSectionResult {
   remainder?: FormRemainder;
 }
 
+export type NativeSectionDecisionKind = 'converted' | 'native' | 'fallback';
+
+export interface NativeSectionDecision extends NativeSectionResult {
+  decision: NativeSectionDecisionKind;
+}
+
+export interface NativeReconstructAggregate {
+  sections: NativeSectionDecision[];
+  sectionMarkup: string[];
+  expectedText: string[];
+  bodyText: string[];
+  expectedAssets: string[];
+  provenanceFlags: string[];
+  fallbackDiagnostics: FallbackDiagnostic[];
+  iconAssets: Array<{ path: string; svg: string }>;
+  heroIsCover: boolean;
+}
+
 export interface ConvertedSectionInput {
   markup: string | null;
   wpHtmlResidue: number;

From 86f39fd1fd0d193c2201401c02feb0012a4ddb0c Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 20:59:25 -0400
Subject: [PATCH 092/113] feat(theme): wire native reconstruct decisions

---
 .../page-reconstruct-dla-baseline.corpus.ts   | 390 ++++++++
 ...page-reconstruct-dla-baseline.goldens.json | 854 ++++++++++++++++++
 ...me-reconstruct-dla-baseline-parity.test.ts | 132 +++
 .../src/__tests__/theme-reconstruct.test.ts   | 126 ++-
 .../blocks-engine/src/theme/reconstruct.ts    | 495 ++++++++--
 5 files changed, 1864 insertions(+), 133 deletions(-)
 create mode 100644 packages/blocks-engine/src/__fixtures__/page-reconstruct-dla-baseline.corpus.ts
 create mode 100644 packages/blocks-engine/src/__fixtures__/page-reconstruct-dla-baseline.goldens.json
 create mode 100644 packages/blocks-engine/src/__tests__/theme-reconstruct-dla-baseline-parity.test.ts

diff --git a/packages/blocks-engine/src/__fixtures__/page-reconstruct-dla-baseline.corpus.ts b/packages/blocks-engine/src/__fixtures__/page-reconstruct-dla-baseline.corpus.ts
new file mode 100644
index 00000000..d47931a8
--- /dev/null
+++ b/packages/blocks-engine/src/__fixtures__/page-reconstruct-dla-baseline.corpus.ts
@@ -0,0 +1,390 @@
+import type {
+  InteractionModel,
+  SectionSpec,
+  SectionSpecButton,
+  SectionSpecCell,
+  SectionSpecForm,
+  SectionSpecImage,
+} from '../theme/section-spec.js';
+
+export interface FrozenConvertedSection {
+  sectionIndex: number;
+  markup: string | null;
+  wpHtmlResidue: number;
+}
+
+export interface FrozenReconstructOptions {
+  patternSlug: string;
+  title: string;
+  slug: string;
+  sourceUrl: string;
+  convertedSections?: FrozenConvertedSection[];
+}
+
+export interface FrozenReconstructCase {
+  id: string;
+  sections: SectionSpec[];
+  options: FrozenReconstructOptions;
+}
+
+const WP = 'http://localhost:8883/wp-content/uploads/2026/05/';
+const CDN = 'https://cdn.example.test/assets/';
+
+const contactForm: SectionSpecForm = {
+  fields: [
+    { kind: 'name', label: 'Full name', required: true, widthPct: 50 },
+    { kind: 'email', label: 'Email address', required: true, widthPct: 50 },
+    { kind: 'select', label: 'Topic', required: false, options: ['Billing', 'Support'] },
+    { kind: 'textarea', label: 'Message', required: false },
+    { kind: 'hidden', label: 'Campaign id', required: false },
+  ],
+  submitLabel: 'Send Message',
+};
+
+function options(id: string, partial: Partial<FrozenReconstructOptions> = {}): FrozenReconstructOptions {
+  return {
+    patternSlug: `baseline/${id}`,
+    title: `Baseline ${id}`,
+    slug: id,
+    sourceUrl: `https://example.test/${id}`,
+    ...partial,
+  };
+}
+
+function image(name: string, width = 800, height = 600, alt = name): SectionSpecImage {
+  return {
+    url: `${WP}${name}`,
+    sourceUrl: `${CDN}${name}`,
+    alt,
+    kind: 'img',
+    width,
+    height,
+  };
+}
+
+function remoteImage(name: string, width = 800, height = 600): SectionSpecImage {
+  return {
+    url: `${CDN}${name}`,
+    sourceUrl: `${CDN}${name}`,
+    alt: name,
+    kind: 'img',
+    width,
+    height,
+  };
+}
+
+function button(label: string, href = '#'): SectionSpecButton {
+  return { label, href, background: null, color: null };
+}
+
+function cell(partial: Partial<SectionSpecCell>): SectionSpecCell {
+  return {
+    heading: null,
+    body: [],
+    image: null,
+    icon: null,
+    button: null,
+    ...partial,
+  };
+}
+
+function section(
+  sectionIndex: number,
+  interactionModel: InteractionModel,
+  partial: Partial<SectionSpec> = {},
+): SectionSpec {
+  return {
+    sectionIndex,
+    interactionModel,
+    top: sectionIndex * 500,
+    height: 420,
+    headings: [],
+    bodyText: [],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 255,
+    backgroundColor: 'rgb(255, 255, 255)',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: { motionClass: 'none', signals: [], animatedElements: 0 },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: { containerWidth: 1200, padding: '0', childLayout: 'stack', columnCount: 1, gap: '24px' },
+    ...partial,
+  } as SectionSpec;
+}
+
+function converted(markup: string | null, wpHtmlResidue = 0, sectionIndex = 0): FrozenConvertedSection[] {
+  return [{ sectionIndex, markup, wpHtmlResidue }];
+}
+
+export const reconstructBaselineCases: FrozenReconstructCase[] = [
+  {
+    id: 'converted-accept',
+    sections: [section(0, 'static', { headings: ['Converted Heading'], bodyText: ['Converted body copy'] })],
+    options: options('converted-accept', {
+      convertedSections: converted(
+        '<!-- wp:heading --><h2>Converted Heading</h2><!-- /wp:heading -->\n' +
+          '<!-- wp:paragraph --><p>Converted body copy</p><!-- /wp:paragraph -->',
+      ),
+    }),
+  },
+  {
+    id: 'converted-reject-residue',
+    sections: [section(0, 'static', { headings: ['Residue Heading'], bodyText: ['Structured render survives'] })],
+    options: options('converted-reject-residue', {
+      convertedSections: converted('<!-- wp:html --><div>unconverted residue</div><!-- /wp:html -->', 1),
+    }),
+  },
+  {
+    id: 'converted-reject-remote-asset',
+    sections: [section(0, 'static', { headings: ['Remote Photo'], images: [remoteImage('remote-photo.jpg')] })],
+    options: options('converted-reject-remote-asset', {
+      convertedSections: converted(
+        '<!-- wp:heading --><h2>Remote Photo</h2><!-- /wp:heading -->\n' +
+          '<!-- wp:image --><figure class="wp-block-image"><img src="https://cdn.example.test/assets/remote-photo.jpg" alt=""/></figure><!-- /wp:image -->',
+      ),
+    }),
+  },
+  {
+    id: 'converted-reject-placeholder',
+    sections: [section(0, 'static', { headings: ['Template Token'], bodyText: ['Token body'] })],
+    options: options('converted-reject-placeholder', {
+      convertedSections: converted(
+        '<!-- wp:heading --><h2>Template Token</h2><!-- /wp:heading -->\n' +
+          '<!-- wp:paragraph --><p>Hello {{ visitor }}</p><!-- /wp:paragraph -->',
+      ),
+    }),
+  },
+  {
+    id: 'converted-reject-injection',
+    sections: [section(0, 'static', { headings: ['Injected Section'], bodyText: ['Clean body'] })],
+    options: options('converted-reject-injection', {
+      convertedSections: converted(
+        '<!-- wp:heading --><h2 onclick="alert(1)">Injected Section</h2><!-- /wp:heading -->\n' +
+          '<!-- wp:paragraph --><p>Clean body</p><!-- /wp:paragraph -->',
+      ),
+    }),
+  },
+  {
+    id: 'converted-reject-coverage-loss',
+    sections: [section(0, 'static', { headings: ['Coverage Heading'], bodyText: ['Required body copy'] })],
+    options: options('converted-reject-coverage-loss', {
+      convertedSections: converted('<!-- wp:heading --><h2>Coverage Heading</h2><!-- /wp:heading -->'),
+    }),
+  },
+  {
+    id: 'static-text-band',
+    sections: [section(0, 'static', { headings: ['Static Band'], bodyText: ['Plain section copy'], buttonLabels: ['Read More'] })],
+    options: options('static-text-band'),
+  },
+  {
+    id: 'cta-text-band',
+    sections: [section(0, 'cta', { headings: ['Start Today'], bodyText: ['A compact call to action.'], buttons: [button('Contact Us', '/contact')] })],
+    options: options('cta-text-band'),
+  },
+  {
+    id: 'price-list-text-band',
+    sections: [section(0, 'price-list', { headings: ['Service Menu'], bodyText: ['Consulting 100', 'Implementation 250'] })],
+    options: options('price-list-text-band'),
+  },
+  {
+    id: 'app-download-text-band',
+    sections: [section(0, 'app-download', { headings: ['Get the App'], bodyText: ['Download the fictional app today.'], images: [image('app-badge.png', 220, 70)] })],
+    options: options('app-download-text-band'),
+  },
+  {
+    id: 'horizontal-showcase-text-band',
+    sections: [section(0, 'horizontal-showcase', { headings: ['Featured Work'], bodyText: ['A scrolling showcase without JS.'] })],
+    options: options('horizontal-showcase-text-band'),
+  },
+  {
+    id: 'cover-with-headline-cover',
+    sections: [
+      section(0, 'cover-with-headline', {
+        headings: ['Wide Cover Hero'],
+        bodyText: ['Text over a full bleed image.'],
+        images: [image('wide-cover.jpg', 1400, 700)],
+        fullBleed: true,
+        backgroundBrightness: 24,
+        backgroundColor: 'rgb(20, 20, 20)',
+      }),
+    ],
+    options: options('cover-with-headline-cover'),
+  },
+  {
+    id: 'cover-with-headline-media-text',
+    sections: [section(0, 'cover-with-headline', { headings: ['Side Hero'], bodyText: ['Photo beside text.'], images: [image('side-hero.jpg', 800, 600)] })],
+    options: options('cover-with-headline-media-text'),
+  },
+  {
+    id: 'animated-cover-cover',
+    sections: [section(0, 'animated-cover', { headings: ['Animated Cover'], bodyText: ['Motion-free frozen baseline.'], images: [image('animated-cover.jpg', 1500, 820)] })],
+    options: options('animated-cover-cover'),
+  },
+  {
+    id: 'media-text-alternating',
+    sections: [section(0, 'media-text', { headings: ['Media Text'], bodyText: ['Copy paired with a lead image.'], images: [image('media-text.jpg')] })],
+    options: options('media-text-alternating'),
+  },
+  {
+    id: 'columns-media-text',
+    sections: [section(0, 'columns', { headings: ['Column Story'], bodyText: ['One image in columns routes to media text.'], images: [image('columns-photo.jpg')] })],
+    options: options('columns-media-text'),
+  },
+  {
+    id: 'columns-cell-grid',
+    sections: [
+      section(0, 'columns', {
+        headings: ['Feature Columns'],
+        layout: { containerWidth: 1200, padding: '0', childLayout: 'grid', columnCount: 3, gap: '32px' },
+        cells: [
+          cell({ heading: 'Plan', body: ['Define the fictional goal.'], icon: { kind: 'glyph', glyph: '*', fontFamily: 'serif', width: 24, height: 24 } }),
+          cell({ heading: 'Build', body: ['Assemble the deterministic pieces.'] }),
+          cell({ heading: 'Ship', body: ['Verify the final artifact.'], button: 'Launch' }),
+        ],
+      }),
+    ],
+    options: options('columns-cell-grid'),
+  },
+  {
+    id: 'gallery-image-row',
+    sections: [section(0, 'gallery', { headings: ['Gallery'], images: [image('gallery-1.jpg'), image('gallery-2.jpg'), image('gallery-3.jpg')] })],
+    options: options('gallery-image-row'),
+  },
+  {
+    id: 'logo-strip-image-row',
+    sections: [section(0, 'logo-strip', { headings: ['Partners'], images: [image('logo-1.png', 180, 90), image('logo-2.png', 180, 90), image('logo-3.png', 180, 90)] })],
+    options: options('logo-strip-image-row'),
+  },
+  {
+    id: 'marquee-strip-image-row',
+    sections: [section(0, 'marquee-strip', { headings: ['Marquee'], images: [image('marquee-1.jpg'), image('marquee-2.jpg'), image('marquee-3.jpg')] })],
+    options: options('marquee-strip-image-row'),
+  },
+  {
+    id: 'color-block-grid-image-row',
+    sections: [section(0, 'color-block-grid', { headings: ['Color Blocks'], images: [image('color-1.jpg'), image('color-2.jpg'), image('color-3.jpg')] })],
+    options: options('color-block-grid-image-row'),
+  },
+  {
+    id: 'product-card-row',
+    sections: [section(0, 'product-card-row', { headings: ['Shop Products', 'Pillow', 'Blanket'], bodyText: ['$20', '$40'], images: [image('pillow.jpg'), image('blanket.jpg')], buttonLabels: ['Buy Pillow', 'Buy Blanket'] })],
+    options: options('product-card-row'),
+  },
+  {
+    id: 'project-card-grid',
+    sections: [section(0, 'project-card-grid', { headings: ['Projects', 'Atrium', 'Lobby'], bodyText: ['Glass renovation', 'Stone refresh'], images: [image('atrium.jpg'), image('lobby.jpg')] })],
+    options: options('project-card-grid'),
+  },
+  {
+    id: 'blog-card-grid',
+    sections: [section(0, 'blog-card-grid', { headings: ['Latest Notes', 'Launch Recap', 'Design Review'], bodyText: ['What changed', 'What we learned'], images: [image('post-1.jpg'), image('post-2.jpg')] })],
+    options: options('blog-card-grid'),
+  },
+  {
+    id: 'testimonial-review-grid',
+    sections: [section(0, 'testimonial', { headings: ['Customers'], reviews: [{ category: 'Service', stars: 5, quote: 'They kept every promise.', author: 'A. Customer' }] })],
+    options: options('testimonial-review-grid'),
+  },
+  {
+    id: 'review-grid',
+    sections: [
+      section(0, 'review-grid', {
+        headings: ['Reviews'],
+        reviews: [
+          { category: 'Support', stars: 5, quote: 'Fast fictional support.', author: 'Morgan' },
+          { category: 'Quality', stars: 4, quote: 'Reliable fictional quality.', author: 'Casey' },
+        ],
+      }),
+    ],
+    options: options('review-grid'),
+  },
+  {
+    id: 'faq-details',
+    sections: [section(0, 'static', { headings: ['FAQ'], faqs: [{ question: 'Do you ship?', answer: 'We ship fictional orders daily.' }] })],
+    options: options('faq-details'),
+  },
+  {
+    id: 'heading-echo-entities',
+    sections: [
+      section(0, 'static', {
+        headings: ['Food & Drink'],
+        bodyText: ['Food & Drink', 'Reservations open tonight.'],
+        sectionHtml: '<section><p class="headline">Food &amp; Drink</p><p>Reservations open tonight.</p></section>',
+      }),
+    ],
+    options: options('heading-echo-entities'),
+  },
+  {
+    id: 'missing-image-placeholder',
+    sections: [section(0, 'static', { headings: ['Remote Missing'], images: [remoteImage('missing-photo.jpg')] })],
+    options: options('missing-image-placeholder'),
+  },
+  {
+    id: 'recoverable-image-append',
+    sections: [
+      section(0, 'columns', {
+        headings: ['Recoverable Media'],
+        images: [image('recoverable.jpg', 900, 700)],
+        layout: { containerWidth: 1200, padding: '0', childLayout: 'grid', columnCount: 2, gap: '24px' },
+        cells: [
+          cell({ heading: 'One', body: ['First card body.'] }),
+          cell({ heading: 'Two', body: ['Second card body.'] }),
+        ],
+      }),
+    ],
+    options: options('recoverable-image-append'),
+  },
+  {
+    id: 'styled-island-tier',
+    sections: [
+      section(0, 'static', {
+        headings: ['Styled Island'],
+        images: [remoteImage('styled-loss.jpg')],
+        sectionHtml: '<section class="source-only"><h2>Styled Island</h2><img src="https://cdn.example.test/assets/styled-loss.jpg"></section>',
+        styledHtml: '<section style="display:grid;gap:12px"><h2>Styled Island</h2><img src="https://cdn.example.test/assets/styled-loss.jpg"></section>',
+      }),
+    ],
+    options: options('styled-island-tier'),
+  },
+  {
+    id: 'responsive-island-tier',
+    sections: [
+      section(0, 'static', {
+        headings: ['Responsive Island'],
+        images: [remoteImage('responsive-loss.jpg')],
+        sectionHtml: '<section class="wp-block-group is-layout-constrained"><h2>Responsive Island</h2><img src="https://cdn.example.test/assets/responsive-loss.jpg"></section>',
+        styledHtml: '<section style="width:1200px"><h2>Responsive Island</h2><img src="https://cdn.example.test/assets/responsive-loss.jpg"></section>',
+      }),
+    ],
+    options: options('responsive-island-tier'),
+  },
+  {
+    id: 'form-jetpack-append',
+    sections: [section(0, 'static', { headings: ['Get in Touch'], bodyText: ['Send a fictional note.'], forms: [contactForm] })],
+    options: options('form-jetpack-append'),
+  },
+  {
+    id: 'form-island-no-jetpack',
+    sections: [
+      section(0, 'static', {
+        headings: ['Contact Island'],
+        images: [remoteImage('form-fallback.jpg')],
+        forms: [contactForm],
+        sectionHtml: '<section><h2>Contact Island</h2><form><input type="email"></form><img src="https://cdn.example.test/assets/form-fallback.jpg"></section>',
+      }),
+    ],
+    options: options('form-island-no-jetpack'),
+  },
+  {
+    id: 'chrome-strip-nav-footer',
+    sections: [
+      section(0, 'nav', { headings: ['Site Nav'], bodyText: ['Home', 'About', 'Contact'], height: 80 }),
+      section(1, 'static', { headings: ['Body Section'], bodyText: ['The real page body.'] }),
+      section(2, 'footer', { headings: ['Shop', 'Support', 'Company'], bodyText: ['Copyright 2026 Example'] }),
+    ],
+    options: options('chrome-strip-nav-footer'),
+  },
+];
diff --git a/packages/blocks-engine/src/__fixtures__/page-reconstruct-dla-baseline.goldens.json b/packages/blocks-engine/src/__fixtures__/page-reconstruct-dla-baseline.goldens.json
new file mode 100644
index 00000000..1d6ccd73
--- /dev/null
+++ b/packages/blocks-engine/src/__fixtures__/page-reconstruct-dla-baseline.goldens.json
@@ -0,0 +1,854 @@
+{
+  "version": 1,
+  "cases": [
+    {
+      "id": "converted-accept",
+      "input": {
+        "convertedSections": [
+          {
+            "sectionIndex": 0,
+            "markup": "<!-- wp:heading --><h2>Converted Heading</h2><!-- /wp:heading -->\n<!-- wp:paragraph --><p>Converted body copy</p><!-- /wp:paragraph -->",
+            "wpHtmlResidue": 0
+          }
+        ]
+      },
+      "output": {
+        "body": "<!-- wp:heading --><h2>Converted Heading</h2><!-- /wp:heading -->\n<!-- wp:paragraph --><p>Converted body copy</p><!-- /wp:paragraph -->\n",
+        "expectedText": [
+          "Converted Heading"
+        ],
+        "bodyText": [
+          "Converted body copy"
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [
+          "html-to-blocks#0: converted native blocks (0 wp:html, text 100%)"
+        ],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "converted-reject-residue",
+      "input": {
+        "convertedSections": [
+          {
+            "sectionIndex": 0,
+            "markup": "<!-- wp:html --><div>unconverted residue</div><!-- /wp:html -->",
+            "wpHtmlResidue": 1
+          }
+        ]
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Residue Heading</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Structured render survives</p>\n<!-- /wp:paragraph -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Residue Heading"
+        ],
+        "bodyText": [
+          "Structured render survives"
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "converted-reject-remote-asset",
+      "input": {
+        "convertedSections": [
+          {
+            "sectionIndex": 0,
+            "markup": "<!-- wp:heading --><h2>Remote Photo</h2><!-- /wp:heading -->\n<!-- wp:image --><figure class=\"wp-block-image\"><img src=\"https://cdn.example.test/assets/remote-photo.jpg\" alt=\"\"/></figure><!-- /wp:image -->",
+            "wpHtmlResidue": 0
+          }
+        ]
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Remote Photo</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-subtle\",\"fontSize\":\"small\"} -->\n<p class=\"has-text-align-center has-text-subtle-color has-text-color has-small-font-size\">[image unavailable — not captured]</p>\n<!-- /wp:paragraph -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Remote Photo"
+        ],
+        "bodyText": [],
+        "expectedAssets": [],
+        "provenanceFlags": [
+          "static#0: image not in WP library (https://cdn.example.test/assets/remote-photo.jpg) — placeholder emitted"
+        ],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "converted-reject-placeholder",
+      "input": {
+        "convertedSections": [
+          {
+            "sectionIndex": 0,
+            "markup": "<!-- wp:heading --><h2>Template Token</h2><!-- /wp:heading -->\n<!-- wp:paragraph --><p>Hello {{ visitor }}</p><!-- /wp:paragraph -->",
+            "wpHtmlResidue": 0
+          }
+        ]
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Template Token</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Token body</p>\n<!-- /wp:paragraph -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Template Token"
+        ],
+        "bodyText": [
+          "Token body"
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "converted-reject-injection",
+      "input": {
+        "convertedSections": [
+          {
+            "sectionIndex": 0,
+            "markup": "<!-- wp:heading --><h2 onclick=\"alert(1)\">Injected Section</h2><!-- /wp:heading -->\n<!-- wp:paragraph --><p>Clean body</p><!-- /wp:paragraph -->",
+            "wpHtmlResidue": 0
+          }
+        ]
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Injected Section</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Clean body</p>\n<!-- /wp:paragraph -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Injected Section"
+        ],
+        "bodyText": [
+          "Clean body"
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "converted-reject-coverage-loss",
+      "input": {
+        "convertedSections": [
+          {
+            "sectionIndex": 0,
+            "markup": "<!-- wp:heading --><h2>Coverage Heading</h2><!-- /wp:heading -->",
+            "wpHtmlResidue": 0
+          }
+        ]
+      },
+      "output": {
+        "body": "<!-- wp:heading --><h2>Coverage Heading</h2><!-- /wp:heading -->\n",
+        "expectedText": [
+          "Coverage Heading"
+        ],
+        "bodyText": [],
+        "expectedAssets": [],
+        "provenanceFlags": [
+          "html-to-blocks#0: converted native blocks (0 wp:html, text 50%)"
+        ],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "static-text-band",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Static Band</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Plain section copy</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Read More</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Static Band",
+          "Read More"
+        ],
+        "bodyText": [
+          "Plain section copy"
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "cta-text-band",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Start Today</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">A compact call to action.</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\" href=\"/contact\">Contact Us</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Start Today",
+          "Contact Us"
+        ],
+        "bodyText": [
+          "A compact call to action."
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "price-list-text-band",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Service Menu</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Consulting 100</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Implementation 250</p>\n<!-- /wp:paragraph -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Service Menu"
+        ],
+        "bodyText": [
+          "Consulting 100",
+          "Implementation 250"
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "app-download-text-band",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Get the App</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Download the fictional app today.</p>\n<!-- /wp:paragraph -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Get the App"
+        ],
+        "bodyText": [
+          "Download the fictional app today."
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "horizontal-showcase-text-band",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Featured Work</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">A scrolling showcase without JS.</p>\n<!-- /wp:paragraph -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Featured Work"
+        ],
+        "bodyText": [
+          "A scrolling showcase without JS."
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "cover-with-headline-cover",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:cover {\"url\":\"http://localhost:8883/wp-content/uploads/2026/05/wide-cover.jpg\",\"dimRatio\":40,\"overlayColor\":\"surface-inverse\",\"isUserOverlayColor\":true,\"minHeight\":33.3,\"minHeightUnit\":\"vw\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0px\"}}},\"layout\":{\"type\":\"constrained\"}} -->\n<div class=\"wp-block-cover alignfull\" style=\"margin-top:0px;min-height:33.3vw\"><img class=\"wp-block-cover__image-background\" src=\"http://localhost:8883/wp-content/uploads/2026/05/wide-cover.jpg\" alt=\"wide-cover.jpg\" data-object-fit=\"cover\"/><span aria-hidden=\"true\" class=\"wp-block-cover__background has-surface-inverse-background-color has-background-dim-40 has-background-dim\"></span>\n<div class=\"wp-block-cover__inner-container\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-inverse\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family\">Wide Cover Hero</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-inverse\"} -->\n<p class=\"has-text-align-center has-text-inverse-color has-text-color\">Text over a full bleed image.</p>\n<!-- /wp:paragraph -->\n</div>\n</div>\n<!-- /wp:cover -->\n",
+        "expectedText": [
+          "Wide Cover Hero"
+        ],
+        "bodyText": [
+          "Text over a full bleed image."
+        ],
+        "expectedAssets": [
+          "http://localhost:8883/wp-content/uploads/2026/05/wide-cover.jpg"
+        ],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": true
+      }
+    },
+    {
+      "id": "cover-with-headline-media-text",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column {\"width\":\"55%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:55%\">\n<!-- wp:heading {\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-default-color has-text-color has-display-font-family\">Side Hero</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\">Photo beside text.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column {\"width\":\"45%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:45%\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"800px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/side-hero.jpg\" alt=\"side-hero.jpg\" style=\"width:800px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Side Hero"
+        ],
+        "bodyText": [
+          "Photo beside text."
+        ],
+        "expectedAssets": [
+          "http://localhost:8883/wp-content/uploads/2026/05/side-hero.jpg"
+        ],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "animated-cover-cover",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:cover {\"url\":\"http://localhost:8883/wp-content/uploads/2026/05/animated-cover.jpg\",\"dimRatio\":40,\"overlayColor\":\"surface-inverse\",\"isUserOverlayColor\":true,\"minHeight\":33.3,\"minHeightUnit\":\"vw\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0px\"}}},\"layout\":{\"type\":\"constrained\"}} -->\n<div class=\"wp-block-cover alignfull\" style=\"margin-top:0px;min-height:33.3vw\"><img class=\"wp-block-cover__image-background\" src=\"http://localhost:8883/wp-content/uploads/2026/05/animated-cover.jpg\" alt=\"animated-cover.jpg\" data-object-fit=\"cover\"/><span aria-hidden=\"true\" class=\"wp-block-cover__background has-surface-inverse-background-color has-background-dim-40 has-background-dim\"></span>\n<div class=\"wp-block-cover__inner-container\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-inverse\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family\">Animated Cover</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-inverse\"} -->\n<p class=\"has-text-align-center has-text-inverse-color has-text-color\">Motion-free frozen baseline.</p>\n<!-- /wp:paragraph -->\n</div>\n</div>\n<!-- /wp:cover -->\n",
+        "expectedText": [
+          "Animated Cover"
+        ],
+        "bodyText": [
+          "Motion-free frozen baseline."
+        ],
+        "expectedAssets": [
+          "http://localhost:8883/wp-content/uploads/2026/05/animated-cover.jpg"
+        ],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": true
+      }
+    },
+    {
+      "id": "media-text-alternating",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column {\"width\":\"55%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:55%\">\n<!-- wp:heading {\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-default-color has-text-color has-display-font-family\">Media Text</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\">Copy paired with a lead image.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column {\"width\":\"45%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:45%\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"800px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/media-text.jpg\" alt=\"media-text.jpg\" style=\"width:800px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Media Text"
+        ],
+        "bodyText": [
+          "Copy paired with a lead image."
+        ],
+        "expectedAssets": [
+          "http://localhost:8883/wp-content/uploads/2026/05/media-text.jpg"
+        ],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "columns-media-text",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column {\"width\":\"55%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:55%\">\n<!-- wp:heading {\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-default-color has-text-color has-display-font-family\">Column Story</h2>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\">One image in columns routes to media text.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column {\"width\":\"45%\"} -->\n<div class=\"wp-block-column\" style=\"flex-basis:45%\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"800px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/columns-photo.jpg\" alt=\"columns-photo.jpg\" style=\"width:800px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Column Story"
+        ],
+        "bodyText": [
+          "One image in columns routes to media text."
+        ],
+        "expectedAssets": [
+          "http://localhost:8883/wp-content/uploads/2026/05/columns-photo.jpg"
+        ],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "columns-cell-grid",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Feature Columns</h2>\n<!-- /wp:heading -->\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Plan</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Define the fictional goal.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Build</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Assemble the deterministic pieces.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Ship</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Verify the final artifact.</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Launch</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Feature Columns",
+          "Plan",
+          "Build",
+          "Ship",
+          "Launch"
+        ],
+        "bodyText": [
+          "Define the fictional goal.",
+          "Assemble the deterministic pieces.",
+          "Verify the final artifact."
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "gallery-image-row",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Gallery</h2>\n<!-- /wp:heading -->\n<!-- wp:gallery {\"columns\":3,\"imageCrop\":false,\"linkTo\":\"none\",\"sizeSlug\":\"large\",\"className\":\"is-gallery-scroller\"} -->\n<figure class=\"wp-block-gallery has-nested-images columns-3 is-gallery-scroller\">\n<!-- wp:image {\"width\":\"560px\",\"height\":\"420px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/gallery-1.jpg\" alt=\"gallery-1.jpg\" style=\"width:560px;height:420px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"560px\",\"height\":\"420px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/gallery-2.jpg\" alt=\"gallery-2.jpg\" style=\"width:560px;height:420px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"560px\",\"height\":\"420px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/gallery-3.jpg\" alt=\"gallery-3.jpg\" style=\"width:560px;height:420px\"/></figure>\n<!-- /wp:image -->\n</figure>\n<!-- /wp:gallery -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Gallery"
+        ],
+        "bodyText": [],
+        "expectedAssets": [
+          "http://localhost:8883/wp-content/uploads/2026/05/gallery-1.jpg",
+          "http://localhost:8883/wp-content/uploads/2026/05/gallery-2.jpg",
+          "http://localhost:8883/wp-content/uploads/2026/05/gallery-3.jpg"
+        ],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "logo-strip-image-row",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Partners</h2>\n<!-- /wp:heading -->\n<!-- wp:gallery {\"columns\":3,\"imageCrop\":true,\"linkTo\":\"none\",\"sizeSlug\":\"large\"} -->\n<figure class=\"wp-block-gallery has-nested-images columns-3 is-cropped\">\n<!-- wp:image {\"width\":\"280px\",\"height\":\"140px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/logo-1.png\" alt=\"logo-1.png\" style=\"width:280px;height:140px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"280px\",\"height\":\"140px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/logo-2.png\" alt=\"logo-2.png\" style=\"width:280px;height:140px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"280px\",\"height\":\"140px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/logo-3.png\" alt=\"logo-3.png\" style=\"width:280px;height:140px\"/></figure>\n<!-- /wp:image -->\n</figure>\n<!-- /wp:gallery -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Partners"
+        ],
+        "bodyText": [],
+        "expectedAssets": [
+          "http://localhost:8883/wp-content/uploads/2026/05/logo-1.png",
+          "http://localhost:8883/wp-content/uploads/2026/05/logo-2.png",
+          "http://localhost:8883/wp-content/uploads/2026/05/logo-3.png"
+        ],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "marquee-strip-image-row",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Marquee</h2>\n<!-- /wp:heading -->\n<!-- wp:gallery {\"columns\":3,\"imageCrop\":false,\"linkTo\":\"none\",\"sizeSlug\":\"large\",\"className\":\"is-gallery-scroller\"} -->\n<figure class=\"wp-block-gallery has-nested-images columns-3 is-gallery-scroller\">\n<!-- wp:image {\"width\":\"560px\",\"height\":\"420px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/marquee-1.jpg\" alt=\"marquee-1.jpg\" style=\"width:560px;height:420px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"560px\",\"height\":\"420px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/marquee-2.jpg\" alt=\"marquee-2.jpg\" style=\"width:560px;height:420px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"560px\",\"height\":\"420px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/marquee-3.jpg\" alt=\"marquee-3.jpg\" style=\"width:560px;height:420px\"/></figure>\n<!-- /wp:image -->\n</figure>\n<!-- /wp:gallery -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Marquee"
+        ],
+        "bodyText": [],
+        "expectedAssets": [
+          "http://localhost:8883/wp-content/uploads/2026/05/marquee-1.jpg",
+          "http://localhost:8883/wp-content/uploads/2026/05/marquee-2.jpg",
+          "http://localhost:8883/wp-content/uploads/2026/05/marquee-3.jpg"
+        ],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "color-block-grid-image-row",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Color Blocks</h2>\n<!-- /wp:heading -->\n<!-- wp:gallery {\"columns\":3,\"imageCrop\":false,\"linkTo\":\"none\",\"sizeSlug\":\"large\",\"className\":\"is-gallery-scroller\"} -->\n<figure class=\"wp-block-gallery has-nested-images columns-3 is-gallery-scroller\">\n<!-- wp:image {\"width\":\"560px\",\"height\":\"420px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/color-1.jpg\" alt=\"color-1.jpg\" style=\"width:560px;height:420px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"560px\",\"height\":\"420px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/color-2.jpg\" alt=\"color-2.jpg\" style=\"width:560px;height:420px\"/></figure>\n<!-- /wp:image -->\n<!-- wp:image {\"width\":\"560px\",\"height\":\"420px\",\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<figure class=\"wp-block-image size-large is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/color-3.jpg\" alt=\"color-3.jpg\" style=\"width:560px;height:420px\"/></figure>\n<!-- /wp:image -->\n</figure>\n<!-- /wp:gallery -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Color Blocks"
+        ],
+        "bodyText": [],
+        "expectedAssets": [
+          "http://localhost:8883/wp-content/uploads/2026/05/color-1.jpg",
+          "http://localhost:8883/wp-content/uploads/2026/05/color-2.jpg",
+          "http://localhost:8883/wp-content/uploads/2026/05/color-3.jpg"
+        ],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "product-card-row",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"800px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/pillow.jpg\" alt=\"pillow.jpg\" style=\"width:800px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Shop Products</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">$20</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Buy Pillow</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"800px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/blanket.jpg\" alt=\"blanket.jpg\" style=\"width:800px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Pillow</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">$40</p>\n<!-- /wp:paragraph -->\n<!-- wp:buttons {\"layout\":{\"type\":\"flex\",\"justifyContent\":\"center\"}} -->\n<div class=\"wp-block-buttons is-content-justification-center\">\n<!-- wp:button {\"backgroundColor\":\"accent-primary\",\"textColor\":\"text-inverse\"} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-text-inverse-color has-accent-primary-background-color has-text-color has-background wp-element-button\">Buy Blanket</a></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:buttons -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Shop Products",
+          "Buy Pillow",
+          "Pillow",
+          "Buy Blanket"
+        ],
+        "bodyText": [
+          "$20",
+          "$40"
+        ],
+        "expectedAssets": [
+          "http://localhost:8883/wp-content/uploads/2026/05/pillow.jpg",
+          "http://localhost:8883/wp-content/uploads/2026/05/blanket.jpg"
+        ],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "project-card-grid",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"800px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/atrium.jpg\" alt=\"atrium.jpg\" style=\"width:800px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Projects</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Glass renovation</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"800px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/lobby.jpg\" alt=\"lobby.jpg\" style=\"width:800px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Atrium</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Stone refresh</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Projects",
+          "Atrium"
+        ],
+        "bodyText": [
+          "Glass renovation",
+          "Stone refresh"
+        ],
+        "expectedAssets": [
+          "http://localhost:8883/wp-content/uploads/2026/05/atrium.jpg",
+          "http://localhost:8883/wp-content/uploads/2026/05/lobby.jpg"
+        ],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "blog-card-grid",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"800px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/post-1.jpg\" alt=\"post-1.jpg\" style=\"width:800px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Latest Notes</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">What changed</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"800px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/post-2.jpg\" alt=\"post-2.jpg\" style=\"width:800px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Launch Recap</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">What we learned</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Latest Notes",
+          "Launch Recap"
+        ],
+        "bodyText": [
+          "What changed",
+          "What we learned"
+        ],
+        "expectedAssets": [
+          "http://localhost:8883/wp-content/uploads/2026/05/post-1.jpg",
+          "http://localhost:8883/wp-content/uploads/2026/05/post-2.jpg"
+        ],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "testimonial-review-grid",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"backgroundColor\":\"surface-raised\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull has-surface-raised-background-color has-background\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Customers</h2>\n<!-- /wp:heading -->\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"accent-primary\"} -->\n<p class=\"has-text-align-center has-accent-primary-color has-text-color\">★★★★★</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-default\"} -->\n<p class=\"has-text-align-center has-text-default-color has-text-color\">They kept every promise.</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\",\"fontSize\":\"small\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">A. Customer</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Customers"
+        ],
+        "bodyText": [
+          "They kept every promise.",
+          "A. Customer"
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "review-grid",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"backgroundColor\":\"surface-raised\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull has-surface-raised-background-color has-background\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Reviews</h2>\n<!-- /wp:heading -->\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"accent-primary\"} -->\n<p class=\"has-text-align-center has-accent-primary-color has-text-color\">★★★★★</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-default\"} -->\n<p class=\"has-text-align-center has-text-default-color has-text-color\">Fast fictional support.</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\",\"fontSize\":\"small\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Morgan</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"accent-primary\"} -->\n<p class=\"has-text-align-center has-accent-primary-color has-text-color\">★★★★</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-default\"} -->\n<p class=\"has-text-align-center has-text-default-color has-text-color\">Reliable fictional quality.</p>\n<!-- /wp:paragraph -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\",\"fontSize\":\"small\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Casey</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Reviews"
+        ],
+        "bodyText": [
+          "Fast fictional support.",
+          "Morgan",
+          "Reliable fictional quality.",
+          "Casey"
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "faq-details",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">FAQ</h2>\n<!-- /wp:heading -->\n<!-- wp:details -->\n<details class=\"wp-block-details\"><summary>Do you ship?</summary>\n<!-- wp:paragraph {\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-muted-color has-text-color\">We ship fictional orders daily.</p>\n<!-- /wp:paragraph -->\n</details>\n<!-- /wp:details -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "FAQ",
+          "Do you ship?"
+        ],
+        "bodyText": [
+          "We ship fictional orders daily."
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "heading-echo-entities",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Food &amp; Drink</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Reservations open tonight.</p>\n<!-- /wp:paragraph -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Food & Drink"
+        ],
+        "bodyText": [
+          "Reservations open tonight."
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "missing-image-placeholder",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Remote Missing</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-subtle\",\"fontSize\":\"small\"} -->\n<p class=\"has-text-align-center has-text-subtle-color has-text-color has-small-font-size\">[image unavailable — not captured]</p>\n<!-- /wp:paragraph -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Remote Missing"
+        ],
+        "bodyText": [],
+        "expectedAssets": [],
+        "provenanceFlags": [
+          "static#0: image not in WP library (https://cdn.example.test/assets/missing-photo.jpg) — placeholder emitted"
+        ],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "recoverable-image-append",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"wideSize\":\"1100px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":2,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h2 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Recoverable Media</h2>\n<!-- /wp:heading -->\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\">\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">One</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">First card body.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h3 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Two</h3>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"fontSize\":\"small\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color has-small-font-size\">Second card body.</p>\n<!-- /wp:paragraph -->\n</div>\n<!-- /wp:column -->\n<!-- wp:column  -->\n<div class=\"wp-block-column\">\n<!-- wp:image {\"sizeSlug\":\"large\",\"width\":\"900px\",\"style\":{\"border\":{\"radius\":\"12px\"}}} -->\n<figure class=\"wp-block-image size-large has-custom-border is-resized\"><img src=\"http://localhost:8883/wp-content/uploads/2026/05/recoverable.jpg\" alt=\"recoverable.jpg\" style=\"width:900px;max-width:100%;height:auto;border-radius:12px;\"/></figure>\n<!-- /wp:image -->\n</div>\n<!-- /wp:column -->\n</div>\n<!-- /wp:columns -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Recoverable Media",
+          "One",
+          "Two"
+        ],
+        "bodyText": [
+          "First card body.",
+          "Second card body."
+        ],
+        "expectedAssets": [
+          "http://localhost:8883/wp-content/uploads/2026/05/recoverable.jpg"
+        ],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "styled-island-tier",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:html {\"metadata\":{\"name\":\"lib-coverage-island\"}} -->\n<section style=\"display:grid;gap:12px\"><h2>Styled Island</h2><img src=\"https://cdn.example.test/assets/styled-loss.jpg\"></section>\n<!-- /wp:html -->\n",
+        "expectedText": [],
+        "bodyText": [],
+        "expectedAssets": [],
+        "provenanceFlags": [
+          "html-fallback-styled#0: structured render dropped content (1 images missing, text 100%) — emitted styled core/html"
+        ],
+        "fallbackDiagnostics": [
+          {
+            "id": "styled-island-tier-s0-dropped_images",
+            "page": "https://example.test/styled-island-tier",
+            "sectionIndex": 0,
+            "interactionModel": "static",
+            "selector": "",
+            "severity": "warning",
+            "reasonCode": "dropped_images",
+            "islandKind": "styled",
+            "droppedImages": [
+              "https://cdn.example.test/assets/styled-loss.jpg"
+            ],
+            "textCoverage": 1,
+            "suggestedRepairClass": "recover_dropped_media",
+            "sourceHtmlPreview": "<section style=\"display:grid;gap:12px\"><h2>Styled Island</h2><img src=\"https://cdn.example.test/assets/styled-loss.jpg\"></section>",
+            "emittedBlockPreview": "<!-- wp:html {\"metadata\":{\"name\":\"lib-coverage-island\"}} -->\n<section style=\"display:grid;gap:12px\"><h2>Styled Island</h2><img src=\"https://cdn.example.test/assets/styled-loss.jpg\"></section>\n<!-- /wp"
+          }
+        ],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "responsive-island-tier",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:html {\"metadata\":{\"name\":\"lib-coverage-island\"}} -->\n<section class=\"wp-block-group is-layout-constrained\"><h2>Responsive Island</h2><img src=\"https://cdn.example.test/assets/responsive-loss.jpg\"></section>\n<!-- /wp:html -->\n",
+        "expectedText": [],
+        "bodyText": [],
+        "expectedAssets": [],
+        "provenanceFlags": [
+          "html-fallback-responsive#0: structured render dropped content (1 images missing, text 100%) — emitted responsive core/html"
+        ],
+        "fallbackDiagnostics": [
+          {
+            "id": "responsive-island-tier-s0-dropped_images",
+            "page": "https://example.test/responsive-island-tier",
+            "sectionIndex": 0,
+            "interactionModel": "static",
+            "selector": "",
+            "severity": "warning",
+            "reasonCode": "dropped_images",
+            "islandKind": "responsive",
+            "droppedImages": [
+              "https://cdn.example.test/assets/responsive-loss.jpg"
+            ],
+            "textCoverage": 1,
+            "suggestedRepairClass": "recover_dropped_media",
+            "sourceHtmlPreview": "<section style=\"width:1200px\"><h2>Responsive Island</h2><img src=\"https://cdn.example.test/assets/responsive-loss.jpg\"></section>",
+            "emittedBlockPreview": "<!-- wp:html {\"metadata\":{\"name\":\"lib-coverage-island\"}} -->\n<section class=\"wp-block-group is-layout-constrained\"><h2>Responsive Island</h2><img src=\"https://cdn.example.test/assets/responsive-loss.j"
+          }
+        ],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "form-jetpack-append",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Get in Touch</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">Send a fictional note.</p>\n<!-- /wp:paragraph -->\n<!-- wp:jetpack/contact-form {\"style\":{\"spacing\":{\"padding\":{\"top\":\"16px\",\"right\":\"16px\",\"bottom\":\"16px\",\"left\":\"16px\"}}}} -->\n<div class=\"wp-block-jetpack-contact-form\">\n<!-- wp:jetpack/field-name {\"label\":\"Full name\",\"required\":true,\"width\":50} /-->\n<!-- wp:jetpack/field-email {\"label\":\"Email address\",\"required\":true,\"width\":50} /-->\n<!-- wp:jetpack/field-select {\"label\":\"Topic\",\"options\":[\"Billing\",\"Support\"]} /-->\n<!-- wp:jetpack/field-textarea {\"label\":\"Message\"} /-->\n<!-- wp:button {\"tagName\":\"button\",\"type\":\"submit\",\"lock\":{\"remove\":true},\"className\":\"form-button-submit is-submit\",\"metadata\":{\"name\":\"Submit button\"}} -->\n<div class=\"wp-block-button form-button-submit is-submit\"><button type=\"submit\" class=\"wp-block-button__link wp-element-button\">Send Message</button></div>\n<!-- /wp:button -->\n</div>\n<!-- /wp:jetpack/contact-form -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Get in Touch",
+          "Full name",
+          "Email address",
+          "Topic",
+          "Billing",
+          "Support",
+          "Message",
+          "Send Message"
+        ],
+        "bodyText": [
+          "Send a fictional note."
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [
+          "form-field-skipped#0: hidden field \"Campaign id\" has no Jetpack form equivalent"
+        ],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "form-island-no-jetpack",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:html {\"metadata\":{\"name\":\"lib-coverage-island\"}} -->\n<section><h2>Contact Island</h2><form><input type=\"email\"></form><img src=\"https://cdn.example.test/assets/form-fallback.jpg\"></section>\n<!-- /wp:html -->\n",
+        "expectedText": [],
+        "bodyText": [],
+        "expectedAssets": [],
+        "provenanceFlags": [
+          "html-fallback#0: structured render dropped content (1 images missing, text 100%) — emitted verbatim core/html"
+        ],
+        "fallbackDiagnostics": [
+          {
+            "id": "form-island-no-jetpack-s0-dropped_images",
+            "page": "https://example.test/form-island-no-jetpack",
+            "sectionIndex": 0,
+            "interactionModel": "static",
+            "selector": "",
+            "severity": "warning",
+            "reasonCode": "dropped_images",
+            "islandKind": "verbatim",
+            "droppedImages": [
+              "https://cdn.example.test/assets/form-fallback.jpg"
+            ],
+            "textCoverage": 1,
+            "suggestedRepairClass": "recover_dropped_media",
+            "sourceHtmlPreview": "<section><h2>Contact Island</h2><form><input type=\"email\"></form><img src=\"https://cdn.example.test/assets/form-fallback.jpg\"></section>",
+            "emittedBlockPreview": "<!-- wp:html {\"metadata\":{\"name\":\"lib-coverage-island\"}} -->\n<section><h2>Contact Island</h2><form><input type=\"email\"></form><img src=\"https://cdn.example.test/assets/form-fallback.jpg\"></section>\n<!"
+          }
+        ],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    },
+    {
+      "id": "chrome-strip-nav-footer",
+      "input": {
+        "convertedSections": []
+      },
+      "output": {
+        "body": "<!-- wp:group {\"tagName\":\"section\",\"align\":\"full\",\"style\":{\"spacing\":{\"margin\":{\"top\":\"0\",\"bottom\":\"0\"},\"padding\":{\"top\":\"var:preset|spacing|60\",\"bottom\":\"var:preset|spacing|60\",\"left\":\"var:preset|spacing|40\",\"right\":\"var:preset|spacing|40\"},\"blockGap\":\"var:preset|spacing|40\"}},\"layout\":{\"type\":\"constrained\",\"contentSize\":\"760px\"}} -->\n<section class=\"wp-block-group alignfull\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)\">\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"fontFamily\":\"display\",\"textColor\":\"text-default\"} -->\n<h1 class=\"wp-block-heading has-text-align-center has-text-default-color has-text-color has-display-font-family\">Body Section</h1>\n<!-- /wp:heading -->\n<!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"text-muted\"} -->\n<p class=\"has-text-align-center has-text-muted-color has-text-color\">The real page body.</p>\n<!-- /wp:paragraph -->\n</section>\n<!-- /wp:group -->\n",
+        "expectedText": [
+          "Body Section"
+        ],
+        "bodyText": [
+          "The real page body."
+        ],
+        "expectedAssets": [],
+        "provenanceFlags": [],
+        "fallbackDiagnostics": [],
+        "iconAssets": [],
+        "heroIsCover": false
+      }
+    }
+  ]
+}
diff --git a/packages/blocks-engine/src/__tests__/theme-reconstruct-dla-baseline-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-reconstruct-dla-baseline-parity.test.ts
new file mode 100644
index 00000000..198896f3
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-reconstruct-dla-baseline-parity.test.ts
@@ -0,0 +1,132 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+import {
+  reconstructBaselineCases,
+  type FrozenConvertedSection,
+  type FrozenReconstructCase,
+} from '../__fixtures__/page-reconstruct-dla-baseline.corpus.js';
+import { reconstructNativeAggregate } from '../theme/reconstruct.js';
+import type { SectionRenderOptions } from '../theme/native-reconstruct-types.js';
+
+interface BaselineOutput {
+  body: string;
+  expectedText: string[];
+  bodyText: string[];
+  expectedAssets: string[];
+  provenanceFlags: string[];
+  fallbackDiagnostics: unknown[];
+  iconAssets: Array<{ path: string; svg: string }>;
+  heroIsCover: boolean;
+}
+
+interface BaselineRecord {
+  id: string;
+  input: {
+    convertedSections: FrozenConvertedSection[];
+  };
+  output: BaselineOutput;
+}
+
+interface BaselineFile {
+  version: 1;
+  cases: BaselineRecord[];
+}
+
+const GOLDEN_PATH = fileURLToPath(
+  new URL('../__fixtures__/page-reconstruct-dla-baseline.goldens.json', import.meta.url),
+);
+
+function hydrateOptions(testCase: FrozenReconstructCase): SectionRenderOptions {
+  const { convertedSections, ...rest } = testCase.options;
+  return {
+    ...rest,
+    ...(convertedSections
+      ? {
+          convertedSections: new Map(
+            convertedSections.map((entry) => [
+              entry.sectionIndex,
+              { markup: entry.markup, wpHtmlResidue: entry.wpHtmlResidue },
+            ]),
+          ),
+        }
+      : {}),
+  };
+}
+
+function freezeResult(testCase: FrozenReconstructCase): BaselineOutput {
+  const aggregate = reconstructNativeAggregate(testCase.sections, hydrateOptions(testCase));
+  return {
+    body: aggregate.sectionMarkup.join('\n\n') + '\n',
+    expectedText: aggregate.expectedText,
+    bodyText: aggregate.bodyText,
+    expectedAssets: aggregate.expectedAssets,
+    provenanceFlags: aggregate.provenanceFlags,
+    fallbackDiagnostics: aggregate.fallbackDiagnostics,
+    iconAssets: aggregate.iconAssets,
+    heroIsCover: aggregate.heroIsCover,
+  };
+}
+
+function runCorpus(): BaselineFile {
+  return {
+    version: 1,
+    cases: reconstructBaselineCases.map((testCase) => ({
+      id: testCase.id,
+      input: {
+        convertedSections: testCase.options.convertedSections ?? [],
+      },
+      output: freezeResult(testCase),
+    })),
+  };
+}
+
+function readGolden(): BaselineFile {
+  if (!existsSync(GOLDEN_PATH)) {
+    throw new Error(`Missing DLA reconstruct baseline golden: ${GOLDEN_PATH}`);
+  }
+  return JSON.parse(readFileSync(GOLDEN_PATH, 'utf8')) as BaselineFile;
+}
+
+function stableJson(value: unknown): string {
+  return JSON.stringify(value, null, 2);
+}
+
+function collectDiffs(actual: BaselineFile, expected: BaselineFile): string[] {
+  const diffs: string[] = [];
+  if (actual.version !== expected.version) diffs.push(`version: expected ${expected.version}, got ${actual.version}`);
+
+  const expectedById = new Map(expected.cases.map((record) => [record.id, record]));
+  for (const actualCase of actual.cases) {
+    const expectedCase = expectedById.get(actualCase.id);
+    if (!expectedCase) {
+      diffs.push(`${actualCase.id}: missing from checked-in goldens`);
+      continue;
+    }
+    if (stableJson(actualCase.input) !== stableJson(expectedCase.input)) {
+      diffs.push(`${actualCase.id}: frozen input changed`);
+    }
+    if (stableJson(actualCase.output) !== stableJson(expectedCase.output)) {
+      diffs.push(`${actualCase.id}: output changed`);
+    }
+  }
+
+  const actualIds = new Set(actual.cases.map((record) => record.id));
+  for (const expectedCase of expected.cases) {
+    if (!actualIds.has(expectedCase.id)) diffs.push(`${expectedCase.id}: golden has no corpus case`);
+  }
+  return diffs;
+}
+
+describe('theme reconstruct DLA-today baseline parity', () => {
+  it('matches the 35-case DLA baseline and is byte-stable across two runs', () => {
+    const first = runCorpus();
+    const second = runCorpus();
+    expect(collectDiffs(first, second)).toEqual([]);
+
+    const diffs = collectDiffs(first, readGolden());
+    console.info(`Engine reconstruct DLA baseline parity: cases=${first.cases.length} diffs=${diffs.length}`);
+    expect(diffs).toEqual([]);
+  });
+});
diff --git a/packages/blocks-engine/src/__tests__/theme-reconstruct.test.ts b/packages/blocks-engine/src/__tests__/theme-reconstruct.test.ts
index eff833c7..8fe89599 100644
--- a/packages/blocks-engine/src/__tests__/theme-reconstruct.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-reconstruct.test.ts
@@ -70,36 +70,36 @@ function fakePool(markupForInput: (html: string) => string): WorkerPool {
   };
 }
 
-function stageCtx(): StageCtx {
+function stageCtx(overrides: Partial<StageCtx> & Record<string, unknown> = {}): StageCtx {
   return {
     srcDir: '/tmp/site',
     site: { root: '/tmp/site', pages: [] },
     themeMeta: { name: 'Fixture Theme', slug: 'fixture-theme' },
     warn() {},
+    ...overrides,
   };
 }
 
 describe('theme reconstruct coverage gate', () => {
-  it('falls back from lossy native blocks to a verbatim coverage island', async () => {
+  it('falls back from native dispatch loss to a verbatim coverage island', async () => {
+    const remoteImage = 'https://cdn.example.com/uploads/hero.jpg';
     const spec = sectionSpec({
       headings: ['Build calmer block themes'],
       bodyText: ['Static source pages become a structured theme pipeline.'],
-      buttonLabels: ['Learn more'],
+      images: [sectionImage(remoteImage)],
       sectionHtml: [
         '<section id="hero">',
         '<h1>Build calmer block themes</h1>',
         '<p>Static source pages become a structured theme pipeline.</p>',
-        '<a class="button" href="./about.html">Learn more</a>',
+        `<img src="${remoteImage}" alt="Hero image">`,
         '</section>',
       ].join(''),
     });
-    const lossyNative =
-      '<!-- wp:buttons -->\n<div class="wp-block-buttons">Learn more</div>\n<!-- /wp:buttons -->';
 
     const [section] = await reconstruct(
       [spec],
       stageCtx(),
-      fakePool(() => lossyNative),
+      fakePool(() => ''),
       {},
       0
     );
@@ -109,40 +109,33 @@ describe('theme reconstruct coverage gate', () => {
     expect(section.blocks).toContain(
       '<p>Static source pages become a structured theme pipeline.</p>'
     );
-    expect(section.blocks).not.toBe(lossyNative);
     expect(measureSectionCoverage(captureSectionContent(spec), section.blocks).lost).toBe(false);
     expect(section.coverage).toBe(0);
   });
 
-  it('keeps full-coverage native blocks unchanged', async () => {
+  it('keeps full-coverage native dispatch blocks', async () => {
     const spec = sectionSpec({
       headings: ['Native heading'],
       bodyText: ['Native body copy.'],
       sectionHtml: '<section><h2>Native heading</h2><p>Native body copy.</p></section>',
     });
-    const nativeBlocks = [
-      '<!-- wp:heading -->',
-      '<h2>Native heading</h2>',
-      '<!-- /wp:heading -->',
-      '<!-- wp:paragraph -->',
-      '<p>Native body copy.</p>',
-      '<!-- /wp:paragraph -->',
-    ].join('\n');
 
     const [section] = await reconstruct(
       [spec],
       stageCtx(),
-      fakePool(() => nativeBlocks),
+      fakePool(() => ''),
       {},
       0
     );
 
-    expect(section.blocks).toBe(nativeBlocks);
+    expect(section.blocks).toContain('<!-- wp:group');
+    expect(section.blocks).toContain('Native heading');
+    expect(section.blocks).toContain('Native body copy.');
     expect(section.blocks).not.toContain('lib-coverage-island');
     expect(section.coverage).toBe(1);
   });
 
-  it('falls back from converted native blocks with unmigrated remote assets to an island', async () => {
+  it('rejects injected converted native blocks with unmigrated remote assets', async () => {
     const remoteImage = 'https://cdn.example.com/uploads/hero.jpg';
     const spec = sectionSpec({
       headings: ['Remote asset hero'],
@@ -172,8 +165,10 @@ describe('theme reconstruct coverage gate', () => {
 
     const [section] = await reconstruct(
       [spec],
-      stageCtx(),
-      fakePool(() => convertedNative),
+      stageCtx({
+        convertedSections: new Map([[spec.sectionIndex, { markup: convertedNative, wpHtmlResidue: 0 }]]),
+      }),
+      fakePool(() => ''),
       {},
       0
     );
@@ -183,7 +178,7 @@ describe('theme reconstruct coverage gate', () => {
     expect(section.coverage).toBe(0);
   });
 
-  it('falls back from converted native blocks with injection or placeholders to an island', async () => {
+  it('rejects injected converted native blocks with injection or placeholders', async () => {
     const injectionSpec = sectionSpec({
       headings: ['Safe hero'],
       bodyText: ['Fallback copy survives.'],
@@ -202,16 +197,18 @@ describe('theme reconstruct coverage gate', () => {
 
     const [injectedSection] = await reconstruct(
       [injectionSpec],
-      stageCtx(),
-      fakePool(() => injectedNative),
+      stageCtx({
+        convertedSections: new Map([[injectionSpec.sectionIndex, { markup: injectedNative, wpHtmlResidue: 0 }]]),
+      }),
+      fakePool(() => ''),
       {},
       0
     );
 
-    expect(injectedSection.blocks).toContain('metadata":{"name":"lib-coverage-island"}');
-    expect(injectedSection.blocks).toContain('<p>Fallback copy survives.</p>');
+    expect(injectedSection.blocks).toContain('Fallback copy survives.');
     expect(injectedSection.blocks).not.toContain('<script');
     expect(injectedSection.blocks).not.toBe(injectedNative);
+    expect(injectedSection.coverage).toBe(1);
 
     const placeholderSpec = sectionSpec({
       headings: ['Personalized hero'],
@@ -232,19 +229,21 @@ describe('theme reconstruct coverage gate', () => {
 
     const [placeholderSection] = await reconstruct(
       [placeholderSpec],
-      stageCtx(),
-      fakePool(() => placeholderNative),
+      stageCtx({
+        convertedSections: new Map([[placeholderSpec.sectionIndex, { markup: placeholderNative, wpHtmlResidue: 0 }]]),
+      }),
+      fakePool(() => ''),
       {},
       0
     );
 
-    expect(placeholderSection.blocks).toContain('metadata":{"name":"lib-coverage-island"}');
-    expect(placeholderSection.blocks).toContain('<p>Clean fallback copy.</p>');
+    expect(placeholderSection.blocks).toContain('Clean fallback copy.');
     expect(placeholderSection.blocks).not.toContain('{{first-name}}');
     expect(placeholderSection.blocks).not.toBe(placeholderNative);
+    expect(placeholderSection.coverage).toBe(1);
   });
 
-  it('keeps converted native blocks when converted coverage matches image basename', async () => {
+  it('keeps injected converted native blocks when converted coverage matches image basename', async () => {
     const remoteImage = 'https://cdn.example.com/uploads/hero.jpg?width=1200';
     const uploadsImage = '/wp-content/uploads/2026/06/hero.jpg';
     const spec = sectionSpec({
@@ -273,8 +272,11 @@ describe('theme reconstruct coverage gate', () => {
 
     const [section] = await reconstruct(
       [spec],
-      stageCtx(),
-      fakePool(() => nativeBlocks),
+      stageCtx({
+        mediaUrlMap: new Map([[remoteImage, uploadsImage]]),
+        convertedSections: new Map([[spec.sectionIndex, { markup: nativeBlocks, wpHtmlResidue: 0 }]]),
+      }),
+      fakePool(() => ''),
       {},
       0
     );
@@ -285,26 +287,43 @@ describe('theme reconstruct coverage gate', () => {
     expect(section.coverage).toBe(1);
   });
 
-  it('keeps existing onSection coverage-floor gating after fallback', async () => {
-    const spec = sectionSpec({
+  it('fires onSection for low coverage and form remainder, not full-coverage non-form sections', async () => {
+    const lowCoverage = sectionSpec({
+      sectionIndex: 0,
       headings: ['Hooked hero'],
-      bodyText: ['Copy that should survive.'],
-      buttonLabels: ['Act now'],
+      images: [sectionImage('https://cdn.example.com/uploads/missing.jpg')],
       sectionHtml:
-        '<section><h1>Hooked hero</h1><p>Copy that should survive.</p><a>Act now</a></section>',
+        '<section><h1>Hooked hero</h1><img src="https://cdn.example.com/uploads/missing.jpg"></section>',
     });
-    const seenCoverages: number[] = [];
+    const formSection = sectionSpec({
+      sectionIndex: 1,
+      headings: ['Contact us'],
+      bodyText: ['Send a note.'],
+      forms: [
+        {
+          fields: [{ kind: 'email', label: 'Email', required: true }],
+          submitLabel: 'Send',
+        },
+      ],
+    });
+    const fullCoverage = sectionSpec({
+      sectionIndex: 2,
+      headings: ['Plain section'],
+      bodyText: ['No hook needed.'],
+    });
+    const seen: Array<{ sectionIndex: number; coverage: number; forms: number }> = [];
 
-    const [section] = await reconstruct(
-      [spec],
+    const sections = await reconstruct(
+      [lowCoverage, formSection, fullCoverage],
       stageCtx(),
-      fakePool(
-        () =>
-          '<!-- wp:buttons -->\n<div class="wp-block-buttons">Act now</div>\n<!-- /wp:buttons -->'
-      ),
+      fakePool(() => ''),
       {
         async onSection(section) {
-          seenCoverages.push(section.coverage);
+          seen.push({
+            sectionIndex: section.spec.sectionIndex,
+            coverage: section.coverage,
+            forms: section.remainder?.forms.length ?? 0,
+          });
           return {
             ...section,
             blocks: `${section.blocks}\n<!-- hooked -->`,
@@ -314,8 +333,15 @@ describe('theme reconstruct coverage gate', () => {
       0
     );
 
-    expect(seenCoverages).toEqual([0]);
-    expect(section.blocks).toContain('lib-coverage-island');
-    expect(section.blocks).toContain('<!-- hooked -->');
+    expect(seen).toEqual([
+      { sectionIndex: 0, coverage: 0, forms: 0 },
+      { sectionIndex: 1, coverage: 1, forms: 1 },
+    ]);
+    expect(sections[0].blocks).toContain('lib-coverage-island');
+    expect(sections[0].blocks).toContain('<!-- hooked -->');
+    expect(sections[1].blocks).toContain('jetpack/contact-form');
+    expect(sections[1].blocks).toContain('<!-- hooked -->');
+    expect(sections[2].coverage).toBe(1);
+    expect(sections[2].blocks).not.toContain('<!-- hooked -->');
   });
 });
diff --git a/packages/blocks-engine/src/theme/reconstruct.ts b/packages/blocks-engine/src/theme/reconstruct.ts
index 070702ef..fd4943d2 100644
--- a/packages/blocks-engine/src/theme/reconstruct.ts
+++ b/packages/blocks-engine/src/theme/reconstruct.ts
@@ -1,108 +1,446 @@
-import { convert } from '../convert.js';
-import { escapeHtmlAttr, escapeHtmlText } from '../escape.js';
+import * as cheerio from 'cheerio';
 import type { WorkerPool } from '../pool/types.js';
+import { buildFallbackDiagnostic } from './fallback-diagnostic.js';
+import { formToBlocks, SKIPPED_FIELD_KINDS } from './form-blocks.js';
 import { buildHtmlFallbackBlock, selectIslandSource, type HtmlFallbackOpts } from './html-fallback.js';
 import { hasUnmigratedRemoteAsset, scanForInjection } from './injection-scan.js';
-import { captureSectionContent, measureConvertedCoverage } from './section-coverage.js';
-import type { SectionSpec, SectionSpecButton, SectionSpecImage } from './section-spec.js';
+import { imageBlock, visibleText } from './native-block-builders.js';
+import { nearestFamily } from './native-fonts.js';
+import { centerOf } from './native-layout.js';
+import { isWpMediaUrl } from './native-media.js';
+import { renderSection } from './native-renderers-dispatch.js';
+import type {
+  ConvertedSectionInput,
+  NativeReconstructAggregate,
+  NativeRenderCtx,
+  NativeRenderOut,
+  NativeSectionDecision,
+  SectionRenderOptions,
+} from './native-reconstruct-types.js';
+import { normalizeCopy, stripChrome } from './page-reconstruct-helpers.js';
+import {
+  captureSectionContent,
+  foldText,
+  measureConvertedCoverage,
+  measureSectionCoverage,
+} from './section-coverage.js';
+import type { CapturedSectionContent, CoverageResult } from './section-coverage.js';
+import type { SectionSpec, SectionSpecCell, SectionSpecImage } from './section-spec.js';
 import type { SectionBlocks, SiteToThemeHooks, StageCtx } from './types.js';
 import { rewriteMediaUrls } from './url-rewrite.js';
 import type { InternalLinkMap } from './url-rewrite.js';
 
-const BLOCK_COMMENT_RE = /<!--\s+wp:/;
 const HTML_ISLAND_RE = /<!--\s+wp:(?:core\/)?html(?:\s|-->|{)/;
 const UNRESOLVED_PLACEHOLDER_RE = /\{\{[\w -]+\}\}/;
+const MIN_CELL_IMAGE_PX = 90;
+const SECTION_CLOSE = '</section>\n<!-- /wp:group -->';
 
-type RewriteCtx = StageCtx & {
-  mediaUrlMap?: Map<string, string>;
+type RewriteCtx = StageCtx & SectionRenderOptions & {
   linkMap?: InternalLinkMap;
 };
 
-function nonEmpty(value: string | null | undefined): string | null {
-  const trimmed = value?.trim();
-  return trimmed ? trimmed : null;
+function fallbackOptions(options: SectionRenderOptions | RewriteCtx): HtmlFallbackOpts {
+  const rewriteCtx = options as RewriteCtx;
+  const opts: HtmlFallbackOpts = {};
+  if (rewriteCtx.mediaUrlMap) opts.mediaUrlMap = rewriteCtx.mediaUrlMap;
+  if (rewriteCtx.linkMap) opts.linkMap = rewriteCtx.linkMap;
+  return opts;
+}
+
+function rewriteConvertedMedia(blocks: string, options: SectionRenderOptions): string {
+  const mediaUrlMap = options.mediaUrlMap;
+  return mediaUrlMap && mediaUrlMap.size > 0 ? rewriteMediaUrls(blocks, mediaUrlMap) : blocks;
+}
+
+function convertedOutputLost(captured: CapturedSectionContent, blocks: string): CoverageResult | null {
+  if (
+    scanForInjection(blocks).length > 0 ||
+    hasUnmigratedRemoteAsset(blocks) ||
+    UNRESOLVED_PLACEHOLDER_RE.test(blocks)
+  ) {
+    return null;
+  }
+  const coverage = measureConvertedCoverage(captured, blocks);
+  return coverage.lost ? null : coverage;
 }
 
-function imageHtml(image: SectionSpecImage): string | null {
-  const src = nonEmpty(image.url) ?? nonEmpty(image.sourceUrl);
-  if (!src) return null;
+function publicCoverage(blocks: string, coverage: CoverageResult): number {
+  if (HTML_ISLAND_RE.test(blocks)) return 0;
+  return coverage.lost ? 0 : 1;
+}
 
-  const alt = escapeHtmlAttr(image.alt);
-  return `<figure><img src="${escapeHtmlAttr(src)}" alt="${alt}"></figure>`;
+function dedupe(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))];
 }
 
-function buttonHtml(button: SectionSpecButton): string | null {
-  const label = nonEmpty(button.label);
-  if (!label) return null;
+function nativeCapturedContent(section: SectionSpec): CapturedSectionContent {
+  const captured = captureSectionContent(section);
+  if (captured.images.length > 0 || !(section.sectionHtml || section.styledHtml)) return captured;
 
-  const href = nonEmpty(button.href) ?? '#';
-  return `<p><a href="${escapeHtmlAttr(href)}">${escapeHtmlText(label)}</a></p>`;
+  const source = section.sectionHtml ?? section.styledHtml ?? '';
+  const $ = cheerio.load(source, null, false);
+  const sourceImages = $('img[src]')
+    .map((_, element) => $(element).attr('src')?.trim() ?? '')
+    .get()
+    .filter(Boolean);
+
+  return sourceImages.length ? { ...captured, images: dedupe(sourceImages) } : captured;
 }
 
-function semanticFallbackHtml(spec: SectionSpec): string {
-  const fragments: string[] = [];
+function normalizeSections(sections: SectionSpec[], options: SectionRenderOptions): SectionSpec[] {
+  const famTokens = options.fontFamilies ?? [];
+  const resolveFamilies = (names?: string[]): string[] | undefined =>
+    names ? names.map((name) => nearestFamily(name, famTokens) ?? '') : undefined;
 
-  for (const [index, heading] of spec.headings.entries()) {
-    const text = nonEmpty(heading);
-    if (!text) continue;
+  return stripChrome(sections).map((section) => {
+    const headFamSlugs = resolveFamilies(section.headingFamilies);
+    const bodyFamSlugs = resolveFamilies(section.bodyFamilies);
+    let out = section;
+    if (headFamSlugs || bodyFamSlugs) {
+      out = {
+        ...out,
+        ...(headFamSlugs ? { headingFamilies: headFamSlugs } : {}),
+        ...(bodyFamSlugs ? { bodyFamilies: bodyFamSlugs } : {}),
+      };
+    }
 
-    const level = index === 0 ? 2 : 3;
-    fragments.push(`<h${level}>${escapeHtmlText(text)}</h${level}>`);
-  }
+    const sourceHtml = section.sectionHtml ?? section.styledHtml;
+    if (!(sourceHtml && (out.bodyText ?? []).length && out.headings.length)) return out;
 
-  for (const body of spec.bodyText) {
-    const text = nonEmpty(body);
-    if (text) fragments.push(`<p>${escapeHtmlText(text)}</p>`);
+    const sourceText = foldText(cheerio.load(sourceHtml, null, false).root().text());
+    const headingSet = new Set(out.headings.map((heading) => foldText(heading)));
+    const countOccurrences = (needle: string): number => {
+      if (!needle) return 0;
+      let count = 0;
+      for (
+        let index = sourceText.indexOf(needle);
+        index !== -1;
+        index = sourceText.indexOf(needle, index + needle.length)
+      ) {
+        count++;
+      }
+      return count;
+    };
+    const keep = (out.bodyText ?? []).map((body) => {
+      const normalized = foldText(body);
+      return !(headingSet.has(normalized) && countOccurrences(normalized) === 1);
+    });
+
+    if (!keep.includes(false)) return out;
+
+    const filterAligned = <T>(arr: T[]): T[] => arr.filter((_, index) => keep[index] !== false);
+    return {
+      ...out,
+      bodyText: (out.bodyText ?? []).filter((_, index) => keep[index]),
+      ...(out.bodyTextSizes ? { bodyTextSizes: filterAligned(out.bodyTextSizes) } : {}),
+      ...(out.bodyFamilies ? { bodyFamilies: filterAligned(out.bodyFamilies) } : {}),
+      ...(out.bodyLineHeights ? { bodyLineHeights: filterAligned(out.bodyLineHeights) } : {}),
+    };
+  });
+}
+
+function renderSectionForms(section: SectionSpec, expectedText: string[], flags: string[]): string {
+  if (!section.forms || section.forms.length === 0) return '';
+  const parts: string[] = [];
+  for (const form of section.forms) {
+    const formBlocks = formToBlocks(form);
+    parts.push(formBlocks.markup);
+    for (const field of form.fields) {
+      if (SKIPPED_FIELD_KINDS.has(field.kind)) continue;
+      expectedText.push(field.label, ...(field.options ?? []));
+    }
+    expectedText.push(form.submitLabel);
+    for (const skipped of formBlocks.skipped) {
+      flags.push(
+        `form-field-skipped#${section.sectionIndex}: ${skipped.kind} field "${skipped.label}" has no Jetpack form equivalent`,
+      );
+    }
   }
+  return parts.join('\n');
+}
 
-  const structuredButtons =
-    spec.buttons?.map(buttonHtml).filter((html): html is string => html !== null) ?? [];
-  const labelButtons = spec.buttonLabels
-    .map((label) => nonEmpty(label))
-    .filter((label): label is string => label !== null)
-    .map((label) => `<p><a href="#">${escapeHtmlText(label)}</a></p>`);
-  const buttons = structuredButtons.length > 0 ? structuredButtons : labelButtons;
-  fragments.push(...buttons);
+function suppressFormEchoes(section: SectionSpec): SectionSpec {
+  if (!section.forms || section.forms.length === 0) return section;
 
-  fragments.push(...spec.images.map(imageHtml).filter((html): html is string => html !== null));
+  const submitBudget = (): Map<string, number> => {
+    const budget = new Map<string, number>();
+    for (const form of section.forms ?? []) {
+      const key = normalizeCopy(form.submitLabel).toLowerCase();
+      budget.set(key, (budget.get(key) ?? 0) + 1);
+    }
+    return budget;
+  };
+  const dropOncePerSubmit = (budget: Map<string, number>) => (label: string) => {
+    const key = normalizeCopy(label).toLowerCase();
+    const left = budget.get(key) ?? 0;
+    if (left > 0) {
+      budget.set(key, left - 1);
+      return false;
+    }
+    return true;
+  };
+  const keepLabel = dropOncePerSubmit(submitBudget());
+  const keepButton = dropOncePerSubmit(submitBudget());
+  const keepCellButton = dropOncePerSubmit(submitBudget());
 
-  return fragments.length > 0 ? `<section>${fragments.join('')}</section>` : '<section></section>';
+  const fieldBudget = new Map<string, number>();
+  for (const form of section.forms ?? []) {
+    for (const field of form.fields) {
+      const key = normalizeCopy(field.label).toLowerCase();
+      fieldBudget.set(key, (fieldBudget.get(key) ?? 0) + 1);
+    }
+  }
+  const cellIsFieldEcho = (cell: SectionSpecCell): boolean => {
+    if (!cell.heading || cell.image || cell.icon || cell.button) return false;
+    if ((cell.body ?? []).some((body) => /[a-z0-9]/i.test(normalizeCopy(body)))) return false;
+    const key = normalizeCopy(cell.heading).toLowerCase();
+    const left = fieldBudget.get(key) ?? 0;
+    if (left <= 0) return false;
+    fieldBudget.set(key, left - 1);
+    return true;
+  };
+  const cellsSansFieldEchoes = section.cells?.filter((cell) => !cellIsFieldEcho(cell));
+
+  return (
+    {
+      ...section,
+      buttonLabels: (section.buttonLabels ?? []).filter(keepLabel),
+      ...(section.buttons ? { buttons: section.buttons.filter((button) => keepButton(button.label)) } : {}),
+      ...(cellsSansFieldEchoes
+        ? {
+            cells: cellsSansFieldEchoes.map((cell) => {
+              if (!(cell.button && !keepCellButton(cell.button))) return cell;
+              const headingEchoesButton =
+                cell.heading != null &&
+                normalizeCopy(cell.heading).toLowerCase() === normalizeCopy(cell.button).toLowerCase();
+              return { ...cell, button: null, ...(headingEchoesButton ? { heading: null } : {}) };
+            }),
+          }
+        : {}),
+    }
+  );
 }
 
-function sectionInputHtml(spec: SectionSpec): string {
-  return spec.sectionHtml?.trim() ? spec.sectionHtml : semanticFallbackHtml(spec);
+function appendFormBlock(out: NativeRenderOut, formBlock: string): void {
+  if (!formBlock) return;
+  out.remainder = { forms: out.remainder?.forms ?? [] };
+  out.markup = out.markup.endsWith(SECTION_CLOSE)
+    ? out.markup.slice(0, -SECTION_CLOSE.length) + formBlock + '\n' + SECTION_CLOSE
+    : out.markup
+      ? out.markup + '\n\n' + formBlock
+      : formBlock;
 }
 
-function skeletonCoverage(blocks: string): number {
-  if (HTML_ISLAND_RE.test(blocks)) return 0;
-  return BLOCK_COMMENT_RE.test(blocks) ? 1 : 0;
+function appendRecoverableImages(
+  section: SectionSpec,
+  out: NativeRenderOut,
+  captured: CapturedSectionContent,
+  coverage: CoverageResult,
+): CoverageResult {
+  if (!(coverage.lost && coverage.missingImages.length > 0)) return coverage;
+
+  const recoverable = coverage.missingImages
+    .map((url) => (section.images ?? []).find((image) => image.url === url))
+    .filter(
+      (image): image is SectionSpecImage =>
+        !!image &&
+        isWpMediaUrl(image.url) &&
+        Math.min(image.width || 0, image.height || 0) >= MIN_CELL_IMAGE_PX,
+    );
+  if (recoverable.length !== coverage.missingImages.length) return coverage;
+
+  const recovered = recoverable
+    .map((image) =>
+      imageBlock(image, out, `recovered#${section.sectionIndex}`, {
+        align: centerOf(section) ? 'center' : null,
+        rounded: true,
+      }),
+    )
+    .filter(Boolean);
+  const augmented = out.markup.endsWith(SECTION_CLOSE)
+    ? out.markup.slice(0, -SECTION_CLOSE.length) + recovered.join('\n') + '\n' + SECTION_CLOSE
+    : (out.markup ? out.markup + '\n\n' : '') + recovered.join('\n');
+  const reMeasured = measureSectionCoverage(captured, augmented);
+  if (reMeasured.lost) return coverage;
+
+  out.markup = augmented;
+  out.flags.push(
+    `media-recovered#${section.sectionIndex}: appended ${recovered.length} dropped image(s) as blocks (island averted)`,
+  );
+  return reMeasured;
 }
 
-function fallbackOptions(ctx: StageCtx): HtmlFallbackOpts {
-  const rewriteCtx = ctx as RewriteCtx;
-  const opts: HtmlFallbackOpts = {};
-  if (rewriteCtx.mediaUrlMap) opts.mediaUrlMap = rewriteCtx.mediaUrlMap;
-  if (rewriteCtx.linkMap) opts.linkMap = rewriteCtx.linkMap;
-  return opts;
+function fallbackDecision(
+  section: SectionSpec,
+  coverage: CoverageResult,
+  options: SectionRenderOptions,
+): NativeSectionDecision | null {
+  if (!(coverage.lost && (section.styledHtml || section.sectionHtml))) return null;
+
+  const { source, tier } = selectIslandSource(section);
+  const island = buildHtmlFallbackBlock(source, fallbackOptions(options));
+  const page = options.sourceUrl ?? options.slug ?? '';
+  const slug = options.slug ?? options.sourceUrl ?? '';
+  return {
+    spec: section,
+    blocks: island,
+    coverage,
+    expectedText: [],
+    bodyText: [],
+    expectedAssets: [],
+    provenanceFlags: [
+      `html-fallback${tier === 'verbatim' ? '' : `-${tier}`}#${section.sectionIndex}: structured render dropped content ` +
+        `(${coverage.missingImages.length} images missing, text ${Math.round(coverage.textCoverage * 100)}%) — ` +
+        `emitted ${tier} core/html`,
+    ],
+    fallbackDiagnostics: [
+      buildFallbackDiagnostic({
+        page,
+        slug,
+        section,
+        coverage,
+        islandKind: tier,
+        islandMarkup: island,
+      }),
+    ],
+    iconAssets: [],
+    decision: 'fallback',
+  };
 }
 
-function rewriteConvertedMedia(blocks: string, ctx: StageCtx): string {
-  const mediaUrlMap = (ctx as RewriteCtx).mediaUrlMap;
-  return mediaUrlMap && mediaUrlMap.size > 0 ? rewriteMediaUrls(blocks, mediaUrlMap) : blocks;
+function convertedDecision(
+  section: SectionSpec,
+  converted: ConvertedSectionInput | undefined,
+  options: SectionRenderOptions,
+): NativeSectionDecision | null {
+  if (!(converted && converted.markup && converted.wpHtmlResidue === 0)) return null;
+
+  const markup = rewriteConvertedMedia(converted.markup, options);
+  const captured = captureSectionContent(section);
+  const coverage = convertedOutputLost(captured, markup);
+  if (!coverage) return null;
+
+  const expectedText: string[] = [];
+  const bodyText: string[] = [];
+  const expectedAssets = [...captured.images];
+  const provenanceFlags = [
+    `html-to-blocks#${section.sectionIndex}: converted native blocks ` +
+      `(0 wp:html, text ${Math.round(coverage.textCoverage * 100)}%)`,
+  ];
+  for (const match of markup.matchAll(/<h[1-6][^>]*>([\s\S]*?)<\/h[1-6]>/gi)) {
+    expectedText.push(visibleText(match[1]));
+  }
+  for (const match of markup.matchAll(/<p\b[^>]*>([\s\S]*?)<\/p>/gi)) {
+    bodyText.push(visibleText(match[1]));
+  }
+
+  const formBlock = renderSectionForms(section, expectedText, provenanceFlags);
+  const blocks = formBlock ? `${markup}\n\n${formBlock}` : markup;
+  return {
+    spec: section,
+    blocks,
+    coverage,
+    expectedText,
+    bodyText,
+    expectedAssets,
+    provenanceFlags,
+    fallbackDiagnostics: [],
+    iconAssets: [],
+    remainder: formBlock && section.forms ? { forms: section.forms } : undefined,
+    decision: 'converted',
+  };
 }
 
-function convertedOutputLost(spec: SectionSpec, blocks: string): boolean {
-  return (
-    measureConvertedCoverage(captureSectionContent(spec), blocks).lost ||
-    scanForInjection(blocks).length > 0 ||
-    hasUnmigratedRemoteAsset(blocks) ||
-    UNRESOLVED_PLACEHOLDER_RE.test(blocks)
-  );
+function nativeDecision(section: SectionSpec, options: SectionRenderOptions, ctx: NativeRenderCtx): NativeSectionDecision | null {
+  const renderSpec = suppressFormEchoes(section);
+  const out = renderSection(renderSpec, ctx);
+  const formBlock = renderSectionForms(section, out.expectedText, out.flags);
+  if (formBlock) {
+    appendFormBlock(out, formBlock);
+    if (section.forms) out.remainder = { forms: section.forms };
+  }
+
+  const captured = nativeCapturedContent(section);
+  let coverage = measureSectionCoverage(captured, out.markup);
+  coverage = appendRecoverableImages(section, out, captured, coverage);
+
+  const fallback = fallbackDecision(section, coverage, options);
+  if (fallback) return fallback;
+
+  if (!out.markup) return null;
+  return {
+    spec: section,
+    blocks: out.markup,
+    coverage,
+    expectedText: out.expectedText,
+    bodyText: out.bodyText,
+    expectedAssets: out.assets,
+    provenanceFlags: out.flags,
+    fallbackDiagnostics: [],
+    iconAssets: out.iconAssets,
+    remainder: out.remainder,
+    decision: 'native',
+  };
 }
 
-function buildLossFallback(spec: SectionSpec, ctx: StageCtx): string {
-  const { source } = selectIslandSource(spec);
-  return buildHtmlFallbackBlock(source, fallbackOptions(ctx));
+function optionsFromCtx(ctx: StageCtx): SectionRenderOptions {
+  const rewriteCtx = ctx as RewriteCtx;
+  return {
+    ...(rewriteCtx.mediaUrlMap ? { mediaUrlMap: rewriteCtx.mediaUrlMap } : {}),
+    ...(rewriteCtx.convertedSections ? { convertedSections: rewriteCtx.convertedSections } : {}),
+    ...(rewriteCtx.paletteTokens ? { paletteTokens: rewriteCtx.paletteTokens } : {}),
+    ...(rewriteCtx.fontFamilies ? { fontFamilies: rewriteCtx.fontFamilies } : {}),
+    ...(rewriteCtx.sourceUrl ? { sourceUrl: rewriteCtx.sourceUrl } : {}),
+    ...(rewriteCtx.slug ? { slug: rewriteCtx.slug } : {}),
+  };
+}
+
+export function reconstructNativeAggregate(
+  specs: SectionSpec[],
+  options: SectionRenderOptions = {},
+): NativeReconstructAggregate {
+  const ctx: NativeRenderCtx = {
+    mediaTextIndex: 0,
+    iconCounter: 0,
+    paletteTokens: options.paletteTokens ?? [],
+    fontFamilies: options.fontFamilies ?? [],
+  };
+
+  const decisions: NativeSectionDecision[] = [];
+  const sectionMarkup: string[] = [];
+  const expectedText: string[] = [];
+  const bodyText: string[] = [];
+  const expectedAssets: string[] = [];
+  const provenanceFlags: string[] = [];
+  const fallbackDiagnostics: NativeReconstructAggregate['fallbackDiagnostics'] = [];
+  const iconAssets: NativeReconstructAggregate['iconAssets'] = [];
+
+  for (const section of normalizeSections(specs, options)) {
+    const converted = options.convertedSections?.get(section.sectionIndex);
+    const decision = convertedDecision(section, converted, options) ?? nativeDecision(section, options, ctx);
+    if (!decision) continue;
+
+    decisions.push(decision);
+    sectionMarkup.push(decision.blocks);
+    expectedText.push(...decision.expectedText);
+    bodyText.push(...decision.bodyText);
+    expectedAssets.push(...decision.expectedAssets);
+    provenanceFlags.push(...decision.provenanceFlags);
+    fallbackDiagnostics.push(...decision.fallbackDiagnostics);
+    iconAssets.push(...decision.iconAssets);
+  }
+
+  return {
+    sections: decisions,
+    sectionMarkup,
+    expectedText: dedupe(expectedText),
+    bodyText: dedupe(bodyText),
+    expectedAssets: dedupe(expectedAssets),
+    provenanceFlags,
+    fallbackDiagnostics,
+    iconAssets,
+    heroIsCover: sectionMarkup.length > 0 && /^\s*<!-- wp:cover\b/.test(sectionMarkup[0]),
+  };
 }
 
 export async function reconstruct(
@@ -112,28 +450,19 @@ export async function reconstruct(
   hooks: SiteToThemeHooks,
   coverageFloor: number
 ): Promise<SectionBlocks[]> {
+  void pool;
+  const aggregate = reconstructNativeAggregate(specs, optionsFromCtx(ctx));
   const sections: SectionBlocks[] = [];
 
-  for (const spec of specs) {
-    let blocks = await convert(sectionInputHtml(spec), { url: '' }, { pool });
-    if (!HTML_ISLAND_RE.test(blocks)) {
-      blocks = rewriteConvertedMedia(blocks, ctx);
-      if (convertedOutputLost(spec, blocks)) {
-        blocks = buildLossFallback(spec, ctx);
-      }
-    }
-
+  for (const decision of aggregate.sections) {
     const section: SectionBlocks = {
-      spec,
-      blocks,
-      coverage: skeletonCoverage(blocks),
+      spec: decision.spec,
+      blocks: decision.blocks,
+      coverage: publicCoverage(decision.blocks, decision.coverage),
+      ...(decision.remainder ? { remainder: decision.remainder } : {}),
     };
-
-    sections.push(
-      section.coverage <= coverageFloor && hooks.onSection
-        ? await hooks.onSection(section, ctx)
-        : section,
-    );
+    const shouldFire = section.coverage <= coverageFloor || Boolean(section.remainder?.forms.length);
+    sections.push(shouldFire && hooks.onSection ? await hooks.onSection(section, ctx) : section);
   }
 
   return sections;

From 683d81ed65d945cd4cac02025a62fcecc5272409 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 21:12:55 -0400
Subject: [PATCH 093/113] feat(theme): freeze site render options surface

---
 .../blocks-engine/src/__tests__/theme-contracts.test.ts  | 5 ++++-
 .../__tests__/theme-native-reconstruct-contract.test.ts  | 9 ++++++++-
 packages/blocks-engine/src/theme/index.ts                | 1 +
 packages/blocks-engine/src/theme/reconstruct.ts          | 4 +++-
 packages/blocks-engine/src/theme/types.ts                | 3 ++-
 5 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/theme-contracts.test.ts b/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
index b14a445d..e37c021e 100644
--- a/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
@@ -30,6 +30,7 @@ import {
   type SectionSpecImage,
   type SectionSpecLayout,
   type SectionSpecMotion,
+  type SectionRenderOptions,
   type SiteModel,
   type SitePage,
   type SiteToThemeHooks,
@@ -55,7 +56,8 @@ type ThemeStageSignatures = {
     ctx: StageCtx,
     pool: WorkerPool,
     hooks: SiteToThemeHooks,
-    coverageFloor: number
+    coverageFloor: number,
+    renderOptions?: SectionRenderOptions
   ) => Promise<SectionBlocks[]>;
   assemble: (parts: {
     site: SiteModel;
@@ -291,6 +293,7 @@ type CompileOnlyThemeContractAssignments = {
     {
       outDir: string;
       sections: Record<string, SectionSpec[]>;
+      renderOptions: Record<string, SectionRenderOptions>;
       foundationAggregates: FoundationAggregates;
       hooks: SiteToThemeHooks;
       fetchImpl: typeof fetch;
diff --git a/packages/blocks-engine/src/__tests__/theme-native-reconstruct-contract.test.ts b/packages/blocks-engine/src/__tests__/theme-native-reconstruct-contract.test.ts
index 03c2d16e..ccb33047 100644
--- a/packages/blocks-engine/src/__tests__/theme-native-reconstruct-contract.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-native-reconstruct-contract.test.ts
@@ -1,7 +1,13 @@
 import { describe, expect, expectTypeOf, it } from 'vitest';
 
 import type { WorkerPool } from '../pool/types.js';
-import { reconstruct, type SectionBlocks, type SiteToThemeHooks, type StageCtx } from '../theme/index.js';
+import {
+  reconstruct,
+  type SectionBlocks,
+  type SectionRenderOptions,
+  type SiteToThemeHooks,
+  type StageCtx,
+} from '../theme/index.js';
 import type { FallbackDiagnostic } from '../theme/fallback-diagnostic.js';
 import type {
   FormRemainder,
@@ -57,6 +63,7 @@ describe('native reconstruct frozen internal contract', () => {
         pool: WorkerPool,
         hooks: SiteToThemeHooks,
         coverageFloor: number,
+        renderOptions?: SectionRenderOptions,
       ) => Promise<SectionBlocks[]>
     >();
 
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index e80e2a30..c689ecf1 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -105,6 +105,7 @@ export type {
 export type * from './font-faces.js';
 export type { FormBlocksResult } from './form-blocks.js';
 export type { FontFamilyToken } from './page-reconstruct-helpers.js';
+export type { ConvertedSectionInput, SectionRenderOptions } from './native-reconstruct-types.js';
 export type { InternalLinkMap } from './url-rewrite.js';
 export type * from './section-spec.js';
 export type * from './source-assets.js';
diff --git a/packages/blocks-engine/src/theme/reconstruct.ts b/packages/blocks-engine/src/theme/reconstruct.ts
index fd4943d2..87f772f2 100644
--- a/packages/blocks-engine/src/theme/reconstruct.ts
+++ b/packages/blocks-engine/src/theme/reconstruct.ts
@@ -448,9 +448,11 @@ export async function reconstruct(
   ctx: StageCtx,
   pool: WorkerPool,
   hooks: SiteToThemeHooks,
-  coverageFloor: number
+  coverageFloor: number,
+  renderOptions: SectionRenderOptions = {}
 ): Promise<SectionBlocks[]> {
   void pool;
+  void renderOptions;
   const aggregate = reconstructNativeAggregate(specs, optionsFromCtx(ctx));
   const sections: SectionBlocks[] = [];
 
diff --git a/packages/blocks-engine/src/theme/types.ts b/packages/blocks-engine/src/theme/types.ts
index c58ddcce..da1d4e3a 100644
--- a/packages/blocks-engine/src/theme/types.ts
+++ b/packages/blocks-engine/src/theme/types.ts
@@ -1,6 +1,6 @@
 import type { WorkerPool } from '../pool/types.js';
 import type { SectionSpec } from './section-spec.js';
-import type { FormRemainder } from './native-reconstruct-types.js';
+import type { FormRemainder, SectionRenderOptions } from './native-reconstruct-types.js';
 import type { SourceCssCarryOptions } from './source-css-carry.js';
 
 export interface SiteModel {
@@ -83,6 +83,7 @@ export interface SiteToThemeOptions extends SourceCssCarryOptions {
   outDir?: string;
   pool?: WorkerPool;
   sections?: Record<string, SectionSpec[]>;
+  renderOptions?: Record<string, SectionRenderOptions>;
   foundationAggregates?: FoundationAggregates;
   hooks?: SiteToThemeHooks;
   fetchImpl?: typeof fetch;

From cb0c8f5329daae47baec03f3a7e93e0e01afe715 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 21:16:37 -0400
Subject: [PATCH 094/113] feat(theme): thread site render options into
 reconstruct

---
 .../src/__tests__/site-to-theme.e2e.test.ts   | 62 +++++++++++++++++++
 .../blocks-engine/src/theme/reconstruct.ts    |  6 +-
 .../blocks-engine/src/theme/site-to-theme.ts  |  9 ++-
 3 files changed, 74 insertions(+), 3 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
index 60e51bb5..1e9015fc 100644
--- a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
+++ b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
@@ -797,6 +797,68 @@ describe('site-to-theme P0-3 orchestration', () => {
     });
   });
 
+  it('FTP2g-pre-siteToTheme-renderOptions threads converted sections into reconstruct', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+    const { fetchImpl } = mockFontFetch();
+    const sectionsByPage = {
+      about: [semanticSpec(0)],
+      home: [semanticSpec(0)],
+    };
+    const convertedMarkup = [
+      '<!-- wp:group {"className":"ftp2g-pre-converted"} -->',
+      '<div class="wp-block-group ftp2g-pre-converted">',
+      '<!-- wp:heading -->',
+      '<h2>Semantic heading</h2>',
+      '<!-- /wp:heading -->',
+      '<!-- wp:paragraph -->',
+      '<p>Semantic body copy.</p>',
+      '<!-- /wp:paragraph -->',
+      '</div>',
+      '<!-- /wp:group -->',
+    ].join('\n');
+
+    await withTempDir('blocks-engine-site-to-theme-render-options-', async (rootDir) => {
+      const siteDir = join(rootDir, 'site');
+      mkdirSync(siteDir);
+      copyFixtureSite(siteDir);
+      const controlOut = join(rootDir, 'theme-control');
+      const injectedOut = join(rootDir, 'theme-injected');
+
+      await siteToTheme(siteDir, {
+        outDir: controlOut,
+        pool: p1Pool(),
+        sections: sectionsByPage,
+        fetchImpl,
+        themeMeta: themeMeta(),
+      });
+
+      await siteToTheme(siteDir, {
+        outDir: injectedOut,
+        pool: p1Pool(),
+        sections: sectionsByPage,
+        renderOptions: {
+          home: {
+            convertedSections: new Map([
+              [0, { markup: convertedMarkup, wpHtmlResidue: 0 }],
+            ]),
+          },
+        },
+        fetchImpl,
+        themeMeta: themeMeta(),
+      });
+
+      const controlTemplate = readFileSync(join(controlOut, 'templates', 'front-page.html'), 'utf8');
+      const injectedTemplate = readFileSync(join(injectedOut, 'templates', 'front-page.html'), 'utf8');
+
+      expect(controlTemplate).toContain('Semantic heading');
+      expect(controlTemplate).toContain('Semantic body copy.');
+      expect(controlTemplate).not.toContain('ftp2g-pre-converted');
+      expect(injectedTemplate).toContain('ftp2g-pre-converted');
+      expect(injectedTemplate).toContain('<p>Semantic body copy.</p>');
+      expect(injectedTemplate).not.toContain('lib-coverage-island');
+    });
+  });
+
   it('siteToTheme-e2e-chrome runs chrome extraction even when body sections are injected', async () => {
     const { siteToTheme } = await import('../theme/index.js');
 
diff --git a/packages/blocks-engine/src/theme/reconstruct.ts b/packages/blocks-engine/src/theme/reconstruct.ts
index 87f772f2..9b372458 100644
--- a/packages/blocks-engine/src/theme/reconstruct.ts
+++ b/packages/blocks-engine/src/theme/reconstruct.ts
@@ -452,8 +452,10 @@ export async function reconstruct(
   renderOptions: SectionRenderOptions = {}
 ): Promise<SectionBlocks[]> {
   void pool;
-  void renderOptions;
-  const aggregate = reconstructNativeAggregate(specs, optionsFromCtx(ctx));
+  const aggregate = reconstructNativeAggregate(specs, {
+    ...optionsFromCtx(ctx),
+    ...renderOptions,
+  });
   const sections: SectionBlocks[] = [];
 
   for (const decision of aggregate.sections) {
diff --git a/packages/blocks-engine/src/theme/site-to-theme.ts b/packages/blocks-engine/src/theme/site-to-theme.ts
index 593c103a..f9458c20 100644
--- a/packages/blocks-engine/src/theme/site-to-theme.ts
+++ b/packages/blocks-engine/src/theme/site-to-theme.ts
@@ -54,7 +54,14 @@ export async function siteToTheme(
       const specs =
         options?.sections?.[page.slug] ??
         sectionExtract({ ...page, html: chromeRes.mainHtmlByPage[page.slug] ?? page.html });
-      pages[page.slug] = await reconstruct(specs, ctx, pool, hooks, coverageFloor);
+      pages[page.slug] = await reconstruct(
+        specs,
+        ctx,
+        pool,
+        hooks,
+        coverageFloor,
+        options?.renderOptions?.[page.slug]
+      );
     }
 
     const assetStage = await runAssetsStage(ctx, { fetchImpl: options?.fetchImpl });

From bad8ec920795792d3d48d7ddb65dfddb5c8340f3 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 21:33:58 -0400
Subject: [PATCH 095/113] feat(theme): freeze variation hoist surface

---
 .../src/__tests__/theme-contracts.test.ts     | 81 +++++++++++++++++++
 packages/blocks-engine/src/theme/index.ts     |  2 +
 packages/blocks-engine/src/theme/types.ts     |  2 +
 .../src/theme/variation-hoist.ts              | 30 +++++++
 .../blocks-engine/src/theme/write-theme.ts    | 13 +++
 5 files changed, 128 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/variation-hoist.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-contracts.test.ts b/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
index e37c021e..b7704095 100644
--- a/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
@@ -1,11 +1,18 @@
 import { describe, expect, it } from 'vitest';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import type { WorkerPool } from '../pool/types.js';
 import {
   assemble,
+  applyHoistSwaps,
   buildFallbackDiagnostic,
   buildTriageRemovalDiagnostic,
   foundation,
   formToBlocks,
+  hoistVariations,
+  HOIST_MIN_INSTANCES,
   ingest,
   planTemplates,
   reconstruct,
@@ -20,6 +27,9 @@ import {
   type FoundationAggregates,
   type FoundationTokens,
   type FormBlocksResult,
+  type HoistedVariation,
+  type HoistPage,
+  type HoistResult,
   type SectionBlocks,
   type SectionSpec,
   type SectionSpecButton,
@@ -65,6 +75,8 @@ type ThemeStageSignatures = {
     pages: Record<string, SectionBlocks[]>;
     meta: ThemeMeta;
   }) => ThemeModel;
+  hoistVariations: (pagesIn: HoistPage[], opts?: { minInstances?: number }) => HoistResult;
+  applyHoistSwaps: (markup: string, variations: HoistedVariation[]) => string;
 };
 
 const themeStageSignatures: ThemeStageSignatures = {
@@ -76,6 +88,8 @@ const themeStageSignatures: ThemeStageSignatures = {
   planTemplates,
   reconstruct,
   assemble,
+  hoistVariations,
+  applyHoistSwaps,
 };
 
 void themeStageSignatures;
@@ -232,6 +246,7 @@ type CompileOnlyThemeContractAssignments = {
       templates: Record<string, string>;
       parts: Record<string, string>;
       patterns: Record<string, string>;
+      styleBlocks: Record<string, Record<string, unknown>>;
       assets: AssetFile[];
     }
   >;
@@ -294,6 +309,7 @@ type CompileOnlyThemeContractAssignments = {
       outDir: string;
       sections: Record<string, SectionSpec[]>;
       renderOptions: Record<string, SectionRenderOptions>;
+      variationHoist: false;
       foundationAggregates: FoundationAggregates;
       hooks: SiteToThemeHooks;
       fetchImpl: typeof fetch;
@@ -375,6 +391,8 @@ describe('theme public contract', () => {
       [planTemplates, 1],
       [reconstruct, 5],
       [assemble, 1],
+      [hoistVariations, 1],
+      [applyHoistSwaps, 2],
     ] as const;
 
     for (const [stage, expectedArity] of runtimeStages) {
@@ -383,6 +401,69 @@ describe('theme public contract', () => {
     }
   });
 
+  it('freezes the variation hoist public constants', () => {
+    expect(HOIST_MIN_INSTANCES).toBe(3);
+  });
+
+  it('writeTheme emits additive block style variation files only when provided', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'blocks-engine-theme-contract-'));
+    try {
+      const written = await writeTheme(
+        {
+          styleCss: '',
+          themeJson: { version: 3 },
+          templates: {},
+          parts: {},
+          patterns: {},
+          styleBlocks: {
+            'lib-paragraph-color.json': {
+              version: 3,
+              title: 'Paragraph color',
+              blockTypes: ['core/paragraph'],
+              styles: { color: { text: '#111111' } },
+            },
+          },
+          assets: [],
+        },
+        dir
+      );
+
+      expect(written).toContain('styles/blocks/lib-paragraph-color.json');
+      expect(
+        JSON.parse(readFileSync(join(dir, 'styles', 'blocks', 'lib-paragraph-color.json'), 'utf8'))
+      ).toEqual({
+        version: 3,
+        title: 'Paragraph color',
+        blockTypes: ['core/paragraph'],
+        styles: { color: { text: '#111111' } },
+      });
+    } finally {
+      await rm(dir, { force: true, recursive: true });
+    }
+  });
+
+  it('writeTheme preserves existing output shape when styleBlocks is absent', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'blocks-engine-theme-contract-'));
+    try {
+      const written = await writeTheme(
+        {
+          styleCss: '',
+          themeJson: { version: 3 },
+          templates: {},
+          parts: {},
+          patterns: {},
+          assets: [],
+        },
+        dir
+      );
+
+      expect(written).toEqual(['style.css', 'theme.json']);
+      expect(existsSync(join(dir, 'styles'))).toBe(false);
+    } finally {
+      await rm(dir, { force: true, recursive: true });
+    }
+  });
+
 });
 
 describe('fallback diagnostics DLA parity', () => {
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index c689ecf1..920fc0bd 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -68,6 +68,7 @@ export {
 export { sectionExtract } from './section-extract.js';
 export { siteToTheme } from './site-to-theme.js';
 export { lintThemeJson } from './theme-json-lint.js';
+export { applyHoistSwaps, hoistVariations, HOIST_MIN_INSTANCES } from './variation-hoist.js';
 export { writeTheme } from './write-theme.js';
 
 export type * from './assets-static.js';
@@ -111,4 +112,5 @@ export type * from './section-spec.js';
 export type * from './source-assets.js';
 export type { TemplatePlan } from './template-plan.js';
 export type * from './types.js';
+export type * from './variation-hoist.js';
 export type { ThemeJsonLintResult } from './theme-json-lint.js';
diff --git a/packages/blocks-engine/src/theme/types.ts b/packages/blocks-engine/src/theme/types.ts
index da1d4e3a..ec43cac2 100644
--- a/packages/blocks-engine/src/theme/types.ts
+++ b/packages/blocks-engine/src/theme/types.ts
@@ -40,6 +40,7 @@ export interface ThemeModel {
   templates: Record<string, string>;
   parts: Record<string, string>;
   patterns: Record<string, string>;
+  styleBlocks?: Record<string, Record<string, unknown>>;
   assets: AssetFile[];
 }
 
@@ -84,6 +85,7 @@ export interface SiteToThemeOptions extends SourceCssCarryOptions {
   pool?: WorkerPool;
   sections?: Record<string, SectionSpec[]>;
   renderOptions?: Record<string, SectionRenderOptions>;
+  variationHoist?: false;
   foundationAggregates?: FoundationAggregates;
   hooks?: SiteToThemeHooks;
   fetchImpl?: typeof fetch;
diff --git a/packages/blocks-engine/src/theme/variation-hoist.ts b/packages/blocks-engine/src/theme/variation-hoist.ts
new file mode 100644
index 00000000..fec6c163
--- /dev/null
+++ b/packages/blocks-engine/src/theme/variation-hoist.ts
@@ -0,0 +1,30 @@
+export const HOIST_MIN_INSTANCES = 3;
+
+export interface HoistedVariation {
+  slug: string;
+  title: string;
+  blockTypes: string[];
+  styles: Record<string, unknown>;
+  count: number;
+}
+
+export interface HoistPage {
+  slug: string;
+  markup: string;
+}
+
+export interface HoistResult {
+  pages: HoistPage[];
+  variations: HoistedVariation[];
+}
+
+export function hoistVariations(
+  pagesIn: HoistPage[],
+  _opts: { minInstances?: number } = {}
+): HoistResult {
+  return { pages: pagesIn.map(p => ({ ...p })), variations: [] };
+}
+
+export function applyHoistSwaps(markup: string, _variations: HoistedVariation[]): string {
+  return markup;
+}
diff --git a/packages/blocks-engine/src/theme/write-theme.ts b/packages/blocks-engine/src/theme/write-theme.ts
index 17aa5b95..1354f027 100644
--- a/packages/blocks-engine/src/theme/write-theme.ts
+++ b/packages/blocks-engine/src/theme/write-theme.ts
@@ -18,6 +18,7 @@ export async function writeTheme(model: ThemeModel, outDir: string): Promise<str
     ...recordFiles('templates', model.templates),
     ...recordFiles('parts', model.parts),
     ...recordFiles('patterns', model.patterns),
+    ...jsonRecordFiles('styles/blocks', model.styleBlocks ?? {}),
   ];
 
   for (const asset of model.assets) {
@@ -40,6 +41,18 @@ function recordFiles(baseDir: string, files: Record<string, string>): Array<[str
     .map(([key, content]) => [recordRelativePath(baseDir, key), content]);
 }
 
+function jsonRecordFiles(
+  baseDir: string,
+  files: Record<string, Record<string, unknown>>
+): Array<[string, string]> {
+  return Object.entries(files)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, content]) => [
+      recordRelativePath(baseDir, key),
+      JSON.stringify(content, null, 2) + '\n',
+    ]);
+}
+
 function recordRelativePath(baseDir: string, key: string): string {
   const trimmed = key.trim();
   if (trimmed.startsWith(`${baseDir}/`) || trimmed.includes('/')) {

From f5b9194b8ab7624787de8adb7e90dc1df7d3800b Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 21:47:15 -0400
Subject: [PATCH 096/113] feat(theme): hoist recurring block style variations

---
 .../capture-variation-hoist-goldens.mjs       | 123 +++++++++++
 .../fixtures/variation-hoist-corpus.d.ts      |  21 ++
 .../fixtures/variation-hoist-corpus.js        |  99 +++++++++
 .../fixtures/variation-hoist-dla-goldens.json | 138 ++++++++++++
 .../src/__tests__/site-to-theme.e2e.test.ts   |  82 ++++++++
 .../theme-variation-hoist-parity.test.ts      | 101 +++++++++
 packages/blocks-engine/src/theme/assemble.ts  |   2 +
 .../blocks-engine/src/theme/site-to-theme.ts  |  63 ++++++
 .../src/theme/variation-hoist.ts              | 198 ++++++++++++++++--
 9 files changed, 814 insertions(+), 13 deletions(-)
 create mode 100644 packages/blocks-engine/scripts/capture-variation-hoist-goldens.mjs
 create mode 100644 packages/blocks-engine/src/__tests__/fixtures/variation-hoist-corpus.d.ts
 create mode 100644 packages/blocks-engine/src/__tests__/fixtures/variation-hoist-corpus.js
 create mode 100644 packages/blocks-engine/src/__tests__/fixtures/variation-hoist-dla-goldens.json
 create mode 100644 packages/blocks-engine/src/__tests__/theme-variation-hoist-parity.test.ts

diff --git a/packages/blocks-engine/scripts/capture-variation-hoist-goldens.mjs b/packages/blocks-engine/scripts/capture-variation-hoist-goldens.mjs
new file mode 100644
index 00000000..5766f960
--- /dev/null
+++ b/packages/blocks-engine/scripts/capture-variation-hoist-goldens.mjs
@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { execFileSync, spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const DEFAULT_DLA_ROOT = '/Users/matt/projects/a8c/data-liberation-agent';
+const TSX_BOOTSTRAP_ENV = 'BLOCKS_ENGINE_VARIATION_HOIST_GOLDENS_TSX';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+const corpusUrl = pathToFileURL(
+  path.join(packageRoot, 'src/__tests__/fixtures/variation-hoist-corpus.js')
+).href;
+const outputPath = path.join(packageRoot, 'src/__tests__/fixtures/variation-hoist-dla-goldens.json');
+
+function hasTsxLoader() {
+  return process.execArgv.some((arg, index, argv) => {
+    if (arg === '--import') return argv[index + 1]?.includes('tsx');
+    return arg.startsWith('--import=') && arg.includes('tsx');
+  });
+}
+
+if (!process.env[TSX_BOOTSTRAP_ENV] && !hasTsxLoader()) {
+  const result = spawnSync(process.execPath, ['--import', 'tsx', fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+    cwd: packageRoot,
+    env: { ...process.env, [TSX_BOOTSTRAP_ENV]: '1' },
+    stdio: 'inherit',
+  });
+  if (result.error) throw result.error;
+  process.exit(result.status ?? 1);
+}
+
+const {
+  DLA_VARIATION_HOIST_BLOB,
+  DLA_VARIATION_HOIST_COMMIT,
+  DLA_VARIATION_HOIST_PATH,
+  runVariationHoistParity,
+} = await import(corpusUrl);
+
+const args = new Set(process.argv.slice(2));
+const shouldWrite = args.has('--write');
+const shouldCheck = args.has('--check');
+const shouldStdout = args.has('--stdout') || (!shouldWrite && !shouldCheck);
+const dlaRoot = process.env.DLA_ROOT || DEFAULT_DLA_ROOT;
+
+const explicitModeCount = [shouldWrite, shouldCheck, args.has('--stdout')].filter(Boolean).length;
+if (explicitModeCount > 1) {
+  throw new Error('Use only one mode: --write, --check, or --stdout.');
+}
+
+function git(gitArgs) {
+  return execFileSync('git', ['-C', dlaRoot, ...gitArgs], { encoding: 'utf8' }).trim();
+}
+
+function stableJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function verifyDlaOracle() {
+  const currentCommit = git(['rev-parse', 'HEAD']);
+  if (currentCommit !== DLA_VARIATION_HOIST_COMMIT) {
+    throw new Error(`DLA checkout must be at ${DLA_VARIATION_HOIST_COMMIT}; got ${currentCommit}`);
+  }
+
+  const headBlob = git(['rev-parse', `HEAD:${DLA_VARIATION_HOIST_PATH}`]);
+  if (headBlob !== DLA_VARIATION_HOIST_BLOB) {
+    throw new Error(
+      `DLA ${DLA_VARIATION_HOIST_PATH} HEAD blob must be ${DLA_VARIATION_HOIST_BLOB}; got ${headBlob}`
+    );
+  }
+
+  const liveBlob = git(['hash-object', DLA_VARIATION_HOIST_PATH]);
+  if (liveBlob !== DLA_VARIATION_HOIST_BLOB) {
+    throw new Error(
+      `DLA ${DLA_VARIATION_HOIST_PATH} working tree blob must be ${DLA_VARIATION_HOIST_BLOB}; got ${liveBlob}`
+    );
+  }
+
+  const requiredStatus = git([
+    'status',
+    '--porcelain',
+    '--',
+    DLA_VARIATION_HOIST_PATH,
+    'src/lib/replicate/form-blocks.ts',
+  ]);
+  if (requiredStatus) {
+    throw new Error(`DLA required variation-hoist sources must be clean:\n${requiredStatus}`);
+  }
+}
+
+function report(mode, parityFile) {
+  process.stderr.write(
+    `variation-hoist goldens ${mode}: DLA commit=${DLA_VARIATION_HOIST_COMMIT} blob=${DLA_VARIATION_HOIST_BLOB} cases=${parityFile.cases.length}\n`
+  );
+}
+
+verifyDlaOracle();
+
+const dlaVariationHoist = await import(pathToFileURL(path.join(dlaRoot, DLA_VARIATION_HOIST_PATH)).href);
+const parityFile = runVariationHoistParity({
+  hoistVariations: dlaVariationHoist.hoistVariations,
+  applyHoistSwaps: dlaVariationHoist.applyHoistSwaps,
+});
+const json = stableJson(parityFile);
+
+if (shouldCheck) {
+  const existing = readFileSync(outputPath, 'utf8');
+  if (existing !== json) {
+    throw new Error(`${outputPath} is out of date with DLA blob ${DLA_VARIATION_HOIST_BLOB}`);
+  }
+  report('check', parityFile);
+}
+
+if (shouldWrite) {
+  writeFileSync(outputPath, json);
+  report('write', parityFile);
+}
+
+if (shouldStdout) {
+  process.stdout.write(json);
+  report('stdout', parityFile);
+}
diff --git a/packages/blocks-engine/src/__tests__/fixtures/variation-hoist-corpus.d.ts b/packages/blocks-engine/src/__tests__/fixtures/variation-hoist-corpus.d.ts
new file mode 100644
index 00000000..5bcdca60
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/fixtures/variation-hoist-corpus.d.ts
@@ -0,0 +1,21 @@
+import type { HoistedVariation, HoistPage, HoistResult } from '../../theme/index.js';
+
+export const DLA_VARIATION_HOIST_COMMIT: string;
+export const DLA_VARIATION_HOIST_PATH: string;
+export const DLA_VARIATION_HOIST_BLOB: string;
+export const VARIATION_HOIST_DERIVATION: string;
+
+export interface VariationHoistCase {
+  id: string;
+  pages: HoistPage[];
+  options?: { minInstances?: number };
+  swapMarkup: string;
+}
+
+export interface VariationHoistImpl {
+  hoistVariations(pagesIn: HoistPage[], opts?: { minInstances?: number }): HoistResult;
+  applyHoistSwaps(markup: string, variations: HoistedVariation[]): string;
+}
+
+export function variationHoistCases(): VariationHoistCase[];
+export function runVariationHoistParity(impl: VariationHoistImpl): unknown;
diff --git a/packages/blocks-engine/src/__tests__/fixtures/variation-hoist-corpus.js b/packages/blocks-engine/src/__tests__/fixtures/variation-hoist-corpus.js
new file mode 100644
index 00000000..46eb60ff
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/fixtures/variation-hoist-corpus.js
@@ -0,0 +1,99 @@
+export const DLA_VARIATION_HOIST_COMMIT = '1e393c535850ee1a9482f83459f779d0e225b027';
+export const DLA_VARIATION_HOIST_PATH = 'src/lib/replicate/variation-hoist.ts';
+export const DLA_VARIATION_HOIST_BLOB = '62b9cf4c87b62dfc03bffe2e25ffbe4e6109438b';
+export const VARIATION_HOIST_DERIVATION =
+  `Mechanically generated from DLA ${DLA_VARIATION_HOIST_PATH} at commit ${DLA_VARIATION_HOIST_COMMIT} with blob ${DLA_VARIATION_HOIST_BLOB}.`;
+
+const commentEscapeName =
+  'Alpha \\u002d\\u002d \\u003cunsafe\\u003e \\u0026 \\u0022quoted\\u0022 value';
+
+function paragraph(attrs, body) {
+  return `<!-- wp:paragraph ${attrs} -->\n<p>${body}</p>\n<!-- /wp:paragraph -->`;
+}
+
+function group(attrs, body) {
+  return `<!-- wp:group ${attrs} -->\n<div class="wp-block-group">${body}</div>\n<!-- /wp:group -->`;
+}
+
+function jetpack(attrs, body) {
+  return `<!-- wp:jetpack/contact-form ${attrs} -->\n<div class="wp-block-jetpack-contact-form">${body}</div>\n<!-- /wp:jetpack/contact-form -->`;
+}
+
+export function variationHoistCases() {
+  const paragraphStyleA = '{"style":{"color":{"text":"#123456"},"spacing":{"padding":{"top":"16px","bottom":"16px"}}}}';
+  const paragraphStyleB = '{"style":{"spacing":{"padding":{"bottom":"16px","top":"16px"}},"color":{"text":"#123456"}}}';
+  const groupEscapeAttrs =
+    `{"metadata":{"name":"${commentEscapeName}"},"style":{"border":{"color":"#333333","width":"2px"}}}`;
+  const jetpackAttrs = '{"style":{"color":{"background":"#f0f0f0"}}}';
+
+  return [
+    {
+      id: 'core-paragraph-hoists-three-matches',
+      pages: [
+        { slug: 'home', markup: paragraph(paragraphStyleA, 'Alpha') },
+        { slug: 'about', markup: paragraph(paragraphStyleB, 'Beta') },
+        { slug: 'services', markup: paragraph(paragraphStyleA, 'Gamma') },
+      ],
+      swapMarkup: paragraph(paragraphStyleB, 'Pattern copy'),
+    },
+    {
+      id: 'applies-existing-class-swap',
+      pages: [
+        {
+          slug: 'one',
+          markup: paragraph('{"className":"lead","style":{"typography":{"fontSize":"18px"}}}', 'One'),
+        },
+        {
+          slug: 'two',
+          markup: paragraph('{"className":"lead","style":{"typography":{"fontSize":"18px"}}}', 'Two'),
+        },
+      ],
+      options: { minInstances: 2 },
+      swapMarkup: paragraph('{"className":"pattern","style":{"typography":{"fontSize":"18px"}}}', 'Reusable pattern'),
+    },
+    {
+      id: 'jetpack-styled-blocks-are-excluded',
+      pages: [
+        { slug: 'contact-a', markup: jetpack(jetpackAttrs, 'A') },
+        { slug: 'contact-b', markup: jetpack(jetpackAttrs, 'B') },
+        { slug: 'contact-c', markup: jetpack(jetpackAttrs, 'C') },
+      ],
+      swapMarkup: jetpack(jetpackAttrs, 'Pattern contact'),
+    },
+    {
+      id: 'serialize-block-attrs-escapes-comment-delimiters',
+      pages: [
+        { slug: 'safe-a', markup: group(groupEscapeAttrs, '<p>A</p>') },
+        { slug: 'safe-b', markup: group(groupEscapeAttrs, '<p>B</p>') },
+        { slug: 'safe-c', markup: group(groupEscapeAttrs, '<p>C</p>') },
+      ],
+      swapMarkup: group(groupEscapeAttrs, '<p>Pattern</p>'),
+    },
+  ];
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function runVariationHoistParity(impl) {
+  return {
+    version: 1,
+    derivation: VARIATION_HOIST_DERIVATION,
+    oracle: {
+      commit: DLA_VARIATION_HOIST_COMMIT,
+      path: DLA_VARIATION_HOIST_PATH,
+      blob: DLA_VARIATION_HOIST_BLOB,
+    },
+    cases: variationHoistCases().map((entry) => {
+      const result = impl.hoistVariations(clone(entry.pages), entry.options ?? {});
+      return {
+        id: entry.id,
+        options: entry.options ?? {},
+        variations: result.variations,
+        pages: result.pages,
+        swappedMarkup: impl.applyHoistSwaps(entry.swapMarkup, result.variations),
+      };
+    }),
+  };
+}
diff --git a/packages/blocks-engine/src/__tests__/fixtures/variation-hoist-dla-goldens.json b/packages/blocks-engine/src/__tests__/fixtures/variation-hoist-dla-goldens.json
new file mode 100644
index 00000000..c8e1bd0b
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/fixtures/variation-hoist-dla-goldens.json
@@ -0,0 +1,138 @@
+{
+  "version": 1,
+  "derivation": "Mechanically generated from DLA src/lib/replicate/variation-hoist.ts at commit 1e393c535850ee1a9482f83459f779d0e225b027 with blob 62b9cf4c87b62dfc03bffe2e25ffbe4e6109438b.",
+  "oracle": {
+    "commit": "1e393c535850ee1a9482f83459f779d0e225b027",
+    "path": "src/lib/replicate/variation-hoist.ts",
+    "blob": "62b9cf4c87b62dfc03bffe2e25ffbe4e6109438b"
+  },
+  "cases": [
+    {
+      "id": "core-paragraph-hoists-three-matches",
+      "options": {},
+      "variations": [
+        {
+          "slug": "lib-paragraph-color-spacing",
+          "title": "Paragraph color spacing",
+          "blockTypes": [
+            "core/paragraph"
+          ],
+          "styles": {
+            "color": {
+              "text": "#123456"
+            },
+            "spacing": {
+              "padding": {
+                "top": "16px",
+                "bottom": "16px"
+              }
+            }
+          },
+          "count": 3
+        }
+      ],
+      "pages": [
+        {
+          "slug": "home",
+          "markup": "<!-- wp:paragraph {\"className\":\"is-style-lib-paragraph-color-spacing\"} -->\n<p>Alpha</p>\n<!-- /wp:paragraph -->"
+        },
+        {
+          "slug": "about",
+          "markup": "<!-- wp:paragraph {\"className\":\"is-style-lib-paragraph-color-spacing\"} -->\n<p>Beta</p>\n<!-- /wp:paragraph -->"
+        },
+        {
+          "slug": "services",
+          "markup": "<!-- wp:paragraph {\"className\":\"is-style-lib-paragraph-color-spacing\"} -->\n<p>Gamma</p>\n<!-- /wp:paragraph -->"
+        }
+      ],
+      "swappedMarkup": "<!-- wp:paragraph {\"className\":\"is-style-lib-paragraph-color-spacing\"} -->\n<p>Pattern copy</p>\n<!-- /wp:paragraph -->"
+    },
+    {
+      "id": "applies-existing-class-swap",
+      "options": {
+        "minInstances": 2
+      },
+      "variations": [
+        {
+          "slug": "lib-paragraph-typography",
+          "title": "Paragraph typography",
+          "blockTypes": [
+            "core/paragraph"
+          ],
+          "styles": {
+            "typography": {
+              "fontSize": "18px"
+            }
+          },
+          "count": 2
+        }
+      ],
+      "pages": [
+        {
+          "slug": "one",
+          "markup": "<!-- wp:paragraph {\"className\":\"lead is-style-lib-paragraph-typography\"} -->\n<p>One</p>\n<!-- /wp:paragraph -->"
+        },
+        {
+          "slug": "two",
+          "markup": "<!-- wp:paragraph {\"className\":\"lead is-style-lib-paragraph-typography\"} -->\n<p>Two</p>\n<!-- /wp:paragraph -->"
+        }
+      ],
+      "swappedMarkup": "<!-- wp:paragraph {\"className\":\"pattern is-style-lib-paragraph-typography\"} -->\n<p>Reusable pattern</p>\n<!-- /wp:paragraph -->"
+    },
+    {
+      "id": "jetpack-styled-blocks-are-excluded",
+      "options": {},
+      "variations": [],
+      "pages": [
+        {
+          "slug": "contact-a",
+          "markup": "<!-- wp:jetpack/contact-form {\"style\":{\"color\":{\"background\":\"#f0f0f0\"}}} -->\n<div class=\"wp-block-jetpack-contact-form\">A</div>\n<!-- /wp:jetpack/contact-form -->"
+        },
+        {
+          "slug": "contact-b",
+          "markup": "<!-- wp:jetpack/contact-form {\"style\":{\"color\":{\"background\":\"#f0f0f0\"}}} -->\n<div class=\"wp-block-jetpack-contact-form\">B</div>\n<!-- /wp:jetpack/contact-form -->"
+        },
+        {
+          "slug": "contact-c",
+          "markup": "<!-- wp:jetpack/contact-form {\"style\":{\"color\":{\"background\":\"#f0f0f0\"}}} -->\n<div class=\"wp-block-jetpack-contact-form\">C</div>\n<!-- /wp:jetpack/contact-form -->"
+        }
+      ],
+      "swappedMarkup": "<!-- wp:jetpack/contact-form {\"style\":{\"color\":{\"background\":\"#f0f0f0\"}}} -->\n<div class=\"wp-block-jetpack-contact-form\">Pattern contact</div>\n<!-- /wp:jetpack/contact-form -->"
+    },
+    {
+      "id": "serialize-block-attrs-escapes-comment-delimiters",
+      "options": {},
+      "variations": [
+        {
+          "slug": "lib-group-border",
+          "title": "Group border",
+          "blockTypes": [
+            "core/group"
+          ],
+          "styles": {
+            "border": {
+              "color": "#333333",
+              "width": "2px"
+            }
+          },
+          "count": 3
+        }
+      ],
+      "pages": [
+        {
+          "slug": "safe-a",
+          "markup": "<!-- wp:group {\"metadata\":{\"name\":\"Alpha \\u002d\\u002d \\u003cunsafe\\u003e \\u0026 \\u0022quoted\\u0022 value\"},\"className\":\"is-style-lib-group-border\"} -->\n<div class=\"wp-block-group\"><p>A</p></div>\n<!-- /wp:group -->"
+        },
+        {
+          "slug": "safe-b",
+          "markup": "<!-- wp:group {\"metadata\":{\"name\":\"Alpha \\u002d\\u002d \\u003cunsafe\\u003e \\u0026 \\u0022quoted\\u0022 value\"},\"className\":\"is-style-lib-group-border\"} -->\n<div class=\"wp-block-group\"><p>B</p></div>\n<!-- /wp:group -->"
+        },
+        {
+          "slug": "safe-c",
+          "markup": "<!-- wp:group {\"metadata\":{\"name\":\"Alpha \\u002d\\u002d \\u003cunsafe\\u003e \\u0026 \\u0022quoted\\u0022 value\"},\"className\":\"is-style-lib-group-border\"} -->\n<div class=\"wp-block-group\"><p>C</p></div>\n<!-- /wp:group -->"
+        }
+      ],
+      "swappedMarkup": "<!-- wp:group {\"metadata\":{\"name\":\"Alpha \\u002d\\u002d \\u003cunsafe\\u003e \\u0026 \\u0022quoted\\u0022 value\"},\"className\":\"is-style-lib-group-border\"} -->\n<div class=\"wp-block-group\"><p>Pattern</p></div>\n<!-- /wp:group -->"
+    }
+  ]
+}
diff --git a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
index 1e9015fc..0680203f 100644
--- a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
+++ b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
@@ -859,6 +859,88 @@ describe('site-to-theme P0-3 orchestration', () => {
     });
   });
 
+  it('FTP2h-siteToTheme hoists recurring converted block styles by default with an opt-out', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+    const { fetchImpl } = mockFontFetch();
+    const sectionsByPage = {
+      about: [semanticSpec(0)],
+      home: [semanticSpec(0), semanticSpec(1)],
+    };
+    const styledConvertedMarkup = [
+      '<!-- wp:group -->',
+      '<div class="wp-block-group">',
+      '<!-- wp:heading -->',
+      '<h2>Semantic heading</h2>',
+      '<!-- /wp:heading -->',
+      '<!-- wp:paragraph {"style":{"typography":{"fontSize":"18px"},"spacing":{"margin":{"top":"1rem"}}}} -->',
+      '<p>Semantic body copy.</p>',
+      '<!-- /wp:paragraph -->',
+      '</div>',
+      '<!-- /wp:group -->',
+    ].join('\n');
+
+    await withTempDir('blocks-engine-site-to-theme-hoist-', async (rootDir) => {
+      const siteDir = join(rootDir, 'site');
+      mkdirSync(siteDir);
+      copyFixtureSite(siteDir);
+      const hoistedOut = join(rootDir, 'theme-hoisted');
+      const optOutOut = join(rootDir, 'theme-opt-out');
+      const renderOptions = {
+        about: {
+          convertedSections: new Map([[0, { markup: styledConvertedMarkup, wpHtmlResidue: 0 }]]),
+        },
+        home: {
+          convertedSections: new Map([
+            [0, { markup: styledConvertedMarkup, wpHtmlResidue: 0 }],
+            [1, { markup: styledConvertedMarkup, wpHtmlResidue: 0 }],
+          ]),
+        },
+      };
+
+      const hoisted = await siteToTheme(siteDir, {
+        outDir: hoistedOut,
+        pool: p1Pool(),
+        sections: sectionsByPage,
+        renderOptions,
+        fetchImpl,
+        themeMeta: themeMeta(),
+      });
+      const optOut = await siteToTheme(siteDir, {
+        outDir: optOutOut,
+        pool: p1Pool(),
+        sections: sectionsByPage,
+        renderOptions,
+        variationHoist: false,
+        fetchImpl,
+        themeMeta: themeMeta(),
+      });
+
+      const variationPath = join(hoistedOut, 'styles', 'blocks', 'lib-paragraph-spacing-typography.json');
+      const hoistedTemplate = readFileSync(join(hoistedOut, 'templates', 'front-page.html'), 'utf8');
+      const optOutTemplate = readFileSync(join(optOutOut, 'templates', 'front-page.html'), 'utf8');
+
+      expect(hoisted.written).toContain('styles/blocks/lib-paragraph-spacing-typography.json');
+      expect(hoisted.model.styleBlocks?.['lib-paragraph-spacing-typography.json']).toEqual({
+        version: 3,
+        slug: 'lib-paragraph-spacing-typography',
+        title: 'Paragraph spacing typography',
+        blockTypes: ['core/paragraph'],
+        styles: { typography: { fontSize: '18px' }, spacing: { margin: { top: '1rem' } } },
+      });
+      expect(JSON.parse(readFileSync(variationPath, 'utf8'))).toEqual(
+        hoisted.model.styleBlocks?.['lib-paragraph-spacing-typography.json']
+      );
+      expect(hoistedTemplate).toContain('"className":"is-style-lib-paragraph-spacing-typography"');
+      expect(hoistedTemplate).not.toContain('"style":{"typography":{"fontSize":"18px"}');
+
+      expect(optOut.written).not.toContain('styles/blocks/lib-paragraph-spacing-typography.json');
+      expect(existsSync(join(optOutOut, 'styles'))).toBe(false);
+      expect(optOut.model.styleBlocks).toBeUndefined();
+      expect(optOutTemplate).toContain('"style":{"typography":{"fontSize":"18px"}');
+      expect(optOutTemplate).not.toContain('is-style-lib-paragraph-spacing-typography');
+    });
+  });
+
   it('siteToTheme-e2e-chrome runs chrome extraction even when body sections are injected', async () => {
     const { siteToTheme } = await import('../theme/index.js');
 
diff --git a/packages/blocks-engine/src/__tests__/theme-variation-hoist-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-variation-hoist-parity.test.ts
new file mode 100644
index 00000000..e759d856
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-variation-hoist-parity.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+
+import expectedGoldens from './fixtures/variation-hoist-dla-goldens.json' with { type: 'json' };
+import {
+  runVariationHoistParity,
+  variationHoistCases,
+} from './fixtures/variation-hoist-corpus.js';
+import {
+  applyHoistSwaps,
+  hoistVariations,
+  type HoistedVariation,
+  type HoistPage,
+  type HoistResult,
+} from '../theme/index.js';
+
+interface VariationHoistImpl {
+  hoistVariations(pagesIn: HoistPage[], opts?: { minInstances?: number }): HoistResult;
+  applyHoistSwaps(markup: string, variations: HoistedVariation[]): string;
+}
+
+interface VariationHoistCaseRecord {
+  id: string;
+  options: Record<string, unknown>;
+  variations: HoistedVariation[];
+  pages: HoistPage[];
+  swappedMarkup: string;
+}
+
+interface VariationHoistParityFile {
+  version: 1;
+  derivation: string;
+  oracle: {
+    commit: string;
+    path: string;
+    blob: string;
+  };
+  cases: VariationHoistCaseRecord[];
+}
+
+const EXPECTED_CASES = 4;
+
+const engineImpl: VariationHoistImpl = {
+  hoistVariations,
+  applyHoistSwaps,
+};
+
+function stableJson(value: unknown): string {
+  return JSON.stringify(value, null, 2);
+}
+
+function collectDiffs(actual: VariationHoistParityFile, expected: VariationHoistParityFile): string[] {
+  const diffs: string[] = [];
+  if (actual.version !== expected.version) diffs.push(`version: expected ${expected.version}, got ${actual.version}`);
+  if (actual.derivation !== expected.derivation) diffs.push('derivation: changed');
+  if (stableJson(actual.oracle) !== stableJson(expected.oracle)) diffs.push('oracle: changed');
+
+  const expectedById = new Map(expected.cases.map((record) => [record.id, record]));
+  for (const actualCase of actual.cases) {
+    const expectedCase = expectedById.get(actualCase.id);
+    if (!expectedCase) {
+      diffs.push(`${actualCase.id}: missing from checked-in DLA goldens`);
+      continue;
+    }
+    if (stableJson(actualCase.options) !== stableJson(expectedCase.options)) {
+      diffs.push(`${actualCase.id}: options changed`);
+    }
+    if (stableJson(actualCase.variations) !== stableJson(expectedCase.variations)) {
+      diffs.push(`${actualCase.id}: variations changed`);
+    }
+    if (stableJson(actualCase.pages) !== stableJson(expectedCase.pages)) {
+      diffs.push(`${actualCase.id}: hoisted page markup changed`);
+    }
+    if (actualCase.swappedMarkup !== expectedCase.swappedMarkup) {
+      diffs.push(`${actualCase.id}: applyHoistSwaps markup changed`);
+    }
+  }
+
+  const actualIds = new Set(actual.cases.map((record) => record.id));
+  for (const expectedCase of expected.cases) {
+    if (!actualIds.has(expectedCase.id)) diffs.push(`${expectedCase.id}: golden has no corpus case`);
+  }
+  return diffs;
+}
+
+describe('variation hoist DLA parity', () => {
+  it('matches checked-in DLA hoistVariations and applyHoistSwaps goldens byte-for-byte', () => {
+    const first = runVariationHoistParity(engineImpl) as VariationHoistParityFile;
+    const second = runVariationHoistParity(engineImpl) as VariationHoistParityFile;
+    expect(stableJson(first)).toBe(stableJson(second));
+
+    const expected = expectedGoldens as VariationHoistParityFile;
+    const diffs = collectDiffs(first, expected);
+    console.info(
+      `variation hoist parity: cases=${first.cases.length} corpus=${variationHoistCases().length} diffs=${diffs.length}`
+    );
+
+    expect(first.cases.length).toBe(EXPECTED_CASES);
+    expect(variationHoistCases()).toHaveLength(EXPECTED_CASES);
+    expect(diffs).toEqual([]);
+  });
+});
diff --git a/packages/blocks-engine/src/theme/assemble.ts b/packages/blocks-engine/src/theme/assemble.ts
index 89dc61c3..ac48913c 100644
--- a/packages/blocks-engine/src/theme/assemble.ts
+++ b/packages/blocks-engine/src/theme/assemble.ts
@@ -26,6 +26,7 @@ type ThemeAssemblyParts = ThemeAssemblySourceCssInput & {
   chromeParts?: Record<string, string>;
   chromeSlugsByPage?: Record<string, ChromeSlugs>;
   layoutOffsetWrapperClass?: string;
+  styleBlocks?: Record<string, Record<string, unknown>>;
 };
 
 type PaletteEntry = {
@@ -69,6 +70,7 @@ export function assemble(parts: ThemeAssemblyParts): ThemeModel {
     },
     parts: { ...(parts.chromeParts ?? {}) },
     patterns: {},
+    ...(parts.styleBlocks ? { styleBlocks: parts.styleBlocks } : {}),
     assets: collectAssets(parts),
   };
 }
diff --git a/packages/blocks-engine/src/theme/site-to-theme.ts b/packages/blocks-engine/src/theme/site-to-theme.ts
index f9458c20..ff688353 100644
--- a/packages/blocks-engine/src/theme/site-to-theme.ts
+++ b/packages/blocks-engine/src/theme/site-to-theme.ts
@@ -11,6 +11,7 @@ import { reconstruct } from './reconstruct.js';
 import { sectionExtract } from './section-extract.js';
 import { collectSourceAssets, type MediaAsset } from './source-assets.js';
 import { shouldCarrySourceCss } from './source-css-carry.js';
+import { applyHoistSwaps, hoistVariations, type HoistedVariation } from './variation-hoist.js';
 import { writeTheme } from './write-theme.js';
 import type {
   AssetFile,
@@ -64,6 +65,8 @@ export async function siteToTheme(
       );
     }
 
+    const styleBlocks =
+      options?.variationHoist === false ? undefined : hoistPageStyleBlocks(site, pages, warnings);
     const assetStage = await runAssetsStage(ctx, { fetchImpl: options?.fetchImpl });
     const sourceAssets = collectSourceAssets(
       site.root,
@@ -94,6 +97,7 @@ export async function siteToTheme(
       chromeParts: chromeRes.parts,
       chromeSlugsByPage: chromeRes.slugsByPage,
       layoutOffsetWrapperClass,
+      styleBlocks,
       sourceCss: sourceCssCarry?.css,
     });
     const model = hooks.onRefine ? await hooks.onRefine(assembled, ctx) : assembled;
@@ -121,6 +125,65 @@ export async function siteToTheme(
   }
 }
 
+function hoistPageStyleBlocks(
+  site: { pages: Array<{ slug: string }> },
+  pages: Record<string, SectionBlocks[]>,
+  warnings: string[]
+): Record<string, Record<string, unknown>> | undefined {
+  const hoistPages = site.pages
+    .map((page) => ({
+      slug: page.slug,
+      markup: joinHoistSections(pages[page.slug] ?? []),
+    }))
+    .filter((page) => page.markup);
+
+  if (hoistPages.length === 0) return undefined;
+
+  try {
+    const hoisted = hoistVariations(hoistPages);
+    if (hoisted.variations.length === 0) return undefined;
+
+    for (const sections of Object.values(pages)) {
+      for (const section of sections) {
+        section.blocks = applyHoistSwaps(section.blocks, hoisted.variations);
+      }
+    }
+
+    return styleBlocksFromVariations(hoisted.variations);
+  } catch (error) {
+    warnings.push(
+      `variation hoist failed (continuing un-hoisted): ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+    return undefined;
+  }
+}
+
+function joinHoistSections(sections: SectionBlocks[]): string {
+  return sections
+    .map((section) => section.blocks.trim())
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+function styleBlocksFromVariations(
+  variations: HoistedVariation[]
+): Record<string, Record<string, unknown>> {
+  return Object.fromEntries(
+    variations.map((variation) => [
+      `${variation.slug}.json`,
+      {
+        version: 3,
+        slug: variation.slug,
+        title: variation.title,
+        blockTypes: variation.blockTypes,
+        styles: variation.styles,
+      },
+    ])
+  );
+}
+
 function prepareSourceCssCarry(
   css: string,
   mediaAssets: MediaAsset[],
diff --git a/packages/blocks-engine/src/theme/variation-hoist.ts b/packages/blocks-engine/src/theme/variation-hoist.ts
index fec6c163..cdb91949 100644
--- a/packages/blocks-engine/src/theme/variation-hoist.ts
+++ b/packages/blocks-engine/src/theme/variation-hoist.ts
@@ -1,5 +1,22 @@
+// src/lib/replicate/variation-hoist.ts
+// Post-emit variation hoisting (Neptune technique #6): identical instance
+// `style` constellations recurring across the page set are hoisted into theme
+// block-style-variation files (<theme>/styles/blocks/lib-<slug>.json) and the
+// instances swap to `is-style-lib-<slug>` classes. Rendered CSS is identical
+// by construction — same properties, hoisted channel; the win is dedupe +
+// editor-native named styles. Exact-constellation match only (no subset
+// merging). Fail-open everywhere: anything unparseable is left untouched.
+// See docs/superpowers/specs/2026-06-10-neptune-best-parts-design.md (section D).
+import { serializeBlockAttrs } from './form-blocks.js';
+
 export const HOIST_MIN_INSTANCES = 3;
 
+/** Slugs become theme file names (<theme>/styles/blocks/<slug>.json) AND
+ *  is-style-* classNames — both demand a tight charset. Style keys come from
+ *  markup JSON, so guard rather than trust (a hostile/odd key must not become
+ *  a path segment). Mirrors builder-envelope's VARIATION_SLUG_RE. */
+const HOIST_SLUG_RE = /^lib-[a-z0-9][a-z0-9-]*$/;
+
 export interface HoistedVariation {
   slug: string;
   title: string;
@@ -8,23 +25,178 @@ export interface HoistedVariation {
   count: number;
 }
 
-export interface HoistPage {
-  slug: string;
-  markup: string;
+export interface HoistPage { slug: string; markup: string; }
+export interface HoistResult { pages: HoistPage[]; variations: HoistedVariation[]; }
+
+interface BlockHit {
+  pageIndex: number;
+  /** Offset of the attrs JSON within the page markup. */
+  attrStart: number;
+  attrEnd: number;
+  blockName: string;
+  attrs: Record<string, unknown>;
+}
+
+const OPEN_RE = /<!--\s+wp:([a-z0-9-]+\/)?([a-z0-9-]+)\s+\{/g;
+
+/** Stable stringify: object keys sorted recursively. */
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return '[' + value.map(canonicalJson).join(',') + ']';
+  if (typeof value === 'object' && value !== null) {
+    const obj = value as Record<string, unknown>;
+    return '{' + Object.keys(obj).sort().map(k => JSON.stringify(k) + ':' + canonicalJson(obj[k])).join(',') + '}';
+  }
+  return JSON.stringify(value);
+}
+
+/** Balanced-brace scan starting at `start` (which must point at '{'). */
+function balancedEnd(s: string, start: number): number {
+  let depth = 0, inString = false, escape = false;
+  for (let j = start; j < s.length; j++) {
+    const c = s[j]!;
+    if (escape) { escape = false; continue; }
+    if (inString) {
+      if (c === '\\') escape = true;
+      else if (c === '"') inString = false;
+      continue;
+    }
+    if (c === '"') inString = true;
+    else if (c === '{') depth++;
+    else if (c === '}') { depth--; if (depth === 0) return j; }
+  }
+  return -1;
 }
 
-export interface HoistResult {
-  pages: HoistPage[];
-  variations: HoistedVariation[];
+function findStyledBlocks(pages: HoistPage[]): BlockHit[] {
+  const hits: BlockHit[] = [];
+  pages.forEach((p, pageIndex) => {
+    OPEN_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = OPEN_RE.exec(p.markup)) !== null) {
+      const ns = m[1] ?? 'core/';
+      const blockName = ns + m[2];
+      if (blockName === 'core/html') continue;
+      // Jetpack blocks are NEVER hoisted: Jetpack's forms renderer regexes
+      // `is-style-(\S+)` off the contact-form block's className (get_form_style
+      // in class-contact-form-field.php) and treats ANY unknown is-style-* as a
+      // form style variation — render_label() then returns '' and every field
+      // label silently vanishes. A hoist swap (style → is-style-lib-*) on any
+      // jetpack block is therefore a rendering-behavior change, not a pure
+      // CSS-channel move. Same guard style as core/html above; covers both
+      // hoistVariations and applyHoistSwaps (shared scan).
+      if (blockName.startsWith('jetpack/')) continue;
+      const attrStart = OPEN_RE.lastIndex - 1; // points at '{'
+      const attrEnd = balancedEnd(p.markup, attrStart);
+      if (attrEnd === -1) continue;
+      try {
+        const attrs = JSON.parse(p.markup.slice(attrStart, attrEnd + 1)) as Record<string, unknown>;
+        if (typeof attrs.style === 'object' && attrs.style !== null) {
+          hits.push({ pageIndex, attrStart, attrEnd, blockName, attrs });
+        }
+      } catch { /* fail-open: malformed attrs stay as-is */ }
+      OPEN_RE.lastIndex = attrEnd + 1;
+    }
+  });
+  return hits;
+}
+
+function styleGroupsSlugPart(styles: Record<string, unknown>): string {
+  return Object.keys(styles).sort().join('-');
+}
+
+export function hoistVariations(pagesIn: HoistPage[], opts: { minInstances?: number } = {}): HoistResult {
+  const minInstances = opts.minInstances ?? HOIST_MIN_INSTANCES;
+  const pages = pagesIn.map(p => ({ ...p }));
+  const hits = findStyledBlocks(pages);
+
+  // Group by blockName + canonical style JSON.
+  const groups = new Map<string, BlockHit[]>();
+  for (const h of hits) {
+    const key = h.blockName + ' ' + canonicalJson(h.attrs.style);
+    const list = groups.get(key) ?? [];
+    list.push(h);
+    groups.set(key, list);
+  }
+
+  const variations: HoistedVariation[] = [];
+  const usedSlugs = new Set<string>();
+  const edits: Array<{ hit: BlockHit; slug: string }> = [];
+
+  for (const [, list] of [...groups.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    if (list.length < minInstances) continue;
+    const sample = list[0]!;
+    const styles = sample.attrs.style as Record<string, unknown>;
+    const shortName = sample.blockName.split('/')[1]!;
+    let slug = 'lib-' + shortName + '-' + styleGroupsSlugPart(styles);
+    // Fail-open: a constellation whose derived slug fails the charset guard
+    // (an unexpected style key) is simply not hoisted — never a bad filename.
+    if (!HOIST_SLUG_RE.test(slug)) continue;
+    let n = 2;
+    while (usedSlugs.has(slug)) slug = 'lib-' + shortName + '-' + styleGroupsSlugPart(styles) + '-' + n++;
+    usedSlugs.add(slug);
+    variations.push({
+      slug,
+      title: shortName.charAt(0).toUpperCase() + shortName.slice(1) + ' ' + styleGroupsSlugPart(styles).replace(/-/g, ' '),
+      blockTypes: [sample.blockName],
+      styles,
+      count: list.length,
+    });
+    for (const hit of list) edits.push({ hit, slug });
+  }
+
+  // Apply edits per page, descending by offset so earlier offsets stay valid.
+  edits.sort((a, b) => b.hit.attrStart - a.hit.attrStart);
+  for (const { hit, slug } of edits) {
+    const page = pages[hit.pageIndex]!;
+    page.markup = applyAttrEdit(page.markup, hit, slug);
+  }
+
+  return { pages, variations };
 }
 
-export function hoistVariations(
-  pagesIn: HoistPage[],
-  _opts: { minInstances?: number } = {}
-): HoistResult {
-  return { pages: pagesIn.map(p => ({ ...p })), variations: [] };
+/** Swap one styled block's attrs JSON for the is-style-* form, in place.
+ *  Re-serialize through serializeBlockAttrs, NOT plain JSON.stringify: the
+ *  original attrs may carry @wordpress/blocks comment-safe escapes
+ *  (unicode-escaped `--`) that JSON.parse decoded — re-emitting them raw
+ *  could terminate the surrounding HTML comment delimiter. */
+function applyAttrEdit(markup: string, hit: BlockHit, slug: string): string {
+  const attrs = { ...hit.attrs };
+  delete attrs.style;
+  const existing = typeof attrs.className === 'string' ? attrs.className + ' ' : '';
+  attrs.className = existing + 'is-style-' + slug;
+  return markup.slice(0, hit.attrStart) + serializeBlockAttrs(attrs) + markup.slice(hit.attrEnd + 1);
 }
 
-export function applyHoistSwaps(markup: string, _variations: HoistedVariation[]): string {
-  return markup;
+/**
+ * Apply ALREADY-DECIDED hoist swaps to a sibling copy of the markup (the
+ * theme pattern file body, which embeds the same block markup as the page's
+ * post_content modulo PHP↔literal asset-ref form in the inner HTML — block
+ * comment attrs are identical between the two forms). This does NOT re-run
+ * constellation counting: only instances whose blockName + exact style
+ * constellation match a variation decided by `hoistVariations` are swapped,
+ * so pattern copies can never inflate counts or mint new variations.
+ * Fail-open like the hoist itself: no matches → markup returned unchanged.
+ *
+ * NOTE: currently unused by the reconstruct handler — pattern files are
+ * written PRE-hoist because they never pass block-fixer canonicalization, and
+ * a comment-attr-only swap without it leaves the pattern editor-invalid
+ * (is-style attrs over pre-hoist inline HTML). Wire this back in only
+ * together with pattern canonicalization.
+ */
+export function applyHoistSwaps(markup: string, variations: HoistedVariation[]): string {
+  if (variations.length === 0) return markup;
+  const slugBySig = new Map<string, string>();
+  for (const v of variations) {
+    for (const bt of v.blockTypes) slugBySig.set(bt + ' ' + canonicalJson(v.styles), v.slug);
+  }
+  const hits = findStyledBlocks([{ slug: '', markup }]);
+  // Descending by offset so earlier offsets stay valid across edits.
+  hits.sort((a, b) => b.attrStart - a.attrStart);
+  let out = markup;
+  for (const hit of hits) {
+    const slug = slugBySig.get(hit.blockName + ' ' + canonicalJson(hit.attrs.style));
+    if (slug === undefined) continue;
+    out = applyAttrEdit(out, hit, slug);
+  }
+  return out;
 }

From 591fd1f83bc57132fd41c8a1485f8099c5305040 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 21:58:10 -0400
Subject: [PATCH 097/113] test(theme): freeze region audit diagnostic surface

---
 .../src/__tests__/theme-contracts.test.ts     | 31 ++++++++++
 packages/blocks-engine/src/theme/index.ts     |  7 +++
 .../blocks-engine/src/theme/region-audit.ts   | 58 +++++++++++++++++++
 .../blocks-engine/src/theme/region-census.ts  | 13 +++++
 .../src/theme/section-selector.ts             | 10 ++++
 .../blocks-engine/src/theme/site-to-theme.ts  |  3 +
 packages/blocks-engine/src/theme/types.ts     |  6 ++
 7 files changed, 128 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/region-audit.ts
 create mode 100644 packages/blocks-engine/src/theme/region-census.ts
 create mode 100644 packages/blocks-engine/src/theme/section-selector.ts

diff --git a/packages/blocks-engine/src/__tests__/theme-contracts.test.ts b/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
index b7704095..9f50174d 100644
--- a/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-contracts.test.ts
@@ -9,14 +9,18 @@ import {
   applyHoistSwaps,
   buildFallbackDiagnostic,
   buildTriageRemovalDiagnostic,
+  extractSourceLandmarksFromHtml,
   foundation,
   formToBlocks,
   hoistVariations,
   HOIST_MIN_INSTANCES,
   ingest,
+  landmarkRoleForHtmlRoot,
   planTemplates,
   reconstruct,
+  reconcileRegions,
   sectionExtract,
+  selectorForHtmlRoot,
   siteToTheme,
   SKIPPED_FIELD_KINDS,
   writeTheme,
@@ -30,6 +34,8 @@ import {
   type HoistedVariation,
   type HoistPage,
   type HoistResult,
+  type PlacedRegion,
+  type RegionSelectionReport,
   type SectionBlocks,
   type SectionSpec,
   type SectionSpecButton,
@@ -48,8 +54,10 @@ import {
   type StageCtx,
   type TemplatePlan,
   type ThemeBuildResult,
+  type ThemeDiagnostics,
   type ThemeMeta,
   type ThemeModel,
+  type SourceLandmark,
 } from '../theme/index.js';
 
 type Satisfies<T, U extends T> = U;
@@ -77,6 +85,15 @@ type ThemeStageSignatures = {
   }) => ThemeModel;
   hoistVariations: (pagesIn: HoistPage[], opts?: { minInstances?: number }) => HoistResult;
   applyHoistSwaps: (markup: string, variations: HoistedVariation[]) => string;
+  reconcileRegions: (
+    census: SourceLandmark[],
+    placed: PlacedRegion[],
+    page?: string,
+    entryUrl?: string
+  ) => RegionSelectionReport;
+  extractSourceLandmarksFromHtml: (html: string) => SourceLandmark[];
+  selectorForHtmlRoot: (html: string) => string | undefined;
+  landmarkRoleForHtmlRoot: (html: string) => SourceLandmark['role'] | undefined;
 };
 
 const themeStageSignatures: ThemeStageSignatures = {
@@ -90,6 +107,10 @@ const themeStageSignatures: ThemeStageSignatures = {
   assemble,
   hoistVariations,
   applyHoistSwaps,
+  reconcileRegions,
+  extractSourceLandmarksFromHtml,
+  selectorForHtmlRoot,
+  landmarkRoleForHtmlRoot,
 };
 
 void themeStageSignatures;
@@ -325,6 +346,7 @@ type CompileOnlyThemeContractAssignments = {
       written: string[];
       tallies: Record<string, number>;
       warnings: string[];
+      diagnostics: ThemeDiagnostics;
     }
   >;
 };
@@ -350,6 +372,15 @@ function assertBalanced(markup: string): void {
   expect(stack).toEqual([]);
 }
 
+describe('region audit diagnostic surface contract', () => {
+  it('exports browser-free region audit helpers for diagnostic consumers', () => {
+    expect(typeof reconcileRegions).toBe('function');
+    expect(typeof extractSourceLandmarksFromHtml).toBe('function');
+    expect(typeof selectorForHtmlRoot).toBe('function');
+    expect(typeof landmarkRoleForHtmlRoot).toBe('function');
+  });
+});
+
 function diagnosticSection(partial: Partial<SectionSpec> = {}): SectionSpec {
   return {
     sectionIndex: 0,
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 920fc0bd..14a5d71d 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -24,6 +24,12 @@ export { ingest } from './ingest.js';
 export { detectLayoutOffsetWrapper } from './layout-offset-wrapper.js';
 export { buildAdminBarAccommodationCss } from './admin-bar-accommodation.js';
 export { planTemplates } from './template-plan.js';
+export {
+  extractSourceLandmarksFromHtml,
+  landmarkRoleForHtmlRoot,
+  selectorForHtmlRoot,
+} from './region-census.js';
+export { reconcileRegions } from './region-audit.js';
 export {
   normalizeCopy,
   sanitizePatternHeaderField,
@@ -107,6 +113,7 @@ export type * from './font-faces.js';
 export type { FormBlocksResult } from './form-blocks.js';
 export type { FontFamilyToken } from './page-reconstruct-helpers.js';
 export type { ConvertedSectionInput, SectionRenderOptions } from './native-reconstruct-types.js';
+export type * from './region-audit.js';
 export type { InternalLinkMap } from './url-rewrite.js';
 export type * from './section-spec.js';
 export type * from './source-assets.js';
diff --git a/packages/blocks-engine/src/theme/region-audit.ts b/packages/blocks-engine/src/theme/region-audit.ts
new file mode 100644
index 00000000..b331377d
--- /dev/null
+++ b/packages/blocks-engine/src/theme/region-audit.ts
@@ -0,0 +1,58 @@
+export type SourceLandmarkRole =
+  | 'main'
+  | 'nav'
+  | 'header'
+  | 'footer'
+  | 'section'
+  | 'article'
+  | 'aside'
+  | 'complementary';
+
+export interface SourceLandmark {
+  role: SourceLandmarkRole;
+  tag: string;
+  selector: string;
+  textLength: number;
+  mediaCount: number;
+  linkCount?: number;
+}
+
+export type RegionAssignmentKind =
+  | 'page_body_section'
+  | 'header_part'
+  | 'footer_part'
+  | 'non_actionable'
+  | 'unassigned';
+
+export interface RegionAssignment {
+  landmark: SourceLandmark;
+  kind: RegionAssignmentKind;
+}
+
+export interface PlacedRegion {
+  kind: 'page_body_section' | 'header_part' | 'footer_part';
+  selector?: string;
+  role?: 'header' | 'nav' | 'footer' | 'aside' | 'complementary';
+}
+
+export interface RegionSelectionReport {
+  page: string;
+  entryUrl: string;
+  assignments: RegionAssignment[];
+  unassignedRegions: SourceLandmark[];
+  counts: {
+    sourceLandmarks: Record<string, number>;
+    assigned: number;
+    unassigned: number;
+    nonActionable: number;
+  };
+}
+
+export function reconcileRegions(
+  _census: SourceLandmark[],
+  _placed: PlacedRegion[],
+  _page = '',
+  _entryUrl = ''
+): RegionSelectionReport {
+  throw new Error('region audit reconciliation is not implemented');
+}
diff --git a/packages/blocks-engine/src/theme/region-census.ts b/packages/blocks-engine/src/theme/region-census.ts
new file mode 100644
index 00000000..f9e78cc0
--- /dev/null
+++ b/packages/blocks-engine/src/theme/region-census.ts
@@ -0,0 +1,13 @@
+import type { SourceLandmark } from './region-audit.js';
+
+export function selectorForHtmlRoot(_html: string): string | undefined {
+  throw new Error('region audit census is not implemented');
+}
+
+export function landmarkRoleForHtmlRoot(_html: string): SourceLandmark['role'] | undefined {
+  throw new Error('region audit census is not implemented');
+}
+
+export function extractSourceLandmarksFromHtml(_html: string): SourceLandmark[] {
+  throw new Error('region audit census is not implemented');
+}
diff --git a/packages/blocks-engine/src/theme/section-selector.ts b/packages/blocks-engine/src/theme/section-selector.ts
new file mode 100644
index 00000000..3a382f51
--- /dev/null
+++ b/packages/blocks-engine/src/theme/section-selector.ts
@@ -0,0 +1,10 @@
+export interface SelectorParts {
+  tag: string;
+  id: string | null;
+  classes: string[];
+  nthOfType: number;
+}
+
+export function buildSelector(_parts: SelectorParts): string {
+  throw new Error('region audit selector builder is not implemented');
+}
diff --git a/packages/blocks-engine/src/theme/site-to-theme.ts b/packages/blocks-engine/src/theme/site-to-theme.ts
index ff688353..fe922d14 100644
--- a/packages/blocks-engine/src/theme/site-to-theme.ts
+++ b/packages/blocks-engine/src/theme/site-to-theme.ts
@@ -117,6 +117,9 @@ export async function siteToTheme(
         warnings: warnings.length,
       },
       warnings,
+      diagnostics: {
+        regionAudit: [],
+      },
     };
   } finally {
     if (ownsPool) {
diff --git a/packages/blocks-engine/src/theme/types.ts b/packages/blocks-engine/src/theme/types.ts
index ec43cac2..c3f6f909 100644
--- a/packages/blocks-engine/src/theme/types.ts
+++ b/packages/blocks-engine/src/theme/types.ts
@@ -1,4 +1,5 @@
 import type { WorkerPool } from '../pool/types.js';
+import type { RegionSelectionReport } from './region-audit.js';
 import type { SectionSpec } from './section-spec.js';
 import type { FormRemainder, SectionRenderOptions } from './native-reconstruct-types.js';
 import type { SourceCssCarryOptions } from './source-css-carry.js';
@@ -93,10 +94,15 @@ export interface SiteToThemeOptions extends SourceCssCarryOptions {
   themeMeta?: Partial<ThemeMeta>;
 }
 
+export interface ThemeDiagnostics {
+  regionAudit: RegionSelectionReport[];
+}
+
 export interface ThemeBuildResult {
   outDir: string;
   model: ThemeModel;
   written: string[];
   tallies: Record<string, number>;
   warnings: string[];
+  diagnostics: ThemeDiagnostics;
 }

From 85b17f06d8562ffb807c48b724c84e0437d393a8 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Thu, 25 Jun 2026 22:02:56 -0400
Subject: [PATCH 098/113] feat(theme): add region audit diagnostics

---
 .../scripts/capture-region-audit-goldens.mjs  | 133 ++++++
 .../src/__fixtures__/region-audit-corpus.ts   | 168 +++++++
 .../region-audit-dla-goldens.json             | 436 ++++++++++++++++++
 .../src/__tests__/site-to-theme.e2e.test.ts   |  24 +
 .../theme-region-audit-parity.test.ts         |  80 ++++
 .../blocks-engine/src/theme/region-audit.ts   | 107 ++++-
 .../blocks-engine/src/theme/region-census.ts  | 102 +++-
 .../src/theme/section-selector.ts             |  19 +-
 .../blocks-engine/src/theme/site-to-theme.ts  |  38 +-
 9 files changed, 1092 insertions(+), 15 deletions(-)
 create mode 100644 packages/blocks-engine/scripts/capture-region-audit-goldens.mjs
 create mode 100644 packages/blocks-engine/src/__fixtures__/region-audit-corpus.ts
 create mode 100644 packages/blocks-engine/src/__fixtures__/region-audit-dla-goldens.json
 create mode 100644 packages/blocks-engine/src/__tests__/theme-region-audit-parity.test.ts

diff --git a/packages/blocks-engine/scripts/capture-region-audit-goldens.mjs b/packages/blocks-engine/scripts/capture-region-audit-goldens.mjs
new file mode 100644
index 00000000..a2aa4cf9
--- /dev/null
+++ b/packages/blocks-engine/scripts/capture-region-audit-goldens.mjs
@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import { execFileSync, spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const DEFAULT_DLA_ROOT = '/Users/matt/projects/a8c/data-liberation-agent';
+const TSX_BOOTSTRAP_ENV = 'BLOCKS_ENGINE_REGION_AUDIT_GOLDENS_TSX';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+const corpusUrl = pathToFileURL(path.join(packageRoot, 'src/__fixtures__/region-audit-corpus.ts')).href;
+const outputPath = path.join(packageRoot, 'src/__fixtures__/region-audit-dla-goldens.json');
+
+function hasTsxLoader() {
+  return process.execArgv.some((arg, index, argv) => {
+    if (arg === '--import') return argv[index + 1]?.includes('tsx');
+    return arg.startsWith('--import=') && arg.includes('tsx');
+  });
+}
+
+if (!process.env[TSX_BOOTSTRAP_ENV] && !hasTsxLoader()) {
+  const result = spawnSync(process.execPath, ['--import', 'tsx', fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+    cwd: packageRoot,
+    env: { ...process.env, [TSX_BOOTSTRAP_ENV]: '1' },
+    stdio: 'inherit',
+  });
+  if (result.error) throw result.error;
+  process.exit(result.status ?? 1);
+}
+
+const {
+  DLA_REGION_AUDIT_BLOB,
+  DLA_REGION_AUDIT_COMMIT,
+  DLA_REGION_AUDIT_PATH,
+  DLA_REGION_CENSUS_BLOB,
+  DLA_REGION_CENSUS_PATH,
+  DLA_SECTION_SELECTOR_BLOB,
+  DLA_SECTION_SELECTOR_PATH,
+  runRegionAuditParity,
+} = await import(corpusUrl);
+
+const args = new Set(process.argv.slice(2));
+const shouldWrite = args.has('--write');
+const shouldCheck = args.has('--check');
+const shouldStdout = args.has('--stdout') || (!shouldWrite && !shouldCheck);
+const dlaRoot = process.env.DLA_ROOT || DEFAULT_DLA_ROOT;
+
+const explicitModeCount = [shouldWrite, shouldCheck, args.has('--stdout')].filter(Boolean).length;
+if (explicitModeCount > 1) {
+  throw new Error('Use only one mode: --write, --check, or --stdout.');
+}
+
+function git(gitArgs) {
+  return execFileSync('git', ['-C', dlaRoot, ...gitArgs], { encoding: 'utf8' }).trim();
+}
+
+function stableJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function verifyBlob(pathName, expectedBlob) {
+  const headBlob = git(['rev-parse', `HEAD:${pathName}`]);
+  if (headBlob !== expectedBlob) {
+    throw new Error(`DLA ${pathName} HEAD blob must be ${expectedBlob}; got ${headBlob}`);
+  }
+
+  const liveBlob = git(['hash-object', pathName]);
+  if (liveBlob !== expectedBlob) {
+    throw new Error(`DLA ${pathName} working tree blob must be ${expectedBlob}; got ${liveBlob}`);
+  }
+}
+
+function verifyDlaOracle() {
+  const currentCommit = git(['rev-parse', 'HEAD']);
+  if (currentCommit !== DLA_REGION_AUDIT_COMMIT) {
+    throw new Error(`DLA checkout must be at ${DLA_REGION_AUDIT_COMMIT}; got ${currentCommit}`);
+  }
+
+  verifyBlob(DLA_REGION_AUDIT_PATH, DLA_REGION_AUDIT_BLOB);
+  verifyBlob(DLA_REGION_CENSUS_PATH, DLA_REGION_CENSUS_BLOB);
+  verifyBlob(DLA_SECTION_SELECTOR_PATH, DLA_SECTION_SELECTOR_BLOB);
+
+  const requiredStatus = git([
+    'status',
+    '--porcelain',
+    '--',
+    DLA_REGION_AUDIT_PATH,
+    DLA_REGION_CENSUS_PATH,
+    DLA_SECTION_SELECTOR_PATH,
+  ]);
+  if (requiredStatus) {
+    throw new Error(`DLA required region-audit sources must be clean:\n${requiredStatus}`);
+  }
+}
+
+function report(mode, parityFile) {
+  process.stderr.write(
+    `region-audit goldens ${mode}: DLA commit=${DLA_REGION_AUDIT_COMMIT} ` +
+      `regionAudit=${DLA_REGION_AUDIT_BLOB} regionCensus=${DLA_REGION_CENSUS_BLOB} ` +
+      `sectionSelector=${DLA_SECTION_SELECTOR_BLOB} cases=${parityFile.cases.length}\n`
+  );
+}
+
+verifyDlaOracle();
+
+const dlaAudit = await import(pathToFileURL(path.join(dlaRoot, DLA_REGION_AUDIT_PATH)).href);
+const dlaCensus = await import(pathToFileURL(path.join(dlaRoot, DLA_REGION_CENSUS_PATH)).href);
+const parityFile = runRegionAuditParity({
+  reconcileRegions: dlaAudit.reconcileRegions,
+  extractSourceLandmarksFromHtml: dlaCensus.extractSourceLandmarksFromHtml,
+  selectorForHtmlRoot: dlaCensus.selectorForHtmlRoot,
+  landmarkRoleForHtmlRoot: dlaCensus.landmarkRoleForHtmlRoot,
+});
+const json = stableJson(parityFile);
+
+if (shouldCheck) {
+  const existing = readFileSync(outputPath, 'utf8');
+  if (existing !== json) {
+    throw new Error(`${outputPath} is out of date with DLA region-audit blobs`);
+  }
+  report('check', parityFile);
+}
+
+if (shouldWrite) {
+  writeFileSync(outputPath, json);
+  report('write', parityFile);
+}
+
+if (shouldStdout) {
+  process.stdout.write(json);
+  report('stdout', parityFile);
+}
diff --git a/packages/blocks-engine/src/__fixtures__/region-audit-corpus.ts b/packages/blocks-engine/src/__fixtures__/region-audit-corpus.ts
new file mode 100644
index 00000000..9207346f
--- /dev/null
+++ b/packages/blocks-engine/src/__fixtures__/region-audit-corpus.ts
@@ -0,0 +1,168 @@
+import type {
+  PlacedRegion,
+  RegionSelectionReport,
+  SourceLandmark,
+} from '../theme/index.js';
+
+export const DLA_REGION_AUDIT_COMMIT = '1e393c535850ee1a9482f83459f779d0e225b027';
+export const DLA_REGION_AUDIT_PATH = 'src/lib/replicate/region-audit.ts';
+export const DLA_REGION_CENSUS_PATH = 'src/lib/replicate/region-census.ts';
+export const DLA_SECTION_SELECTOR_PATH = 'src/lib/replicate/section-selector.ts';
+export const DLA_REGION_AUDIT_BLOB = '3e4bff0205056183fb3b09612df6caf5018a844f';
+export const DLA_REGION_CENSUS_BLOB = 'c447895fe50d42395ea4a4b8786467bef9eeabda';
+export const DLA_SECTION_SELECTOR_BLOB = 'a900bd3d4fe719af039faf9c586b17ae19403c38';
+
+export const REGION_AUDIT_DERIVATION =
+  'DLA region-audit + region-census over source HTML and explicit placed-region corpus';
+
+export interface RegionAuditCorpusCase {
+  id: string;
+  page: string;
+  entryUrl: string;
+  sourceHtml: string;
+  placed: PlacedRegion[];
+}
+
+export interface RegionAuditImpl {
+  extractSourceLandmarksFromHtml(html: string): SourceLandmark[];
+  selectorForHtmlRoot(html: string): string | undefined;
+  landmarkRoleForHtmlRoot(html: string): SourceLandmark['role'] | undefined;
+  reconcileRegions(
+    census: SourceLandmark[],
+    placed: PlacedRegion[],
+    page?: string,
+    entryUrl?: string
+  ): RegionSelectionReport;
+}
+
+export interface RegionAuditCaseRecord {
+  id: string;
+  input: RegionAuditCorpusCase;
+  rootSelector?: string;
+  rootRole?: SourceLandmark['role'];
+  census: SourceLandmark[];
+  report: RegionSelectionReport;
+}
+
+export interface RegionAuditParityFile {
+  version: 1;
+  derivation: string;
+  oracle: {
+    commit: string;
+    paths: {
+      regionAudit: string;
+      regionCensus: string;
+      sectionSelector: string;
+    };
+    blobs: {
+      regionAudit: string;
+      regionCensus: string;
+      sectionSelector: string;
+    };
+  };
+  cases: RegionAuditCaseRecord[];
+}
+
+export function regionAuditCases(): RegionAuditCorpusCase[] {
+  return [
+    {
+      id: 'home-header-body-footer',
+      page: 'home',
+      entryUrl: 'index.html',
+      sourceHtml: [
+        '<!doctype html><html><body>',
+        '<header id="mast"><nav class="main-menu"><a href="/">Home</a><a href="/shop">Shop</a></nav></header>',
+        '<main id="content"><section class="hero"><h1>Welcome</h1><p>Useful body copy long enough for actionability.</p><img src="hero.jpg"></section></main>',
+        '<footer><a href="/privacy">Privacy</a><a href="/contact">Contact</a></footer>',
+        '</body></html>',
+      ].join(''),
+      placed: [
+        { kind: 'header_part', role: 'header', selector: 'header#mast' },
+        { kind: 'page_body_section', selector: 'main#content' },
+        { kind: 'footer_part', role: 'footer', selector: 'footer:nth-of-type(1)' },
+      ],
+    },
+    {
+      id: 'dropped-complementary-rail',
+      page: 'home',
+      entryUrl: 'index.html',
+      sourceHtml: [
+        '<html><body>',
+        '<main id="content"><p>Main article text is present and placed in the page body.</p></main>',
+        '<aside class="rail"><a href="/a">Alpha</a><a href="/b">Beta</a><p>Related links with enough rail text.</p></aside>',
+        '</body></html>',
+      ].join(''),
+      placed: [{ kind: 'page_body_section', selector: 'main#content' }],
+    },
+    {
+      id: 'non-actionable-skip-nav',
+      page: 'home',
+      entryUrl: 'index.html',
+      sourceHtml: [
+        '<html><body>',
+        '<nav class="skip"><a href="#main">Skip</a></nav>',
+        '<main id="main"><p>Primary copy remains long enough to be actionable.</p></main>',
+        '</body></html>',
+      ].join(''),
+      placed: [{ kind: 'page_body_section', selector: 'main#main' }],
+    },
+    {
+      id: 'repeated-section-selector-exactness',
+      page: 'services',
+      entryUrl: 'services/index.html',
+      sourceHtml: [
+        '<html><body>',
+        '<section><h2>First</h2><p>First section copy long enough to audit.</p></section>',
+        '<section><h2>Second</h2><p>Second section copy long enough to audit.</p></section>',
+        '</body></html>',
+      ].join(''),
+      placed: [{ kind: 'page_body_section', selector: 'section:nth-of-type(1)' }],
+    },
+    {
+      id: 'role-qualified-aside-match',
+      page: 'about',
+      entryUrl: 'about/index.html',
+      sourceHtml: [
+        '<html><body>',
+        '<aside class="rail"><a href="/team">Team</a><a href="/careers">Careers</a><p>People rail content.</p></aside>',
+        '<main><p>About page body content remains in the page template.</p></main>',
+        '</body></html>',
+      ].join(''),
+      placed: [
+        { kind: 'header_part', role: 'aside', selector: 'aside.rail' },
+        { kind: 'page_body_section', selector: 'main:nth-of-type(1)' },
+      ],
+    },
+  ];
+}
+
+export function runRegionAuditParity(impl: RegionAuditImpl): RegionAuditParityFile {
+  return {
+    version: 1,
+    derivation: REGION_AUDIT_DERIVATION,
+    oracle: {
+      commit: DLA_REGION_AUDIT_COMMIT,
+      paths: {
+        regionAudit: DLA_REGION_AUDIT_PATH,
+        regionCensus: DLA_REGION_CENSUS_PATH,
+        sectionSelector: DLA_SECTION_SELECTOR_PATH,
+      },
+      blobs: {
+        regionAudit: DLA_REGION_AUDIT_BLOB,
+        regionCensus: DLA_REGION_CENSUS_BLOB,
+        sectionSelector: DLA_SECTION_SELECTOR_BLOB,
+      },
+    },
+    cases: regionAuditCases().map((testCase) => {
+      const census = impl.extractSourceLandmarksFromHtml(testCase.sourceHtml);
+      return {
+        id: testCase.id,
+        input: testCase,
+        rootSelector: impl.selectorForHtmlRoot(testCase.sourceHtml),
+        rootRole: impl.landmarkRoleForHtmlRoot(testCase.sourceHtml),
+        census,
+        report: impl.reconcileRegions(census, testCase.placed, testCase.page, testCase.entryUrl),
+      };
+    }),
+  };
+}
diff --git a/packages/blocks-engine/src/__fixtures__/region-audit-dla-goldens.json b/packages/blocks-engine/src/__fixtures__/region-audit-dla-goldens.json
new file mode 100644
index 00000000..886cf11f
--- /dev/null
+++ b/packages/blocks-engine/src/__fixtures__/region-audit-dla-goldens.json
@@ -0,0 +1,436 @@
+{
+  "version": 1,
+  "derivation": "DLA region-audit + region-census over source HTML and explicit placed-region corpus",
+  "oracle": {
+    "commit": "1e393c535850ee1a9482f83459f779d0e225b027",
+    "paths": {
+      "regionAudit": "src/lib/replicate/region-audit.ts",
+      "regionCensus": "src/lib/replicate/region-census.ts",
+      "sectionSelector": "src/lib/replicate/section-selector.ts"
+    },
+    "blobs": {
+      "regionAudit": "3e4bff0205056183fb3b09612df6caf5018a844f",
+      "regionCensus": "c447895fe50d42395ea4a4b8786467bef9eeabda",
+      "sectionSelector": "a900bd3d4fe719af039faf9c586b17ae19403c38"
+    }
+  },
+  "cases": [
+    {
+      "id": "home-header-body-footer",
+      "input": {
+        "id": "home-header-body-footer",
+        "page": "home",
+        "entryUrl": "index.html",
+        "sourceHtml": "<!doctype html><html><body><header id=\"mast\"><nav class=\"main-menu\"><a href=\"/\">Home</a><a href=\"/shop\">Shop</a></nav></header><main id=\"content\"><section class=\"hero\"><h1>Welcome</h1><p>Useful body copy long enough for actionability.</p><img src=\"hero.jpg\"></section></main><footer><a href=\"/privacy\">Privacy</a><a href=\"/contact\">Contact</a></footer></body></html>",
+        "placed": [
+          {
+            "kind": "header_part",
+            "role": "header",
+            "selector": "header#mast"
+          },
+          {
+            "kind": "page_body_section",
+            "selector": "main#content"
+          },
+          {
+            "kind": "footer_part",
+            "role": "footer",
+            "selector": "footer:nth-of-type(1)"
+          }
+        ]
+      },
+      "rootSelector": "header#mast",
+      "rootRole": "header",
+      "census": [
+        {
+          "role": "header",
+          "tag": "header",
+          "selector": "header#mast",
+          "textLength": 8,
+          "mediaCount": 0,
+          "linkCount": 2
+        },
+        {
+          "role": "main",
+          "tag": "main",
+          "selector": "main#content",
+          "textLength": 54,
+          "mediaCount": 1,
+          "linkCount": 0
+        },
+        {
+          "role": "footer",
+          "tag": "footer",
+          "selector": "footer:nth-of-type(1)",
+          "textLength": 14,
+          "mediaCount": 0,
+          "linkCount": 2
+        }
+      ],
+      "report": {
+        "page": "home",
+        "entryUrl": "index.html",
+        "assignments": [
+          {
+            "landmark": {
+              "role": "header",
+              "tag": "header",
+              "selector": "header#mast",
+              "textLength": 8,
+              "mediaCount": 0,
+              "linkCount": 2
+            },
+            "kind": "header_part"
+          },
+          {
+            "landmark": {
+              "role": "main",
+              "tag": "main",
+              "selector": "main#content",
+              "textLength": 54,
+              "mediaCount": 1,
+              "linkCount": 0
+            },
+            "kind": "page_body_section"
+          },
+          {
+            "landmark": {
+              "role": "footer",
+              "tag": "footer",
+              "selector": "footer:nth-of-type(1)",
+              "textLength": 14,
+              "mediaCount": 0,
+              "linkCount": 2
+            },
+            "kind": "footer_part"
+          }
+        ],
+        "unassignedRegions": [],
+        "counts": {
+          "sourceLandmarks": {
+            "header": 1,
+            "main": 1,
+            "footer": 1
+          },
+          "assigned": 3,
+          "unassigned": 0,
+          "nonActionable": 0
+        }
+      }
+    },
+    {
+      "id": "dropped-complementary-rail",
+      "input": {
+        "id": "dropped-complementary-rail",
+        "page": "home",
+        "entryUrl": "index.html",
+        "sourceHtml": "<html><body><main id=\"content\"><p>Main article text is present and placed in the page body.</p></main><aside class=\"rail\"><a href=\"/a\">Alpha</a><a href=\"/b\">Beta</a><p>Related links with enough rail text.</p></aside></body></html>",
+        "placed": [
+          {
+            "kind": "page_body_section",
+            "selector": "main#content"
+          }
+        ]
+      },
+      "rootSelector": "main#content",
+      "rootRole": "main",
+      "census": [
+        {
+          "role": "main",
+          "tag": "main",
+          "selector": "main#content",
+          "textLength": 57,
+          "mediaCount": 0,
+          "linkCount": 0
+        },
+        {
+          "role": "aside",
+          "tag": "aside",
+          "selector": "aside.rail",
+          "textLength": 45,
+          "mediaCount": 0,
+          "linkCount": 2
+        }
+      ],
+      "report": {
+        "page": "home",
+        "entryUrl": "index.html",
+        "assignments": [
+          {
+            "landmark": {
+              "role": "main",
+              "tag": "main",
+              "selector": "main#content",
+              "textLength": 57,
+              "mediaCount": 0,
+              "linkCount": 0
+            },
+            "kind": "page_body_section"
+          },
+          {
+            "landmark": {
+              "role": "aside",
+              "tag": "aside",
+              "selector": "aside.rail",
+              "textLength": 45,
+              "mediaCount": 0,
+              "linkCount": 2
+            },
+            "kind": "unassigned"
+          }
+        ],
+        "unassignedRegions": [
+          {
+            "role": "aside",
+            "tag": "aside",
+            "selector": "aside.rail",
+            "textLength": 45,
+            "mediaCount": 0,
+            "linkCount": 2
+          }
+        ],
+        "counts": {
+          "sourceLandmarks": {
+            "main": 1,
+            "aside": 1
+          },
+          "assigned": 1,
+          "unassigned": 1,
+          "nonActionable": 0
+        }
+      }
+    },
+    {
+      "id": "non-actionable-skip-nav",
+      "input": {
+        "id": "non-actionable-skip-nav",
+        "page": "home",
+        "entryUrl": "index.html",
+        "sourceHtml": "<html><body><nav class=\"skip\"><a href=\"#main\">Skip</a></nav><main id=\"main\"><p>Primary copy remains long enough to be actionable.</p></main></body></html>",
+        "placed": [
+          {
+            "kind": "page_body_section",
+            "selector": "main#main"
+          }
+        ]
+      },
+      "rootSelector": "nav.skip",
+      "rootRole": "nav",
+      "census": [
+        {
+          "role": "nav",
+          "tag": "nav",
+          "selector": "nav.skip",
+          "textLength": 4,
+          "mediaCount": 0,
+          "linkCount": 1
+        },
+        {
+          "role": "main",
+          "tag": "main",
+          "selector": "main#main",
+          "textLength": 50,
+          "mediaCount": 0,
+          "linkCount": 0
+        }
+      ],
+      "report": {
+        "page": "home",
+        "entryUrl": "index.html",
+        "assignments": [
+          {
+            "landmark": {
+              "role": "nav",
+              "tag": "nav",
+              "selector": "nav.skip",
+              "textLength": 4,
+              "mediaCount": 0,
+              "linkCount": 1
+            },
+            "kind": "non_actionable"
+          },
+          {
+            "landmark": {
+              "role": "main",
+              "tag": "main",
+              "selector": "main#main",
+              "textLength": 50,
+              "mediaCount": 0,
+              "linkCount": 0
+            },
+            "kind": "page_body_section"
+          }
+        ],
+        "unassignedRegions": [],
+        "counts": {
+          "sourceLandmarks": {
+            "nav": 1,
+            "main": 1
+          },
+          "assigned": 1,
+          "unassigned": 0,
+          "nonActionable": 1
+        }
+      }
+    },
+    {
+      "id": "repeated-section-selector-exactness",
+      "input": {
+        "id": "repeated-section-selector-exactness",
+        "page": "services",
+        "entryUrl": "services/index.html",
+        "sourceHtml": "<html><body><section><h2>First</h2><p>First section copy long enough to audit.</p></section><section><h2>Second</h2><p>Second section copy long enough to audit.</p></section></body></html>",
+        "placed": [
+          {
+            "kind": "page_body_section",
+            "selector": "section:nth-of-type(1)"
+          }
+        ]
+      },
+      "rootSelector": "section:nth-of-type(1)",
+      "rootRole": "section",
+      "census": [
+        {
+          "role": "section",
+          "tag": "section",
+          "selector": "section:nth-of-type(1)",
+          "textLength": 45,
+          "mediaCount": 0,
+          "linkCount": 0
+        },
+        {
+          "role": "section",
+          "tag": "section",
+          "selector": "section:nth-of-type(2)",
+          "textLength": 47,
+          "mediaCount": 0,
+          "linkCount": 0
+        }
+      ],
+      "report": {
+        "page": "services",
+        "entryUrl": "services/index.html",
+        "assignments": [
+          {
+            "landmark": {
+              "role": "section",
+              "tag": "section",
+              "selector": "section:nth-of-type(1)",
+              "textLength": 45,
+              "mediaCount": 0,
+              "linkCount": 0
+            },
+            "kind": "page_body_section"
+          },
+          {
+            "landmark": {
+              "role": "section",
+              "tag": "section",
+              "selector": "section:nth-of-type(2)",
+              "textLength": 47,
+              "mediaCount": 0,
+              "linkCount": 0
+            },
+            "kind": "unassigned"
+          }
+        ],
+        "unassignedRegions": [
+          {
+            "role": "section",
+            "tag": "section",
+            "selector": "section:nth-of-type(2)",
+            "textLength": 47,
+            "mediaCount": 0,
+            "linkCount": 0
+          }
+        ],
+        "counts": {
+          "sourceLandmarks": {
+            "section": 2
+          },
+          "assigned": 1,
+          "unassigned": 1,
+          "nonActionable": 0
+        }
+      }
+    },
+    {
+      "id": "role-qualified-aside-match",
+      "input": {
+        "id": "role-qualified-aside-match",
+        "page": "about",
+        "entryUrl": "about/index.html",
+        "sourceHtml": "<html><body><aside class=\"rail\"><a href=\"/team\">Team</a><a href=\"/careers\">Careers</a><p>People rail content.</p></aside><main><p>About page body content remains in the page template.</p></main></body></html>",
+        "placed": [
+          {
+            "kind": "header_part",
+            "role": "aside",
+            "selector": "aside.rail"
+          },
+          {
+            "kind": "page_body_section",
+            "selector": "main:nth-of-type(1)"
+          }
+        ]
+      },
+      "rootSelector": "aside.rail",
+      "rootRole": "aside",
+      "census": [
+        {
+          "role": "aside",
+          "tag": "aside",
+          "selector": "aside.rail",
+          "textLength": 31,
+          "mediaCount": 0,
+          "linkCount": 2
+        },
+        {
+          "role": "main",
+          "tag": "main",
+          "selector": "main:nth-of-type(1)",
+          "textLength": 53,
+          "mediaCount": 0,
+          "linkCount": 0
+        }
+      ],
+      "report": {
+        "page": "about",
+        "entryUrl": "about/index.html",
+        "assignments": [
+          {
+            "landmark": {
+              "role": "aside",
+              "tag": "aside",
+              "selector": "aside.rail",
+              "textLength": 31,
+              "mediaCount": 0,
+              "linkCount": 2
+            },
+            "kind": "header_part"
+          },
+          {
+            "landmark": {
+              "role": "main",
+              "tag": "main",
+              "selector": "main:nth-of-type(1)",
+              "textLength": 53,
+              "mediaCount": 0,
+              "linkCount": 0
+            },
+            "kind": "page_body_section"
+          }
+        ],
+        "unassignedRegions": [],
+        "counts": {
+          "sourceLandmarks": {
+            "aside": 1,
+            "main": 1
+          },
+          "assigned": 2,
+          "unassigned": 0,
+          "nonActionable": 0
+        }
+      }
+    }
+  ]
+}
diff --git a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
index 0680203f..6a2b3997 100644
--- a/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
+++ b/packages/blocks-engine/src/__tests__/site-to-theme.e2e.test.ts
@@ -1206,6 +1206,30 @@ describe('site-to-theme P0-3 orchestration', () => {
     });
   });
 
+  it('surfaces homepage region audit diagnostics without writing audit artifacts', async () => {
+    const { siteToTheme } = await import('../theme/index.js');
+
+    await withTempDir('blocks-engine-site-to-theme-region-audit-', async (siteDir) => {
+      copyFixtureSite(siteDir);
+      const outDir = join(siteDir, 'theme-out');
+
+      const result = await siteToTheme(siteDir, { outDir });
+
+      expect(result.diagnostics.regionAudit).toHaveLength(1);
+      const [audit] = result.diagnostics.regionAudit;
+      expect(audit.page).toBe('home');
+      expect(audit.entryUrl).toBe('index.html');
+      expect(audit.counts.sourceLandmarks).toEqual({ header: 1, main: 1, footer: 1 });
+      expect(audit.assignments.map((assignment) => assignment.kind)).toEqual([
+        'header_part',
+        'page_body_section',
+        'non_actionable',
+      ]);
+      expect(result.written).not.toContain('region-audit.json');
+      expect(existsSync(join(outDir, 'region-audit.json'))).toBe(false);
+    });
+  });
+
   it('treats absent hooks the same as empty and explicit identity hooks byte-for-byte', async () => {
     const { siteToTheme } = await import('../theme/index.js');
 
diff --git a/packages/blocks-engine/src/__tests__/theme-region-audit-parity.test.ts b/packages/blocks-engine/src/__tests__/theme-region-audit-parity.test.ts
new file mode 100644
index 00000000..a6335c65
--- /dev/null
+++ b/packages/blocks-engine/src/__tests__/theme-region-audit-parity.test.ts
@@ -0,0 +1,80 @@
+import expectedGoldens from '../__fixtures__/region-audit-dla-goldens.json' with { type: 'json' };
+import {
+  regionAuditCases,
+  runRegionAuditParity,
+  type RegionAuditParityFile,
+} from '../__fixtures__/region-audit-corpus.js';
+import {
+  extractSourceLandmarksFromHtml,
+  landmarkRoleForHtmlRoot,
+  reconcileRegions,
+  selectorForHtmlRoot,
+} from '../theme/index.js';
+import { describe, expect, it } from 'vitest';
+
+function stableJson(value: unknown): string {
+  return JSON.stringify(value, null, 2);
+}
+
+function collectDiffs(actual: RegionAuditParityFile, expected: RegionAuditParityFile): string[] {
+  const diffs: string[] = [];
+  if (actual.version !== expected.version) diffs.push(`version: expected ${expected.version}, got ${actual.version}`);
+  if (actual.derivation !== expected.derivation) diffs.push('derivation: changed');
+  if (stableJson(actual.oracle) !== stableJson(expected.oracle)) diffs.push('oracle: changed');
+
+  const expectedById = new Map(expected.cases.map((record) => [record.id, record]));
+  for (const actualCase of actual.cases) {
+    const expectedCase = expectedById.get(actualCase.id);
+    if (!expectedCase) {
+      diffs.push(`${actualCase.id}: missing from checked-in DLA goldens`);
+      continue;
+    }
+    if (stableJson(actualCase.input) !== stableJson(expectedCase.input)) {
+      diffs.push(`${actualCase.id}: input changed`);
+    }
+    if (actualCase.rootSelector !== expectedCase.rootSelector) {
+      diffs.push(`${actualCase.id}: root selector changed`);
+    }
+    if (actualCase.rootRole !== expectedCase.rootRole) {
+      diffs.push(`${actualCase.id}: root role changed`);
+    }
+    if (stableJson(actualCase.census) !== stableJson(expectedCase.census)) {
+      diffs.push(`${actualCase.id}: census changed`);
+    }
+    if (stableJson(actualCase.report) !== stableJson(expectedCase.report)) {
+      diffs.push(`${actualCase.id}: report changed`);
+    }
+  }
+
+  const actualIds = new Set(actual.cases.map((record) => record.id));
+  for (const expectedCase of expected.cases) {
+    if (!actualIds.has(expectedCase.id)) diffs.push(`${expectedCase.id}: golden has no corpus case`);
+  }
+  return diffs;
+}
+
+describe('region audit DLA parity', () => {
+  it('matches checked-in DLA region census and reconciliation goldens byte-for-byte', () => {
+    const first = runRegionAuditParity({
+      extractSourceLandmarksFromHtml,
+      selectorForHtmlRoot,
+      landmarkRoleForHtmlRoot,
+      reconcileRegions,
+    });
+    const second = runRegionAuditParity({
+      extractSourceLandmarksFromHtml,
+      selectorForHtmlRoot,
+      landmarkRoleForHtmlRoot,
+      reconcileRegions,
+    });
+    expect(collectDiffs(first, second)).toEqual([]);
+
+    const expected = expectedGoldens as unknown as RegionAuditParityFile;
+    const diffs = collectDiffs(first, expected);
+    console.info(`region audit parity: cases=${first.cases.length} diffs=${diffs.length}`);
+
+    expect(first.cases.length).toBe(5);
+    expect(regionAuditCases()).toHaveLength(5);
+    expect(diffs).toEqual([]);
+  });
+});
diff --git a/packages/blocks-engine/src/theme/region-audit.ts b/packages/blocks-engine/src/theme/region-audit.ts
index b331377d..7efdf1bf 100644
--- a/packages/blocks-engine/src/theme/region-audit.ts
+++ b/packages/blocks-engine/src/theme/region-audit.ts
@@ -48,11 +48,108 @@ export interface RegionSelectionReport {
   };
 }
 
+const ACTIONABLE_TEXT_MIN = 24;
+const ACTIONABLE_LINK_MIN = 2;
+
+function normalizePositionalSelector(selector: string): string {
+  return selector.replace(/:nth-of-type\(\d+\)/g, ':nth-of-type(1)');
+}
+
+interface PlacementIndex {
+  exact: Map<string, PlacedRegion>;
+  normalized: Map<string, PlacedRegion[]>;
+  sourceCounts: Map<string, number>;
+  sourceRoleCounts: Map<string, number>;
+}
+
+function roleKey(role: SourceLandmark['role'], selector: string): string {
+  return `${role}\u0000${selector}`;
+}
+
+function requiresRoleQualifiedSelector(role: SourceLandmark['role']): boolean {
+  return role === 'aside' || role === 'complementary';
+}
+
+function buildPlacementIndex(census: SourceLandmark[], placed: PlacedRegion[]): PlacementIndex {
+  const exact = new Map<string, PlacedRegion>();
+  const normalized = new Map<string, PlacedRegion[]>();
+  const sourceCounts = new Map<string, number>();
+  const sourceRoleCounts = new Map<string, number>();
+  for (const l of census) {
+    const key = normalizePositionalSelector(l.selector);
+    sourceCounts.set(key, (sourceCounts.get(key) ?? 0) + 1);
+    const rKey = roleKey(l.role, key);
+    sourceRoleCounts.set(rKey, (sourceRoleCounts.get(rKey) ?? 0) + 1);
+  }
+  for (const p of placed) {
+    if (!p.selector) continue;
+    exact.set(p.selector, p);
+    const key = normalizePositionalSelector(p.selector);
+    const entries = normalized.get(key) ?? [];
+    entries.push(p);
+    normalized.set(key, entries);
+  }
+  return { exact, normalized, sourceCounts, sourceRoleCounts };
+}
+
+function placedBySelector(l: SourceLandmark, index: PlacementIndex): PlacedRegion | undefined {
+  const exact = index.exact.get(l.selector);
+  const roleQualified = requiresRoleQualifiedSelector(l.role);
+  if (exact) return exact;
+
+  const key = normalizePositionalSelector(l.selector);
+  const candidates = index.normalized.get(key) ?? [];
+  if (candidates.length === 0) return undefined;
+
+  const roleCandidates = candidates.filter((p) => p.role === l.role || (!roleQualified && p.role === undefined));
+  if (roleCandidates.length === 1 && (index.sourceRoleCounts.get(roleKey(l.role, key)) ?? 0) === 1) {
+    return roleCandidates[0];
+  }
+
+  if (!roleQualified && candidates.length === 1 && (index.sourceCounts.get(key) ?? 0) === 1) {
+    return candidates[0];
+  }
+
+  return undefined;
+}
+
+function classify(l: SourceLandmark, placed: PlacedRegion[], index: PlacementIndex): RegionAssignmentKind {
+  if (l.textLength < ACTIONABLE_TEXT_MIN && l.mediaCount === 0 && (l.linkCount ?? 0) < ACTIONABLE_LINK_MIN) return 'non_actionable';
+  const hasHeader = placed.some((p) => p.kind === 'header_part');
+  const hasFooter = placed.some((p) => p.kind === 'footer_part');
+  const bodySelectors = new Set(placed.filter((p) => p.kind === 'page_body_section').map((p) => p.selector));
+  if ((l.role === 'header' || l.role === 'nav') && hasHeader) return 'header_part';
+  if (l.role === 'footer' && hasFooter) return 'footer_part';
+  if (l.role === 'main' || l.role === 'article') return bodySelectors.size > 0 ? 'page_body_section' : 'unassigned';
+  if (l.role === 'aside' || l.role === 'complementary') {
+    const selectorPlacement = placedBySelector(l, index);
+    if (selectorPlacement) return selectorPlacement.kind;
+    const placedLandmark = placed.find((p) => p.role === l.role && p.selector === undefined);
+    if (placedLandmark) return placedLandmark.kind;
+    return 'unassigned';
+  }
+  if (bodySelectors.has(l.selector) || placedBySelector(l, index)?.kind === 'page_body_section') return 'page_body_section';
+  return 'unassigned';
+}
+
 export function reconcileRegions(
-  _census: SourceLandmark[],
-  _placed: PlacedRegion[],
-  _page = '',
-  _entryUrl = ''
+  census: SourceLandmark[],
+  placed: PlacedRegion[],
+  page = '',
+  entryUrl = '',
 ): RegionSelectionReport {
-  throw new Error('region audit reconciliation is not implemented');
+  const index = buildPlacementIndex(census, placed);
+  const assignments = census.map((l) => ({ landmark: l, kind: classify(l, placed, index) }));
+  const sourceLandmarks: Record<string, number> = {};
+  for (const l of census) sourceLandmarks[l.role] = (sourceLandmarks[l.role] ?? 0) + 1;
+  const unassignedRegions = assignments.filter((a) => a.kind === 'unassigned').map((a) => a.landmark);
+  return {
+    page, entryUrl, assignments, unassignedRegions,
+    counts: {
+      sourceLandmarks,
+      assigned: assignments.filter((a) => ['page_body_section', 'header_part', 'footer_part'].includes(a.kind)).length,
+      unassigned: unassignedRegions.length,
+      nonActionable: assignments.filter((a) => a.kind === 'non_actionable').length,
+    },
+  };
 }
diff --git a/packages/blocks-engine/src/theme/region-census.ts b/packages/blocks-engine/src/theme/region-census.ts
index f9e78cc0..dd4033d9 100644
--- a/packages/blocks-engine/src/theme/region-census.ts
+++ b/packages/blocks-engine/src/theme/region-census.ts
@@ -1,13 +1,103 @@
+import * as cheerio from 'cheerio';
+import type { CheerioAPI } from 'cheerio';
+import { isTag } from 'domhandler';
+import type { Element } from 'domhandler';
 import type { SourceLandmark } from './region-audit.js';
+import { buildSelector, type SelectorParts } from './section-selector.js';
 
-export function selectorForHtmlRoot(_html: string): string | undefined {
-  throw new Error('region audit census is not implemented');
+const LANDMARK_TAGS = new Set(['main', 'nav', 'header', 'footer', 'section', 'article', 'aside']);
+const LANDMARK_SELECTOR = 'main,nav,header,footer,section,article,aside,[role="complementary"]';
+
+function normalizeText(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+function roleOf($: CheerioAPI, el: Element): SourceLandmark['role'] {
+  const ariaRole = ($(el).attr('role') ?? '').trim().toLowerCase();
+  if (ariaRole === 'complementary') return 'complementary';
+  const tag = el.tagName?.toLowerCase() ?? 'section';
+  if (
+    tag === 'main' || tag === 'nav' || tag === 'header' || tag === 'footer' ||
+    tag === 'section' || tag === 'article' || tag === 'aside'
+  ) {
+    return tag;
+  }
+  return 'section';
+}
+
+function isLandmark($: CheerioAPI, el: Element): boolean {
+  const tag = el.tagName?.toLowerCase() ?? '';
+  return LANDMARK_TAGS.has(tag) || roleOf($, el) === 'complementary';
+}
+
+function hasLandmarkAncestor($: CheerioAPI, el: Element): boolean {
+  for (let a = el.parent; a && isTag(a); a = a.parent) {
+    if (isLandmark($, a as Element)) return true;
+  }
+  return false;
+}
+
+function isProbablyVisible($: CheerioAPI, el: Element): boolean {
+  const $el = $(el);
+  if ($el.attr('hidden') !== undefined) return false;
+  if (($el.attr('aria-hidden') ?? '').trim().toLowerCase() === 'true') return false;
+  const style = ($el.attr('style') ?? '').replace(/\s+/g, '').toLowerCase();
+  return !/display:none|visibility:hidden/.test(style);
+}
+
+function selectorParts($: CheerioAPI, el: Element): SelectorParts {
+  const tag = el.tagName.toLowerCase();
+  let nthOfType = 1;
+  for (let prev = el.prev; prev; prev = prev.prev) {
+    if (isTag(prev) && (prev as Element).tagName?.toLowerCase() === tag) nthOfType += 1;
+  }
+  const $el = $(el);
+  return {
+    tag,
+    id: ($el.attr('id') ?? '').trim() || null,
+    classes: ($el.attr('class') ?? '').split(/\s+/).filter(Boolean),
+    nthOfType,
+  };
+}
+
+export function selectorForHtmlRoot(html: string): string | undefined {
+  const $ = cheerio.load(html);
+  const el = $('body').children().first().get(0) ?? $.root().children().first().get(0);
+  if (!el || !isTag(el)) return undefined;
+  return buildSelector(selectorParts($, el as Element));
 }
 
-export function landmarkRoleForHtmlRoot(_html: string): SourceLandmark['role'] | undefined {
-  throw new Error('region audit census is not implemented');
+export function landmarkRoleForHtmlRoot(html: string): SourceLandmark['role'] | undefined {
+  const $ = cheerio.load(html);
+  const el = $('body').children().first().get(0) ?? $.root().children().first().get(0);
+  if (!el || !isTag(el)) return undefined;
+  const element = el as Element;
+  return isLandmark($, element) ? roleOf($, element) : undefined;
 }
 
-export function extractSourceLandmarksFromHtml(_html: string): SourceLandmark[] {
-  throw new Error('region audit census is not implemented');
+export function extractSourceLandmarksFromHtml(html: string): SourceLandmark[] {
+  const $ = cheerio.load(html);
+  const landmarks: SourceLandmark[] = [];
+  const seen = new Set<Element>();
+
+  $(LANDMARK_SELECTOR).each((_, node) => {
+    if (!isTag(node)) return;
+    const el = node as Element;
+    if (seen.has(el)) return;
+    seen.add(el);
+    if (hasLandmarkAncestor($, el)) return;
+    if (!isProbablyVisible($, el)) return;
+
+    const $el = $(el);
+    landmarks.push({
+      role: roleOf($, el),
+      tag: el.tagName.toLowerCase(),
+      selector: buildSelector(selectorParts($, el)),
+      textLength: normalizeText($el.text()).length,
+      mediaCount: $el.find('img,video,picture').length,
+      linkCount: $el.find('a[href]').length,
+    });
+  });
+
+  return landmarks;
 }
diff --git a/packages/blocks-engine/src/theme/section-selector.ts b/packages/blocks-engine/src/theme/section-selector.ts
index 3a382f51..11fea550 100644
--- a/packages/blocks-engine/src/theme/section-selector.ts
+++ b/packages/blocks-engine/src/theme/section-selector.ts
@@ -1,10 +1,25 @@
 export interface SelectorParts {
+  /** Lowercased tag name. */
   tag: string;
+  /** Element id, or null. */
   id: string | null;
+  /** Raw class list in document order. */
   classes: string[];
+  /** 1-based index among same-tag siblings (for :nth-of-type). */
   nthOfType: number;
 }
 
-export function buildSelector(_parts: SelectorParts): string {
-  throw new Error('region audit selector builder is not implemented');
+/** True for builder-generated hash-y classes we should not anchor on. */
+function isHashy(cls: string): boolean {
+  return cls.length >= 16 || /[0-9a-f]{6,}/i.test(cls);
+}
+
+export function buildSelector(parts: SelectorParts): string {
+  let sel = parts.tag;
+  if (parts.id) sel += `#${parts.id}`;
+  const kept = parts.classes.filter((c) => c && !isHashy(c)).slice(0, 3);
+  for (const c of kept) sel += `.${c}`;
+  // Disambiguate by position ONLY when neither id nor a kept class is present.
+  if (!parts.id && kept.length === 0) sel += `:nth-of-type(${parts.nthOfType})`;
+  return sel;
 }
diff --git a/packages/blocks-engine/src/theme/site-to-theme.ts b/packages/blocks-engine/src/theme/site-to-theme.ts
index fe922d14..f2c45c0e 100644
--- a/packages/blocks-engine/src/theme/site-to-theme.ts
+++ b/packages/blocks-engine/src/theme/site-to-theme.ts
@@ -8,6 +8,8 @@ import { foundation } from './foundation.js';
 import { ingest } from './ingest.js';
 import { detectLayoutOffsetWrapper } from './layout-offset-wrapper.js';
 import { reconstruct } from './reconstruct.js';
+import { extractSourceLandmarksFromHtml } from './region-census.js';
+import { reconcileRegions, type PlacedRegion, type RegionSelectionReport } from './region-audit.js';
 import { sectionExtract } from './section-extract.js';
 import { collectSourceAssets, type MediaAsset } from './source-assets.js';
 import { shouldCarrySourceCss } from './source-css-carry.js';
@@ -65,6 +67,7 @@ export async function siteToTheme(
       );
     }
 
+    const regionAudit = buildRegionAuditDiagnostics(site, pages, chromeRes.parts, chromeRes.slugsByPage, warnings);
     const styleBlocks =
       options?.variationHoist === false ? undefined : hoistPageStyleBlocks(site, pages, warnings);
     const assetStage = await runAssetsStage(ctx, { fetchImpl: options?.fetchImpl });
@@ -118,7 +121,7 @@ export async function siteToTheme(
       },
       warnings,
       diagnostics: {
-        regionAudit: [],
+        regionAudit,
       },
     };
   } finally {
@@ -128,6 +131,37 @@ export async function siteToTheme(
   }
 }
 
+function buildRegionAuditDiagnostics(
+  site: { pages: Array<{ slug: string; relPath: string; html: string }> },
+  pages: Record<string, SectionBlocks[]>,
+  chromeParts: Record<string, string>,
+  chromeSlugsByPage: Record<string, { header: string; footer: string }>,
+  warnings: string[]
+): RegionSelectionReport[] {
+  const home = homePage(site);
+  if (!home) return [];
+
+  try {
+    const census = extractSourceLandmarksFromHtml(home.html);
+    const placed: PlacedRegion[] = (pages[home.slug] ?? [])
+      .map((section) => section.spec.selector)
+      .filter((selector): selector is string => Boolean(selector))
+      .map((selector) => ({ kind: 'page_body_section' as const, selector }));
+    const chromeSlugs = chromeSlugsByPage[home.slug];
+    if (chromeSlugs && chromeParts[`${chromeSlugs.header}.html`]) {
+      placed.push({ kind: 'header_part', role: 'header' });
+    }
+    if (chromeSlugs && chromeParts[`${chromeSlugs.footer}.html`]) {
+      placed.push({ kind: 'footer_part', role: 'footer' });
+    }
+
+    return [reconcileRegions(census, placed, home.slug, home.relPath)];
+  } catch (error) {
+    warnings.push(`region audit failed (continuing): ${error instanceof Error ? error.message : String(error)}`);
+    return [];
+  }
+}
+
 function hoistPageStyleBlocks(
   site: { pages: Array<{ slug: string }> },
   pages: Record<string, SectionBlocks[]>,
@@ -293,7 +327,7 @@ function normalizeThemeMeta(srcDir: string, meta: Partial<ThemeMeta> | undefined
   };
 }
 
-function homePage(site: { pages: Array<{ slug: string; html: string }> }): { html: string } | undefined {
+function homePage<T extends { slug: string }>(site: { pages: T[] }): T | undefined {
   return site.pages.find((page) => page.slug === 'home') ?? site.pages[0];
 }
 

From d48fa0514a9e86b80aaf36fde13e89e54b85e978 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Fri, 26 Jun 2026 07:42:48 -0400
Subject: [PATCH 099/113] feat(cli): default to whole-site theme builds

---
 .../blocks-engine/src/__tests__/cli.test.ts   | 151 +++++++++++++++++-
 packages/blocks-engine/src/cli.ts             | 138 ++++++++++++++--
 2 files changed, 271 insertions(+), 18 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/cli.test.ts b/packages/blocks-engine/src/__tests__/cli.test.ts
index 633d2513..2a25a984 100644
--- a/packages/blocks-engine/src/__tests__/cli.test.ts
+++ b/packages/blocks-engine/src/__tests__/cli.test.ts
@@ -7,6 +7,7 @@ import { describe, expect, it } from 'vitest';
 
 import { runCli } from '../cli';
 import { BlocksEngineError } from '../errors';
+import type { SiteToThemeOptions, ThemeBuildResult } from '../theme/types';
 
 function writableBuffer() {
   let output = '';
@@ -22,6 +23,26 @@ function writableBuffer() {
   };
 }
 
+function themeResult(outDir: string, written: string[] = ['theme.json']): ThemeBuildResult {
+  return {
+    outDir,
+    model: {
+      styleCss: '',
+      themeJson: {},
+      templates: {},
+      parts: {},
+      patterns: {},
+      assets: [],
+    },
+    written,
+    tallies: {},
+    warnings: [],
+    diagnostics: {
+      regionAudit: [],
+    },
+  };
+}
+
 describe('CLI one-shot conversion', () => {
   it('reads a file arg and writes block markup to stdout', async () => {
     const dir = await mkdtemp(join(tmpdir(), 'blocks-engine-cli-'));
@@ -32,7 +53,7 @@ describe('CLI one-shot conversion', () => {
 
       const stdout = writableBuffer();
       const stderr = writableBuffer();
-      const exitCode = await runCli([filePath], {
+      const exitCode = await runCli(['convert', filePath], {
         stdout: stdout.stream,
         stderr: stderr.stream,
       });
@@ -45,12 +66,12 @@ describe('CLI one-shot conversion', () => {
     }
   });
 
-  it('reads stdin when no file arg is provided', async () => {
+  it('reads stdin when convert has no file arg', async () => {
     let seenUrl: string | undefined;
     const stdout = writableBuffer();
     const stderr = writableBuffer();
 
-    const exitCode = await runCli([], {
+    const exitCode = await runCli(['convert'], {
       stdin: Readable.from(['<p>From stdin.</p>']),
       stdout: stdout.stream,
       stderr: stderr.stream,
@@ -71,7 +92,7 @@ describe('CLI one-shot conversion', () => {
     const stdout = writableBuffer();
     const stderr = writableBuffer();
 
-    const exitCode = await runCli([], {
+    const exitCode = await runCli(['convert'], {
       stdin: Readable.from(['<p>Unsafe.</p>']),
       stdout: stdout.stream,
       stderr: stderr.stream,
@@ -89,3 +110,125 @@ describe('CLI one-shot conversion', () => {
     expect(stderr.text()).toContain('Remove unsupported markup and try again.');
   });
 });
+
+describe('CLI theme builds', () => {
+  it('runs the explicit theme subcommand with output and theme metadata options', async () => {
+    const srcDir = '/tmp/source-site';
+    const outDir = '/tmp/source-theme';
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+    const calls: Array<{ srcDir: string; options: SiteToThemeOptions | undefined }> = [];
+
+    const exitCode = await runCli(
+      ['theme', srcDir, '--out', outDir, '--slug', 'demo', '--name', 'Demo'],
+      {
+        stdout: stdout.stream,
+        stderr: stderr.stream,
+        siteToThemeImpl: async (calledSrcDir, options) => {
+          calls.push({ srcDir: calledSrcDir, options });
+          return {
+            ...themeResult(outDir, ['theme.json', 'style.css']),
+            warnings: ['kept source CSS'],
+          };
+        },
+      }
+    );
+
+    expect(exitCode).toBe(0);
+    expect(calls).toEqual([
+      {
+        srcDir,
+        options: {
+          outDir,
+          themeMeta: {
+            slug: 'demo',
+            name: 'Demo',
+          },
+        },
+      },
+    ]);
+    expect(stdout.text()).toBe(`wrote theme to ${outDir} (2 files)\n`);
+    expect(stderr.text()).toBe('kept source CSS\n');
+  });
+
+  it('treats a bare path argument as theme shorthand', async () => {
+    const srcDir = '/tmp/source-site';
+    const outDir = '/tmp/bare-theme';
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+    const calls: Array<{ srcDir: string; options: SiteToThemeOptions | undefined }> = [];
+
+    const exitCode = await runCli([srcDir, `--out=${outDir}`], {
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+      siteToThemeImpl: async (calledSrcDir, options) => {
+        calls.push({ srcDir: calledSrcDir, options });
+        return themeResult(outDir, ['theme.json']);
+      },
+    });
+
+    expect(exitCode).toBe(0);
+    expect(calls).toEqual([
+      {
+        srcDir,
+        options: {
+          outDir,
+          themeMeta: {},
+        },
+      },
+    ]);
+    expect(stdout.text()).toBe(`wrote theme to ${outDir} (1 files)\n`);
+    expect(stderr.text()).toBe('');
+  });
+
+  it('prints help with both CLI verbs', async () => {
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+
+    const exitCode = await runCli(['--help'], {
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+    });
+
+    expect(exitCode).toBe(0);
+    expect(stdout.text()).toContain('blocks-engine theme <srcDir>');
+    expect(stdout.text()).toContain('blocks-engine <srcDir>');
+    expect(stdout.text()).toContain('blocks-engine convert [file]');
+    expect(stderr.text()).toBe('');
+  });
+
+  it('prints help when no command or path is provided', async () => {
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+
+    const exitCode = await runCli([], {
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+    });
+
+    expect(exitCode).toBe(0);
+    expect(stdout.text()).toContain('blocks-engine theme <srcDir>');
+    expect(stdout.text()).toContain('blocks-engine convert [file]');
+    expect(stderr.text()).toBe('');
+  });
+
+  it('prints a clear error when the explicit theme command omits srcDir', async () => {
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+    const calls: string[] = [];
+
+    const exitCode = await runCli(['theme'], {
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+      siteToThemeImpl: async (srcDir) => {
+        calls.push(srcDir);
+        return themeResult('/tmp/unused');
+      },
+    });
+
+    expect(exitCode).toBe(1);
+    expect(calls).toEqual([]);
+    expect(stdout.text()).toBe('');
+    expect(stderr.text()).toContain('Missing <srcDir>');
+  });
+});
diff --git a/packages/blocks-engine/src/cli.ts b/packages/blocks-engine/src/cli.ts
index 83c8af68..17d4c79d 100644
--- a/packages/blocks-engine/src/cli.ts
+++ b/packages/blocks-engine/src/cli.ts
@@ -8,18 +8,22 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { convert } from './convert.js';
 import { BlocksEngineError } from './errors.js';
+import { siteToTheme } from './theme/site-to-theme.js';
+import type { SiteToThemeOptions, ThemeBuildResult } from './theme/types.js';
 
 interface WritableLike {
   write(chunk: string | Uint8Array): unknown;
 }
 
 type ConvertHtml = (html: string, ctx: { url: string }) => Promise<string>;
+type SiteToThemeImpl = (srcDir: string, options?: SiteToThemeOptions) => Promise<ThemeBuildResult>;
 
 export interface RunCliOptions {
   stdin?: Readable;
   stdout?: WritableLike;
   stderr?: WritableLike;
   convertHtml?: ConvertHtml;
+  siteToThemeImpl?: SiteToThemeImpl;
 }
 
 async function readStdin(stdin: Readable): Promise<string> {
@@ -37,22 +41,21 @@ export async function runCli(argv: string[], options: RunCliOptions = {}): Promi
   const stdout = options.stdout ?? process.stdout;
   const stderr = options.stderr ?? process.stderr;
   const convertHtml = options.convertHtml ?? convert;
-  const fileArg = argv[0];
+  const siteToThemeImpl = options.siteToThemeImpl ?? siteToTheme;
 
   try {
-    const input =
-      fileArg === undefined
-        ? {
-            html: await readStdin(stdin),
-            url: pathToFileURL(resolve(process.cwd(), 'stdin')).href,
-          }
-        : {
-            html: await readFile(resolve(fileArg), 'utf8'),
-            url: pathToFileURL(resolve(fileArg)).href,
-          };
-
-    stdout.write(await convertHtml(input.html, { url: input.url }));
-    return 0;
+    const command = argv[0];
+    if (command === undefined || command === '--help' || command === '-h') {
+      stdout.write(usage());
+      return 0;
+    }
+
+    if (command === 'convert') {
+      return await runConvert(argv.slice(1), { stdin, stdout, convertHtml });
+    }
+
+    const themeArgs = command === 'theme' ? argv.slice(1) : argv;
+    return await runTheme(themeArgs, { stdout, stderr, siteToThemeImpl });
   } catch (error) {
     if (error instanceof BlocksEngineError) {
       stderr.write(`${error.message}\n${error.hint}\n`);
@@ -65,6 +68,113 @@ export async function runCli(argv: string[], options: RunCliOptions = {}): Promi
   }
 }
 
+async function runConvert(
+  argv: string[],
+  options: { stdin: Readable; stdout: WritableLike; convertHtml: ConvertHtml }
+): Promise<number> {
+  const fileArg = argv[0];
+  const input =
+    fileArg === undefined
+      ? {
+          html: await readStdin(options.stdin),
+          url: pathToFileURL(resolve(process.cwd(), 'stdin')).href,
+        }
+      : {
+          html: await readFile(resolve(fileArg), 'utf8'),
+          url: pathToFileURL(resolve(fileArg)).href,
+        };
+
+  options.stdout.write(await options.convertHtml(input.html, { url: input.url }));
+  return 0;
+}
+
+async function runTheme(
+  argv: string[],
+  options: { stdout: WritableLike; stderr: WritableLike; siteToThemeImpl: SiteToThemeImpl }
+): Promise<number> {
+  const { srcDir, themeOptions } = parseThemeArgs(argv);
+  const result = await options.siteToThemeImpl(srcDir, themeOptions);
+
+  options.stdout.write(`wrote theme to ${result.outDir} (${result.written.length} files)\n`);
+  for (const warning of result.warnings) {
+    options.stderr.write(`${warning}\n`);
+  }
+
+  return 0;
+}
+
+function parseThemeArgs(argv: string[]): { srcDir: string; themeOptions: SiteToThemeOptions } {
+  const srcDir = argv[0];
+  if (srcDir === undefined) {
+    throw new Error('Missing <srcDir> for theme command.');
+  }
+
+  const flags: { outDir?: string; slug?: string; name?: string } = {};
+
+  for (let index = 1; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--out' || arg === '--slug' || arg === '--name') {
+      const value = argv[index + 1];
+      if (value === undefined) {
+        throw new Error(`Missing value for ${arg}.`);
+      }
+      setThemeFlag(flags, arg, value);
+      index += 1;
+    } else if (arg.startsWith('--out=') || arg.startsWith('--slug=') || arg.startsWith('--name=')) {
+      const equalsIndex = arg.indexOf('=');
+      setThemeFlag(flags, arg.slice(0, equalsIndex), arg.slice(equalsIndex + 1));
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+
+  const themeMeta: NonNullable<SiteToThemeOptions['themeMeta']> = {};
+  if (flags.slug !== undefined) themeMeta.slug = flags.slug;
+  if (flags.name !== undefined) themeMeta.name = flags.name;
+
+  return {
+    srcDir,
+    themeOptions: {
+      ...(flags.outDir !== undefined ? { outDir: flags.outDir } : {}),
+      themeMeta,
+    },
+  };
+}
+
+function setThemeFlag(
+  flags: { outDir?: string; slug?: string; name?: string },
+  name: string,
+  value: string
+): void {
+  if (name === '--out') {
+    flags.outDir = value;
+  } else if (name === '--slug') {
+    flags.slug = value;
+  } else {
+    flags.name = value;
+  }
+}
+
+function usage(): string {
+  return `Usage:
+  blocks-engine theme <srcDir> [--out <dir>] [--slug <slug>] [--name <name>]
+  blocks-engine <srcDir> [--out <dir>] [--slug <slug>] [--name <name>]
+  blocks-engine convert [file]
+  blocks-engine --help | -h
+
+Commands:
+  theme    Build a whole-site block theme from a source directory.
+  convert  Convert one HTML file, or stdin, to block markup.
+
+Options:
+  --out <dir>    Write the generated theme to a directory.
+  --slug <slug>  Set the generated theme slug.
+  --name <name>  Set the generated theme name.
+`;
+}
+
 function realpathOrResolve(path: string): string {
   try {
     return realpathSync(path);

From 30914077a942b162623923b33023daa34da9e0cb Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Fri, 26 Jun 2026 08:00:02 -0400
Subject: [PATCH 100/113] feat(cli): default theme output to ./_block-theme

When --out is omitted, the theme command writes to ./_block-theme in the
current directory and exits asking for --out if that directory already
exists, so a stray _block-theme/ is never silently overwritten.
---
 .../blocks-engine/src/__tests__/cli.test.ts   | 68 +++++++++++++++++++
 packages/blocks-engine/src/cli.ts             | 36 ++++++++--
 2 files changed, 97 insertions(+), 7 deletions(-)

diff --git a/packages/blocks-engine/src/__tests__/cli.test.ts b/packages/blocks-engine/src/__tests__/cli.test.ts
index 2a25a984..2c26b40d 100644
--- a/packages/blocks-engine/src/__tests__/cli.test.ts
+++ b/packages/blocks-engine/src/__tests__/cli.test.ts
@@ -181,6 +181,74 @@ describe('CLI theme builds', () => {
     expect(stderr.text()).toBe('');
   });
 
+  it('defaults the output dir to ./_block-theme when --out is omitted', async () => {
+    const srcDir = '/tmp/source-site';
+    const expectedOut = join(process.cwd(), '_block-theme');
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+    const calls: Array<{ srcDir: string; options: SiteToThemeOptions | undefined }> = [];
+
+    const exitCode = await runCli([srcDir], {
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+      pathExists: () => false,
+      siteToThemeImpl: async (calledSrcDir, options) => {
+        calls.push({ srcDir: calledSrcDir, options });
+        return themeResult(expectedOut, ['theme.json']);
+      },
+    });
+
+    expect(exitCode).toBe(0);
+    expect(calls).toEqual([{ srcDir, options: { outDir: expectedOut, themeMeta: {} } }]);
+    expect(stdout.text()).toBe(`wrote theme to ${expectedOut} (1 files)\n`);
+  });
+
+  it('exits and asks for --out when the default ./_block-theme already exists', async () => {
+    const srcDir = '/tmp/source-site';
+    const expectedOut = join(process.cwd(), '_block-theme');
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+    const calls: string[] = [];
+
+    const exitCode = await runCli([srcDir], {
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+      pathExists: (path) => path === expectedOut,
+      siteToThemeImpl: async (calledSrcDir) => {
+        calls.push(calledSrcDir);
+        return themeResult(expectedOut);
+      },
+    });
+
+    expect(exitCode).toBe(1);
+    expect(calls).toEqual([]);
+    expect(stdout.text()).toBe('');
+    expect(stderr.text()).toContain('already exists');
+    expect(stderr.text()).toContain('--out');
+  });
+
+  it('builds with an explicit --out even if that directory already exists', async () => {
+    const srcDir = '/tmp/source-site';
+    const outDir = '/tmp/existing-theme';
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+    const calls: string[] = [];
+
+    const exitCode = await runCli([srcDir, '--out', outDir], {
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+      pathExists: () => true,
+      siteToThemeImpl: async (calledSrcDir) => {
+        calls.push(calledSrcDir);
+        return themeResult(outDir, ['theme.json']);
+      },
+    });
+
+    expect(exitCode).toBe(0);
+    expect(calls).toEqual([srcDir]);
+    expect(stdout.text()).toBe(`wrote theme to ${outDir} (1 files)\n`);
+  });
+
   it('prints help with both CLI verbs', async () => {
     const stdout = writableBuffer();
     const stderr = writableBuffer();
diff --git a/packages/blocks-engine/src/cli.ts b/packages/blocks-engine/src/cli.ts
index 17d4c79d..07efc2b1 100644
--- a/packages/blocks-engine/src/cli.ts
+++ b/packages/blocks-engine/src/cli.ts
@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { realpathSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import type { Readable } from 'node:stream';
@@ -24,6 +24,7 @@ export interface RunCliOptions {
   stderr?: WritableLike;
   convertHtml?: ConvertHtml;
   siteToThemeImpl?: SiteToThemeImpl;
+  pathExists?: (path: string) => boolean;
 }
 
 async function readStdin(stdin: Readable): Promise<string> {
@@ -42,6 +43,7 @@ export async function runCli(argv: string[], options: RunCliOptions = {}): Promi
   const stderr = options.stderr ?? process.stderr;
   const convertHtml = options.convertHtml ?? convert;
   const siteToThemeImpl = options.siteToThemeImpl ?? siteToTheme;
+  const pathExists = options.pathExists ?? existsSync;
 
   try {
     const command = argv[0];
@@ -55,7 +57,7 @@ export async function runCli(argv: string[], options: RunCliOptions = {}): Promi
     }
 
     const themeArgs = command === 'theme' ? argv.slice(1) : argv;
-    return await runTheme(themeArgs, { stdout, stderr, siteToThemeImpl });
+    return await runTheme(themeArgs, { stdout, stderr, siteToThemeImpl, pathExists });
   } catch (error) {
     if (error instanceof BlocksEngineError) {
       stderr.write(`${error.message}\n${error.hint}\n`);
@@ -90,9 +92,23 @@ async function runConvert(
 
 async function runTheme(
   argv: string[],
-  options: { stdout: WritableLike; stderr: WritableLike; siteToThemeImpl: SiteToThemeImpl }
+  options: {
+    stdout: WritableLike;
+    stderr: WritableLike;
+    siteToThemeImpl: SiteToThemeImpl;
+    pathExists: (path: string) => boolean;
+  }
 ): Promise<number> {
-  const { srcDir, themeOptions } = parseThemeArgs(argv);
+  const { srcDir, themeOptions, outDirExplicit } = parseThemeArgs(argv);
+
+  // The default output dir is created in the current directory; refuse to touch
+  // an existing one so a stray _block-theme/ is never silently overwritten.
+  if (!outDirExplicit && themeOptions.outDir !== undefined && options.pathExists(themeOptions.outDir)) {
+    throw new Error(
+      `Default output directory ${themeOptions.outDir} already exists. Pass --out <dir> to choose where to write the theme.`
+    );
+  }
+
   const result = await options.siteToThemeImpl(srcDir, themeOptions);
 
   options.stdout.write(`wrote theme to ${result.outDir} (${result.written.length} files)\n`);
@@ -103,7 +119,11 @@ async function runTheme(
   return 0;
 }
 
-function parseThemeArgs(argv: string[]): { srcDir: string; themeOptions: SiteToThemeOptions } {
+function parseThemeArgs(argv: string[]): {
+  srcDir: string;
+  themeOptions: SiteToThemeOptions;
+  outDirExplicit: boolean;
+} {
   const srcDir = argv[0];
   if (srcDir === undefined) {
     throw new Error('Missing <srcDir> for theme command.');
@@ -136,8 +156,9 @@ function parseThemeArgs(argv: string[]): { srcDir: string; themeOptions: SiteToT
 
   return {
     srcDir,
+    outDirExplicit: flags.outDir !== undefined,
     themeOptions: {
-      ...(flags.outDir !== undefined ? { outDir: flags.outDir } : {}),
+      outDir: flags.outDir ?? resolve(process.cwd(), '_block-theme'),
       themeMeta,
     },
   };
@@ -169,7 +190,8 @@ Commands:
   convert  Convert one HTML file, or stdin, to block markup.
 
 Options:
-  --out <dir>    Write the generated theme to a directory.
+  --out <dir>    Write the generated theme to a directory
+                 (default: ./_block-theme; the command exits if it already exists).
   --slug <slug>  Set the generated theme slug.
   --name <name>  Set the generated theme name.
 `;

From b8e7e3d37e92c99f299ac4aba03deb7f7ae4ebb9 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Fri, 26 Jun 2026 09:34:04 -0400
Subject: [PATCH 101/113] fix(cli): harden path errors

---
 packages/blocks-engine/README.md              | 28 ++++++-
 packages/blocks-engine/package.json           |  2 +
 .../blocks-engine/src/__tests__/cli.test.ts   | 79 ++++++++++++++++++-
 packages/blocks-engine/src/cli.ts             | 38 ++++++++-
 4 files changed, 138 insertions(+), 9 deletions(-)

diff --git a/packages/blocks-engine/README.md b/packages/blocks-engine/README.md
index e12fadb1..fb65a306 100644
--- a/packages/blocks-engine/README.md
+++ b/packages/blocks-engine/README.md
@@ -31,13 +31,35 @@ Install the package:
 npm install @automattic/blocks-engine
 ```
 
-Run a one-shot file conversion without adding a dependency:
+Build a block theme from a source directory without adding a dependency:
 
 ```sh
-npx @automattic/blocks-engine page.html
+npx @automattic/blocks-engine theme ./my-site
 ```
 
-The CLI reads `page.html` and writes block markup to stdout. With no file argument, it reads HTML from stdin.
+The `theme` command writes the generated theme to `./_block-theme` by default and exits if that directory already exists. Use `--out`, `--slug`, and `--name` to set the output directory and theme metadata:
+
+```sh
+npx @automattic/blocks-engine theme ./my-site --out ./theme --slug my-site --name "My Site"
+```
+
+The bare source-directory shorthand is equivalent to `theme`:
+
+```sh
+npx @automattic/blocks-engine ./my-site
+```
+
+Convert a single HTML file to block markup with the `convert` subcommand:
+
+```sh
+npx @automattic/blocks-engine convert page.html
+```
+
+`convert` writes block markup to stdout. With no file argument, it reads HTML from stdin:
+
+```sh
+printf '<h2>Hi</h2>' | npx @automattic/blocks-engine convert
+```
 
 ## Start Here
 
diff --git a/packages/blocks-engine/package.json b/packages/blocks-engine/package.json
index 001f87f0..0bb74125 100644
--- a/packages/blocks-engine/package.json
+++ b/packages/blocks-engine/package.json
@@ -1,6 +1,8 @@
 {
   "name": "@automattic/blocks-engine",
   "version": "0.1.0",
+  "description": "Convert HTML and static sites into WordPress block markup and block themes.",
+  "keywords": ["wordpress", "blocks", "gutenberg", "block-theme", "html", "static-site"],
   "license": "GPL-3.0-or-later",
   "type": "module",
   "bin": {
diff --git a/packages/blocks-engine/src/__tests__/cli.test.ts b/packages/blocks-engine/src/__tests__/cli.test.ts
index 2c26b40d..0b0d9048 100644
--- a/packages/blocks-engine/src/__tests__/cli.test.ts
+++ b/packages/blocks-engine/src/__tests__/cli.test.ts
@@ -66,6 +66,28 @@ describe('CLI one-shot conversion', () => {
     }
   });
 
+  it('prints a clear error when a convert file is missing', async () => {
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+    const calls: string[] = [];
+    const filePath = '/tmp/blocks-engine-missing-file.html';
+
+    const exitCode = await runCli(['convert', filePath], {
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+      pathExists: () => false,
+      convertHtml: async (html) => {
+        calls.push(html);
+        return '<!-- wp:paragraph --><p>unused</p><!-- /wp:paragraph -->';
+      },
+    });
+
+    expect(exitCode).toBe(1);
+    expect(calls).toEqual([]);
+    expect(stdout.text()).toBe('');
+    expect(stderr.text()).toContain(`File ${filePath} not found.`);
+  });
+
   it('reads stdin when convert has no file arg', async () => {
     let seenUrl: string | undefined;
     const stdout = writableBuffer();
@@ -124,6 +146,8 @@ describe('CLI theme builds', () => {
       {
         stdout: stdout.stream,
         stderr: stderr.stream,
+        pathExists: () => true,
+        isDirectory: () => true,
         siteToThemeImpl: async (calledSrcDir, options) => {
           calls.push({ srcDir: calledSrcDir, options });
           return {
@@ -161,6 +185,8 @@ describe('CLI theme builds', () => {
     const exitCode = await runCli([srcDir, `--out=${outDir}`], {
       stdout: stdout.stream,
       stderr: stderr.stream,
+      pathExists: () => true,
+      isDirectory: () => true,
       siteToThemeImpl: async (calledSrcDir, options) => {
         calls.push({ srcDir: calledSrcDir, options });
         return themeResult(outDir, ['theme.json']);
@@ -191,7 +217,8 @@ describe('CLI theme builds', () => {
     const exitCode = await runCli([srcDir], {
       stdout: stdout.stream,
       stderr: stderr.stream,
-      pathExists: () => false,
+      pathExists: (path) => path === srcDir,
+      isDirectory: (path) => path === srcDir,
       siteToThemeImpl: async (calledSrcDir, options) => {
         calls.push({ srcDir: calledSrcDir, options });
         return themeResult(expectedOut, ['theme.json']);
@@ -213,7 +240,8 @@ describe('CLI theme builds', () => {
     const exitCode = await runCli([srcDir], {
       stdout: stdout.stream,
       stderr: stderr.stream,
-      pathExists: (path) => path === expectedOut,
+      pathExists: (path) => path === srcDir || path === expectedOut,
+      isDirectory: (path) => path === srcDir,
       siteToThemeImpl: async (calledSrcDir) => {
         calls.push(calledSrcDir);
         return themeResult(expectedOut);
@@ -238,6 +266,7 @@ describe('CLI theme builds', () => {
       stdout: stdout.stream,
       stderr: stderr.stream,
       pathExists: () => true,
+      isDirectory: () => true,
       siteToThemeImpl: async (calledSrcDir) => {
         calls.push(calledSrcDir);
         return themeResult(outDir, ['theme.json']);
@@ -299,4 +328,50 @@ describe('CLI theme builds', () => {
     expect(stdout.text()).toBe('');
     expect(stderr.text()).toContain('Missing <srcDir>');
   });
+
+  it('prints a clear error when the theme source directory is missing', async () => {
+    const srcDir = '/tmp/blocks-engine-missing-source';
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+    const calls: string[] = [];
+
+    const exitCode = await runCli(['theme', srcDir], {
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+      pathExists: () => false,
+      siteToThemeImpl: async (calledSrcDir) => {
+        calls.push(calledSrcDir);
+        return themeResult('/tmp/unused');
+      },
+    });
+
+    expect(exitCode).toBe(1);
+    expect(calls).toEqual([]);
+    expect(stdout.text()).toBe('');
+    expect(stderr.text()).toContain(`Source directory ${srcDir} not found.`);
+  });
+
+  it('suggests convert when the theme source is a file', async () => {
+    const srcDir = '/tmp/blocks-engine-page.html';
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+    const calls: string[] = [];
+
+    const exitCode = await runCli([srcDir], {
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+      pathExists: () => true,
+      isDirectory: () => false,
+      siteToThemeImpl: async (calledSrcDir) => {
+        calls.push(calledSrcDir);
+        return themeResult('/tmp/unused');
+      },
+    });
+
+    expect(exitCode).toBe(1);
+    expect(calls).toEqual([]);
+    expect(stdout.text()).toBe('');
+    expect(stderr.text()).toContain(`${srcDir} is a file, not a directory.`);
+    expect(stderr.text()).toContain(`blocks-engine convert ${srcDir}`);
+  });
 });
diff --git a/packages/blocks-engine/src/cli.ts b/packages/blocks-engine/src/cli.ts
index 07efc2b1..a47ae4cf 100644
--- a/packages/blocks-engine/src/cli.ts
+++ b/packages/blocks-engine/src/cli.ts
@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { existsSync, realpathSync } from 'node:fs';
+import { existsSync, realpathSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import type { Readable } from 'node:stream';
@@ -25,6 +25,7 @@ export interface RunCliOptions {
   convertHtml?: ConvertHtml;
   siteToThemeImpl?: SiteToThemeImpl;
   pathExists?: (path: string) => boolean;
+  isDirectory?: (path: string) => boolean;
 }
 
 async function readStdin(stdin: Readable): Promise<string> {
@@ -44,6 +45,15 @@ export async function runCli(argv: string[], options: RunCliOptions = {}): Promi
   const convertHtml = options.convertHtml ?? convert;
   const siteToThemeImpl = options.siteToThemeImpl ?? siteToTheme;
   const pathExists = options.pathExists ?? existsSync;
+  const isDirectory =
+    options.isDirectory ??
+    ((path: string) => {
+      try {
+        return statSync(path).isDirectory();
+      } catch {
+        return false;
+      }
+    });
 
   try {
     const command = argv[0];
@@ -53,11 +63,11 @@ export async function runCli(argv: string[], options: RunCliOptions = {}): Promi
     }
 
     if (command === 'convert') {
-      return await runConvert(argv.slice(1), { stdin, stdout, convertHtml });
+      return await runConvert(argv.slice(1), { stdin, stdout, convertHtml, pathExists });
     }
 
     const themeArgs = command === 'theme' ? argv.slice(1) : argv;
-    return await runTheme(themeArgs, { stdout, stderr, siteToThemeImpl, pathExists });
+    return await runTheme(themeArgs, { stdout, stderr, siteToThemeImpl, pathExists, isDirectory });
   } catch (error) {
     if (error instanceof BlocksEngineError) {
       stderr.write(`${error.message}\n${error.hint}\n`);
@@ -72,9 +82,18 @@ export async function runCli(argv: string[], options: RunCliOptions = {}): Promi
 
 async function runConvert(
   argv: string[],
-  options: { stdin: Readable; stdout: WritableLike; convertHtml: ConvertHtml }
+  options: {
+    stdin: Readable;
+    stdout: WritableLike;
+    convertHtml: ConvertHtml;
+    pathExists: (path: string) => boolean;
+  }
 ): Promise<number> {
   const fileArg = argv[0];
+  if (fileArg !== undefined && !options.pathExists(resolve(fileArg))) {
+    throw new Error(`File ${fileArg} not found.`);
+  }
+
   const input =
     fileArg === undefined
       ? {
@@ -97,10 +116,21 @@ async function runTheme(
     stderr: WritableLike;
     siteToThemeImpl: SiteToThemeImpl;
     pathExists: (path: string) => boolean;
+    isDirectory: (path: string) => boolean;
   }
 ): Promise<number> {
   const { srcDir, themeOptions, outDirExplicit } = parseThemeArgs(argv);
 
+  if (!options.pathExists(srcDir)) {
+    throw new Error(`Source directory ${srcDir} not found.`);
+  }
+
+  if (!options.isDirectory(srcDir)) {
+    throw new Error(
+      `${srcDir} is a file, not a directory. To convert a single HTML file, run: blocks-engine convert ${srcDir}`
+    );
+  }
+
   // The default output dir is created in the current directory; refuse to touch
   // an existing one so a stray _block-theme/ is never silently overwritten.
   if (!outDirExplicit && themeOptions.outDir !== undefined && options.pathExists(themeOptions.outDir)) {

From d40cba7937e181ab8a1154e45491da5a1e3c6d40 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Fri, 26 Jun 2026 10:00:55 -0400
Subject: [PATCH 102/113] chore: Add ADR docs, move .gitignore, add CONTEXT.md

---
 .gitignore                                    |  5 ++
 CONTEXT.md                                    | 47 +++++++++++++++++++
 ...engine-owns-translation-and-composition.md | 15 ++++++
 ...2-composable-operations-and-worker-pool.md | 20 ++++++++
 .../0003-single-package-with-entry-points.md  | 16 +++++++
 ...ngine-owns-deterministic-theme-assembly.md | 43 +++++++++++++++++
 packages/blocks-engine/.gitignore             |  2 -
 7 files changed, 146 insertions(+), 2 deletions(-)
 create mode 100644 .gitignore
 create mode 100644 CONTEXT.md
 create mode 100644 docs/adr/0001-engine-owns-translation-and-composition.md
 create mode 100644 docs/adr/0002-composable-operations-and-worker-pool.md
 create mode 100644 docs/adr/0003-single-package-with-entry-points.md
 create mode 100644 docs/adr/0004-engine-owns-deterministic-theme-assembly.md
 delete mode 100644 packages/blocks-engine/.gitignore

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 00000000..f50b3dee
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+.claude/worktrees/
+.superpowers/
+dist/
+docs/superpowers/
+node_modules/
\ No newline at end of file
diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 00000000..be2ace6e
--- /dev/null
+++ b/CONTEXT.md
@@ -0,0 +1,47 @@
+# blocks-engine (JS engine)
+
+The deterministic engine for WordPress blocks, shipped as one pluggable package (`@automattic/blocks-engine`) with a React-free default entry and an opt-in in-process `/wp` entry. It owns two generic, consumer-agnostic capabilities — **HTML→blocks translation** and **deterministic theme assembly** (static directory → block theme) — and exposes extension seams; consumers (the first being the data-liberation-agent static-site importer) plug their own choices, including non-deterministic quality steps, into those seams. Sibling to the existing `php-transformer`, with which it does **not** target output parity.
+
+(Identity note: the engine's scope deliberately expanded from "translation only" to "translation + theme assembly" — see ADR 0004, which supersedes the translation-only framing of ADR 0001.)
+
+## Language
+
+**Engine**:
+The translation + theme-assembly core plus its extension seams. Owns generic logic; knows nothing about any one consumer.
+_Avoid_: importer (that's the consumer)
+
+**Theme assembly / Assembler**:
+The engine's multi-**stage** process that turns a static site directory into a block theme on disk (ingest → foundation → section-extract → reconstruct → chrome → assets → plan → assemble). Run by the `siteToTheme` convenience command or by composing the stages directly.
+_Avoid_: pipeline (reserved for the **consumer's** end-to-end run, e.g. DLA's). The engine has an *assembler*, the consumer has a *pipeline*.
+
+**Stage**:
+One isolated unit of the assembler with a frozen input→output contract (e.g. `foundation`, `sectionExtract`, `assemble`). Stages are public and composable; `siteToTheme` chains them.
+
+**Hook**:
+An optional async seam at a named stage (`onFoundation`/`onSection`/`onAssets`/`onRefine`) where a consumer injects a **non-deterministic** quality step (visual polish, asset triage, repair). Absent hook = deterministic identity (byte-identical to no hook).
+_Avoid_: plugin, middleware.
+
+**SectionSpec**:
+The engine's shared contract describing one visual section (structure + style facts) consumed by reconstruction. Produced deterministically two ways: the engine's browser-free **cheerio** `sectionExtract` (best-effort, from static HTML), or **injected** by a consumer that captured richer computed-style specs (e.g. DLA's Playwright `extractFull`). Injected via the `sections` data input — NOT a hook (it is data, not a non-deterministic step).
+
+**ThemeModel**:
+The pure in-memory result of assembly (`styleCss`, `themeJson`, `templates`, `parts`, `patterns`, `assets`). Materialized to disk by `writeTheme`. Keeps the assembler snapshot-testable without disk.
+
+**Converter**:
+A pluggable unit (`(html, context) → block markup | null`) the engine applies to translate an HTML fragment. Built-ins ship with the engine; consumers may supply their own.
+_Avoid_: recipe (a consumer's word for its platform-specific converters)
+
+**ConversionContext**:
+The context object threaded through conversion (e.g. source URL, media-URL map). Carries only generic fields — never consumer-specific state.
+_Avoid_: BlockRecipeContext (the old consumer-coupled name)
+
+**Fallback block**:
+The block the engine emits for a fragment it can't convert. Defaults to `core/html`; a consumer overrides it via `htmlFallback` (a block name, or an emitter function).
+_Avoid_: island (a consumer's term for its own fallback shape)
+
+**Canonicalize**:
+Normalizing block markup through `@wordpress/blocks` so WordPress's parser/validator accepts it on the way in. One of the two `@wordpress/blocks`-backed operations (with the rawHandler conversion); both are process-isolated because they pull in React.
+_Avoid_: fix, normalize (use "canonicalize")
+
+**Transformer**:
+The PHP sibling package (`php-transformer`) — a separate engine with its own `TransformerResult` contract. Referenced only to say the JS engine does not mirror it.
diff --git a/docs/adr/0001-engine-owns-translation-and-composition.md b/docs/adr/0001-engine-owns-translation-and-composition.md
new file mode 100644
index 00000000..5821d655
--- /dev/null
+++ b/docs/adr/0001-engine-owns-translation-and-composition.md
@@ -0,0 +1,15 @@
+# blocks-engine owns HTML→blocks translation and composition behind a pluggable extension API
+
+blocks-engine owns the generic work of translating HTML into WordPress blocks — the `@wordpress/blocks` rawHandler core, the block-markup canonicalizer, the deterministic converter catalog, **and** the precedence that composes converters in order. Consumer-specific choices are not baked in; they are supplied through three extension seams: a `ConversionContext`, an ordered list of consumer **Converters** (functions or declarative `selector→block` recipe tables), and an `htmlFallback` override (default `core/html`). The data-liberation-agent is the first consumer but won't be the only one, so the boundary is: *generic translation logic + composition + extension seams → engine; the specific things plugged into those seams → consumer.*
+
+## Considered Options
+
+- **Engine = low-level primitives only; each consumer composes.** Rejected: duplicates the generic catalog and the recipe-table mechanism in every consumer, leaving "the hard work" outside the shared engine.
+- **Engine = generic conversion only; consumers own precedence/composition.** Rejected: a second consumer would have to bring its own recipe-table engine and precedence logic; the reusable extensible surface stays trapped in the first consumer.
+
+## Consequences
+
+- The first consumer's types (`AdapterBlocks` / `BlockRecipe` / `BlockRecipeContext`) become, or alias, the engine's `Converter` / recipe-rule / `ConversionContext` types; the consumer passes its platform recipes as **data**.
+- "Behavior-preserving / byte-identical" constrains engine **output**, not interface — the type and precedence relocation is deliberate; golden fixtures pin the emitted markup.
+- The `htmlFallback` seam must be threaded through the engine's **internal recursion**, not just applied at the outer boundary — otherwise nested fallbacks lose the consumer's chosen block.
+- The consumer's fallback marker (DLA's `PIPELINE_ISLAND_OPENER`) and its install-time gate (`validateReplicaInputs`) stay in the consumer, supplied via `htmlFallback`.
diff --git a/docs/adr/0002-composable-operations-and-worker-pool.md b/docs/adr/0002-composable-operations-and-worker-pool.md
new file mode 100644
index 00000000..eedf2474
--- /dev/null
+++ b/docs/adr/0002-composable-operations-and-worker-pool.md
@@ -0,0 +1,20 @@
+# Engine API surface: composable operations + a worker pool
+
+The engine exposes three **composable operations** rather than one monolithic `convert()`:
+
+- `compose(html, ctx, { converters, htmlFallback })` — **pure, synchronous**, React-free. Runs consumer converters (functions or recipe tables) → built-in generic catalog → `htmlFallback`. No `@wordpress/blocks`.
+- `rawConvert(html)` and `canonicalize(markup)` — **async**, backed by a package-managed **pool** of `fork()`ed worker processes (default `min(cores, 4)`, configurable, dies with the parent). These load `@wordpress/blocks`, isolated in the pool.
+
+A convenience `convert()` chains `rawConvert → compose → canonicalize` for consumers who just want "HTML in, blocks out."
+
+(Packaging of these operations into one package with entry points is ADR 0003.)
+
+## Considered Options
+
+- **One monolithic `convert()` owning rawHandler internally.** Rejected: it would force consumer **function** converters (e.g. DLA's imperative Squarespace walk) through the worker IPC boundary, where functions can't be serialized — breaking function-converters under isolation. It would also force the consumer's currently-synchronous composition path to become async.
+- **Single forked child instead of a pool.** Rejected: throughput regression versus the current `cluster(min(cores, 4))` on whole-site runs, which is exactly the workload the parallelism exists for.
+
+## Consequences
+
+- Consumer **function** converters run in the pure, in-process `compose`; only HTML/markup **strings** cross the worker boundary. Serialization is never an issue.
+- The first consumer (DLA) deletes its bespoke HTTP server + cluster client and consumes the package's worker pool; it keeps wiring the three ops at its own pipeline stages.
diff --git a/docs/adr/0003-single-package-with-entry-points.md b/docs/adr/0003-single-package-with-entry-points.md
new file mode 100644
index 00000000..7724e872
--- /dev/null
+++ b/docs/adr/0003-single-package-with-entry-points.md
@@ -0,0 +1,16 @@
+# Single package with entry points (not a pure/wp package split)
+
+Ship the engine as **one** package — `@automattic/blocks-engine` — with entry points rather than two packages:
+
+- **default** (`.`) — React-free: `compose` + helpers + `createWorker()` (the pool client). Never loads `@wordpress/blocks` in the importing process.
+- **`/wp`** — opt-in, **in-process** sync `rawConvert` / `canonicalize` / `convert` that load `@wordpress/blocks` in the current process; this is also what the forked worker child runs.
+
+## Considered Options
+
+- **Two packages (`@automattic/blocks-engine` pure + `@automattic/blocks-engine-wp`).** Rejected. The React isolation consumers need comes from the worker **process**, not a package boundary, so the split doesn't earn it. Its only real benefit — letting a helpers-only consumer skip the `@wordpress/*` + jsdom install — serves a largely hypothetical consumer: the package exists to do HTML→blocks, which needs rawHandler, and the cheerio-based pure code isn't browser-ready, so there's no edge/browser story either. The split also puts the headline name on the weaker half (the pure layer alone is a best-effort converter, not the engine).
+
+## Consequences
+
+- One version, one publish pipeline; no cross-package version coupling.
+- React isolation is a property of the worker `fork()`, reachable from the single package's default entry — the importing process never loads React 18.
+- A consumer with no React conflict can `import … from '@automattic/blocks-engine/wp'` for a synchronous in-process engine.
diff --git a/docs/adr/0004-engine-owns-deterministic-theme-assembly.md b/docs/adr/0004-engine-owns-deterministic-theme-assembly.md
new file mode 100644
index 00000000..f80e9cf7
--- /dev/null
+++ b/docs/adr/0004-engine-owns-deterministic-theme-assembly.md
@@ -0,0 +1,43 @@
+# Engine identity expands to deterministic theme assembly
+
+The engine's scope expands from **HTML→blocks translation only** to **translation +
+deterministic theme assembly**: a static site directory → a block theme on disk
+(`theme.json`, templates, parts, patterns, `style.css`, carried/rewritten assets),
+exposed as a `siteToTheme` convenience command over composable, public **stages**.
+
+This supersedes the framing in ADR 0001 / `CONTEXT.md` that treated a
+pipeline/importer as exclusively the **consumer's** job and the engine as a pure
+translator. The engine still knows nothing about any one consumer; "theme assembly"
+is generic, consumer-agnostic work — but it IS more than translation.
+
+Non-deterministic quality (visual-parity polish, decorative-asset triage, repair) is
+explicitly NOT engine code. It enters through optional async **hooks**
+(`onFoundation`/`onSection`/`onAssets`/`onRefine`); absent hook = deterministic
+identity. The engine owns the deterministic skeleton; consumers inject judgment.
+
+## Considered Options
+
+- **Keep the engine translation-only; theme assembly stays in the consumer (DLA).**
+  Rejected: the deterministic theme-assembly logic is generic (not DLA-specific) and
+  other implementers want it; leaving it in DLA blocks reuse, which is the whole point.
+- **Make theme assembly a separate sibling package.** Rejected: it shares the
+  translation core, the worker pool, and the React-isolation machinery; a package
+  split re-introduces the cross-package version coupling ADR 0003 avoided.
+- **Engine does its own browser capture to reach DLA-grade fidelity.** Rejected:
+  violates the browser-free posture and ADR 0003. Instead, `SectionSpec` is a shared
+  input contract — the engine ships a browser-free cheerio extractor for a best-effort
+  static path, and consumers inject richer captured specs for full fidelity.
+
+## Consequences
+
+- `CONTEXT.md` gains: Theme assembly / Assembler, Stage, Hook, SectionSpec, ThemeModel.
+  "pipeline" stays reserved for the consumer's end-to-end run; the engine has an
+  *assembler*.
+- The browser-free **static-dir** path is a NEW, lower-fidelity capability with its own
+  golden fixtures. It is NOT held to DLA-output parity.
+- The migration definition-of-done for lifting DLA's logic is: **engine + DLA-injected
+  specs/aggregates/hooks == DLA-today, byte-identical** (proves the lift preserved
+  behavior). Static-path output is governed by golden fixtures, not DLA parity.
+- DLA eventually deletes its deterministic copies and imports the engine, wiring its AI
+  skills into the hooks and feeding its captured `SectionSpec`s via the `sections` input.
+  The Studio/WP install stays in DLA.
diff --git a/packages/blocks-engine/.gitignore b/packages/blocks-engine/.gitignore
deleted file mode 100644
index b9470778..00000000
--- a/packages/blocks-engine/.gitignore
+++ /dev/null
@@ -1,2 +0,0 @@
-node_modules/
-dist/

From 2fa557bfb93013f9f0e6a8f2d38f33ce27606168 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Fri, 26 Jun 2026 10:48:09 -0400
Subject: [PATCH 103/113] feat(theme): export reconstructNativeAggregate
 harness entry

---
 .../theme/__tests__/reconstruct-export.test.ts    | 15 +++++++++++++++
 packages/blocks-engine/src/theme/index.ts         |  9 +++++++--
 2 files changed, 22 insertions(+), 2 deletions(-)
 create mode 100644 packages/blocks-engine/src/theme/__tests__/reconstruct-export.test.ts

diff --git a/packages/blocks-engine/src/theme/__tests__/reconstruct-export.test.ts b/packages/blocks-engine/src/theme/__tests__/reconstruct-export.test.ts
new file mode 100644
index 00000000..64dc9360
--- /dev/null
+++ b/packages/blocks-engine/src/theme/__tests__/reconstruct-export.test.ts
@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import * as theme from '../index.js';
+
+describe('theme barrel exports the harness entry', () => {
+  it('exports reconstructNativeAggregate', () => {
+    expect(typeof theme.reconstructNativeAggregate).toBe('function');
+  });
+
+  it('reconstructNativeAggregate returns an aggregate shape for empty specs', () => {
+    const agg = theme.reconstructNativeAggregate([]);
+    expect(agg.sectionMarkup).toEqual([]);
+    expect(agg.sections).toEqual([]);
+    expect(agg.heroIsCover).toBe(false);
+  });
+});
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 14a5d71d..89824edc 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -36,7 +36,7 @@ export {
   sanitizeSvgAsset,
   stripChrome,
 } from './page-reconstruct-helpers.js';
-export { reconstruct } from './reconstruct.js';
+export { reconstruct, reconstructNativeAggregate } from './reconstruct.js';
 export {
   buildCoverageIsland,
   buildHtmlFallbackBlock,
@@ -112,7 +112,12 @@ export type {
 export type * from './font-faces.js';
 export type { FormBlocksResult } from './form-blocks.js';
 export type { FontFamilyToken } from './page-reconstruct-helpers.js';
-export type { ConvertedSectionInput, SectionRenderOptions } from './native-reconstruct-types.js';
+export type {
+  ConvertedSectionInput,
+  NativeReconstructAggregate,
+  NativeSectionDecision,
+  SectionRenderOptions,
+} from './native-reconstruct-types.js';
 export type * from './region-audit.js';
 export type { InternalLinkMap } from './url-rewrite.js';
 export type * from './section-spec.js';

From 5b1fddf6b29a5f38f6d1029b48c6de40be9f7748 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Fri, 26 Jun 2026 13:02:58 -0400
Subject: [PATCH 104/113] feat(theme): freeze reconstruct strategy contracts

---
 .../theme-native-reconstruct-contract.test.ts |  2 ++
 .../src/theme/native-reconstruct-types.ts     | 21 +++++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/packages/blocks-engine/src/__tests__/theme-native-reconstruct-contract.test.ts b/packages/blocks-engine/src/__tests__/theme-native-reconstruct-contract.test.ts
index ccb33047..5d1acd8d 100644
--- a/packages/blocks-engine/src/__tests__/theme-native-reconstruct-contract.test.ts
+++ b/packages/blocks-engine/src/__tests__/theme-native-reconstruct-contract.test.ts
@@ -14,6 +14,7 @@ import type {
   NativeReconstructAggregate,
   NativeSectionDecision,
   NativeSectionDecisionKind,
+  StrategyDedupOutput,
 } from '../theme/native-reconstruct-types.js';
 import type { CoverageResult } from '../theme/section-coverage.js';
 import type { SectionSpec } from '../theme/section-spec.js';
@@ -51,6 +52,7 @@ describe('native reconstruct frozen internal contract', () => {
       fallbackDiagnostics: FallbackDiagnostic[];
       iconAssets: Array<{ path: string; svg: string }>;
       heroIsCover: boolean;
+      dedup?: StrategyDedupOutput;
     }>();
   });
 
diff --git a/packages/blocks-engine/src/theme/native-reconstruct-types.ts b/packages/blocks-engine/src/theme/native-reconstruct-types.ts
index 1af0dc1c..86a3122b 100644
--- a/packages/blocks-engine/src/theme/native-reconstruct-types.ts
+++ b/packages/blocks-engine/src/theme/native-reconstruct-types.ts
@@ -44,6 +44,25 @@ export interface NativeSectionDecision extends NativeSectionResult {
   decision: NativeSectionDecisionKind;
 }
 
+export interface StrategyState {
+  instanceStyles?: unknown;
+}
+
+export interface StrategyDedupOutput {
+  cssRules?: string[];
+}
+
+export interface SectionStrategy {
+  name: string;
+  render(
+    section: SectionSpec,
+    options: SectionRenderOptions,
+    ctx: NativeRenderCtx,
+    state: StrategyState
+  ): NativeSectionDecision | null;
+  drainDedup?(state: StrategyState): StrategyDedupOutput;
+}
+
 export interface NativeReconstructAggregate {
   sections: NativeSectionDecision[];
   sectionMarkup: string[];
@@ -54,6 +73,7 @@ export interface NativeReconstructAggregate {
   fallbackDiagnostics: FallbackDiagnostic[];
   iconAssets: Array<{ path: string; svg: string }>;
   heroIsCover: boolean;
+  dedup?: StrategyDedupOutput;
 }
 
 export interface ConvertedSectionInput {
@@ -68,4 +88,5 @@ export interface SectionRenderOptions {
   fontFamilies?: FontFamilyToken[];
   sourceUrl?: string;
   slug?: string;
+  strategy?: SectionStrategy;
 }

From b7351b04087e1f64476bfed87ce1888b5843fa4e Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Fri, 26 Jun 2026 13:04:33 -0400
Subject: [PATCH 105/113] test(theme): freeze strategy seam default output

---
 .../src/theme/__tests__/strategy-seam.test.ts | 213 ++++++++++++++++++
 1 file changed, 213 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/__tests__/strategy-seam.test.ts

diff --git a/packages/blocks-engine/src/theme/__tests__/strategy-seam.test.ts b/packages/blocks-engine/src/theme/__tests__/strategy-seam.test.ts
new file mode 100644
index 00000000..98769a23
--- /dev/null
+++ b/packages/blocks-engine/src/theme/__tests__/strategy-seam.test.ts
@@ -0,0 +1,213 @@
+import { describe, expect, it } from 'vitest';
+
+import type { WorkerPool } from '../../pool/types.js';
+import { reconstruct, reconstructNativeAggregate } from '../reconstruct.js';
+import type { SectionSpec } from '../section-spec.js';
+import type { StageCtx } from '../types.js';
+
+function sectionSpec(overrides: Partial<SectionSpec> = {}): SectionSpec {
+  return {
+    sectionIndex: 0,
+    interactionModel: 'static',
+    top: 0,
+    height: 0,
+    headings: [],
+    bodyText: [],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 1,
+    backgroundColor: 'transparent',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: {
+      motionClass: 'none',
+      signals: [],
+      animatedElements: 0,
+    },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: {
+      containerWidth: 0,
+      padding: '0',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '0',
+    },
+    ...overrides,
+  };
+}
+
+function sectionImage(
+  url: string,
+  overrides: Partial<SectionSpec['images'][number]> = {},
+): SectionSpec['images'][number] {
+  return {
+    url,
+    sourceUrl: url,
+    alt: 'Fixture image',
+    kind: 'img',
+    width: 1200,
+    height: 800,
+    ...overrides,
+  };
+}
+
+function fakePool(): WorkerPool {
+  return {
+    async rawConvert(items: string[]) {
+      return items.map((html) => ({ html, wpHtmlResidue: 0 }));
+    },
+    async canonicalize(items: string[]) {
+      return items.map((html) => ({ html, changed: false, fixedIssues: [] }));
+    },
+    async stop() {},
+  };
+}
+
+function stageCtx(overrides: Partial<StageCtx> & Record<string, unknown> = {}): StageCtx {
+  return {
+    srcDir: '/tmp/strategy-site',
+    site: { root: '/tmp/strategy-site', pages: [] },
+    themeMeta: { name: 'Strategy Fixture', slug: 'strategy-fixture' },
+    warn() {},
+    ...overrides,
+  };
+}
+
+const convertedMarkup = [
+  '<!-- wp:heading -->',
+  '<h2>Converted service</h2>',
+  '<!-- /wp:heading -->',
+  '<!-- wp:paragraph -->',
+  '<p>Converted copy survives intact.</p>',
+  '<!-- /wp:paragraph -->',
+].join('\n');
+
+const sections: SectionSpec[] = [
+  sectionSpec({
+    sectionIndex: 1,
+    interactionModel: 'cover-with-headline',
+    height: 720,
+    headings: ['Cover hero'],
+    bodyText: ['Hero body copy.'],
+    fullBleed: true,
+    images: [sectionImage('/wp-content/uploads/2026/hero.jpg', { width: 1440, height: 900 })],
+    sectionHtml:
+      '<section id="hero" class="hero cover"><h1>Cover hero</h1><p>Hero body copy.</p><img src="/wp-content/uploads/2026/hero.jpg" alt="Fixture image"></section>',
+  }),
+  sectionSpec({
+    sectionIndex: 0,
+    headings: ['Native text'],
+    bodyText: ['Native body copy.'],
+    sectionHtml: '<section id="native" class="band text"><h2>Native text</h2><p>Native body copy.</p></section>',
+  }),
+  sectionSpec({
+    sectionIndex: 2,
+    headings: ['Converted service'],
+    bodyText: ['Converted copy survives intact.'],
+    sectionHtml:
+      '<section id="converted" class="service"><h2>Converted service</h2><p>Converted copy survives intact.</p></section>',
+  }),
+  sectionSpec({
+    sectionIndex: 3,
+    headings: ['Lossy fallback'],
+    bodyText: ['Fallback body copy.'],
+    images: [sectionImage('https://cdn.example.com/lossy.jpg')],
+    sectionHtml:
+      '<section id="lossy" class="fallback"><h2>Lossy fallback</h2><p>Fallback body copy.</p><img src="https://cdn.example.com/lossy.jpg" alt="Fixture image"></section>',
+  }),
+];
+
+const options = {
+  sourceUrl: 'https://example.com/strategy',
+  slug: 'strategy',
+  convertedSections: new Map([[2, { markup: convertedMarkup, wpHtmlResidue: 0 }]]),
+};
+
+function frozenAggregate() {
+  const aggregate = reconstructNativeAggregate(sections, options);
+  return {
+    sectionMarkup: aggregate.sectionMarkup,
+    heroIsCover: aggregate.heroIsCover,
+    provenanceFlags: aggregate.provenanceFlags,
+    expectedText: aggregate.expectedText,
+    bodyText: aggregate.bodyText,
+    expectedAssets: aggregate.expectedAssets,
+  };
+}
+
+describe('reconstruct strategy seam default path', () => {
+  it('keeps the pre-seam direct aggregate byte-identical without dedup output', () => {
+    const aggregate = reconstructNativeAggregate(sections, options);
+    console.info(`Strategy seam default byte-identity cases=${sections.length}`);
+    expect(aggregate.dedup).toBeUndefined();
+    expect(frozenAggregate()).toMatchInlineSnapshot(`
+      {
+        "bodyText": [
+          "Hero body copy.",
+          "Native body copy.",
+          "Converted copy survives intact.",
+        ],
+        "expectedAssets": [
+          "/wp-content/uploads/2026/hero.jpg",
+        ],
+        "expectedText": [
+          "Cover hero",
+          "Native text",
+          "Converted service",
+        ],
+        "heroIsCover": true,
+        "provenanceFlags": [
+          "html-to-blocks#2: converted native blocks (0 wp:html, text 100%)",
+          "html-fallback#3: structured render dropped content (1 images missing, text 100%) — emitted verbatim core/html",
+        ],
+        "sectionMarkup": [
+          "<!-- wp:cover {"url":"/wp-content/uploads/2026/hero.jpg","dimRatio":40,"overlayColor":"surface-inverse","isUserOverlayColor":true,"minHeight":50,"minHeightUnit":"vw","align":"full","style":{"spacing":{"margin":{"top":"0px"}}},"layout":{"type":"constrained"}} -->
+      <div class="wp-block-cover alignfull" style="margin-top:0px;min-height:50vw"><img class="wp-block-cover__image-background" src="/wp-content/uploads/2026/hero.jpg" alt="Fixture image" data-object-fit="cover"/><span aria-hidden="true" class="wp-block-cover__background has-surface-inverse-background-color has-background-dim-40 has-background-dim"></span>
+      <div class="wp-block-cover__inner-container">
+      <!-- wp:heading {"textAlign":"center","level":1,"fontFamily":"display","textColor":"text-inverse"} -->
+      <h1 class="wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family">Cover hero</h1>
+      <!-- /wp:heading -->
+      <!-- wp:paragraph {"align":"center","textColor":"text-inverse"} -->
+      <p class="has-text-align-center has-text-inverse-color has-text-color">Hero body copy.</p>
+      <!-- /wp:paragraph -->
+      </div>
+      </div>
+      <!-- /wp:cover -->",
+          "<!-- wp:group {"tagName":"section","align":"full","backgroundColor":"surface-inverse","textColor":"text-inverse","style":{"spacing":{"margin":{"top":"0","bottom":"0"},"padding":{"top":"var:preset|spacing|60","bottom":"var:preset|spacing|60","left":"var:preset|spacing|40","right":"var:preset|spacing|40"},"blockGap":"var:preset|spacing|40"}},"layout":{"type":"constrained","contentSize":"760px"}} -->
+      <section class="wp-block-group alignfull has-surface-inverse-background-color has-text-inverse-color has-text-color has-background" style="margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--60);padding-right:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--60);padding-left:var(--wp--preset--spacing--40)">
+      <!-- wp:heading {"textAlign":"center","level":1,"fontFamily":"display","textColor":"text-inverse"} -->
+      <h1 class="wp-block-heading has-text-align-center has-text-inverse-color has-text-color has-display-font-family">Native text</h1>
+      <!-- /wp:heading -->
+      <!-- wp:paragraph {"align":"center","textColor":"text-inverse"} -->
+      <p class="has-text-align-center has-text-inverse-color has-text-color">Native body copy.</p>
+      <!-- /wp:paragraph -->
+      </section>
+      <!-- /wp:group -->",
+          "<!-- wp:heading -->
+      <h2>Converted service</h2>
+      <!-- /wp:heading -->
+      <!-- wp:paragraph -->
+      <p>Converted copy survives intact.</p>
+      <!-- /wp:paragraph -->",
+          "<!-- wp:html {"metadata":{"name":"lib-coverage-island"}} -->
+      <section id="lossy" class="fallback"><h2>Lossy fallback</h2><p>Fallback body copy.</p><img src="https://cdn.example.com/lossy.jpg" alt="Fixture image"></section>
+      <!-- /wp:html -->",
+        ],
+      }
+    `);
+  });
+
+  it('keeps reconstruct() routed through the same default aggregate bytes', async () => {
+    const aggregate = reconstructNativeAggregate(sections, options);
+    const routed = await reconstruct(
+      sections,
+      stageCtx(options),
+      fakePool(),
+      {},
+      0,
+    );
+    expect(routed.map((section) => section.blocks)).toEqual(aggregate.sectionMarkup);
+  });
+});

From 57f71dff9d01f988db1d54bf328c65f2aa8b28a6 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Fri, 26 Jun 2026 13:12:50 -0400
Subject: [PATCH 106/113] feat(theme): add reconstruct section strategy seam

---
 .../src/theme/__tests__/strategy-seam.test.ts | 61 ++++++++++++++++++-
 packages/blocks-engine/src/theme/index.ts     |  5 +-
 .../blocks-engine/src/theme/reconstruct.ts    | 48 +++++++++++++--
 3 files changed, 108 insertions(+), 6 deletions(-)

diff --git a/packages/blocks-engine/src/theme/__tests__/strategy-seam.test.ts b/packages/blocks-engine/src/theme/__tests__/strategy-seam.test.ts
index 98769a23..2bd5cd3a 100644
--- a/packages/blocks-engine/src/theme/__tests__/strategy-seam.test.ts
+++ b/packages/blocks-engine/src/theme/__tests__/strategy-seam.test.ts
@@ -1,10 +1,20 @@
 import { describe, expect, it } from 'vitest';
 
 import type { WorkerPool } from '../../pool/types.js';
-import { reconstruct, reconstructNativeAggregate } from '../reconstruct.js';
+import {
+  classifySemanticStrategy,
+  reconstruct,
+  reconstructNativeAggregate,
+  type SectionStrategy,
+} from '../index.js';
 import type { SectionSpec } from '../section-spec.js';
 import type { StageCtx } from '../types.js';
 
+type SourceIdentitySection = SectionSpec & {
+  sourceId?: string;
+  sourceClasses?: string[];
+};
+
 function sectionSpec(overrides: Partial<SectionSpec> = {}): SectionSpec {
   return {
     sectionIndex: 0,
@@ -138,6 +148,12 @@ function frozenAggregate() {
 }
 
 describe('reconstruct strategy seam default path', () => {
+  it('exports the classify semantic default strategy from the theme barrel', () => {
+    expect(classifySemanticStrategy.name).toBe('classify-semantic');
+    expect(typeof classifySemanticStrategy.render).toBe('function');
+    expect(classifySemanticStrategy.drainDedup).toBeUndefined();
+  });
+
   it('keeps the pre-seam direct aggregate byte-identical without dedup output', () => {
     const aggregate = reconstructNativeAggregate(sections, options);
     console.info(`Strategy seam default byte-identity cases=${sections.length}`);
@@ -210,4 +226,47 @@ describe('reconstruct strategy seam default path', () => {
     );
     expect(routed.map((section) => section.blocks)).toEqual(aggregate.sectionMarkup);
   });
+
+  it('passes recovered source identity into custom strategies and drains dedup output', () => {
+    const seen: Array<{ sourceId?: string; sourceClasses?: string[] }> = [];
+    let drainedState: unknown;
+    const strategy: SectionStrategy = {
+      name: 'probe-source-identity',
+      render(section, _options, _ctx, state) {
+        const source = section as SourceIdentitySection;
+        seen.push({ sourceId: source.sourceId, sourceClasses: source.sourceClasses });
+        state.instanceStyles = { observed: seen.length };
+        return null;
+      },
+      drainDedup(state) {
+        drainedState = state.instanceStyles;
+        return { cssRules: ['.probe-source-identity{}'] };
+      },
+    };
+
+    const aggregate = reconstructNativeAggregate(
+      [
+        sectionSpec({
+          sectionIndex: 10,
+          headings: ['Identity'],
+          sectionHtml: '<article id="source-card" class="alpha beta"><h2>Identity</h2></article>',
+        }),
+        sectionSpec({
+          sectionIndex: 11,
+          headings: ['Styled identity'],
+          sectionHtml: '<section><h2>Styled identity</h2></section>',
+          styledHtml: '<section id="styled-card" class="gamma delta"><h2>Styled identity</h2></section>',
+        }),
+      ],
+      { strategy },
+    );
+
+    expect(seen).toEqual([
+      { sourceId: 'source-card', sourceClasses: ['alpha', 'beta'] },
+      { sourceId: 'styled-card', sourceClasses: ['gamma', 'delta'] },
+    ]);
+    expect(drainedState).toEqual({ observed: 2 });
+    expect(aggregate.sectionMarkup).toEqual([]);
+    expect(aggregate.dedup).toEqual({ cssRules: ['.probe-source-identity{}'] });
+  });
 });
diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 89824edc..3e2641ce 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -36,7 +36,7 @@ export {
   sanitizeSvgAsset,
   stripChrome,
 } from './page-reconstruct-helpers.js';
-export { reconstruct, reconstructNativeAggregate } from './reconstruct.js';
+export { classifySemanticStrategy, reconstruct, reconstructNativeAggregate } from './reconstruct.js';
 export {
   buildCoverageIsland,
   buildHtmlFallbackBlock,
@@ -117,6 +117,9 @@ export type {
   NativeReconstructAggregate,
   NativeSectionDecision,
   SectionRenderOptions,
+  SectionStrategy,
+  StrategyDedupOutput,
+  StrategyState,
 } from './native-reconstruct-types.js';
 export type * from './region-audit.js';
 export type { InternalLinkMap } from './url-rewrite.js';
diff --git a/packages/blocks-engine/src/theme/reconstruct.ts b/packages/blocks-engine/src/theme/reconstruct.ts
index 9b372458..4d34d65b 100644
--- a/packages/blocks-engine/src/theme/reconstruct.ts
+++ b/packages/blocks-engine/src/theme/reconstruct.ts
@@ -16,6 +16,8 @@ import type {
   NativeRenderOut,
   NativeSectionDecision,
   SectionRenderOptions,
+  SectionStrategy,
+  StrategyState,
 } from './native-reconstruct-types.js';
 import { normalizeCopy, stripChrome } from './page-reconstruct-helpers.js';
 import {
@@ -39,6 +41,11 @@ type RewriteCtx = StageCtx & SectionRenderOptions & {
   linkMap?: InternalLinkMap;
 };
 
+type SourceIdentitySection = SectionSpec & {
+  sourceId?: string;
+  sourceClasses?: string[];
+};
+
 function fallbackOptions(options: SectionRenderOptions | RewriteCtx): HtmlFallbackOpts {
   const rewriteCtx = options as RewriteCtx;
   const opts: HtmlFallbackOpts = {};
@@ -91,16 +98,37 @@ function normalizeSections(sections: SectionSpec[], options: SectionRenderOption
   const famTokens = options.fontFamilies ?? [];
   const resolveFamilies = (names?: string[]): string[] | undefined =>
     names ? names.map((name) => nearestFamily(name, famTokens) ?? '') : undefined;
+  const sourceIdentity = (section: SectionSpec): Partial<SourceIdentitySection> => {
+    const current = section as SourceIdentitySection;
+    const patch: Partial<SourceIdentitySection> = {};
+    const readRoot = (sourceHtml?: string): { id?: string; classes: string[] } => {
+      if (!sourceHtml) return { classes: [] };
+      const root = cheerio.load(sourceHtml, null, false).root().children().first();
+      return {
+        id: root.attr('id')?.trim() || undefined,
+        classes: (root.attr('class') ?? '').split(/\s+/).filter(Boolean),
+      };
+    };
+    const sectionRoot = readRoot(section.sectionHtml);
+    const styledRoot = readRoot(section.styledHtml);
+    const id = sectionRoot.id ?? styledRoot.id;
+    const classes = sectionRoot.classes.length > 0 ? sectionRoot.classes : styledRoot.classes;
+    if (!('sourceId' in current) && id) patch.sourceId = id;
+    if (!('sourceClasses' in current) && classes.length > 0) patch.sourceClasses = classes;
+    return patch;
+  };
 
   return stripChrome(sections).map((section) => {
     const headFamSlugs = resolveFamilies(section.headingFamilies);
     const bodyFamSlugs = resolveFamilies(section.bodyFamilies);
+    const identity = sourceIdentity(section);
     let out = section;
-    if (headFamSlugs || bodyFamSlugs) {
+    if (headFamSlugs || bodyFamSlugs || Object.keys(identity).length > 0) {
       out = {
         ...out,
         ...(headFamSlugs ? { headingFamilies: headFamSlugs } : {}),
         ...(bodyFamSlugs ? { bodyFamilies: bodyFamSlugs } : {}),
+        ...identity,
       };
     }
 
@@ -383,6 +411,14 @@ function nativeDecision(section: SectionSpec, options: SectionRenderOptions, ctx
   };
 }
 
+export const classifySemanticStrategy: SectionStrategy = {
+  name: 'classify-semantic',
+  render(section, options, ctx) {
+    const converted = options.convertedSections?.get(section.sectionIndex);
+    return convertedDecision(section, converted, options) ?? nativeDecision(section, options, ctx);
+  },
+};
+
 function optionsFromCtx(ctx: StageCtx): SectionRenderOptions {
   const rewriteCtx = ctx as RewriteCtx;
   return {
@@ -406,6 +442,8 @@ export function reconstructNativeAggregate(
     fontFamilies: options.fontFamilies ?? [],
   };
 
+  const strategy = options.strategy ?? classifySemanticStrategy;
+  const state: StrategyState = {};
   const decisions: NativeSectionDecision[] = [];
   const sectionMarkup: string[] = [];
   const expectedText: string[] = [];
@@ -416,8 +454,7 @@ export function reconstructNativeAggregate(
   const iconAssets: NativeReconstructAggregate['iconAssets'] = [];
 
   for (const section of normalizeSections(specs, options)) {
-    const converted = options.convertedSections?.get(section.sectionIndex);
-    const decision = convertedDecision(section, converted, options) ?? nativeDecision(section, options, ctx);
+    const decision = strategy.render(section, options, ctx, state);
     if (!decision) continue;
 
     decisions.push(decision);
@@ -430,7 +467,7 @@ export function reconstructNativeAggregate(
     iconAssets.push(...decision.iconAssets);
   }
 
-  return {
+  const aggregate: NativeReconstructAggregate = {
     sections: decisions,
     sectionMarkup,
     expectedText: dedupe(expectedText),
@@ -441,6 +478,9 @@ export function reconstructNativeAggregate(
     iconAssets,
     heroIsCover: sectionMarkup.length > 0 && /^\s*<!-- wp:cover\b/.test(sectionMarkup[0]),
   };
+  const dedup = strategy.drainDedup?.(state);
+  if (dedup) aggregate.dedup = dedup;
+  return aggregate;
 }
 
 export async function reconstruct(

From 592447df7a111fcf819717602ff177b03d05b3f2 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Fri, 26 Jun 2026 13:35:00 -0400
Subject: [PATCH 107/113] feat(theme): add preserve DOM strategy core

---
 packages/blocks-engine/src/theme/index.ts     |   1 +
 .../preserve-dom/__tests__/strategy.test.ts   | 131 +++++++++++
 .../src/theme/preserve-dom/instance-styles.ts |  43 ++++
 .../src/theme/preserve-dom/strategy.ts        | 208 ++++++++++++++++++
 4 files changed, 383 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/preserve-dom/__tests__/strategy.test.ts
 create mode 100644 packages/blocks-engine/src/theme/preserve-dom/instance-styles.ts
 create mode 100644 packages/blocks-engine/src/theme/preserve-dom/strategy.ts

diff --git a/packages/blocks-engine/src/theme/index.ts b/packages/blocks-engine/src/theme/index.ts
index 3e2641ce..9e8bfac2 100644
--- a/packages/blocks-engine/src/theme/index.ts
+++ b/packages/blocks-engine/src/theme/index.ts
@@ -44,6 +44,7 @@ export {
   sanitize,
   selectIslandSource,
 } from './html-fallback.js';
+export { preserveDomStrategy } from './preserve-dom/strategy.js';
 export {
   collectHtmlImages,
   collectSourceAssets,
diff --git a/packages/blocks-engine/src/theme/preserve-dom/__tests__/strategy.test.ts b/packages/blocks-engine/src/theme/preserve-dom/__tests__/strategy.test.ts
new file mode 100644
index 00000000..8f7fb63c
--- /dev/null
+++ b/packages/blocks-engine/src/theme/preserve-dom/__tests__/strategy.test.ts
@@ -0,0 +1,131 @@
+import { describe, expect, it } from 'vitest';
+
+import { preserveDomStrategy, reconstructNativeAggregate } from '../../index.js';
+import type { SectionSpec } from '../../section-spec.js';
+import { InstanceStyleSheet } from '../instance-styles.js';
+
+function sectionSpec(overrides: Partial<SectionSpec> = {}): SectionSpec {
+  return {
+    sectionIndex: 0,
+    interactionModel: 'static',
+    top: 0,
+    height: 0,
+    headings: [],
+    bodyText: [],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 1,
+    backgroundColor: 'transparent',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: {
+      motionClass: 'none',
+      signals: [],
+      animatedElements: 0,
+    },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: {
+      containerWidth: 0,
+      padding: '0',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '0',
+    },
+    ...overrides,
+  };
+}
+
+describe('preserveDomStrategy', () => {
+  it('emits lib-i core heading markup and drains deduped css rules', () => {
+    const aggregate = reconstructNativeAggregate(
+      [
+        sectionSpec({
+          sectionIndex: 2,
+          headings: ['Build fast'],
+          bodyText: ['Copy link'],
+          sectionHtml:
+            '<section id="hero-panel" class="feature shell"><h2 class="eyebrow" style="max-width:46ch">Build <span class="accent">fast</span></h2><p class="lede">Copy <a href="/go">link</a></p></section>',
+        }),
+      ],
+      { strategy: preserveDomStrategy },
+    );
+
+    expect(aggregate.sectionMarkup).toEqual([
+      '<!-- wp:group {"anchor":"hero-panel","tagName":"section","className":"feature shell"} -->\n' +
+        '<section id="hero-panel" class="wp-block-group feature shell"><!-- wp:heading {"className":"eyebrow lib-i91a84cc172"} -->\n' +
+        '<h2 class="wp-block-heading eyebrow lib-i91a84cc172">Build <span class="accent">fast</span></h2>\n' +
+        '<!-- /wp:heading -->\n' +
+        '<!-- wp:paragraph {"className":"lede"} -->\n' +
+        '<p class="lede">Copy <a href="/go">link</a></p>\n' +
+        '<!-- /wp:paragraph --></section>\n' +
+        '<!-- /wp:group -->',
+    ]);
+    expect(aggregate.sectionMarkup[0]).not.toContain('style=');
+    expect(aggregate.dedup).toEqual({ cssRules: ['.lib-i91a84cc172{max-width:46ch}'] });
+  });
+
+  it('emits byte-stable wrapper, direct image, and leaf span lib-i core paths', () => {
+    const aggregate = reconstructNativeAggregate(
+      [
+        sectionSpec({
+          sectionIndex: 3,
+          bodyText: ['Caption'],
+          sectionHtml:
+            '<section id="media-panel" class="media shell" style="padding:2rem"><img class="photo" style="width:100%" src="/photo.jpg" alt="Photo"><span class="caption" style="font-weight:700">Caption</span></section>',
+        }),
+      ],
+      { strategy: preserveDomStrategy },
+    );
+
+    expect(aggregate.sectionMarkup).toEqual([
+      '<!-- wp:group {"anchor":"media-panel","tagName":"section","className":"media shell lib-i42aa6d9c6f"} -->\n' +
+        '<section id="media-panel" class="wp-block-group media shell lib-i42aa6d9c6f"><!-- wp:image {"className":"photo lib-i0466783d98"} -->\n' +
+        '<figure class="wp-block-image photo lib-i0466783d98"><img src="/photo.jpg" alt="Photo"/></figure>\n' +
+        '<!-- /wp:image -->\n' +
+        '<!-- wp:paragraph {"className":"caption lib-ie3ec02ace9"} -->\n' +
+        '<p class="caption lib-ie3ec02ace9">Caption</p>\n' +
+        '<!-- /wp:paragraph --></section>\n' +
+        '<!-- /wp:group -->',
+    ]);
+    expect(aggregate.dedup).toEqual({
+      cssRules: [
+        '.lib-i0466783d98{width:100%}',
+        '.lib-i42aa6d9c6f{padding:2rem}',
+        '.lib-ie3ec02ace9{font-weight:700}',
+      ],
+    });
+  });
+
+  it('does not flatten deferred non-leaf wrappers through the leaf span/div path', () => {
+    const aggregate = reconstructNativeAggregate(
+      [
+        sectionSpec({
+          sectionIndex: 4,
+          bodyText: ['Nested'],
+          sectionHtml:
+            '<section id="nested-panel" class="shell"><div id="card" class="card"><span class="label">Nested</span></div></section>',
+        }),
+      ],
+      { strategy: preserveDomStrategy },
+    );
+
+    expect(aggregate.sectionMarkup).toEqual([
+      '<!-- wp:group {"anchor":"nested-panel","tagName":"section","className":"shell"} -->\n' +
+        '<section id="nested-panel" class="wp-block-group shell"></section>\n' +
+        '<!-- /wp:group -->',
+    ]);
+    expect(aggregate.sections[0]?.coverage.lost).toBe(true);
+    expect(aggregate.provenanceFlags).toEqual(['preserve-dom#4: skipped non-core elements']);
+  });
+
+  it('freezes lib-i hash parity for max-width declarations', () => {
+    const sheet = new InstanceStyleSheet();
+    const cls = sheet.classFor('max-width:46ch');
+
+    console.info('P3-S2 lib-i frozen slug=lib-i91a84cc172');
+    expect(cls).toBe('lib-i91a84cc172');
+    expect(sheet.toCss()).toBe('.lib-i91a84cc172{max-width:46ch}');
+  });
+});
diff --git a/packages/blocks-engine/src/theme/preserve-dom/instance-styles.ts b/packages/blocks-engine/src/theme/preserve-dom/instance-styles.ts
new file mode 100644
index 00000000..7d6a5715
--- /dev/null
+++ b/packages/blocks-engine/src/theme/preserve-dom/instance-styles.ts
@@ -0,0 +1,43 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Canonicalize a CSS declaration string for content-addressed dedup: split on
+ * ';', trim each declaration, collapse internal whitespace, normalize the
+ * `prop: value` spacing, drop empties, rejoin with ';'. So 'a: 1px ;  b:2px'
+ * and 'a:1px;b:2px' produce the same key.
+ */
+export function normalizeDeclarations(style: string): string {
+  return style
+    .split(';')
+    .map((decl) => decl.trim().replace(/\s+/g, ' '))
+    .filter(Boolean)
+    .map((decl) => {
+      const i = decl.indexOf(':');
+      if (i < 0) return decl;
+      return `${decl.slice(0, i).trim()}:${decl.slice(i + 1).trim()}`;
+    })
+    .join(';');
+}
+
+export class InstanceStyleSheet {
+  private readonly rules = new Map<string, string>();
+
+  classFor(style: string | undefined | null): string | null {
+    const decls = normalizeDeclarations(style ?? '');
+    if (!decls) return null;
+    const cls = `lib-i${createHash('sha1').update(decls).digest('hex').slice(0, 10)}`;
+    this.rules.set(cls, decls);
+    return cls;
+  }
+
+  get size(): number {
+    return this.rules.size;
+  }
+
+  toCss(): string {
+    return [...this.rules.entries()]
+      .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+      .map(([cls, decls]) => `.${cls}{${decls}}`)
+      .join('\n');
+  }
+}
diff --git a/packages/blocks-engine/src/theme/preserve-dom/strategy.ts b/packages/blocks-engine/src/theme/preserve-dom/strategy.ts
new file mode 100644
index 00000000..7f983162
--- /dev/null
+++ b/packages/blocks-engine/src/theme/preserve-dom/strategy.ts
@@ -0,0 +1,208 @@
+import * as cheerio from 'cheerio';
+import type { Cheerio, CheerioAPI } from 'cheerio';
+import { isTag, isText } from 'domhandler';
+import type { Element } from 'domhandler';
+import { escapeHtmlAttr as escapeHtml } from '../../escape.js';
+import type { NativeSectionDecision, SectionStrategy, StrategyState } from '../native-reconstruct-types.js';
+import type { SectionSpec } from '../section-spec.js';
+import { InstanceStyleSheet } from './instance-styles.js';
+
+type SourceIdentitySection = SectionSpec & {
+  sourceId?: string;
+  sourceClasses?: string[];
+};
+
+interface ChildResult {
+  markup: string;
+  clean: boolean;
+}
+
+function attrJson(value: string): string {
+  return JSON.stringify(value).replace(/--/g, '\\u002d\\u002d');
+}
+
+function classNameOf($el: Cheerio<Element>): string {
+  return ($el.attr('class') ?? '').split(/\s+/).filter(Boolean).join(' ');
+}
+
+function blockAttrs(pairs: string[], className: string): string {
+  const all = className ? [...pairs, `"className":${attrJson(className)}`] : pairs;
+  return all.length ? ` {${all.join(',')}}` : '';
+}
+
+function classNameWithInstance($el: Cheerio<Element>, sheet: InstanceStyleSheet): string {
+  const base = classNameOf($el);
+  const instance = sheet.classFor($el.attr('style'));
+  return [base, instance].filter(Boolean).join(' ');
+}
+
+function paragraphBlock(inner: string): string {
+  return `<!-- wp:paragraph -->\n<p>${inner}</p>\n<!-- /wp:paragraph -->`;
+}
+
+const HEADING = /^h([1-6])$/;
+const INLINE_ALLOWED = new Set(['a', 'strong', 'em', 'b', 'i', 'br', 'span']);
+
+function inlineHtml($: CheerioAPI, el: Element): string {
+  let out = '';
+  for (const node of $(el).contents().get()) {
+    if (isText(node)) {
+      out += escapeHtml(node.data);
+    } else if (isTag(node)) {
+      const tag = node.tagName?.toLowerCase() ?? '';
+      if (tag === 'br') {
+        out += '<br/>';
+        continue;
+      }
+      const cls = ($(node).attr('class') ?? '').trim();
+      const styleA = ($(node).attr('style') ?? '').trim();
+      if (INLINE_ALLOWED.has(tag)) {
+        const inner = inlineHtml($, node);
+        const clsAttr = cls ? ` class="${escapeHtml(cls)}"` : '';
+        if (tag === 'a') {
+          const href = escapeHtml($(node).attr('href') ?? '');
+          out += `<a${clsAttr} href="${href}">${inner}</a>`;
+        } else {
+          const styleAttr = styleA ? ` style="${escapeHtml(styleA)}"` : '';
+          out += `<${tag}${clsAttr}${styleAttr}>${inner}</${tag}>`;
+        }
+      } else {
+        out += inlineHtml($, node);
+      }
+    }
+  }
+  return out;
+}
+
+function imageBlock($: CheerioAPI, imgEl: Element, sheet: InstanceStyleSheet): string {
+  const src = escapeHtml($(imgEl).attr('src') ?? '');
+  const alt = escapeHtml($(imgEl).attr('alt') ?? '');
+  const cls = classNameWithInstance($(imgEl), sheet);
+  const attrs = blockAttrs([], cls);
+  const figCls = ['wp-block-image', cls].filter(Boolean).join(' ');
+  return `<!-- wp:image${attrs} -->\n<figure class="${escapeHtml(figCls)}"><img src="${src}" alt="${alt}"/></figure>\n<!-- /wp:image -->`;
+}
+
+function emitChild($: CheerioAPI, el: Element, sheet: InstanceStyleSheet): ChildResult {
+  const tag = el.tagName?.toLowerCase() ?? '';
+  const $el = $(el);
+
+  const h = HEADING.exec(tag);
+  if (h) {
+    const level = Number(h[1]);
+    const cls = classNameWithInstance($el, sheet);
+    const attrs = blockAttrs(level === 2 ? [] : [`"level":${level}`], cls);
+    const htmlCls = ['wp-block-heading', cls].filter(Boolean).join(' ');
+    const inner = inlineHtml($, el).trim();
+    return {
+      markup: `<!-- wp:heading${attrs} -->\n<h${level} class="${escapeHtml(htmlCls)}">${inner}</h${level}>\n<!-- /wp:heading -->`,
+      clean: true,
+    };
+  }
+
+  if (tag === 'p') {
+    const cls = classNameWithInstance($el, sheet);
+    const attrs = blockAttrs([], cls);
+    const inner = inlineHtml($, el).trim();
+    const clsPart = cls ? ` class="${escapeHtml(cls)}"` : '';
+    const open = `<p${clsPart}>`;
+    return { markup: `<!-- wp:paragraph${attrs} -->\n${open}${inner}</p>\n<!-- /wp:paragraph -->`, clean: true };
+  }
+
+  if (tag === 'img') {
+    return { markup: imageBlock($, el, sheet), clean: true };
+  }
+
+  const text = $el.text().trim();
+  const elementChildren = $el.children().toArray();
+  if ((tag === 'div' || tag === 'span') && !$el.attr('id') && elementChildren.length === 0 && text) {
+    const cls = classNameWithInstance($el, sheet);
+    const attrs = blockAttrs([], cls);
+    const clsPart = cls ? ` class="${escapeHtml(cls)}"` : '';
+    return {
+      markup: `<!-- wp:paragraph${attrs} -->\n<p${clsPart}>${inlineHtml($, el).trim()}</p>\n<!-- /wp:paragraph -->`,
+      clean: true,
+    };
+  }
+
+  // TODO(P3-S3): port non-core preserve-DOM branches only after this lib-i core proof lands.
+  return { markup: '', clean: false };
+}
+
+function sheetFromState(state: StrategyState): InstanceStyleSheet {
+  if (state.instanceStyles instanceof InstanceStyleSheet) return state.instanceStyles;
+  const sheet = new InstanceStyleSheet();
+  state.instanceStyles = sheet;
+  return sheet;
+}
+
+export const preserveDomStrategy: SectionStrategy = {
+  name: 'preserve-dom',
+  render(section, _options, _ctx, state): NativeSectionDecision | null {
+    const source = section as SourceIdentitySection;
+    const sourceHtml = section.sectionHtml ?? section.styledHtml ?? '';
+    if (!sourceHtml) return null;
+
+    const sheet = sheetFromState(state);
+    const $ = cheerio.load(sourceHtml);
+    const root = $('section, article, main, div').first();
+    const container = root.length ? root : $('body');
+    const childMarkup: string[] = [];
+    let downgrades = 0;
+    let total = 0;
+
+    for (const node of container.contents().get()) {
+      if (isTag(node)) {
+        total += 1;
+        const res = emitChild($, node, sheet);
+        if (!res.clean) downgrades += 1;
+        if (res.markup) childMarkup.push(res.markup);
+      } else if (isText(node)) {
+        const text = node.data.trim();
+        if (!text) continue;
+        total += 1;
+        childMarkup.push(paragraphBlock(escapeHtml(text)));
+      }
+    }
+
+    const inner = childMarkup.join('\n');
+    const sourceId = source.sourceId ?? container.attr('id')?.trim();
+    const sourceClasses =
+      source.sourceClasses && source.sourceClasses.length > 0
+        ? source.sourceClasses
+        : (container.attr('class') ?? '').split(/\s+/).filter(Boolean);
+    const cls = sourceClasses.join(' ');
+    const sectionInstance = sheet.classFor(container.attr('style'));
+    const wrapperCls = [cls, sectionInstance].filter(Boolean).join(' ');
+    const wrapperPairs = ['"tagName":"section"'];
+    if (sourceId) wrapperPairs.unshift(`"anchor":${attrJson(sourceId)}`);
+    const attrs = blockAttrs(wrapperPairs, wrapperCls);
+    const divCls = ['wp-block-group', wrapperCls].filter(Boolean).join(' ');
+    const idPart = sourceId ? ` id="${escapeHtml(sourceId)}"` : '';
+    const blocks =
+      `<!-- wp:group${attrs} -->\n` +
+      `<section${idPart} class="${escapeHtml(divCls)}">${inner}</section>\n` +
+      `<!-- /wp:group -->`;
+
+    return {
+      spec: section,
+      blocks,
+      coverage: {
+        textCoverage: downgrades > 0 ? 0 : 1,
+        missingImages: [],
+        lost: downgrades > 0,
+      },
+      expectedText: section.headings,
+      bodyText: section.bodyText,
+      expectedAssets: section.images.map((image) => image.url || image.sourceUrl).filter(Boolean),
+      provenanceFlags: downgrades > 0 ? [`preserve-dom#${section.sectionIndex}: skipped non-core elements`] : [],
+      fallbackDiagnostics: [],
+      iconAssets: [],
+      decision: 'native',
+    };
+  },
+  drainDedup(state) {
+    if (!(state.instanceStyles instanceof InstanceStyleSheet)) return { cssRules: [] };
+    return { cssRules: state.instanceStyles.size ? state.instanceStyles.toCss().split('\n') : [] };
+  },
+};

From 85e26825ed33e5cbeae5b1484dd7bbad30546e54 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Fri, 26 Jun 2026 13:49:29 -0400
Subject: [PATCH 108/113] test(theme): prove preserve DOM lib-i parity

---
 .../__tests__/libi-parity.test.ts             | 74 +++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 packages/blocks-engine/src/theme/preserve-dom/__tests__/libi-parity.test.ts

diff --git a/packages/blocks-engine/src/theme/preserve-dom/__tests__/libi-parity.test.ts b/packages/blocks-engine/src/theme/preserve-dom/__tests__/libi-parity.test.ts
new file mode 100644
index 00000000..f5495c65
--- /dev/null
+++ b/packages/blocks-engine/src/theme/preserve-dom/__tests__/libi-parity.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+
+import { preserveDomStrategy, reconstructNativeAggregate } from '../../index.js';
+import type { SectionSpec } from '../../section-spec.js';
+
+const LIB_I_CORE_HTML =
+  '<section id="hero" class="hero cover"><h1 class="display" style="margin:20px 0 0;font-size:clamp(3rem,9vw,6.5rem)">Scent</h1><p class="lead" style="max-width:46ch">Made to order.</p></section>';
+
+const DLA_CAPTURED_MARKUP =
+  '<!-- wp:group {"anchor":"hero","tagName":"section","className":"hero cover"} -->\n' +
+  '<section id="hero" class="wp-block-group hero cover"><!-- wp:heading {"level":1,"className":"display lib-i513454c2bb"} -->\n' +
+  '<h1 class="wp-block-heading display lib-i513454c2bb">Scent</h1>\n' +
+  '<!-- /wp:heading -->\n' +
+  '<!-- wp:paragraph {"className":"lead lib-i91a84cc172"} -->\n' +
+  '<p class="lead lib-i91a84cc172">Made to order.</p>\n' +
+  '<!-- /wp:paragraph --></section>\n' +
+  '<!-- /wp:group -->';
+
+const DLA_CAPTURED_CSS =
+  '.lib-i513454c2bb{margin:20px 0 0;font-size:clamp(3rem,9vw,6.5rem)}\n' +
+  '.lib-i91a84cc172{max-width:46ch}';
+
+function sectionSpec(overrides: Partial<SectionSpec> = {}): SectionSpec {
+  return {
+    sectionIndex: 0,
+    interactionModel: 'static',
+    top: 0,
+    height: 0,
+    headings: ['Scent'],
+    bodyText: ['Made to order.'],
+    buttonLabels: [],
+    images: [],
+    icons: [],
+    backgroundBrightness: 1,
+    backgroundColor: 'transparent',
+    gradient: null,
+    gradientSource: null,
+    motionProfile: {
+      motionClass: 'none',
+      signals: [],
+      animatedElements: 0,
+    },
+    dividerAbove: null,
+    dividerBelow: null,
+    layout: {
+      containerWidth: 0,
+      padding: '0',
+      childLayout: 'stack',
+      columnCount: 1,
+      gap: '0',
+    },
+    ...overrides,
+  };
+}
+
+describe('preserveDomStrategy lib-i parity', () => {
+  it('emits byte-identical lib-i core markup and css to DLA emitSectionBlocks', () => {
+    const aggregate = reconstructNativeAggregate(
+      [
+        sectionSpec({
+          sectionHtml: LIB_I_CORE_HTML,
+        }),
+      ],
+      { strategy: preserveDomStrategy },
+    );
+
+    const engineMarkup = aggregate.sectionMarkup[0];
+    const engineCss = aggregate.dedup?.cssRules?.join('\n') ?? '';
+
+    expect(engineMarkup).toBe(DLA_CAPTURED_MARKUP);
+    expect(engineCss).toBe(DLA_CAPTURED_CSS);
+    console.info('P3-S3 lib-i DLA parity identical=true');
+  });
+});

From 9b395f44bee1a2f20e31b5129cde3f971a961146 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 29 Jun 2026 08:41:15 -0400
Subject: [PATCH 109/113] docs(blocks-engine): restructure README with Install
 and Quick Start
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary
Rewrite the blocks-engine package README into a clean top-to-bottom onboarding flow: a scoped header, dedicated Install and Quick Start sections, table-formatted CLI reference, and a JavaScript API section.

## Why
The previous README led with awkward section names ("Start Here", "Which Do I Use?") and buried install instructions. Its exported-symbols list was also stale — it omitted the theme exports (siteToTheme, writeTheme, lintThemeJson) and related types that src/index.ts actually ships.

## How
Added Install and Quick Start sections, converted the CLI commands/options prose into tables, replaced the bare export dump with a use-case table plus a programmatic siteToTheme example, documented the ./theme and ./wp subpath exports, broke the Worker Pool prose into labeled subsections, and added a License section. All API details verified against cli.ts, index.ts, and theme/types.ts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01598tUQPYKEXZnknf2mgeyx
---
 packages/blocks-engine/README.md | 176 ++++++++++++++++++++-----------
 1 file changed, 115 insertions(+), 61 deletions(-)

diff --git a/packages/blocks-engine/README.md b/packages/blocks-engine/README.md
index fb65a306..265b8ce6 100644
--- a/packages/blocks-engine/README.md
+++ b/packages/blocks-engine/README.md
@@ -1,6 +1,48 @@
 # @automattic/blocks-engine
 
-Convert HTML into WordPress block markup from JavaScript or the command line.
+Convert HTML and static sites into WordPress block markup and block themes — from JavaScript or the command line.
+
+- **Convert HTML → blocks.** Turn an HTML fragment or page into clean WordPress block markup.
+- **Build a whole block theme.** Point it at a directory of static HTML and get back a ready-to-install block theme (templates, parts, patterns, `theme.json`, assets).
+- **Use it however you like.** A one-shot async API, a pure in-process composer, a reusable worker pool, and an `npx` CLI all ship in the box.
+
+## Install
+
+```sh
+npm install @automattic/blocks-engine
+```
+
+Or run the CLI without installing anything:
+
+```sh
+npx @automattic/blocks-engine --help
+```
+
+Requires Node.js with support for forking child processes and IPC (the worker pool runs conversions in child processes).
+
+## Quick Start
+
+### Build a block theme from the CLI
+
+```sh
+npx @automattic/blocks-engine theme ./my-site
+```
+
+This reads the static HTML in `./my-site` and writes a complete block theme to `./_block-theme`. The command exits without touching anything if that default directory already exists, so a stray `_block-theme/` is never silently overwritten.
+
+Set the output directory and theme metadata with flags:
+
+```sh
+npx @automattic/blocks-engine theme ./my-site --out ./theme --slug my-site --name "My Site"
+```
+
+The bare source-directory form is shorthand for `theme`:
+
+```sh
+npx @automattic/blocks-engine ./my-site
+```
+
+### Convert HTML in JavaScript
 
 ```js
 import { convert } from '@automattic/blocks-engine';
@@ -23,63 +65,54 @@ Emits:
 <!-- /wp:paragraph -->
 ```
 
-## Install Quickstart
+`convert` is the normal end-to-end path: it tries worker-backed conversion, falls back through composition when needed, canonicalizes the result, and returns WordPress block markup. If you don't pass a pool, it spins one up for the call and stops it before returning.
 
-Install the package:
+## CLI
 
-```sh
-npm install @automattic/blocks-engine
 ```
-
-Build a block theme from a source directory without adding a dependency:
-
-```sh
-npx @automattic/blocks-engine theme ./my-site
+blocks-engine theme <srcDir> [--out <dir>] [--slug <slug>] [--name <name>]
+blocks-engine <srcDir> [--out <dir>] [--slug <slug>] [--name <name>]
+blocks-engine convert [file]
+blocks-engine --help | -h
 ```
 
-The `theme` command writes the generated theme to `./_block-theme` by default and exits if that directory already exists. Use `--out`, `--slug`, and `--name` to set the output directory and theme metadata:
+| Command   | Description |
+|-----------|-------------|
+| `theme`   | Build a whole-site block theme from a source directory. |
+| `convert` | Convert a single HTML file — or stdin — to block markup. |
 
-```sh
-npx @automattic/blocks-engine theme ./my-site --out ./theme --slug my-site --name "My Site"
-```
+| Option          | Description |
+|-----------------|-------------|
+| `--out <dir>`   | Write the generated theme to a directory (default: `./_block-theme`; the command exits if it already exists). |
+| `--slug <slug>` | Set the generated theme slug. |
+| `--name <name>` | Set the generated theme name. |
 
-The bare source-directory shorthand is equivalent to `theme`:
+`convert` writes block markup to stdout. With a file argument it reads that file; with no argument it reads HTML from stdin:
 
 ```sh
-npx @automattic/blocks-engine ./my-site
+npx @automattic/blocks-engine convert page.html
+printf '<h2>Hi</h2>' | npx @automattic/blocks-engine convert
 ```
 
-Convert a single HTML file to block markup with the `convert` subcommand:
+## JavaScript API
 
-```sh
-npx @automattic/blocks-engine convert page.html
-```
+The root export (`@automattic/blocks-engine`) mirrors `src/index.ts`:
 
-`convert` writes block markup to stdout. With no file argument, it reads HTML from stdin:
+**Functions & classes**
 
-```sh
-printf '<h2>Hi</h2>' | npx @automattic/blocks-engine convert
-```
+| Export | Use it to… |
+|--------|-----------|
+| `convert` | Run the normal end-to-end HTML → blocks conversion (async). |
+| `compose` | Run the pure, synchronous in-process composition layer directly. |
+| `createWorker` | Create a reusable `WorkerPool` for batches or long-lived processes. |
+| `siteToTheme` | Build and write a block theme from a source directory (the CLI's `theme` engine). |
+| `writeTheme` | Write an already-built `ThemeModel` to disk. |
+| `lintThemeJson` | Lint a `theme.json` object and get back structured findings. |
+| `BlocksEngineError` | Catch package-level failures carrying a stable `code` and user-facing `hint`. |
 
-## Start Here
-
-The root package export mirrors `src/index.ts`:
-
-- `convert`
-- `compose`
-- `createWorker`
-- `BlocksEngineError`
-- `ConvertOptions`
-- `BlocksEngineErrorOptions`
-- `ConversionContext`
-- `Converter`
-- `HtmlFallback`
-- `CreateWorker`
-- `FixResult`
-- `RawConvertResult`
-- `WorkerPool`
-- `WorkerPoolOptions`
-- `PoolEvent`
+**Types**
+
+`ConvertOptions`, `BlocksEngineErrorOptions`, `SiteToThemeOptions`, `ThemeBuildResult`, `ThemeJsonLintResult`, `ConversionContext`, `Converter`, `HtmlFallback`, `CreateWorker`, `FixResult`, `RawConvertResult`, `WorkerPool`, `WorkerPoolOptions`, `PoolEvent`.
 
 Import runtime functions and classes normally, and import TypeScript shapes with `type`:
 
@@ -89,41 +122,46 @@ import {
   compose,
   convert,
   createWorker,
+  siteToTheme,
   type Converter,
   type PoolEvent,
   type WorkerPool,
 } from '@automattic/blocks-engine';
 ```
 
-Advanced utilities that are not part of the headline path live under `@automattic/blocks-engine/internals`.
-
-## Which Do I Use?
-
-Use `convert` for the normal end-to-end path. It accepts HTML plus an optional conversion context, tries worker-backed conversion, falls back through composition when needed, canonicalizes the result, and returns WordPress block markup. If you do not pass a pool, `convert` creates one for the call and stops it before returning.
-
-Use `compose` when you want the pure, synchronous in-process composition layer directly. It is useful for custom `Converter` chains, custom `HtmlFallback` behavior, and tests or tools that already know they only need best-effort local HTML-to-block composition. It does not create, own, or stop a worker pool.
+Advanced utilities that aren't part of the headline path live under `@automattic/blocks-engine/internals`. Theme- and WordPress-specific helpers are exposed under `@automattic/blocks-engine/theme` and `@automattic/blocks-engine/wp`.
 
-Use `createWorker` when you are converting batches or running a long-lived process. Reuse one `WorkerPool` across calls instead of paying worker startup costs per item, and pass it into `convert` with `ConvertOptions.pool` when you want `convert` to use that shared pool.
+### Build a theme programmatically
 
-Use `BlocksEngineError` when catching package-level failures that include a stable `code` and user-facing `hint`.
-
-## Worker Pool Lifecycle
+```ts
+import { siteToTheme } from '@automattic/blocks-engine';
 
-`createWorker(options?)` returns a `WorkerPool` with `rawConvert(items)`, `canonicalize(items)`, and `stop()`. Treat the pool as an owned process resource.
+const result = await siteToTheme('./my-site', {
+  outDir: './theme',
+  themeMeta: { slug: 'my-site', name: 'My Site' },
+});
 
-The default pool size is `min(cores, 4)`, with a minimum of one worker. Passing `WorkerPoolOptions.size` floors the value and still keeps at least one worker. For most request/response code, start with the default. For CI, deterministic tests, or memory-constrained jobs, prefer `size: 1` or another explicit small number.
+console.log(`Wrote ${result.written.length} files to ${result.outDir}`);
+result.warnings.forEach((warning) => console.warn(warning));
+```
 
-Workers are child processes connected to the parent over Node IPC. Create the pool in the parent process that will send work, and do not try to pass a live pool across process boundaries. Workers die with the parent process, but parent shutdown is not a deterministic cleanup API. Always call `await pool.stop()` in a `finally` block, test teardown, or service shutdown hook. The one-shot `convert` helper handles this for internally-created pools; shared pools are your responsibility.
+`siteToTheme` ingests the source directory, builds the theme model, and writes it to `outDir` (defaulting to `<srcDir>/theme`), returning a `ThemeBuildResult` with the written file list, tallies, warnings, and diagnostics. Pass your own `pool` to reuse a worker pool across builds; otherwise it manages one internally.
 
-Use `recycleAfter` to replace a child after it has processed a configured number of items. The default is `0`, which disables recycling. Recycling is useful for long-running batches, CI isolation, and workloads where periodically refreshing child process state is safer than keeping one process alive indefinitely.
+## Which entry point do I use?
 
-Use `itemTimeoutMs` to bound how long one item can occupy a worker. The default is `10000`. On timeout or worker failure, the pool reroutes work until its reroute limit is reached; unresolved raw conversions return a `RawConvertResult` sentinel and unresolved canonicalization returns the original HTML in a `FixResult`.
+- **`convert`** — the default. Async, worker-backed with composition fallback, and self-contained: it owns and stops its pool unless you supply one.
+- **`compose`** — the pure, synchronous composition layer. Reach for it when you want custom `Converter` chains, custom `HtmlFallback` behavior, or tests and tools that only need best-effort local HTML-to-block composition. It never creates, owns, or stops a worker pool.
+- **`createWorker`** — for batches or long-lived processes. Reuse one `WorkerPool` across calls to avoid per-item worker startup costs, and pass it into `convert` via `ConvertOptions.pool`.
+- **`siteToTheme`** — for turning a directory of static HTML into a full block theme (this is what the CLI's `theme` command runs).
+- **`BlocksEngineError`** — catch this for package-level failures with a stable `code` and user-facing `hint`.
 
-Use `onEvent` for operational visibility. The callback receives `PoolEvent` values for `child-spawn`, `child-crash`, `re-route`, `recycle`, `sentinel`, and `pool-degraded`, with `childId` and `count` when available. In CI, log these events when diagnosing flakes, timeouts, fork limits, or degraded worker startup.
+## Worker Pool Lifecycle
 
-Build or run from an environment that can fork Node child processes and use IPC. For packaged or CI usage, run the package from its built distribution so the worker child file is present; source-mode execution depends on the local TypeScript runner setup.
+`createWorker(options?)` returns a `WorkerPool` with `rawConvert(items)`, `canonicalize(items)`, and `stop()`. Treat the pool as an owned process resource.
 
 ```ts
+import { convert, createWorker, type PoolEvent } from '@automattic/blocks-engine';
+
 const events: PoolEvent[] = [];
 const pool = createWorker({
   size: 2,
@@ -139,3 +177,19 @@ try {
   await pool.stop();
 }
 ```
+
+**Sizing.** The default pool size is `min(cores, 4)`, with a minimum of one worker. `WorkerPoolOptions.size` floors the value and still keeps at least one worker. Start with the default for request/response code; prefer `size: 1` (or another small number) for CI, deterministic tests, or memory-constrained jobs.
+
+**Cleanup.** Workers are child processes connected to the parent over Node IPC. Create the pool in the process that will send work, and don't pass a live pool across process boundaries. Workers die with the parent, but that is not a deterministic cleanup path — always `await pool.stop()` in a `finally` block, test teardown, or shutdown hook. The one-shot `convert` helper handles this for pools it creates itself; shared pools are your responsibility.
+
+**Recycling.** `recycleAfter` replaces a child after it has processed that many items. The default is `0` (disabled). Recycling helps with long-running batches, CI isolation, and workloads where periodically refreshing child-process state is safer than keeping one alive indefinitely.
+
+**Timeouts & resilience.** `itemTimeoutMs` (default `10000`) bounds how long one item can occupy a worker. On timeout or worker failure the pool reroutes work until its reroute limit is reached; unresolved raw conversions return a `RawConvertResult` sentinel and unresolved canonicalization returns the original HTML in a `FixResult`.
+
+**Observability.** `onEvent` receives `PoolEvent` values for `child-spawn`, `child-crash`, `re-route`, `recycle`, `sentinel`, and `pool-degraded`, with `childId` and `count` when available. Log these when diagnosing flakes, timeouts, fork limits, or degraded worker startup.
+
+**Packaging.** Run from an environment that can fork Node child processes and use IPC. For packaged or CI usage, run the package from its built distribution so the worker child file is present; source-mode execution depends on the local TypeScript runner setup.
+
+## License
+
+GPL-3.0-or-later

From c6d1859cdcf7f917309330154e7f8f2b6886ad93 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 29 Jun 2026 08:53:05 -0400
Subject: [PATCH 110/113] build(blocks-engine): prepare package for public npm
 publish

## Summary
Adds the packaging metadata and license file needed to publish @automattic/blocks-engine to the public npm registry.

## Why
The scoped package had no publish configuration, so npm would default to a private (paid-scope) publish and a misrouted registry. The declared GPL-3.0-or-later license also shipped no LICENSE file, since npm only includes a LICENSE that lives inside the package directory.

## How
- Add publishConfig with access: public and the public npmjs.org registry so a plain `npm publish` targets the right place and publishes the scope publicly.
- Add a prepublishOnly script that runs the tsup build, so the gitignored dist is always freshly built before publish.
- Vendor a copy of the GPL-3.0 LICENSE into the package so it ships in the tarball.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XaSpm1VM21MrJWWRe3ujbs
---
 packages/blocks-engine/LICENSE      | 674 ++++++++++++++++++++++++++++
 packages/blocks-engine/package.json |   7 +-
 2 files changed, 680 insertions(+), 1 deletion(-)
 create mode 100644 packages/blocks-engine/LICENSE

diff --git a/packages/blocks-engine/LICENSE b/packages/blocks-engine/LICENSE
new file mode 100644
index 00000000..f288702d
--- /dev/null
+++ b/packages/blocks-engine/LICENSE
@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.
diff --git a/packages/blocks-engine/package.json b/packages/blocks-engine/package.json
index 0bb74125..690cb951 100644
--- a/packages/blocks-engine/package.json
+++ b/packages/blocks-engine/package.json
@@ -5,6 +5,10 @@
   "keywords": ["wordpress", "blocks", "gutenberg", "block-theme", "html", "static-site"],
   "license": "GPL-3.0-or-later",
   "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "bin": {
     "blocks-engine": "./dist/cli.js"
   },
@@ -39,7 +43,8 @@
   },
   "scripts": {
     "build": "tsup",
-    "test": "vitest run"
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "cheerio": "1.2.0",

From 11e0b88e459d2ac10e9237195fc86c9ec618f365 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 29 Jun 2026 08:59:32 -0400
Subject: [PATCH 111/113] build(blocks-engine): add per-package release tooling

## Summary
Wires up monorepo-consistent version tagging for @automattic/blocks-engine: a homeboy release config and an npm tag-version prefix, both producing `blocks-engine-v<version>` tags to match php-transformer and figma-transformer.

## Why
blocks-engine had no release automation and no tag convention. npm version would default to bare `v<version>` tags, which collide with the monorepo's per-package tag namespace. The package also had no homeboy entry, so it couldn't be driven through the same release preflight as the sibling PHP packages.

## How
- Add homeboy.json with id `blocks-engine`, package.json as the single version target, and CHANGELOG.md as the changelog target. Releases run via `homeboy release blocks-engine` and tag as `blocks-engine-v<version>`.
- Set tag-version-prefix in .npmrc so any `npm version` bump also produces a correctly namespaced tag rather than a bare `v<version>`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XaSpm1VM21MrJWWRe3ujbs
---
 packages/blocks-engine/.npmrc       |  4 ++++
 packages/blocks-engine/homeboy.json | 12 ++++++++++++
 2 files changed, 16 insertions(+)
 create mode 100644 packages/blocks-engine/homeboy.json

diff --git a/packages/blocks-engine/.npmrc b/packages/blocks-engine/.npmrc
index 4c2f52b3..4c85a0be 100644
--- a/packages/blocks-engine/.npmrc
+++ b/packages/blocks-engine/.npmrc
@@ -1,2 +1,6 @@
 auto-install-peers=true
 strict-peer-dependencies=false
+
+# `npm version` creates monorepo-scoped tags (e.g. blocks-engine-v0.1.0)
+# to match the per-package tag convention used by php-transformer/figma-transformer.
+tag-version-prefix=blocks-engine-v
diff --git a/packages/blocks-engine/homeboy.json b/packages/blocks-engine/homeboy.json
new file mode 100644
index 00000000..e3c0c27d
--- /dev/null
+++ b/packages/blocks-engine/homeboy.json
@@ -0,0 +1,12 @@
+{
+  "auto_cleanup": false,
+  "changelog_target": "CHANGELOG.md",
+  "id": "blocks-engine",
+  "remote_path": "",
+  "version_targets": [
+    {
+      "file": "package.json",
+      "pattern": "\"version\": \"([0-9]+\\.[0-9]+\\.[0-9]+)\""
+    }
+  ]
+}

From 5c867a1b64044db633203300910f74cd0c35d4e8 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 29 Jun 2026 09:27:24 -0400
Subject: [PATCH 112/113] feat(blocks-engine): polish developer experience from
 DX review

## Summary
Closes the DX gaps surfaced by the developer-experience review of the public package surface: a documented error-code contract, self-healing CLI errors, complete npm metadata, and contribution scaffolding.

## What changed
- README: add an "Error handling" section documenting the four stable BlocksEngineError codes (alphabetized) with a try/catch example. The `code` is now an explicit part of the package contract.
- CLI: introduce CliUsageError for argument-syntax mistakes (unknown option, missing srcDir, missing value, unexpected argument) and reprint usage on them, so a mistyped flag self-heals instead of printing a bare line.
- package.json: add repository (with monorepo directory), homepage, bugs, and engines.node (>=20, matching CI); add a `typecheck` script (tsc --noEmit).
- Add a root CONTRIBUTING.md and a .github bug-report issue template so external users have a guided path to develop and report issues.

## Testing
- [x] pnpm test (334 passing, includes 2 new CLI usage-reprint tests added red-first)
- [x] pnpm typecheck (tsc --noEmit, 0 errors)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XaSpm1VM21MrJWWRe3ujbs
---
 .github/ISSUE_TEMPLATE/bug_report.md          | 28 ++++++++++++++
 CONTRIBUTING.md                               | 34 +++++++++++++++++
 packages/blocks-engine/README.md              | 25 +++++++++++++
 packages/blocks-engine/package.json           | 11 ++++++
 .../blocks-engine/src/__tests__/cli.test.ts   | 37 +++++++++++++++++++
 packages/blocks-engine/src/cli.ts             | 16 ++++++--
 6 files changed, 147 insertions(+), 4 deletions(-)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md
 create mode 100644 CONTRIBUTING.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 00000000..7490cc9e
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Report a problem with a package in this repository
+title: ''
+labels: bug
+assignees: ''
+---
+
+**Package and version**
+Which package (e.g. `@automattic/blocks-engine`) and what version?
+
+**What happened**
+A clear description of the bug, including any `BlocksEngineError` `code` and `hint` you saw.
+
+**Reproduction**
+Minimal steps or code/CLI command that triggers the problem. Include sample input if relevant.
+
+```
+# command or code
+```
+
+**Expected behavior**
+What you expected to happen instead.
+
+**Environment**
+- Node version:
+- OS:
+- Install method (npm/npx/pnpm):
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..fa884d4c
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,34 @@
+# Contributing
+
+This repository is a monorepo of WordPress block tooling. Each package is developed and released independently:
+
+- `packages/blocks-engine` — `@automattic/blocks-engine` (JS/TS engine + CLI)
+- `php-transformer` — `automattic/blocks-engine-php-transformer` (Composer)
+- `figma-transformer`
+
+## Reporting bugs
+
+Open an issue using the bug-report template. Include the package affected, the version, a minimal reproduction, and what you expected versus what happened.
+
+## Developing `@automattic/blocks-engine`
+
+```sh
+cd packages/blocks-engine
+pnpm install        # install dependencies (uses the committed lockfile)
+pnpm build          # build dist via tsup
+pnpm test           # run the vitest suite
+```
+
+The worker pool forks Node child processes, so a development environment must support `child_process` fork + IPC. When running tests or tools against the built output, run `pnpm build` first so the worker child file is present in `dist`.
+
+## Pull requests
+
+- Branch off `trunk`.
+- Keep changes scoped to one package per PR where practical; CI runs per-package on paths under that package.
+- Use Conventional Commits (`feat`, `fix`, `docs`, `build`, `test`, `refactor`, `chore`) with a package scope, e.g. `fix(blocks-engine): …`.
+- Add or update tests for behavior changes. The suite must pass before review.
+- Public API and `BlocksEngineError` `code` values are a stable contract — call out any change to them in the PR description and the package `CHANGELOG.md`.
+
+## Releasing
+
+Releases are tagged per package (`blocks-engine-v*`, `php-transformer-v*`, `figma-transformer-v*`). See the package's own release notes/tooling for the current process.
diff --git a/packages/blocks-engine/README.md b/packages/blocks-engine/README.md
index 265b8ce6..0524c21c 100644
--- a/packages/blocks-engine/README.md
+++ b/packages/blocks-engine/README.md
@@ -190,6 +190,31 @@ try {
 
 **Packaging.** Run from an environment that can fork Node child processes and use IPC. For packaged or CI usage, run the package from its built distribution so the worker child file is present; source-mode execution depends on the local TypeScript runner setup.
 
+## Error handling
+
+Package-level failures throw a `BlocksEngineError` carrying a stable `code` and a user-facing `hint`. The `code` is part of the package's contract — switch on it rather than matching message text. From the CLI, the `message` and `hint` are printed to stderr and the process exits non-zero.
+
+```ts
+import { siteToTheme, BlocksEngineError } from '@automattic/blocks-engine';
+
+try {
+  await siteToTheme('./my-site');
+} catch (error) {
+  if (error instanceof BlocksEngineError) {
+    console.error(`[${error.code}] ${error.message}\n${error.hint}`);
+  } else {
+    throw error;
+  }
+}
+```
+
+| Code | Thrown when | Fix |
+|------|-------------|-----|
+| `INJECTION_VECTORS_REMAIN` | The default HTML fallback sanitized input but unsafe vectors remained. | Pass a custom `htmlFallback` that emits safe markup, or pre-sanitize the input. |
+| `THEME_INGEST_DUPLICATE_SLUG` | Two source pages resolve to the same theme slug. | Rename or restructure the source pages so each maps to a unique slug. |
+| `THEME_INGEST_NO_HTML` | A theme build finds no `.html`/`.htm` pages under the source directory. | Point the build at a directory that contains at least one HTML page. |
+| `WORKER_CHILD_UNRESOLVED` | The worker pool can't locate its child file (typically running from source, or an incomplete build). | Run `npm run build` and run from the built `dist`; confirm the worker child file is present. |
+
 ## License
 
 GPL-3.0-or-later
diff --git a/packages/blocks-engine/package.json b/packages/blocks-engine/package.json
index 690cb951..e49da579 100644
--- a/packages/blocks-engine/package.json
+++ b/packages/blocks-engine/package.json
@@ -5,6 +5,16 @@
   "keywords": ["wordpress", "blocks", "gutenberg", "block-theme", "html", "static-site"],
   "license": "GPL-3.0-or-later",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Automattic/blocks-engine.git",
+    "directory": "packages/blocks-engine"
+  },
+  "homepage": "https://github.com/Automattic/blocks-engine/tree/trunk/packages/blocks-engine#readme",
+  "bugs": "https://github.com/Automattic/blocks-engine/issues",
+  "engines": {
+    "node": ">=20"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -43,6 +53,7 @@
   },
   "scripts": {
     "build": "tsup",
+    "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
diff --git a/packages/blocks-engine/src/__tests__/cli.test.ts b/packages/blocks-engine/src/__tests__/cli.test.ts
index 0b0d9048..6ace9fef 100644
--- a/packages/blocks-engine/src/__tests__/cli.test.ts
+++ b/packages/blocks-engine/src/__tests__/cli.test.ts
@@ -309,6 +309,43 @@ describe('CLI theme builds', () => {
     expect(stderr.text()).toBe('');
   });
 
+  it('reprints usage when given an unknown option', async () => {
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+    const calls: string[] = [];
+
+    const exitCode = await runCli(['/tmp/source-site', '--ot', '/tmp/out'], {
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+      pathExists: () => true,
+      isDirectory: () => true,
+      siteToThemeImpl: async (calledSrcDir) => {
+        calls.push(calledSrcDir);
+        return themeResult('/tmp/out');
+      },
+    });
+
+    expect(exitCode).toBe(1);
+    expect(calls).toEqual([]);
+    expect(stdout.text()).toBe('');
+    expect(stderr.text()).toContain('Unknown option: --ot');
+    expect(stderr.text()).toContain('blocks-engine theme <srcDir>');
+  });
+
+  it('reprints usage when the explicit theme command omits srcDir', async () => {
+    const stdout = writableBuffer();
+    const stderr = writableBuffer();
+
+    const exitCode = await runCli(['theme'], {
+      stdout: stdout.stream,
+      stderr: stderr.stream,
+    });
+
+    expect(exitCode).toBe(1);
+    expect(stderr.text()).toContain('Missing <srcDir>');
+    expect(stderr.text()).toContain('blocks-engine theme <srcDir>');
+  });
+
   it('prints a clear error when the explicit theme command omits srcDir', async () => {
     const stdout = writableBuffer();
     const stderr = writableBuffer();
diff --git a/packages/blocks-engine/src/cli.ts b/packages/blocks-engine/src/cli.ts
index a47ae4cf..ebe73419 100644
--- a/packages/blocks-engine/src/cli.ts
+++ b/packages/blocks-engine/src/cli.ts
@@ -15,6 +15,9 @@ interface WritableLike {
   write(chunk: string | Uint8Array): unknown;
 }
 
+/** Thrown when the CLI is invoked incorrectly (bad flags, missing arguments). The handler reprints usage. */
+class CliUsageError extends Error {}
+
 type ConvertHtml = (html: string, ctx: { url: string }) => Promise<string>;
 type SiteToThemeImpl = (srcDir: string, options?: SiteToThemeOptions) => Promise<ThemeBuildResult>;
 
@@ -74,6 +77,11 @@ export async function runCli(argv: string[], options: RunCliOptions = {}): Promi
       return 1;
     }
 
+    if (error instanceof CliUsageError) {
+      stderr.write(`${error.message}\n\n${usage()}`);
+      return 1;
+    }
+
     const message = error instanceof Error ? error.message : String(error);
     stderr.write(`${message}\n`);
     return 1;
@@ -156,7 +164,7 @@ function parseThemeArgs(argv: string[]): {
 } {
   const srcDir = argv[0];
   if (srcDir === undefined) {
-    throw new Error('Missing <srcDir> for theme command.');
+    throw new CliUsageError('Missing <srcDir> for theme command.');
   }
 
   const flags: { outDir?: string; slug?: string; name?: string } = {};
@@ -166,7 +174,7 @@ function parseThemeArgs(argv: string[]): {
     if (arg === '--out' || arg === '--slug' || arg === '--name') {
       const value = argv[index + 1];
       if (value === undefined) {
-        throw new Error(`Missing value for ${arg}.`);
+        throw new CliUsageError(`Missing value for ${arg}.`);
       }
       setThemeFlag(flags, arg, value);
       index += 1;
@@ -174,9 +182,9 @@ function parseThemeArgs(argv: string[]): {
       const equalsIndex = arg.indexOf('=');
       setThemeFlag(flags, arg.slice(0, equalsIndex), arg.slice(equalsIndex + 1));
     } else if (arg.startsWith('--')) {
-      throw new Error(`Unknown option: ${arg}`);
+      throw new CliUsageError(`Unknown option: ${arg}`);
     } else {
-      throw new Error(`Unexpected argument: ${arg}`);
+      throw new CliUsageError(`Unexpected argument: ${arg}`);
     }
   }
 

From 067772c3787d4e5a854dc178a29489169b3aaadc Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 29 Jun 2026 09:27:34 -0400
Subject: [PATCH 113/113] ci(blocks-engine): add typecheck step to the JS
 workflow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary
Adds a dedicated Typecheck step (pnpm typecheck → tsc --noEmit) to the path-scoped blocks-engine workflow, so type errors fail the run early and independently of the bundler.

## How
- New "Typecheck" step runs after install and before build.
- Job renamed "Install, build, and test" → "Typecheck, build, and test".
- Relies on the `typecheck` script added to packages/blocks-engine/package.json.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XaSpm1VM21MrJWWRe3ujbs
---
 .github/workflows/js.yml | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/js.yml b/.github/workflows/js.yml
index f6d93cc5..c00ac02c 100644
--- a/.github/workflows/js.yml
+++ b/.github/workflows/js.yml
@@ -14,7 +14,7 @@ on:
 
 jobs:
   validate:
-    name: Install, build, and test
+    name: Typecheck, build, and test
     runs-on: ubuntu-latest
 
     defaults:
@@ -38,6 +38,9 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Typecheck
+        run: pnpm typecheck
+
       - name: Build
         run: pnpm build