@oneie/claude 0.6.0 → 0.8.0

package/skills/puck/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: puck
-description: Build with Puck — the drag-drop visual editor for ONE. Covers @puckeditor/core API, Config/Data types, block registries, PuckEditor (client:only) + PuckRenderer (SSR), iframe brand injection, data-bound blocks, email target mode, and the funnels-pages architecture.
+description: Build with Puck — the drag-drop visual editor for ONE. Covers the @puckeditor/core API, Config/Data types, the block registry in lib/puck/, PuckEditor (client:only) + PuckRenderer (SSR), brand-token injection into the editor iframe, data-bound blocks via RecordPickerField, and the page/funnel storage columns. Use when adding or editing a Puck block, wiring a custom inspector field, debugging a block that renders in the editor but not on /p/, or changing how page data is stored.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 ---
@@ -10,19 +10,22 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 Puck is the drag-drop visual editor powering ONE's page system. Every landing page (`/p/`), funnel step (`/f/`), and eventually newsletter, product page, and course lesson is authored in one editor, stored as one typed JSON shape (Puck `Data`), and rendered by a small set of per-target renderers.
 
 **Architecture doc:** `text/funnels-pages-plan.md`  
-**Repo:** `../apps/puckeditor/` (cloned from https://github.com/puckeditor/puck)  
-**Package:** `@puckeditor/core` (^0.21.3, published on npm) — Puck moved from `@measured/puck`@0.20.x to the `@puckeditor` org; the funnels-pages doc set is synced to this name (2026-06-22). Source mirror: `../apps/puckeditor/`.  
-**ONE block registry:** `one.ie/web/src/lib/puck/config.tsx`
+**Source mirror:** `/Users/toc/Server/apps/puckeditor/` (cloned from https://github.com/puckeditor/puck) — read-only reference for upstream types  
+**Package:** `@puckeditor/core` — declared `^0.21.3`, installed **0.21.3**. Puck moved from `@measured/puck`@0.20.x to the `@puckeditor` org; the doc set is synced to this name.  
+**ONE block registry:** `one.ie/web/src/lib/puck/config.tsx` + its sibling `*-blocks.tsx` files
 
 ## Works With
 
 | Skill | Load when |
 |---|---|
 | `/astro` | The editor is a `client:only` island; the renderer runs SSR in `.astro` files |
-| `/react19` | Block `render` fns are React 19 components; use `use()` + `useTransition` for data-bound blocks |
-| `/shadcn` | Every block wraps a real shadcn component — brand tokens are inherited via the iframe injection |
+| `/react19` | Block `render` fns are React 19 components |
+| `/shadcn` | Every block wraps a real component — brand tokens reach the canvas via the iframe injection |
+| `/reactflow` | `OrgChartView` and `WorkflowFlow` are lazy-loaded as blocks in `config.tsx` |
 
-Auto-loads with `*puck*` file patterns.
+This skill is invoked explicitly, not by file glob. What *does* auto-load when you
+edit a block file is `rules/react.md` (`**/*.tsx`) and `rules/design.md`
+(`one.ie/web/**/*.{tsx,astro,css}`) — the 6-token ban list applies to every block.
 
 ---
 
@@ -45,36 +48,52 @@ import "@puckeditor/core/puck.css"; // in the PuckEditor component only
 
 A Puck config is the block registry: a map of component names to their field schema and render function.
 
+In `config.tsx` the registry is not one literal — it is 12 block groups merged, then
+wrapped, with categories derived from each block's `metadata.category`:
+
 ```ts
-import type { Config } from "@puckeditor/core";
-
-const config: Config = {
-  // Optional: group palette by category
-  categories: {
-    Structural: { components: ["Heading", "Text", "Image", "Button", "Form", "Columns", "Spacer"] },
-    CRO:        { components: ["LandingHero", "ProofBar", "HowItWorks", "LandingFeatures", "Testimonials", "ComparisonTable", "PricingSection", "FAQSection", "SecondaryCTA"] },
-    Funnel:     { components: ["CheckoutBlock", "UpsellBlock"] },
-    "Data-bound": { components: ["ProductBlock", "ListBlock"] },
-  },
+// one.ie/web/src/lib/puck/config.tsx — the tail of the file
+export const puckConfig: Config = {
+  components: withChrome({
+    ...blocks, ...dataBlocks, ...teamFlowBlocks, ...studioBlocks, ...appBlocks,
+    ...walletBlocks, ...socialBlocks, ...socialFormatBlocks, ...authBlocks,
+    ...aiBlocks, ...ecommerceNewBlocks, ...generalNewBlocks,
+  }),
+  categories: buildCategories(blocks, dataBlocks, teamFlowBlocks, studioBlocks,
+    appBlocks, walletBlocks, socialBlocks, socialFormatBlocks, authBlocks,
+    aiBlocks, ecommerceNewBlocks, generalNewBlocks),
+};
+```
 
-  components: {
-    Heading: {
-      label: "Heading",
-      fields: {
-        text:  { type: "text" },
-        level: { type: "select", options: [{ label: "H1", value: "h1" }, { label: "H2", value: "h2" }] },
-      },
-      defaultProps: { text: "Heading", level: "h1" },
-      render: ({ text, level }) => {
-        const Tag = level as "h1" | "h2";
-        return <Tag className="font-bold tracking-tight">{text}</Tag>;
-      },
-    },
-    // ... more blocks
+`withChrome` and `buildCategories` are module-private helpers at the tail of
+`config.tsx` (lines ~6732 and ~6776) — `withChrome` wraps every block's render
+with the shared section chrome; `buildCategories` derives the palette groups from
+each block's `metadata.category`.
+
+Adding a block means adding a key to one of those groups — never a new
+top-level spread. A single block looks like this:
+
+```tsx
+Heading: {
+  metadata: { surface: 'section', semantics: {}, ...web, category: 'content',
+              icon: 'Type', description: 'Section heading' },
+  fields: {
+    text:  { type: 'text' as const },
+    level: { type: 'select' as const, options: [
+      { label: 'H1', value: 'h1' }, { label: 'H2', value: 'h2' },
+    ] },
   },
-};
+  defaultProps: { text: 'Heading', level: 'h1' },
+  render: ({ text, level }: { text: string; level: string }) => {
+    const Tag = level as 'h1' | 'h2';
+    return <Tag className="font-bold tracking-tight text-font">{text}</Tag>;
+  },
+},
 ```
 
+Note `as const` on every field `type` — without it TypeScript widens the literal
+to `string` and the `Fields` type rejects the object.
+
 ### ComponentConfig anatomy
 
 ```ts
@@ -82,58 +101,82 @@ type ComponentConfig<Props> = {
   label?: string;           // palette display name (defaults to component key)
   fields: Fields<Props>;    // inspector form schema
   defaultProps?: Props;     // initial values on drag-in
-  render: (props: WithId<Props>) => JSX.Element;  // the block renderer
-  resolveData?: (data, params) => Promise<{props?>}>;  // async data resolution (data-bound blocks)
+  render: (props: WithId<Props>) => JSX.Element;             // the block renderer
+  metadata?: Record<string, any>;                            // ONE's extension point — see below
+  resolveData?: (data, params) => Promise<{ props?: Partial<Props> }>;
   resolveFields?: (data, params) => Promise<Fields<Props>>;  // dynamic inspector fields
-  permissions?: { drag?, duplicate?, delete?, insert?, move? };  // per-block permission overrides
+  permissions?: { drag?; duplicate?; delete?; insert?; move? };
   inline?: boolean;         // renders inline (no wrapper div)
 };
 ```
 
+The 0.21 type is **strict about sibling keys** — anything ONE-specific must go
+under `metadata`, never beside `fields`. `metadata` in this repo carries
+`category`, `icon`, `description`, `preview`, `surface`, `semantics`, and
+`targets`; `buildBlockIndex` (`lib/puck/block-index.ts`) reads exactly those, with
+fallbacks `category → 'content'`, `icon → 'Square'`, `description → ''`.
+
 ---
 
 ## Field types
 
-The inspector is driven by `fields` in each block's config. ONE uses these field types:
+The inspector is driven by `fields` in each block's config. Counts below are live
+occurrences in `config.tsx` — they tell you which shapes are load-bearing here:
 
-| Type | Usage |
-|---|---|
-| `{ type: "text" }` | Single-line text input; `contentEditable?: true` for inline editing on canvas |
-| `{ type: "textarea" }` | Multi-line text |
-| `{ type: "number", min?, max?, step? }` | Numeric |
-| `{ type: "richtext" }` | Rich text with Tiptap; `contentEditable?: true` |
-| `{ type: "select", options: [{label, value}] }` | Dropdown |
-| `{ type: "radio", options: [{label, value}] }` | Radio group |
-| `{ type: "array", arrayFields: {…}, getItemSummary?, min?, max? }` | Repeating sub-items (e.g. list of CTA buttons) |
-| `{ type: "object", objectFields: {…} }` | Nested group |
-| `{ type: "external", fetchList, mapProp?, showSearch?, filterFields? }` | The data-bound picker (products, agents) |
-| `{ type: "custom", render: ({value, onChange}) => JSX }` | Fully custom inspector widget |
-| `{ type: "slot" }` | A droppable zone inside a block (DropZone) |
-
-### External field — the data-bound picker
-
-Used for `ProductBlock`, `ListBlock`, and any block that binds to live workspace data:
+| Type | Uses | Usage |
+|---|---|---|
+| `{ type: "text" }` | 421 | Single-line text input; `contentEditable?: true` for inline editing on canvas |
+| `{ type: "radio", options: [{label, value}] }` | 111 | Radio group — the repo's boolean toggle |
+| `{ type: "textarea" }` | 74 | Multi-line text |
+| `{ type: "array", arrayFields: {…}, getItemSummary?, min?, max? }` | 50 | Repeating sub-items (feature rows, CTA lists) |
+| `{ type: "number", min?, max?, step? }` | 27 | Numeric |
+| `{ type: "select", options: [{label, value}] }` | 24 | Dropdown |
+| `{ type: "custom", render: ({value, onChange}) => JSX }` | 9 | Custom inspector widget — **how ONE does every picker** |
+| `{ type: "slot" }` | 7 | A droppable zone inside a block |
+| `{ type: "object", objectFields: {…} }` | 3 | Nested group |
+| `{ type: "external", fetchList, mapProp?, showSearch? }` | 2 | Puck's built-in remote picker — rarely used here |
+| `{ type: "richtext" }` | 1 | Rich text with Tiptap |
+
+### Custom field — how ONE builds a picker
+
+ONE does **not** use Puck's `external` field for workspace data. Pickers are
+`type: 'custom'` wrapping a lazy-loaded React field, so the field's browser deps
+stay out of the SSR worker bundle. `config.tsx` lazy-imports four of them:
+`RecordPickerField`, `TypeBindingField`, `ViewQueryField`, `BrandColorField`.
 
-```ts
-import type { ExternalField } from "@puckeditor/core";
-
-const productPickerField: ExternalField = {
-  type: "external",
-  placeholder: "Search products…",
-  showSearch: true,
-  fetchList: async ({ query }) => {
-    const res = await fetch(`/api/ask`, {
-      method: "POST",
-      body: JSON.stringify({ receiver: "products:list", data: { query } }),
-    });
-    const { result } = await res.json();
-    return result?.items ?? [];
-  },
-  mapProp: (item) => ({ productId: item.id, name: item.name, price: item.price }),
-  mapRow: (item) => ({ Name: item.name, Price: `$${item.price}` }),
-};
+```tsx
+const RecordPickerField = lazy(() =>
+  import('@/components/puck/RecordPickerField').then((m) => ({ default: m.RecordPickerField }))
+);
+
+// inside a block's fields:
+productId: {
+  type: 'custom' as const,
+  render: ({ value, onChange }: { value: string; onChange: (v: string) => void }) => (
+    <Suspense
+      fallback={
+        <input
+          type="text"
+          value={value ?? ''}
+          onChange={(e) => onChange(e.target.value)}
+          style={{ width: '100%', padding: '4px' }}
+        />
+      }
+    >
+      <RecordPickerField value={value ?? ''} onChange={onChange} />
+    </Suspense>
+  ),
+},
 ```
 
+The `Suspense` fallback must be a working plain input — the editor is usable
+while the field chunk loads.
+
+Server-side, `lib/puck/pickable-records.ts` turns a bound resolver's list result
+into flat `{ id, label }[]` for the picker. It resolves the receiver from the
+binding (`boundReceiver(rt, 'list')`), calls it with a **public** caller context,
+and reads the plural key by convention — `'product'` → `result.products`.
+
 ---
 
 ## `Data` shape (the stored IR)
@@ -148,13 +191,28 @@ type Data = {
 };
 
 // An empty page
-const emptyData: Data = { root: { props: {} }, content: [] };
+const emptyData: Data = { root: {}, content: [] };
 ```
 
+`root` is `{}` in every value this repo constructs (`migrate.ts`, `normalize.ts`,
+`templates.ts`) — not `{ props: {} }`. Both satisfy the type; match the repo.
+
 **Where ONE stores it:**
 - Landing pages: `pages.data` column (D1) — row written by `pages:create` / `pages:edit`
 - Funnel steps: `funnel_definitions.steps[N].config.puck` (JSON column)
-- Newsletters (sweep C7): `broadcast.data` column
+
+### normalizePuckData — always run it on load
+
+Puck merges `defaultProps` at **render** time only; it never writes them back into
+the data. A block loaded from storage with sparse props renders its defaults on
+the canvas but shows *empty* inspector fields. `lib/puck/normalize.ts` closes that
+gap — stored props always win over defaults:
+
+```ts
+import { normalizePuckData } from '@/lib/puck/normalize';
+
+const data = normalizePuckData(JSON.parse(row.data));
+```
 
 ---
 
@@ -163,74 +221,82 @@ const emptyData: Data = { root: { props: {} }, content: [] };
 The editor must be `client:only` because Puck requires browser APIs. Use the `Puck` component from `@puckeditor/core`:
 
 ```tsx
-// one.ie/web/src/components/puck/PuckEditor.tsx
-"use client"; // Astro will ignore this; the client:only directive handles it
-import { Puck } from "@puckeditor/core";
-import "@puckeditor/core/puck.css";
-import { puckConfig } from "@/lib/puck/config";
-import type { Data } from "@puckeditor/core";
+// one.ie/web/src/components/puck/PuckEditor.tsx — the real imports
+// @ts-ignore — puck.css has no type declarations but the import is valid at runtime
+import '@puckeditor/core/puck.css'
+import './puck-theme.css'
+import { Puck, usePuck, type Data } from '@puckeditor/core'
+import { puckConfig } from '@/lib/puck/config'
+import { normalizePuckData } from '@/lib/puck/normalize'
+import { computeStyleBlock, type SiteToken } from '@/lib/site'
+```
 
-interface Props {
-  initialData: Partial<Data>;
-  onPublish: (data: Data) => Promise<void>;
-}
+The real component takes ~24 props, not two — `data`, `siteTokens`,
+`siteDarkTokens`, `onChange`, `onPublish`, `workspace`, `pageSlug`, `title`,
+`pageStatus`, `saved`, `error`, `publishing`, `customDomain`, `target = 'web'`,
+and the toolbar/drawer callbacks. Read the `interface Props` before adding one.
 
-export function PuckEditor({ initialData, onPublish }: Props) {
-  return (
-    <Puck
-      config={puckConfig}
-      data={initialData}
-      onPublish={onPublish}
-      // Optional: inject brand tokens into the editor iframe
-      iframe={{ enabled: true }}
-    />
-  );
-}
-```
+Mounted in Astro as `client:only="react"` — Puck needs browser APIs and cannot
+SSR:
 
-Mounted in Astro as:
 ```astro
-<PuckEditor client:only="react" initialData={data} onPublish={handlePublish} />
+<PuckEditor client:only="react" data={data} siteTokens={tokens} pageSlug={slug} />
 ```
 
 ### Brand injection into the iframe
 
-The editor canvas runs in a sandboxed `<iframe>` — Tailwind 4 globals and workspace CSS tokens do **not** cascade in by default. Inject them via `computeStyleBlock` from `lib/site.ts`:
+The editor canvas runs in a sandboxed `<iframe>` — Tailwind 4 globals and the
+workspace's 6 brand tokens do **not** cascade in. Puck's `overrides.iframe`
+receives the live `contentDocument`, which is the first-class injection point.
+This is shipped in `PuckEditor.tsx`:
 
 ```tsx
-import { useEffect } from "react";
-import { computeStyleBlock } from "@/lib/site"; // (tokens, darkTokens?, font?) → CSS rule text (:root{--color-*}), goes in a <style>.textContent (site.ts:59)
-import { Puck } from "@puckeditor/core";
-
-// VERIFIED against @puckeditor/core@0.21 source: the `iframe` OVERRIDE receives the real
-// iframe contentDocument (AutoFrame/index.tsx:420). This is the first-class injection API —
-// no portal, no hack. `overrides.iframe: RenderFunc<{ children; document? }>`.
-const overrides = {
-  iframe: ({ children, document }: { children: React.ReactNode; document?: Document }) => {
-    useEffect(() => {
-      if (!document?.head) return;
-      const el = document.createElement("style");
-      el.setAttribute("data-one-brand", "");
-      el.textContent = computeStyleBlock(tokens, darkTokens, font); // tokens/darkTokens: Partial<Record<SiteToken,string>>, font?: string — passed into PuckEditor as workspace-branding props
-      document.head.appendChild(el);
-      return () => el.remove();
-    }, [document]);
-    return <>{children}</>;
-  },
-};
-
 <Puck
   config={puckConfig}
-  data={initialData}
-  onPublish={onPublish}
-  iframe={{ enabled: true }}     // IframeConfig: { enabled?, waitForStyles?, syncHostStyles? }
-  overrides={overrides}
+  data={normalizePuckData(data)}
+  overrides={{
+    iframe: ({ children, document: iframeDoc }: {
+      children: React.ReactNode;
+      document?: Document;
+    }) => {
+      // Inject the workspace's 6-token brand CSS into the editor iframe so the
+      // canvas paints in the tenant's colors, not the platform default.
+      useEffect(() => {
+        if (!iframeDoc || !siteTokens) return;
+        const style = iframeDoc.createElement('style');
+        style.textContent = computeStyleBlock(siteTokens);
+        iframeDoc.head.appendChild(style);
+        return () => style.remove();
+      }, [iframeDoc]);
+      return <>{children}</>;
+    },
+  }}
 />
 ```
 
-**Pre-mortem guard (verified step, not an open risk):** the `iframe` override is the documented injection point (`apps/puckeditor/apps/docs/.../overrides/iframe.mdx` — "useful for injecting styles"). W4 asserts a `<style data-one-brand>` lands in the iframe `<head>` and a `--color-*` var resolves inside the canvas. First confirm `computeStyleBlock`'s real arg signature at `site.ts:59`.
+Rename the destructured `document` — shadowing the global inside a React
+component breaks any sibling code that expects the real one.
+
+`computeStyleBlock` (`lib/site.ts:59`) has the signature:
+
+```ts
+computeStyleBlock(
+  tokens: Partial<Record<SiteToken, string>>,
+  darkTokens: Partial<Record<SiteToken, string>> = {},
+  font?: string,
+): string
+```
+
+It emits `:root:not(.dark) { … }` and `:root.dark { … }` rules — both at
+specificity (0,2,0), so they beat `Layout.astro`'s `:root` / `html.dark` defaults
+regardless of where the bundler places them, and stored light values can never
+leak into dark mode. It also derives `--color-on-{primary,secondary,tertiary}`
+contrast labels for each brand fill. `PuckEditor` calls it with one argument.
 
-**Tailwind 4 guard:** Tailwind 4 uses `--color-*: initial` wipes at the `:root` level. Scope `@puckeditor/core/puck.css` to the editor chrome class only (e.g. `.puck-editor`). The renderer must import **no** Puck CSS.
+**Tailwind 4 guard:** `Layout.astro` declares `--color-*: initial`, wiping the
+default palette. Puck's own CSS is scoped by importing it *only* in
+`PuckEditor.tsx` (a `client:only` island) alongside the local `puck-theme.css`
+overrides. The renderer imports **no** Puck CSS.
 
 ---
 
@@ -252,21 +318,25 @@ Note the column split: the channels `edit_page`/`create_page` tools write the `p
 No editor chrome, no editor JS shipped to visitors. Pure server-side render via `<Render>`:
 
 ```tsx
-// one.ie/web/src/components/puck/PuckRenderer.tsx
-import { Render } from "@puckeditor/core";
-import { puckConfig } from "@/lib/puck/config";
-import type { Data } from "@puckeditor/core";
+// one.ie/web/src/components/puck/PuckRenderer.tsx — the whole file
+// SSR-safe. NO puck.css import (pulls editor chrome into SSR bundle).
+// NO import of PuckEditor (client:only). Renders published Puck data server-side.
+import { Render, type Data } from '@puckeditor/core'
+import { puckConfig } from '@/lib/puck/config'
 
 interface Props {
-  data: Data;
+  data: Data
 }
 
 export function PuckRenderer({ data }: Props) {
-  // Render is fully SSR-safe — no browser APIs, no editor state
-  return <Render config={puckConfig} data={data} />;
+  if (!data || !data.content || data.content.length === 0) return null
+  return <Render config={puckConfig} data={data} />
 }
 ```
 
+The empty-content guard matters: `<Render>` on an empty `content` array emits a
+bare wrapper div that breaks page layout. Return `null` and let the caller decide.
+
 Used in Astro routes:
 ```astro
 ---
@@ -286,115 +356,219 @@ const data = JSON.parse(page.data); // from D1
 
 ## ONE's block registry (`lib/puck/config.tsx`)
 
-All blocks live in one export: `puckConfig`. The file declares:
-- **7 structural blocks:** `Heading`, `Text`, `Image`, `Button`, `Form`, `Columns`, `Spacer`
-- **9 CRO blocks (migrated 1:1):** `LandingHero`, `ProofBar`, `HowItWorks`, `LandingFeatures`, `Testimonials`, `ComparisonTable`, `PricingSection`, `FAQSection`, `SecondaryCTA`
-- **2 funnel widgets:** `CheckoutBlock` (wraps `PayPanel`), `UpsellBlock`
-- **2 data-bound blocks (sweep):** `ProductBlock`, `ListBlock`
+All blocks reach the editor through one export: `puckConfig`. The groups it merges:
+
+> **No counts here on purpose.** Every number this section ever carried went stale
+> within days — the registry grows constantly. To count, read `puckConfig.components`;
+> `buildBlockIndex` gives you the list without loading `config.tsx`.
+
+| Group | Declared in |
+|---|---|
+| `blocks` | `config.tsx` — structural, CRO, funnel, media, layout |
+| `generalNewBlocks` | `general-{a,b,c}-blocks.tsx` |
+| `ecommerceNewBlocks` | `ecommerce-{discover,evaluate-a,evaluate-b,persuade-a,persuade-b,convert,support}-blocks.tsx` |
+| `socialFormatBlocks` | `social-format-blocks.tsx` |
+| `socialBlocks` | `config.tsx` |
+| `authBlocks` | `config.tsx` |
+| `dataBlocks` | `config.tsx` |
+| `appBlocks` | `config.tsx` |
+| `studioBlocks` | `config.tsx` |
+| `aiBlocks` | `ai-blocks.tsx` |
+| `walletBlocks` | `config.tsx` |
+| `teamFlowBlocks` | `config.tsx` |
+
+Two subsets are pinned by `tests/unit/puck/config.test.ts` and must never
+regress — the **7 structural** blocks (`Heading`, `Text`, `Image`, `Button`,
+`Form`, `Columns`, `Spacer`) and the **9 CRO** blocks (`LandingHero`, `ProofBar`,
+`HowItWorks`, `LandingFeatures`, `Testimonials`, `ComparisonTable`,
+`PricingSection`, `FAQSection`, `SecondaryCTA`). The test asserts each is defined,
+has a `render` function, and carries `metadata.targets` containing `'web'`.
+
+For a live count or a palette search, use `buildBlockIndex(puckConfig)` from
+`lib/puck/block-index.ts` — a pure function with no DOM or Puck-runtime import,
+so it is trivially testable.
 
 Each CRO block wraps the existing component from `one.ie/web/src/components/cro/`:
 
 ```tsx
 import { LandingHero as LandingHeroComponent } from "@/components/cro/LandingHero";
-import type { Config } from "@puckeditor/core";
+import { bgTokenField, bgPatternField } from "@/lib/puck/bg-fields";
 
-// In puckConfig.components:
+// In one of the 12 block groups:
 LandingHero: {
-  label: "Landing Hero",
+  metadata: { surface: 'section', semantics: {}, ...web, category: 'cro',
+              icon: 'Rocket', description: 'Hero with headline and dual CTA' },
   fields: {
-    headline:     { type: "text" },
-    highlight:    { type: "text" },
-    subhead:      { type: "text" },
-    eyebrow:      { type: "text" },
-    frictionText: { type: "text" },
+    bgToken:      bgTokenField,
+    bgPattern:    bgPatternField,
+    headline:     { type: 'text' as const },
+    highlight:    { type: 'text' as const },
+    subhead:      { type: 'text' as const },
+    eyebrow:      { type: 'text' as const },
+    frictionText: { type: 'text' as const },
     primaryCta:   {
-      type: "object",
+      type: 'object' as const,
       objectFields: {
-        label: { type: "text" },
-        href:  { type: "text" },
-      }
+        label: { type: 'text' as const },
+        href:  { type: 'text' as const },
+      },
     },
     secondaryCta: {
-      type: "object",
+      type: 'object' as const,
       objectFields: {
-        label: { type: "text" },
-        href:  { type: "text" },
-      }
+        label: { type: 'text' as const },
+        href:  { type: 'text' as const },
+      },
     },
   },
   defaultProps: {
-    headline: "Your headline here",
-    subhead: "Your sub-headline here",
-    primaryCta: { label: "Get started", href: "#" },
+    headline: 'Your headline here',
+    subhead: 'Your sub-headline here',
+    primaryCta: { label: 'Get started', href: '#' },
   },
   render: (props) => <LandingHeroComponent {...props} />,
 },
 ```
 
-**Reuse contract:** CRO components are **never reimplemented** inside the block — they are always imported and wrapped. `wc -l` of `config.tsx` must stay reasonable; blocks are thin wrappers.
+`bgTokenField` and `bgPatternField` (`lib/puck/bg-fields.tsx`) are the shared
+background-token and pattern fields every themeable block reuses — import them,
+never redeclare a background field inline.
+
+**Reuse contract:** CRO components are **never reimplemented** inside the block —
+they are always imported and wrapped. Blocks are thin wrappers; the component
+lives in `components/cro/`, `components/booking/`, `components/auth/`, etc.
 
-### Per-block target field (planned, C1 stubs it)
+### Per-block target — `metadata.targets`
 
-Each block declares which render targets it supports. This gates the email palette in C7:
+Each block declares which render targets it supports, which is what filters the
+palette when the editor runs in a non-web `target` mode. This is shipped, and
+`config.test.ts` asserts every structural and CRO block carries `'web'`.
 
 ```ts
-// VERIFIED: Puck's ComponentConfig REJECTS unknown sibling keys (0.21 type is strict —
+// Puck's ComponentConfig REJECTS unknown sibling keys (the 0.21 type is strict —
 // render/label/defaultProps/fields/permissions/inline/resolveFields/resolveData/metadata).
-// `targets` is NOT a bare sibling — it lives under the supported `metadata` key:
-const block = {
-  label: "Heading",
-  metadata: { targets: ["web"] },   // future: ["web", "email"] for email-capable blocks
-  fields: { … },
+// `targets` is NOT a bare sibling — it lives under the supported `metadata` key.
+// config.tsx spreads a shared `web` const rather than repeating the literal:
+const web = { targets: ['web'] };
+
+Heading: {
+  // `surface` and `semantics` are not optional — see § The chrome contract.
+  metadata: { surface: 'atomic', semantics: { heading: 'text' }, ...web,
+              category: 'content', icon: 'Type', description: 'Section heading' },
+  fields: { /* … */ },
   render: (props) => <…/>,
 };
 ```
 
-The editor reads `block.metadata.targets` when filtering the palette for `target:'email'` mode (newsletter composer). `metadata` is the supported channel for any ONE-specific block flag — never add bare keys to a Puck component config.
+`metadata` is the supported channel for any ONE-specific block flag — never add
+bare keys to a Puck component config.
+
+### The chrome contract (every block, no exceptions)
+
+`tests/unit/blocks-enhance.test.ts` iterates `puckConfig` and fails the build if a
+block skips either key. It is the reason a new block gets themeable for free.
+
+**`surface`** — how much chrome the block may carry:
+
+| Surface | Carries |
+|---|---|
+| `section` | background colour + texture + auto-contrast |
+| `container` | background colour + auto-contrast; texture optional |
+| `atomic` | text colour only — a fill on a Spacer is a bug |
+| `social-preview` | images only, **never** a brand fill (a tweet card painted `--color-tertiary` stops being a tweet card) |
+| `app` | images only |
+
+A `section` must expose both `bgToken: bgTokenField` and `bgPattern: bgPatternField`;
+a `container` must expose `bgToken`. `withChrome` paints them — do not read `bgToken`
+in your render unless you also add the block to `SELF_CHROME`.
+
+**`semantics`** — maps canonical roles to this block's own prop names,
+`{ heading, body, cta, image }`. It exists because `genericEmailNode` was guessing
+across ~20 aliases. Name only props that exist; a path (`testimonials[].avatar`) is
+fine. `{}` is the honest answer for a Spacer.
+
+**Contrast is never re-derived.** Import from `lib/puck/surface-chrome.ts`
+(`surfaceChrome`, `onText`, `ON_TEXT`). The `on-*` classes must be **static strings** —
+`text-on-${token}` compiles to nothing, which is exactly how text ends up the same
+colour as the fill beneath it.
+
+**Image fields** use the shared `imageSrcField` (`lib/puck/image-field.tsx`) so the
+media library and R2 upload come for free. `src` means an image in `Image`,
+`ImageBlock`, `PortfolioSection`, `LogoGridBlock`; in `VideoEmbed` and `MapEmbed` it is
+an embed URL and stays a text box.
+
+**Your defaultProps must render.** `blocks-enhance-ssr.test.ts` renders every fillable
+block through `PuckRenderer` on a brand fill, with no exclusions — a block that crashes
+on its own defaults fails there.
 
 ---
 
-## Data-bound blocks (`resolveData`)
+## Data-bound blocks (`resolve-bindings`, not `resolveData`)
+
+ONE does **not** use Puck's `resolveData` hook. A data-bound block stores only an
+**id**, and `resolvePageBindings` (`lib/puck/resolve-bindings.ts`) resolves it
+server-side before render, injecting the live record as `_resolved`. The block's
+`render` stays synchronous and never fetches.
 
-A block that renders live workspace data (products, lists) uses Puck's `resolveData` hook to fetch on insert/load:
+Three moving parts:
+
+1. **The field** stores the id — `type: 'custom'` + `RecordPickerField` (see
+   § Custom field above).
+2. **`resolve-bindings.ts`** walks `data.content` server-side, looks the id up
+   through the workspace's binding manifest, and writes `_resolved` into props.
+3. **`render`** reads `_resolved`, with the bare id as the fallback stub.
 
 ```tsx
+import type { PriceRow } from '@/lib/storefront'
+
+// ProductBlock is data-bound. resolvePageBindings resolves `productId` through the
+// commerce binding server-side and injects the live product as `_resolved`; absent
+// it (unbound id, or not published) the block falls back to the id stub.
 ProductBlock: {
-  label: "Product",
+  metadata: { surface: 'section', semantics: {}, ...web, category: 'ecommerce',
+              icon: 'Package', description: 'Data-bound product display' },
   fields: {
-    product: {
-      type: "external",
-      placeholder: "Pick a product…",
-      showSearch: true,
-      fetchList: async ({ query }) => {
-        const r = await fetch("/api/ask", {
-          method: "POST",
-          body: JSON.stringify({ receiver: "products:list", data: { query, limit: 20 } }),
-        });
-        const { result } = await r.json();
-        return result?.items ?? [];
-      },
-      mapProp: (item) => item,  // store the whole record
+    bgToken: bgTokenField,
+    bgPattern: bgPatternField,
+    productId: {
+      type: 'custom' as const,
+      render: ({ value, onChange }: { value: string; onChange: (v: string) => void }) => (
+        <Suspense fallback={<input type="text" value={value ?? ''}
+          onChange={(e) => onChange(e.target.value)} style={{ width: '100%', padding: '4px' }} />}>
+          <RecordPickerField value={value ?? ''} onChange={onChange} />
+        </Suspense>
+      ),
     },
-    showPrice:  { type: "radio", options: [{ label: "Yes", value: true }, { label: "No", value: false }] },
-    showButton: { type: "radio", options: [{ label: "Yes", value: true }, { label: "No", value: false }] },
   },
-  defaultProps: { product: null, showPrice: true, showButton: true },
-  render: ({ product, showPrice, showButton }) => {
-    if (!product) return <div className="text-muted-foreground text-sm p-4">Pick a product in the inspector.</div>;
+  defaultProps: { productId: '' },
+  render: ({ productId, _resolved }: {
+    productId: string
+    _resolved?: { name: string; description: string | null; images: string; prices: PriceRow[] }
+  }) => {
+    if (!_resolved) return <div className="text-font/60 text-sm p-4">Pick a product in the inspector.</div>;
     return (
-      <div className="rounded-lg border p-6">
-        <h3 className="font-semibold">{product.name}</h3>
-        {showPrice && <p className="text-font/60">${product.price}</p>}
-        {showButton && <button className="btn-primary mt-4">Buy</button>}
+      <div className="rounded-lg border p-6" style={{ borderColor: 'var(--color-border)' }}>
+        <h3 className="font-semibold text-font">{_resolved.name}</h3>
+        <p className="text-font/60">{_resolved.description}</p>
       </div>
     );
   },
 },
 ```
 
-> **C6 dependency:** `products:get` (read one product by ID) does not exist yet — only `products:list`. Until C6 lands, `ProductBlock` falls back to `products:list` + local filter. Never make N+1 list calls per block.
->
-> **⚠ Shape correction (verified against `lib/resolvers/commerce.ts:73`):** the `fetchList` examples above are illustrative but wrong on the wire shape. `products:list` takes **`{ slug }`** (the workspace) and returns **`{ products: ProductWithPrices[] }`** — NOT `{ query }` / `{ items }`. There is **no server-side `query` filter** yet, so fetch the workspace's products once and filter client-side. Fix before C6: `const { result } = await r.json(); return (result?.products ?? []).filter(p => p.name.toLowerCase().includes(query.toLowerCase()))`.
+`RecordBlock` is the generic counterpart: any manifest-declared bound type renders
+through it, keyed by `typeKey` (matching the manifest entry) plus `recordId`.
+
+**Wire shapes** (`lib/resolvers/commerce.ts`) — both receivers exist:
+
+| Receiver | In | Out |
+|---|---|---|
+| `products:list` | `{ slug }` | `{ products: ProductWithPrices[] }` |
+| `products:get` | `{ slug, pid }` | `{ product: ProductWithPrices \| null }` |
+
+There is no server-side `query` filter on `products:list` — the picker fetches the
+workspace's products once and filters client-side. Never make an N+1 call per block:
+resolution is one server-side pass over the whole page, not one fetch per block.
 
 ---
 
@@ -417,73 +591,101 @@ function MyCustomField({ value, onChange }) {
 
 ## Migration (`components[]` → Puck `Data`)
 
-C3 migrates existing `pages.components` rows (the old `{component, props}[]` shape) to Puck `Data`. The transform is 1:1 because block `type` names match the old `component` names exactly:
+`pages.components` (the legacy `PageSection[]` shape) converts to Puck `Data` 1:1,
+because block `type` names match the old `component` names exactly. One source of
+truth, used on both the write path (`resolvers/pages.ts` dual-write) and the read
+path (`/p/[slug].astro` lazy-migrate):
 
 ```ts
-// one.ie/web/src/lib/puck/migrate.ts
-import type { Data } from "@puckeditor/core";
-
-type LegacySection = { component: string; props: Record<string, unknown> };
+// one.ie/web/src/lib/puck/migrate.ts — the whole file
+import type { Data } from '@puckeditor/core'
+import type { PageSection } from '@/lib/pages'
 
-export function componentsToPuck(sections: LegacySection[]): Data {
+export function componentsToPuck(sections: PageSection[]): Data {
   return {
-    root: { props: {} },
     content: sections.map((s, i) => ({
-      type: s.component,                     // e.g. "LandingHero" — 1:1 name match
-      props: { ...s.props, id: `migrated-${i}` },
+      type: s.component,
+      props: { ...s.props, id: `${s.component}-${i}` },
     })),
-  };
+    root: {},
+  } as unknown as Data
 }
 ```
 
-**Migration gate (C3 W4):** row-count parity — `pages` rows must equal rows with non-null `pages.data` before deleting `PageRenderer.tsx`. The `components` column is kept for one release as a rollback.
+Two details that are easy to get wrong: the id is `${s.component}-${i}`
+(deterministic per position, so a re-migration is idempotent), and the `as unknown
+as Data` cast is deliberate — `ComponentData` requires an `id` that the mapped
+literal cannot prove structurally.
+
+Both columns still exist. The chat tools (`edit_page` / `create_page`) write
+`pages.components`; manual Puck edits write `pages.data`.
 
 ---
 
-## Starter templates (C5)
+## Starter templates
 
-Seed `Data` objects that make the first page one click. Store in `lib/puck/templates.ts`:
+Seed `Data` skeletons that make the first page one click, in
+`lib/puck/templates.ts`. The export is **`funnelTemplates: PuckTemplate[]`** — an
+array, not a keyed record:
 
 ```ts
-import type { Data } from "@puckeditor/core";
-
-export const OPT_IN_TEMPLATE: Data = {
-  root: { props: {} },
-  content: [
-    { type: "LandingHero", props: { id: "hero", headline: "Get early access", subhead: "…", primaryCta: { label: "Join", href: "#" } } },
-    { type: "Form",        props: { id: "form", submitLabel: "Join waitlist", receiver: "funnel:advance" } },
-  ],
-};
+export interface PuckTemplate {
+  id: string;
+  name: string;
+  description: string;
+  // Static skeleton — applied instantly on click so the canvas is never blank.
+  data: PuckData;
+  // Sent to the chat on click; the model streams a complete, richly-filled
+  // version of this page back as Puck JSON, replacing the skeleton.
+  prompt: string;
+}
 
-export const TEMPLATES: Record<string, { label: string; data: Data }> = {
-  "opt-in":  { label: "Opt-in",  data: OPT_IN_TEMPLATE },
-  "sales":   { label: "Sales",   data: SALES_TEMPLATE },
-  "thanks":  { label: "Thank you", data: THANKS_TEMPLATE },
-  "webinar": { label: "Webinar", data: WEBINAR_TEMPLATE },
-};
+export const funnelTemplates: PuckTemplate[] = [
+  { id: 'opt-in', name: '…', description: '…', data: { content: [...], root: {} }, prompt: '…' },
+  // …
+];
 ```
 
+The `prompt` field is the important half: a template is a skeleton **plus** an AI
+instruction, not a finished page. `PuckEditor` imports `funnelTemplates` directly.
+
 ---
 
-## Email target mode (sweep C7)
+## Email target mode
+
+The editor runs in `target: 'web' | 'email'`, defaulting to `'web'`. `PuckEditor`
+takes `target` as a prop and publishes it through `PuckTargetContext`
+(`components/puck/puck-target-context.ts`) so `BlockPalette` — rendered inside
+`overrides.drawer`, where there is no prop path — can filter by
+`metadata.targets`.
 
-When composing a newsletter, the editor runs in `target:'email'` mode:
-- **Palette filtered** — only blocks with `targets.includes('email')` appear
-- **Canvas width** — fixed 600px (email-client safe)
-- **Serializer** — `broadcast/render.ts` reads the same Puck `Data` but emits table-based, inline-styled HTML with `safeUrl` scheme-allowlisting and `/go/:id` tracking
+```tsx
+import { PuckTargetContext, usePuckTarget } from '@/components/puck/puck-target-context';
+
+// In PuckEditor: <PuckTargetContext.Provider value={target}>…</PuckTargetContext.Provider>
+// In BlockPalette:
+const target = usePuckTarget();  // 'web' | 'email'
+```
 
-A block gains email support by adding an `email` impl to its block registration in `config.tsx`:
+A block opts into the email palette by spreading the shared `emailTarget` const
+instead of `web`:
 
 ```ts
-// Conceptual (C7 shape — not in C1):
+// config.tsx
+const web = { targets: ['web'] as const };
+const emailTarget = { targets: ['web', 'email'] as const };
+
 Heading: {
-  targets: ["web", "email"],
-  emailRender: (props) => `<h2 style="font-size:24px;font-weight:700">${props.text}</h2>`,
-  // ... standard Puck fields and render
-}
+  metadata: { ...emailTarget, category: 'content', icon: 'Type', description: '…' },
+  fields: { /* … */ },
+  render: (props) => <…/>,
+},
 ```
 
-**Email rendering is never done via React DOM `renderToString`** — that produces flexbox HTML that breaks in Gmail. The email serializer is a separate function that walks the `Data.content` array and calls each block's `emailRender()`.
+**Email rendering is never done via React DOM `renderToString`** — that produces
+flexbox HTML that breaks in Gmail. `lib/broadcast/render.ts` is a separate
+serializer emitting table-based, inline-styled HTML with `safeUrl` scheme
+allowlisting and `/go/:id` tracking.
 
 ---
 
@@ -492,24 +694,28 @@ Heading: {
 | Target | Renderer | Input | Output | ONE path |
 |---|---|---|---|---|
 | **Web** | `<Render>` (Puck SSR) | Puck `Data` | React → flexbox HTML | `PuckRenderer.tsx` |
-| **Email** | `broadcast/render.ts` serializer | Puck `Data` | Table-based, inline-style HTML | C7 (sweep) |
-| **Data** | `lib/data-bindings.ts` + `ResourceType` | `{type, id|filter}` | Live workspace rows | C6 (sweep) |
+| **Email** | `broadcast/render.ts` serializer | Puck `Data` | Table-based, inline-style HTML | `lib/broadcast/` |
+| **Data** | `lib/data-bindings.ts` + `ResourceType` | `{type, id\|filter}` | Live workspace rows | `lib/puck/resolve-bindings.ts` |
 
 Do not force email through React or web through the email serializer — they are separate, intentional.
 
 ---
 
-## Kill-switch (the plan's exit criterion)
+## Kill-switch
 
 ```bash
-# Exits 0 only when the core (C1–C5) is complete:
+# All three legs are green as of 2026-08-02:
 grep -q '@puckeditor/core' one.ie/web/package.json \
   && test -f one.ie/web/src/lib/puck/config.tsx \
   && ! test -f one.ie/web/src/components/cro/PageRenderer.tsx \
   && (cd one.ie/web && bun vitest run tests/unit/puck/)
 ```
 
-Note: `@puckeditor/core` is canonical across the funnels-pages doc set (synced 2026-06-22); `@measured/puck`@0.20.x is the superseded upstream name.
+`tests/unit/puck/` holds 16 spec files — `config.test.ts` pins the structural and
+CRO block sets; the rest cover the block packs, bindings, migration, and restore.
+
+Note: `@puckeditor/core` is canonical across the funnels-pages doc set;
+`@measured/puck`@0.20.x is the superseded upstream name.
 
 ---
 
@@ -519,7 +725,6 @@ ONE does **not** use Puck's hosted cloud service or any Puck-managed storage. Th
 
 - `pages:create` / `pages:edit` — landing pages → `pages.data`
 - `funnel:update-step` — funnel step pages → `funnel_definitions.steps[N].config.puck`
-- `broadcast:update` (C7) — newsletters → `broadcast.data`
 
 The `onPublish` callback in `<Puck>` calls ONE's own `/api/ask` endpoint:
 
@@ -547,9 +752,12 @@ Do not use `resolveAllData` with external Puck cloud endpoints. All data resolut
 | Use Puck cloud / puckeditor.com hosted backend | ONE stores all page data in its own D1 via receivers | No `/puck/api` route; `onPublish` must call `/api/ask` |
 | Import `@puckeditor/core/puck.css` in `PuckRenderer` or any Astro layout | Puck chrome styles bleed into visitor pages | Grep: `puck.css` appears only in `PuckEditor.tsx` |
 | Set `prerender:true` on any `/p/` or `/f/` route | astro#16529: two React copies crash the page | All Puck routes must have `export const prerender = false` |
-| Reimplement CRO components inside block `render` fns | They already exist in `components/cro/`; re-registration is a thin wrapper | `wc -l config.tsx` gate + named import grep |
+| Reimplement a component inside a block `render` fn | It already exists in `components/cro/`, `components/booking/`, etc.; the block is a thin wrapper | Named-import grep |
+| Add a bare key beside `fields` in a block config | The 0.21 `ComponentConfig` type is strict and rejects it | Everything ONE-specific goes under `metadata` |
+| Omit `as const` on a field `type` | TS widens the literal to `string` and `Fields` rejects the object | `bun run typecheck` |
 | Trust `body.actorId` or `body.slug` in receiver resolvers | IDOR — use `ctx.ownerSlug` (attested) only | `authorizeWorkspace(locals, slug, db)` on every media/page write route |
-| Fetch live data on every `render()` call | N+1 — use `resolveData` or the binding resolver | No `fetch` inside block `render` fns; data-bound blocks use `resolveData` or the `external` field |
+| Fetch live data inside a block `render()` | N+1 — the page is resolved in one server-side pass | No `fetch` in a `render` fn; use `resolve-bindings.ts` + `_resolved` |
+| Use a hex or a Tailwind palette class in a block | `rules/design.md` auto-loads here; the palette is wiped so it emits no CSS | `hook:design-check` blocks the edit |
 | Merge Puck with the Workflow (ReactFlow) canvas | Different substrates: pages = layout tree, workflows = signal DAG | `lib/puck/` and `lib/workflow*/` must stay separate |
 
 ---
@@ -558,11 +766,18 @@ Do not use `resolveAllData` with external Puck cloud endpoints. All data resolut
 
 1. **Read the plan** — `text/funnels-pages-plan.md` (architecture + pre-mortem table)
 2. **Run the kill-switch** to see current state before editing
-3. **Check the block registry** — `lib/puck/config.tsx` for what exists (don't reimplement)
-4. **Check `components/cro/`** — the 9 CRO components are sources, not blocks; import them
-5. **Check migration number** — `one.ie/web/migrations/` highest number before creating a new SQL file
-6. **Keep all Puck routes `prerender:false`**
-7. **Scope `puck.css` to the editor component only**
-8. **authorizeWorkspace on every write route** (IDOR guard from `lib/analytics/authz.ts`)
-9. **Put vitest files in `tests/unit/puck/`** — not in `src/` (web vitest only discovers `tests/**`)
-10. **Run via `bun vitest run`** (not `bunx vitest`) — uses the local binary
+3. **Search the registry first** — the block you want probably exists. `buildBlockIndex` +
+   `searchBlocks` (`lib/puck/block-index.ts`) answer "does this block exist?"
+   without loading `config.tsx`
+4. **Pick the right group** — a new block joins an existing group; never add a
+   13th top-level spread
+5. **Import, don't reimplement** — the component lives in `components/`
+6. **Give it full `metadata`** — `category`, `icon`, `description`, and a
+   `targets` spread (`...web` or `...emailTarget`); the palette and the block
+   index both read it
+7. **Check migration number** — `one.ie/web/migrations/` highest number before creating a new SQL file
+8. **Keep all Puck routes `prerender:false`**
+9. **Scope `puck.css` to `PuckEditor.tsx` only**
+10. **authorizeWorkspace on every write route** (IDOR guard from `lib/analytics/authz.ts`)
+11. **Put vitest files in `tests/unit/puck/`** — not in `src/` (web vitest only discovers `tests/**`)
+12. **Run via `bun vitest run`** (not `bunx vitest`) — uses the local binary