@wocart/theme 2.2.0 → 3.0.0

package/README.md

@@ -2,26 +2,14 @@
 
 The theme contract for [Wocart](https://github.com/bighadj22/codflow)
 storefronts. A theme declares its components in code — real `.astro`
-components, wrapped with typed, editable fields — and a store's pages are saved
-as JSON documents that reference them. This package validates both sides,
-resolves a saved document against the theme, and renders it with a reference
-Astro renderer.
+components with typed, editable fields — and a store's pages are saved as JSON
+documents that reference them. This package validates both, resolves a saved
+document against the theme, and renders it with a reference Astro renderer.
 
-- **Code-owned definitions.** `defineComponent` and `defineTheme` describe
-  each component's fields, defaults, slots and server-side data loading.
-- **JSON page documents.** `parsePageData` and `validatePageData` read a saved
-  page forgivingly: every problem is reported, and nothing a merchant saved can
-  break the rest of the page.
-- **A serializable manifest.** `themeManifest` turns a theme into plain JSON
-  that editors and tools can read without running theme code.
-- **Editor-ready.** Images, rich text, lists and product references as
-  fields; page types and reusable templates; presets; hidden sections; and the
-  document operations every editor applies — all discoverable from the
-  manifest, which a build emits as a file.
-- **Many languages.** Text values may be translated per language, and
-  `formatMessage` handles placeholders and CLDR plurals.
-- **A reference renderer.** `InstanceView.astro` renders a document section by
-  section through your own components.
+**Documentation: [docs.wocart.store/sdk/theme](https://docs.wocart.store/sdk/theme)**
+— also in [French](https://docs.wocart.store/fr/sdk/theme) and
+[Arabic](https://docs.wocart.store/ar/sdk/theme). Start with the
+[tutorial](https://docs.wocart.store/sdk/theme/tutorial).
 
 ## Install
 
@@ -29,1078 +17,37 @@ Astro renderer.
 npm install @wocart/theme @wocart/storefront
 ```
 
-`@wocart/storefront` is a required peer: the render context carries its
-`StoreConfig` and data loaders receive its `StoreClient`. `astro` (7.x) is an
-optional peer, needed only for the `./astro` renderer. ESM only; tooling needs
-Node 22.12 or newer.
+`@wocart/storefront` 2 is a required peer; `astro` 7 is an optional peer, for
+the `./astro` renderer. ESM only; Node 22.12 or newer for tooling.
 
-## Entry points
-
-| Import | What it holds |
-| --- | --- |
-| `@wocart/theme` | definitions, validation, page documents, resolution, document operations, rich text output, the manifest and its diff, languages and messages — framework-neutral |
-| `@wocart/theme/astro` | `createReadCache`, `themeManifestEndpoint` (the manifest as a build artifact), `hasBlocks`, `isPreview`, `THEME_LIMITS`, `themeStylesEndpoint`, `previewTarget`, the preview markers and the `BlocksHandle` and `RendererIssue` types |
-| `@wocart/theme/astro/InstanceView.astro` | the reference renderer component |
-| `@wocart/theme/astro/Blocks.astro`, `@wocart/theme/astro/Block.astro` | a slot's blocks and a fixed block, placed by a component (see [Blocks](#blocks)) |
-| `@wocart/theme/astro/ThemeStyles.astro` | the stylesheet link and the store's color schemes, for a layout's `<head>` (see [Style](#style)) |
-| `@wocart/theme/image-service` | `mediaImageService` — an Astro image service that resizes media-domain images on the media domain (any storefront host) |
-| `@wocart/theme/preview` | `startPreviewBridge` — the browser module of a theme's preview page (see [Preview](#preview)) |
-| `@wocart/theme/lifecycle` | `bindEach`, `onEachPage`, `PREVIEW_SECTION_LOAD_EVENT` — binding browser behaviour so it survives page and section swaps; tiny, without the bridge (see [Browser scripts](#browser-scripts)) |
-| `@wocart/theme/messages` | `formatMessage`, `messageForms`, `pluralMessageKeys`, `pluralFormIssues` for browser code (see [Messages](#messages-placeholders-and-plurals)) |
-
-Browser code imports only what builds no validator: `./lifecycle`,
-`./messages`, and from the root the style, rich-text and message helpers. A
-test of this package bundles each of them and fails if Zod or the editor's
-bridge reaches a shopper's page.
-
-## Use
+## Quick start
 
 ```ts
-import {
-  defineComponent,
-  defineTheme,
-  parsePageData,
-  validateThemeDefinition,
-} from "@wocart/theme";
+import { defineComponent, defineTheme } from "@wocart/theme";
 import Hero from "./components/Hero.astro";
 
-const hero = defineComponent({
+export const hero = defineComponent({
   type: "hero",
-  component: Hero, // the real .astro component — untouched
+  component: Hero,
   label: "Hero",
-  fields: [{ key: "heroTitle", kind: "text", label: "Title", contentKey: "heroTitle" }],
-  capabilities: { insertable: true },
+  fields: [{ key: "title", kind: "text", label: "Title", default: "Fast delivery" }],
 });
 
 export const theme = defineTheme({ key: "my-theme", version: "1.0.0", components: { hero } });
-
-const definitionIssues = validateThemeDefinition(theme); // [] when the catalog is coherent
-const { page, issues } = parsePageData(savedDocument);   // parse-and-degrade
-```
-
-Then render the page in an `.astro` file:
-
-```astro
----
-import InstanceView from "@wocart/theme/astro/InstanceView.astro";
-import { createReadCache } from "@wocart/theme/astro";
-
-const reads = createReadCache(); // one per render, shared by every section
----
-{page?.sections.map((section) => (
-  <InstanceView instance={section} theme={theme} context={context}
-    storefront={store} reads={reads} />
-))}
-```
-
-`context` is the request's `ThemeRenderContext` (the store config, your
-content pack for the language, `locale`, `isRTL`, `url`), and `store` is the
-server-side `StoreClient` from `@wocart/storefront/server`.
-
-Renderer behavior: `resolveInstance` fills defaults and gates composition;
-`load` (optional, server-only) may enrich props and degrades to base props on
-failure; unknown types render nothing — every degradation, including invalid
-props and undeclared children/slots, is reported through `onIssue` (default:
-`console.warn`). The issue contains a stable `code`, `message`, `instanceId`,
-and, for page-data resolution issues, `path`.
-
-`load` receives the instance's resolved props typed from the component's own
-fields, so a section reads its settings without a cast:
-
-```ts
-defineComponent({
-  type: "best-sellers",
-  component: BestSellers,
-  label: { ar: "الأكثر مبيعاً", fr: "Meilleures ventes" },
-  fields: [
-    { key: "collection", kind: "collection", label: { ar: "المجموعة", fr: "Collection" }, default: "best-sellers" },
-    { key: "limit", kind: "number", label: { ar: "العدد", fr: "Nombre" }, default: 8, min: 1, max: 24 },
-  ],
-  load: async ({ storefront, props }) => ({
-    products: await storefront.products.list({ collection: props.collection, limit: props.limit }),
-  }),
-});
-```
-
-## Field kinds
-
-| Kind | Value | Rules |
-|---|---|---|
-| `text`, `textarea` | string | `default` or `contentKey` (from the theme's content pack), never both |
-| `number` | finite number | optional `min`/`max`; a `default` must sit inside them; with `step`, values sit on the grid that starts at `min` (or 0) |
-| `boolean` | boolean | |
-| `select` | one of `options` | `default` must be one of the options; `optionLabels` gives each option the words an editor shows, per language |
-| `color` | `#rgb` or `#rrggbb` | anything else (a color name, `url(…)`) is rejected at assembly and reported on read |
-| `collection` | a collection handle (`best-sellers`) | lowercase letters, digits and hyphens; its products are listed with `@wocart/storefront`'s `products.list({ collection })`, in the merchant's order |
-| `menu` | a menu handle (`main-menu`) | lowercase letters, digits and hyphens; the store's menu is read with `@wocart/storefront`'s `menus.get(handle)` |
-| `url` | a link target | a site path (`/products`), `#fragment`, `?query`, `http(s)://`, `mailto:` or `tel:`; `javascript:`, `data:`, `//host` and backslash tricks are rejected at assembly and reported on read |
-| `product` | a product handle | read with `@wocart/storefront`'s `products.get(handle)`; a renamed or deleted product reads as no product |
-| `category` | a category slug | found in `@wocart/storefront`'s `categories.list()` |
-| `image` | `{ key, alt?, width?, height?, focal? }` | `key` is the object's key in the store's media (`products/3f2a9c.webp`), never a URL; no default; `alt` per language |
-| `richtext` | a rich-text document, or one per language | a closed JSON format; `formats` narrows what it may contain |
-| `list` | `[{ id, props }]` | item `fields` of any kind but `list` and `colorSchemes`; `min`/`max`; `itemLabel` names the item field an editor shows; default items carry their own ids |
-| `style` | `{ spacing?, layout?, size? }`, a value per breakpoint | `panels` names what it offers; steps and choices only, never CSS (see [Style](#style)) |
-| `colorScheme` | a color scheme's id | one of the store's schemes; the theme needs a `colorSchemes` setting |
-| `colorSchemes` | `[{ id, name, colors }]` | a theme setting, at most one; every role a hex color; at most 24 |
-| `productList` | product handles, in order | distinct; `min`/`max` (at most 50); each read with `products.get(handle)`, a missing one reads as absent |
-| `collectionList` | collection handles, in order | distinct; `min`/`max` (at most 50) |
-
-**How an editor shows a field** never changes what is stored:
-`display: "dropdown" | "radio" | "segmented"` on a `select` (alignment is a
-segmented `select` of `start`, `center`, `end`), `display: "input" | "slider"`
-on a `number` (a slider needs `min`, `max` and `step`), and `inline: true` on
-a `richtext` — one line, a single paragraph with marks and links, rendered
-without a block element by `richTextToHtml(doc, { inline: true })`.
-
-**A field may show only when it applies.** `visibleIf` is a closed JSON
-condition on the fields beside it (the same component's, list item's, or
-theme settings'): `{ field, equals }`, `{ field, in: [...] }`, `{ all: [...] }`,
-`{ any: [...] }`, `{ not: ... }`, nested at most `CONDITION_DEPTH` (4) deep.
-`isFieldVisible(field, values)` evaluates it for an editor — an unset field
-compares as `null` — and the renderer ignores it; a hidden field keeps its
-value.
-
-```ts
-{ key: "source", kind: "select", label: "Products", options: ["latest", "picked"], default: "latest", display: "segmented" },
-{ key: "picked", kind: "productList", label: "Picked products", max: 12, visibleIf: { field: "source", equals: "picked" } },
-```
-
-Use `url` for every editor-settable `href`, never `text`: the reader drops an
-unsafe saved link (`invalid-prop`) and falls back to the field's default, so a
-document can never inject a script URL.
-
-The SDK checks a value as a writer must before saving it:
-`checkFieldValue(field, value)` returns `{ ok: true }` or the reason. It is
-stricter than reading: an image reference or a list item with a key the
-contract does not define is refused, where the reader ignores it.
-
-### Images
-
-An image value names the object in the store's own media bucket; the URL is
-derived at render, so a domain or host change never rewrites a document.
-Resolve it with `@wocart/storefront`'s `mediaUrl`:
-
-```astro
----
-import { mediaUrl } from "@wocart/storefront";
-import { MEDIA_DOMAIN } from "astro:env/server";
-const { image } = Astro.props as InferProps<typeof banner>; // ResolvedImage: alt in the rendered language
-const src = image && mediaUrl(image.key, MEDIA_DOMAIN);
----
-{src && <img src={src} alt={image.alt ?? ""} width={image.width} height={image.height} />}
-```
-
-The SDK never uploads: the editor places files in the store's media and
-stores the key. An image field has no default — a theme cannot know a store's
-media — so the component renders its own fallback.
-
-### Rich text
-
-A rich-text value is `{ type: "doc", version: 1, content }`: paragraphs,
-headings 2–4, bullet and ordered lists, line breaks, bold, italic, underline,
-strike and links that follow the `url` rule. Nothing else is representable, so
-a stored value cannot carry markup or scripts. Render it with the SDK:
-
-```astro
----
-import { richTextToHtml } from "@wocart/theme";
----
-{body && <div set:html={richTextToHtml(body, { href: store.href })} />}
-```
-
-`richTextToHtml` escapes every text and attribute and drops what is not in the
-format even for a value that was never validated; `href` lets the theme
-localize site links. `richTextToPlainText` gives the words for a meta
-description or an `aria-label`. A field's `formats` (`["bold", "link"]`)
-narrows what a merchant may use.
-
-The rich-text types are plain JSON (`RichTextDocument` is a `JsonObject`), so
-a preset or a default can hold a document without a cast.
-
-### Lists
-
-```ts
-{
-  key: "badges",
-  kind: "list",
-  label: "Badges",
-  max: 4,
-  itemLabel: "title",
-  fields: [
-    { key: "title", kind: "text", label: "Title" },
-    { key: "icon", kind: "select", label: "Icon", options: ["truck", "cash"], default: "truck" },
-  ],
-  default: [{ id: "cod", props: { title: { ar: "الدفع عند الاستلام", fr: "Paiement à la livraison" }, icon: "cash" } }],
-}
-```
-
-A component receives `[{ id, title, icon }]`. Each item's id is unique in its
-list, so reordering never changes which item is which; the reader drops a
-broken or repeated item and keeps the others, and keeps the first `max`. Item
-fields cannot default from the content pack: every item would read the same
-key.
-
-## Languages
-
-The contract is built for many languages; a store serves the ones it enables.
-A single-language store is the same contract with one language.
-
-- **The render context says which language to render**: `locale` (a BCP 47
-  tag: `ar`, `fr`, `ar-DZ`) and optionally `fallbackLocales`, tried in order.
-  `content` is the theme's pack for that language.
-- **`text`, `textarea` and `url` values may be translated.** A saved value is
-  either one string, the same in every language (a brand name), or one value
-  per language: `{ "ar": "توصيل مجاني", "fr": "Livraison gratuite" }`.
-  Resolution takes the requested language, then the fallback chain, then
-  `content[contentKey]`, then `default`. A missing translation is not an error;
-  a malformed map (`FR`, a number, an empty map) is reported as `invalid-prop`.
-  Numbers, toggles and choices are shared by every language.
-- **The writer checks every language.** `createInstance` refuses a map with an
-  unsafe link or a wrong type in any language, naming that language.
-- **Editor-facing text can be translated**: a component's `label` and `group`,
-  a field's `label`, `description` and text `default`, a surface's `label`.
-- **A theme declares the languages its packs cover**:
-  `defineTheme({ locales: ["ar", "fr", "en"], … })`. The validator then fails
-  any translated label or default that misses one of them, and the manifest
-  carries the list so an editor knows what the theme can serve.
-- **`localize(value, locales)`** picks the text for the first preferred
-  language; use it wherever a theme or tool shows a translated label.
-
-A page-document writer must save translatable copy as a per-language map.
-Saving a plain string declares it the same in every language.
-
-## Typed props
-
-A component's props come from its definition, so derive them instead of
-writing them twice. `InferProps` types each field by kind (a `select` narrows
-to its options), makes a field with a `default` always present and every other
-field optional, and merges in whatever `load` returns, exactly as the renderer
-does:
-
-```astro
----
-import type { InferProps } from "@wocart/theme";
-import type { productGrid } from "../catalog";
-
-const { products = [], limit } = Astro.props as InferProps<typeof productGrid>;
----
-```
-
-Define components with `defineComponent` so keys, kinds and options keep their
-literal types. Reusable fields are plain values: declare one once and list it
-in several definitions.
-
-## Composition rules (slots)
-
-A component declares where children may go; the document says what is there.
-
-- `slots: [{ name: "default" }]` accepts children. A component with no
-  `default` slot drops children with `undeclared-children`.
-- `multiple: false` keeps the first child and reports the rest
-  (`slot-not-multiple`).
-- `allow: ["product-grid", "note"]` limits a slot to those component types.
-  Assembly reports a type that is not in the catalog; the reader drops any other
-  child with `disallowed-child`. Omit `allow` to accept any type.
-
-`allow` is applied before `multiple: false`, so a disallowed child never
-displaces an allowed one. The rules travel in the manifest, so an editor can
-offer only valid insertions.
-
-## Blocks
-
-A section is often made of parts a merchant arranges — a product section's
-gallery, price, order form, a countdown, "Add to cart" — and some of them must
-always be there. Blocks are components placed inside other components.
-
-**Where a component may go.** `placement: "section"` (the top level of a page),
-`"block"` (only inside a slot) or `"both"`; absent means anywhere. The document
-operations enforce it; the renderer never does.
-
-**A component places its own blocks.** The renderer gives every component a
-`blocks` prop. Put each slot's blocks, and each fixed block, where the design
-wants them — as many slots as the component declares:
-
-```astro
----
-import Blocks from "@wocart/theme/astro/Blocks.astro";
-import Block from "@wocart/theme/astro/Block.astro";
-import { hasBlocks, type BlocksHandle } from "@wocart/theme/astro";
-
-const { blocks, title } = Astro.props as { blocks: BlocksHandle; title: string };
----
-<section>
-  {hasBlocks(blocks, "media") && <div class="media"><Blocks of={blocks} slot="media" /></div>}
-  <h1>{title}</h1>
-  <Block of={blocks} name="buy-box" />
-</section>
-```
-
-`<slot />` keeps working for children, as before; a component that pulls its
-blocks never pays for content pushed into a slot it does not render. `blocks`
-is a reserved prop: no field may use that key.
-
-`isPreview(blocks)` says whether the component renders in an editor's
-preview. A section with nothing to show yet — no products picked, no text
-written — draws a placeholder there, so a merchant can see and select it; a
-shopper's page never shows one.
-
-**Fixed blocks** are placed by the component's code, like Shopify's static
-blocks. Declare them so an editor knows them:
-
-```ts
-fixed: [{ name: "buy-box", type: "buy-box", label: "Buy box" }],
-```
-
-An editor changes a fixed block's fields and fills its slots, but cannot
-remove, move, copy or hide it. It renders even when the document does not
-store it, with its defaults and the id `<owner id>~<name>` (`fixedBlockId`).
-
-**Required blocks** may move but never disappear. A slot — or a surface, for
-its top-level sections — lists them:
-
-```ts
-slots: [{ name: "default", allow: ["order-form", "countdown", "add-to-cart"], max: 4,
-          required: [{ type: "order-form", max: 1 }] }],
-```
-
-The operations refuse to remove, hide or move out the last `min` (default 1)
-of a required type, or to insert past its `max`. A document that lacks one —
-an old document, a theme update — renders it anyway, added at the end of its
-slot, and the reader reports `missing-required-block`.
-
-**Every product page keeps an order form.** A component with
-`role: "order-form"` places orders. Every surface whose `pageType` is
-`product` must guarantee at least one through required sections and fixed or
-required blocks; assembly refuses it otherwise (`order-form-not-guaranteed`).
-Give the order form's entry `max: 1` for exactly one. Its fields are not the
-theme's: a store's checkout form is set in the merchant dashboard and enforced
-by the server.
-
-**Limits** (`THEME_LIMITS`): 50 instances per slot, 50 sections per surface,
-1,000 instances per document, 6 levels of nesting below a section. A slot or
-surface `max` may set fewer. The reader renders up to a limit and reports
-`limit-exceeded`; the operations refuse to go past one. Assembly refuses fixed
-and required blocks that contain themselves or nest deeper than the limit.
-
-## Style
-
-A merchant changes how a section sits on the page and which colors it wears
-— never by writing CSS. A theme gives sizes to the platform's style steps,
-offers style fields, and the SDK writes the CSS.
-
-**Sizes.** The step names are the platform's (`s0` to `s12`); a theme maps the
-ones it offers to pixels, and the widths a section may take:
-
-```ts
-style: { spacing: { s0: 0, s2: 8, s4: 16, s6: 32, s8: 64 }, widths: { wide: 1280, content: 960, narrow: 640 } },
-```
-
-**Style fields.** A `style` field names its panels — `spacing` (padding and
-margin on the block axis, inline padding, gap), `layout` (direction, align,
-justify, wrap) and `size` (width, minimum height). A value holds a choice per
-breakpoint — `base` everywhere, `md` from 768 px, `lg` from 1024 px — phone
-first, on CSS logical properties so right-to-left stores mirror on their own:
-
-```ts
-{ key: "style", kind: "style", label: "Style", panels: ["spacing", "size"],
-  default: { spacing: { paddingBlockStart: { base: "s4", lg: "s8" } } } }
-```
-
-A writer refuses a step or width the theme gives no size; a reader renders one
-as no style.
-
-**Colors.** The store's color schemes are one theme setting, `colorSchemes`:
-named schemes, each a hex color for every role (`background`, `text`,
-`heading`, `accent`, `button`, `buttonText`, `border`). A `colorScheme` field
-picks one by id. A page document never holds a color.
-
-**In the page.** Give the element its classes, serve the stylesheet, and put
-the schemes in the `<head>`:
-
-```astro
----
-import { schemeClass, styleClasses } from "@wocart/theme";
-const { style, scheme } = Astro.props;
----
-<section class={`${schemeClass(scheme)} ${styleClasses(style)}`}>…</section>
-```
-
-```ts
-// src/pages/wocart-styles.css.ts
-import { themeStylesEndpoint } from "@wocart/theme/astro";
-export const prerender = true;
-export const GET = themeStylesEndpoint(theme);
-```
-
-```astro
-<!-- the layout's <head> -->
-<ThemeStyles schemes={settings.colorSchemes} />  <!-- @wocart/theme/astro/ThemeStyles.astro -->
-```
-
-The schemes become custom properties on `.wc-scheme-<id>`
-(`--wc-color-background`, `--wc-color-button-text`, …) with the background
-and text applied. `schemeClass(id)` also gives the element `wc-scheme`
-(`SCHEME_MARKER_CLASS`), the one class every element wearing a scheme
-carries. Derive the theme's own tokens there and on the page, so they follow
-the scheme of the nearest element that wears one:
-
-```css
-:root, .wc-scheme {
-  --surface: var(--wc-color-background, #fff);
-  --ink: var(--wc-color-text, #1d1d1f);
-  --line: color-mix(in srgb, var(--wc-color-border, #e5e5e5) 70%, transparent);
-}
-```
-
-Without that rule a token computed once on `:root` keeps the page's colors
-inside a section that wears another scheme. On a page with a Content-Security-Policy, `ThemeStyles` adds
-its inline sheet's hash to the policy, so `style-src` needs no
-`'unsafe-inline'`. `contrastRatio(a, b)` gives the WCAG ratio an editor warns
-on (below 4.5 for text).
-
-## Pages and templates
-
-A surface is a document a theme can render. Declare the platform page type it
-renders and, optionally, its default document:
-
-```ts
-import homeDocument from "./documents/home.json";
-
-surfaces: [
-  { key: "home", label: "Home", pageType: "home", document: homeDocument },
-  { key: "product", label: "Product", pageType: "product" },
-  { key: "product.compact", label: "Compact product", pageType: "product" },
-],
-```
-
-- A page type with a resource — `product`, `category`, `collection`, `page`,
-  `landing` — makes the surface a **template**: one document renders every
-  product (or category…), and its sections read the resource from
-  `context.params` (see the route example under Ownership rules). There is no
-  document per product.
-- `product.compact` is an **alternate** of `product`: the base must be
-  declared and render the same page type.
-- A surface's `document` is checked at assembly against the surface and the
-  catalog, and travels in the manifest as the theme's default.
-- `capabilities: { surfaces: ["product"] }` keeps a component to the surfaces
-  it can serve (alternates included); `isInsertableOn(component, surface)`
-  applies the rule.
-
-**Areas** are the parts every page shares — a header, a footer — composed of
-sections like a page and edited once for the whole store:
-
-```ts
-areas: [
-  { key: "header", label: "Header", document: headerDocument, required: [{ type: "menu-bar", max: 1 }], max: 4 },
-  { key: "footer", label: "Footer" },
-],
-```
-
-An area's document is the surface `area:<key>` (`areaSurface("header")`):
-read, completed, checked and edited like a page's, with `required` and `max`
-as a surface has them. A component names `area:header` in
-`capabilities.surfaces` to stay in the header. The layout renders it like a
-page: `resolveSurfaceDocument(theme, "area:header", await store.pageData.get("area:header"))`.
-
-A template's preview names the resource it shows: the preview draft's `path`
-(`/products/robe-kabyle`), which `@wocart/storefront`'s `matchStorefrontPath`
-turns into the page type and the route's params.
-
-## Presets
-
-A preset is a ready-made configuration an editor offers when inserting a
-component — props over the field defaults, and child components for its slots:
-
-```ts
-presets: [
-  {
-    key: "with-grid",
-    label: "Hero with products",
-    props: { layout: "columns" },
-    children: [{ type: "hero", props: { align: "center" } }],
-    slots: { aside: [{ type: "product-grid", props: { limit: 2 } }] },
-  },
-],
-```
-
-`instantiatePreset(theme, type, key, newId)` builds the instances, each with an
-id from `newId`. Presets are checked at assembly by building them. A preset's
-props may hold rich text as it is written:
-
-```ts
-const welcome: RichTextDocument = { type: "doc", version: 1, content: [{ type: "paragraph", content: [{ type: "text", text: "Bienvenue" }] }] };
-presets: [{ key: "welcome", label: "Welcome", props: { body: welcome } }],
-```
-
-## Hidden sections
-
-`{ "id": "…", "type": "hero", "hidden": true }` keeps a section in the
-document without rendering it — a merchant switched it off. The renderer skips
-it, its `load` and its children; the reader still checks it.
-
-## Editing documents
-
-Every writer — an editor, a CLI, an assistant — applies the same rules
-through pure operations that return a new document or say why they refused:
-
-```ts
-import { createInstance, insertInstance, moveInstance, newInstanceId, checkPageData } from "@wocart/theme";
-
-const edit = insertInstance(theme, page, createInstance(theme.components.hero, newInstanceId()), { index: 0 });
-if (!edit.ok) console.log(edit.issue.code, edit.issue.message); // "not-available", "slot-full", …
 ```
 
-`insertInstance`, `removeInstance`, `moveInstance`, `duplicateInstance`,
-`setInstanceProps` and `setInstanceHidden` never change their input. They
-refuse a component that is `insertable: false`, not available on the
-document's surface or not placeable there, a slot that does not take it or is
-full, an index out of range, a cycle, an id already in the document, a value
-its field refuses, any change to a fixed block but its fields
-(`fixed-block`), losing a required block (`required-block`) and going past a
-limit (`limit-exceeded`). `removeInstance(theme, page, id)` and
-`setInstanceHidden(theme, page, id, hidden)` take the theme first; their older
-forms without it still refuse a fixed block but cannot know a slot's required
-types. `checkPageData(theme, page)` is the strict check of a whole document
-before saving it; `findInstance` locates an instance, a fixed block included.
-
-Open a document with `completePage(theme, page)`: it adds what the document
-must hold — required sections, fixed blocks, required blocks, each with an id
-unique in the document — so what an editor shows is what renders. Inserting a
-component completes it the same way.
-
-An editor holds a theme's manifest, not its code:
-`manifestCatalog(manifest)` makes the catalog these functions take, with no
-component implementations.
-
-## Preview
-
-An editor shows a merchant's unsaved draft on the live storefront, rendered by
-the theme itself — the same components, data and CSS a shopper gets. A theme
-that does this sets `preview: true` (the manifest says so) and serves a route
-at `THEME_PREVIEW_PATH` (`/wocart-preview`). The editor frames it with
-`GET /wocart-preview?token=…&surface=home&locale=fr`, and the framed page
-re-renders each draft the editor sends by posting it back to the route as
-JSON — never a cross-site form, so Astro's `checkOrigin` stays on. Three parts
-meet there:
-
-1. **The request.** `readPreviewRequest` from `@wocart/storefront/server`
-   checks the editor's signed token and returns the draft — which surface and
-   language to show and, once the editor sends one, the document, settings
-   and text edits (its guide: "Previewing a draft for an editor"). What a
-   draft leaves out renders as saved. The route answers with
-   `previewResponseHeaders`, so only that editor can frame it and nothing
-   stores it; no route rule may cache it.
-2. **The markers.** `<InstanceView preview …>` brackets each instance's nodes
-   with two comments — `wocart:start id=… type=…[ hidden]` and
-   `wocart:end id=…` (`previewStartMarker`, `previewEndMarker`,
-   `parsePreviewMarker`). Comments, not wrapper elements, so a grid or a
-   `> *` selector lays out exactly as it does for a shopper; a hidden instance
-   keeps its markers with nothing between them. A shopper's page has none.
-3. **The bridge.** `startPreviewBridge({ editorOrigin, token })` from
-   `@wocart/theme/preview` runs on the preview page. It reports every marked
-   instance to the editor, turns clicks into selections, and re-renders the
-   drafts the editor sends — swapping in only the sections whose markup
-   changed, or the whole page when sections were added, moved or hidden, or
-   the page around them changed.
-
-```astro
----
-// src/pages/wocart-preview.astro — the middleware read the request
-export const prerender = false;
-const { claims, token } = Astro.locals.preview;
-for (const [name, value] of Object.entries(previewResponseHeaders(claims))) Astro.response.headers.set(name, value);
----
-<Layout>
-  {sections.map((instance) => (
-    <InstanceView preview {instance} {theme} {context} {storefront} {reads} />
-  ))}
-  <wocart-preview-bridge data-editor={claims.editor} data-token={token} hidden />
-</Layout>
-<script>
-  import { startPreviewBridge } from "@wocart/theme/preview";
-  const host = document.querySelector<HTMLElement>("wocart-preview-bridge")!;
-  startPreviewBridge({ editorOrigin: host.dataset.editor!, token: host.dataset.token! });
-</script>
-```
-
-The bridge draws nothing — outlines, toolbars and panels are the editor's. It
-posts only to `editorOrigin` and reads only messages from it, sent by the
-framing window, with `source: "wocart-editor"` and the protocol's `version`
-(`PREVIEW_PROTOCOL_VERSION`):
+## Entry points
 
-| The editor sends | The page answers |
+| Import | Holds |
 | --- | --- |
-| — | `ready` with every instance: `{ id, type, parent, hidden, rect }` |
-| `render` `{ draft, revision? }` | `rendered` `{ revision, instances }`, or `error` `{ revision, reason }`; an answer overtaken by a newer render or a patch is dropped |
-| `patch` `{ patches }` | the change shown at once, on the page as it stands, then `layout` (see below) |
-| `mode` `"edit"` \| `"interactive"` | in `edit`, links and forms do nothing and a click is `select` `{ id }` of the innermost instance |
-| `scroll-to` `{ id }` | the instance scrolls into view |
-| `token` `{ token }` | the next render uses it |
-| — | `hover` `{ id \| null }` as the pointer moves; `layout` after a scroll or resize |
-
-A `patch` shows a change the editor has already made to its draft before the
-render that follows it arrives — so moving, copying, removing or hiding a
-section, and typing a field's text, show on the page at once. Each patch
-(`PreviewPatch`) is a hint: the page applies what it finds — `move` a section
-to an index, `duplicate` an instance under new ids, `remove` one and
-`restore` it, `hide` one or show it again, replace `text` that reads `from`
-inside an instance with `to` — and leaves the rest to the render, which is
-the page's truth. An editor therefore always sends the render too; a page
-from before 1.6.0 ignores patches and still shows every change, a moment
-later.
-
-A swapped section's scripts do not run again. A section with browser behavior
-binds it again on `PREVIEW_SECTION_LOAD_EVENT` (`wocart:section-load`,
-dispatched on `document` with `detail.id`) — also for a section a patch
-copied, restored or showed again. `bindEach` (see [Browser scripts](#browser-scripts))
-does it for you. When the bridge replaces the whole
-page instead, it does what Astro's router does after a navigation — a new
-`<body>`, the root element's attributes, the title — and dispatches
-`astro:page-load`, so a script written for the router mounts again as it does
-there. Changed stylesheets are replaced in place; unchanged ones never reload.
-
-### Which page a preview shows
-
-`previewTarget(theme, draft, client)` from `@wocart/theme/astro` decides it
-for every theme: the surface to render, its route parameters and its
-document — or null, answered 404, for a surface the theme does not declare.
-
-- A template previews the resource the draft's path names, else the store's
-  first product, category, default collection or text page; a store with
-  none still previews, with empty `params`, so its sections can be arranged.
-- An area (`area:header`) previews on the page its path names when the theme
-  composes it, else home; `area` names it, and the page's own document is
-  the saved one.
-- The resource is chosen by the surface's `pageType`, so an alternate
-  (`product.compact`) previews like its base.
-
-```astro
----
-const target = await previewTarget(theme, Astro.locals.preview.draft, Astro.locals.store.client);
-if (!target) return new Response(null, { status: 404, headers: { "Cache-Control": "no-store" } });
----
-<Sections surface={target.surface} params={target.params} document={target.document} preview={target.area === null} />
-```
-
-## Browser scripts
-
-A theme's browser behaviour meets markup three ways: the page loads, Astro's
-router swaps the page (`astro:page-load`), an editor's preview swaps one
-section (`PREVIEW_SECTION_LOAD_EVENT`). `@wocart/theme/lifecycle` binds it
-once per element whichever way it came:
-
-```ts
-import { bindEach, onEachPage } from "@wocart/theme/lifecycle";
-
-bindEach<HTMLFormElement>("[data-order-form]", (form) => {
-  const onResize = () => layout(form);
-  window.addEventListener("resize", onResize);
-  return () => window.removeEventListener("resize", onResize);
-});
-
-onEachPage(() => {
-  const timer = setInterval(tick, 1000);
-  return () => clearInterval(timer);
-});
-```
-
-A bind's teardown runs when its element leaves — before Astro swaps the page
-out, or when a later pass finds it gone — so document and window listeners
-never pile up. Both return a function that stops them.
-
-## Theme manifest (serializable catalogue)
-
-A `ThemeDefinition` mixes data (types, fields, defaults) with runtime (the live
-component reference, the server-only `load` hook), so tooling cannot read it
-without executing theme modules. `themeManifest(theme)` derives the data-only
-half — a JSON-serializable `ThemeManifest` — for editors, CLIs, and marketplaces:
-
-```ts
-import { themeManifest, validateThemeManifest } from "@wocart/theme";
-
-const manifest = themeManifest(theme);
-// {
-//   contractVersion: 1,
-//   key: "my-theme", version: "1.0.0",
-//   sdkVersion: "1.5.0",                // the @wocart/theme that generated it
-//   surfaces: [],                       // declared surfaces (possibly none)
-//   locales: [], settings: [], content: {},
-//   components: { hero: { type, label, group, fields, slots, capabilities, presets } },
-// } — no `component`, no `load`, JSON-round-trip stable.
-
-const { manifest: checked, issues } = validateThemeManifest(
-  JSON.parse(JSON.stringify(manifest)),
-);
-// `checked` is non-null only for a structurally sound manifest; a non-semver
-// theme `version` is the one advisory case (manifest returned with an
-// `invalid-version` issue). Declare extra surfaces on the theme when it can
-// render them: `defineTheme({ key, version, surfaces: [{ key: "home",
-// label: "Home" }], components })` — declaration only, never enforcement:
-// page parsing and resolution never consult the list.
-```
-
-### Manifest guarantees
-
-What a validated manifest promises a consumer:
-
-- **Derived, not authored.** The manifest is generated from the theme's
-  `ThemeDefinition` by `themeManifest()` — there is exactly one source of truth.
-  A hand-written manifest is validated strictly, but never treated as the
-  catalogue; the theme's code is.
-- **Data-only.** No component implementations, loaders, functions, symbols,
-  bigints, non-finite numbers, or circular references. `validateThemeManifest`
-  rejects all of these as `non-serializable`, including `component`/`load` keys
-  whose values would otherwise serialize.
-- **Normalized shapes.** `fields` and `slots` are always arrays (absent means
-  `[]`); every record key equals its component's `type`. Unknown keys are
-  **stripped, not carried** — so an additive field introduced by a newer producer
-  under the same `contractVersion` is ignored by this reader rather than
-  failing it. That is the forward-compat tradeoff: old readers stay green, but
-  they cannot see new metadata until updated.
-- **Validation mirrors assembly.** Relational rules (`contentKey`/`default`
-  exclusivity, number `default` within `min`/`max`, select `default` in
-  `options`, slot-name shape, key/type agreement) are checked identically by
-  `validateThemeDefinition` and `validateThemeManifest`, so a manifest derived
-  from a valid theme always validates clean.
-
-What it deliberately excludes: implementations and loaders (runtime-only).
-Content packs travel only when the theme declares them (`defineTheme({
-content })`).
-
-### The manifest as a build artifact
-
-A theme's definition imports its `.astro` components, so it cannot be loaded
-outside Astro's build. Emit the manifest as a prerendered page at
-`THEME_MANIFEST_PATH` (`/wocart-theme.json`):
-
-```ts
-// src/pages/wocart-theme.json.ts
-import { themeManifestEndpoint } from "@wocart/theme/astro";
-import { theme } from "../theme/theme";
-export const prerender = true;
-export const GET = themeManifestEndpoint(theme);
-```
-
-The manifest is validated when the module loads: an invalid one fails the
-build instead of shipping.
-
-### What changes between versions
-
-`diffThemeManifests(previous, next)` lists the changes saved documents,
-settings and text edits may not survive (`breaking`) — a removed component,
-field, slot, option, surface or content key; a changed kind or page type; a
-narrowed range, list, `allow` list or rich-text formats; a slot made single; a
-field newly required with no default — and those that only add. A breaking
-change belongs in a new major version of the theme.
-
-### Versioning policy
-
-Three versioned contracts coexist — keep them separate:
-
-- `contractVersion` identifies the **manifest schema and interpretation
-  contract**. It starts at `1` and increments only on a breaking change to the
-  manifest shape or how consumers must interpret it. Ordinary additive,
-  backward-compatible metadata does not bump it. An unsupported version fails
-  clearly (`unsupported-contract`), never silently.
-- The theme's own `version` (e.g. `"1.0.0"`) versions the **theme**. The runtime
-  `ThemeDefinition` contract accepts any non-empty string (unchanged); the
-  manifest validator additionally *reports* (never rejects) a non-semver value
-  so version hygiene is visible without breaking registration.
-- `PageData.version` (currently `1`) versions the **page-document envelope** —
-  untouched by the manifest contract.
-
-**One named slot per instance.** The reference renderer fills at most one named
-slot; a second named slot *with content* is reported as
-`multiple-slots-unsupported` and is never silently dropped. This is an Astro
-compiler boundary (a dynamic child expression can lift only one slot attribute
-into the slots-object key), not a temporary limitation — see `SlotDefinition`
-for the escape hatch.
-
-## Ownership rules
-
-The Theme SDK owns composition mechanics: code-owned catalogs, JSON page data,
-field validation, defaults, slot gating, server-only loads, per-render read
-sharing, and structured degradation reports. A theme owns its Astro markup,
-layout, styles, copy packs, route adapters, and browser interaction wiring.
-The Storefront SDK owns commerce data, browser state machines, server adapters,
-screen-value projections, and platform error contracts.
-
-`InstanceView` does not write page documents, mutate catalog definitions, call
-the dashboard, or create themes. Editors, CLIs, publishing, and persistence
-are outside this package.
-
-For a real Astro theme, create one `ReadCache` outside the section map, pass a
-request-built `ThemeRenderContext`, and pass the server-only `StoreClient`
-explicitly. A `load` function must read through `reads.get(key, loader)` so
-siblings share a resource within that render. Validate the catalog during the
-theme's build/test path and treat non-empty issue arrays as actionable
-diagnostics.
-
-On a templated surface (`/products/[slug]`, `/category/[slug]`), pass
-`params: Astro.params` in the render context. A section reads its route
-resource from `context.params`, under a `reads` key that includes the
-parameter, so the page and every section share one read:
-
-```ts
-load: async ({ storefront, reads, context }) => ({
-  product: await reads.get(`product:${context.params?.slug}`, () =>
-    storefront.products.get(context.params?.slug ?? ""),
-  ),
-}),
-```
-
-## Saved documents
-
-A stored page document can be missing, malformed, or built for a catalog that
-has since changed. The SDK reports every degradation and never throws the page
-away. Which document to render instead is a product decision; the recommended
-policy is:
-
-1. **No saved document** → render the theme's shipped default document.
-2. **Envelope invalid** (`parsePageData` returns `page: null`) → render the shipped default.
-3. **Saved sections map to no catalog type at all** (a theme switch left nothing
-   renderable) → render the shipped default.
-4. **Partial overlap** → render what maps. Unknown types render nothing and are
-   reported through `onIssue`.
-5. **An empty saved document** → honor it. A page the merchant emptied renders empty.
-
-`resolveSurfaceDocument(theme, surface, saved)` applies this policy — and
-also renders the default for a document saved for another surface or another
-theme — then completes the result (`completePage`). The shipped default is
-the surface's `document`:
-
-```ts
-const { page, source, reason, issues } = resolveSurfaceDocument(theme, "home", await store.pageData.get("home"));
-// render page.sections; log reason and issues when source is "default"
-```
-
-## Theme settings
-
-A theme's global choices — its font, which menu the header shows, a header
-color — are **settings**: declared once on the theme, in groups, with the same
-field kinds as a section. The merchant's values are stored per store and per
-theme (a value only means something against the theme that declared it) and
-reach the theme as `StoreConfig.themeSettings` from `@wocart/storefront`.
-
-```ts
-export const theme = defineTheme({
-  key: "my-theme",
-  version: "1.0.0",
-  locales: ["ar", "fr"],
-  settings: [
-    {
-      key: "header",
-      label: { ar: "الرأس", fr: "En-tête" },
-      fields: [
-        { key: "headerMenu", kind: "menu", label: { ar: "القائمة", fr: "Menu" }, default: "main-menu" },
-        { key: "font", kind: "select", label: { ar: "الخط", fr: "Police" }, options: ["Cairo", "Tajawal"], default: "Cairo" },
-      ],
-    },
-  ],
-  components: { … },
-});
-
-const { values, issues } = resolveThemeSettings(theme, config?.themeSettings, { locales: [locale] });
-values.headerMenu; // "main-menu" — values: InferSettings<typeof theme>, from 1.1.1
-```
-
-- **Reading never fails.** Each setting takes the merchant's value when the
-  declaration accepts it, else the default (or the content pack, for text),
-  else it is absent. A value the theme no longer accepts — a removed option, a
-  color that is not one, a setting since deleted — is reported in `issues`
-  (`invalid-setting`, `unknown-setting`, `invalid-settings`) and falls back.
-- **Keys are unique across groups**; groups are for the editor, values are flat.
-- **A writer checks strictly** with `checkThemeSettings(theme, values)` before
-  saving: every key declared, every value accepted, in every language.
-- Settings travel in the manifest (`manifest.settings`), so an editor lists
-  them without running the theme.
-- Store identity — the logo, the brand colors — is not a theme setting: it
-  belongs to the store and survives a theme change.
-
-## Content and copy
-
-The theme owns its content. The SDK does not model a content pack, a taxonomy,
-or a copy system — it only reads the resolved pack the request hands it.
-
-- **`ThemeRenderContext.content`** is an opaque, flat `Record<string, string>` —
-  the theme's pack with store overrides already merged.
-- **`FieldDefinition.contentKey`** names a key *in that map*. It is the only
-  bridge between the contract and the theme's copy.
-- **The precedence chain** is: instance value → `content[contentKey]` →
-  `field.default` → omit (the component's own default applies last). A field
-  with neither `contentKey` nor `default` is simply absent from `props`.
-- **Declare the packs on the theme** — `defineTheme({ content: { ar, fr } })`
-  — and every `contentKey` must exist in every pack, each declared language
-  needs its pack, and the manifest carries them, so an editor shows the text a
-  field inherits and lists the labels a merchant may override.
-- **Or check against a key set.** `validateThemeDefinition(theme, {
-  contentKeys })` reports every `contentKey` missing from it as
-  `unknown-content-key`; an explicit set wins over declared packs, and an empty
-  array reports every declared key.
-
-Both ways of consuming copy are legitimate, and the theme picks: a component can
-take per-field props, or read the whole pack and overlay the resolved values
-itself. The SDK deliberately ships neither helper — that would promote one
-theme's implementation choice into platform API.
-
-### Messages: placeholders and plurals
-
-`formatMessage(pack, key, values, { locale, formatNumber? })` is the SDK's one
-message rule — Shopify's locale-file model on the platform's own CLDR data
-(`Intl.PluralRules`), no message-format dependency:
-
-- `{name}` placeholders: every occurrence is filled, numbers are formatted for
-  the language (or by `formatNumber`), an unknown placeholder stays visible.
-- A plural message is flat keys, one per CLDR form — `cartItems_one`,
-  `cartItems_few`, `cartItems_other` — chosen by `values.count`; `_other` is
-  the fallback, and an explicit `_zero` is used for 0 in any language.
-- `pluralFormIssues(pack, locale)` lists the forms a pack is missing for its
-  language, or carries but never uses — run it over every pack in a test.
-- `messageForms(pack, key)` collects one message's keys to hand a browser
-  script; `pluralMessageKeys(pack)` names every plural message in a pack.
-
-Browser code imports the same functions from `@wocart/theme/messages`, an
-entry with nothing else in it.
-
-Packs stay `Record<string, string>`, so store overrides and the editor treat
-plural forms like any other key.
-
-## Capabilities are advisory
-
-`ComponentDefinition.capabilities` (`insertable`, `surfaces`) is metadata for an **editor/CLI insertion
-surface**, not renderer enforcement. Capabilities several components share go
-through `defineCapabilities`:
-
-```ts
-const ANY_PAGE = defineCapabilities({ surfaces: ["home", "product", "collection"] });
-const grid = defineComponent({ type: "product-grid", capabilities: ANY_PAGE, /* … */ });
-```
-
-A plain constant inferred from a literal (`{ surfaces: [...] as const }`) can
-make TypeScript read a definition's `fields` in two shapes when its `load`
-types its props from them; the error then names an unrelated field. Neither `parsePageData` nor
-`resolveInstance` consults it: a saved document containing a component marked
-`insertable: false` still renders, because the render path never second-guesses
-a document that was already saved. Any future enforcement belongs at insertion
-time, in the writer.
-
-## Compatibility
-
-Page data is a persisted format, and the reader is deliberately forgiving — but
-forgiveness is degradation with a report, not silent migration. There is no
-migration engine, by design; what follows is the whole policy:
-
-- **Envelope version.** `PageData.version` is `1`, and only `1` parses. Unknown
-  *top-level* keys are carried through verbatim (a writer may record metadata
-  without a version bump); unknown keys *inside* an instance are stripped.
-- **Removed or renamed component type.** The section reports `unknown-type` and
-  renders nothing; siblings survive. Never rename a `type` once documents
-  reference it — treat it as a breaking change for saved pages.
-- **Renamed, removed, or retyped field.** A stored value for an undeclared key
-  reports `unknown-prop` and is ignored; a value that fails the field's kind or
-  bounds reports `invalid-prop` and falls through the defaults chain
-  (instance → `content[contentKey]` → `field.default` → omit). A `required`
-  field with no resolvable value reports `missing-required-prop`.
-- **Removed slot or narrowed `allow` list.** Saved children that no longer fit
-  report `unknown-slot` or `disallowed-child` and are dropped. Widen a slot's
-  rules freely, but narrow them only as a breaking change for saved pages.
-- **Duplicate instance ids.** First wins depth-first; later duplicates are
-  dropped with `duplicate-id`. Generate stable unique ids at creation.
-- **What never breaks the page.** Any section-level failure preserves the rest
-  of the page. Only an envelope failure (`version`, `surface`, `sections`
-  shape) returns `page: null`.
-- **Theme versions.** The runtime accepts any non-empty `version` string;
-  stick to semver so the manifest validator stays quiet, and compare releases
-  with `diffThemeManifests`.
-- **Provenance.** A document may name the theme that wrote it,
-  `"theme": { "key", "version" }`; `validatePageData` reports `theme-mismatch`
-  for another theme's document, and a malformed one is dropped with
-  `invalid-provenance`.
-- **Features and renderers.** An older renderer strips instance keys it does
-  not know, so it would render a `hidden` section. The manifest's `sdkVersion`
-  says which renderer a theme ships; an editor writes `hidden` only for 1.5.0
-  or later.
-
-## Images
-
-`@wocart/theme/image-service` resizes every `<Image>` of a media-domain image
-with Cloudflare Image Resizing, on the media domain itself
-(`https://<media>/cdn-cgi/image/…`). The media domain is a Cloudflare zone
-wherever the storefront runs, so a storefront on Cloudflare and one on Vercel
-share the same URLs and edge cache. Any other image is served as it is; with no
-media domain, every image passes through.
-
-The domain is read on each image, not at build — one build serves every store.
-Bind it once:
-
-```ts
-// src/image-service.ts
-import { MEDIA_DOMAIN } from "astro:env/server";
-import { mediaImageService } from "@wocart/theme/image-service";
-export default mediaImageService(() => MEDIA_DOMAIN);
-```
-
-```js
-// astro.config.mjs
-image: { service: { entrypoint: "./src/image-service.ts" } },
-// @astrojs/cloudflare: imageService: "custom"   ·   @astrojs/vercel: leave imageService off
-```
-
-The media domain's zone needs Image Transformations on (Images →
-Transformations; included in the Free plan).
-
-## Testing your theme
-
-A theme proves it honors the contract with four checks in its own test suite:
-
-1. **The catalog assembles clean** — with its packs declared on the theme,
-   its default documents and presets are checked too:
-   `expect(validateThemeDefinition(theme)).toEqual([])`. To check something
-   of every component, iterate `componentsOf(theme)`, which lists them as
-   `ComponentDefinition`s.
-2. **The manifest survives a JSON round trip**:
-   `validateThemeManifest(JSON.parse(JSON.stringify(themeManifest(theme))))`
-   returns no issues.
-3. **Every shipped document validates**:
-   `validatePageData(theme, document, { content: pack, locales: [locale] })`
-   returns no issues for each default page the theme ships.
-4. **Every shipped document renders**: render each section through
-   `InstanceView` with Astro's Container API, one `createReadCache()` per page
-   and a stand-in `StoreClient`, and assert that `onIssue` receives nothing
-   unexpected:
-
-```ts
-import { experimental_AstroContainer as AstroContainer } from "astro/container";
-import { createReadCache, type RendererIssue } from "@wocart/theme/astro";
-import InstanceView from "@wocart/theme/astro/InstanceView.astro";
-import type { StoreClient } from "@wocart/storefront/server";
-
-const container = await AstroContainer.create();
-const reads = createReadCache();
-const issues: RendererIssue[] = [];
-const storefront = { products: { list: async () => products } } as unknown as StoreClient;
-
-for (const section of page.sections) {
-  await container.renderToString(InstanceView, {
-    props: { instance: section, theme, context, storefront, reads, onIssue: (i) => issues.push(i) },
-  });
-}
-expect(issues).toEqual([]);
-```
-
-Also test the degradations you rely on, such as a failing `load` still
-rendering base props.
-
-`createInstance` refuses to build an instance the reader would flag: wrong-typed
-values, unknown keys, and a `required` field with no value, default, or
-`contentKey`.
-
-## Versioning
-
-This package follows [semantic versioning](https://semver.org/): breaking
-changes ship only in a new major version and are listed in the
-[changelog](./CHANGELOG.md). The manifest's `contractVersion` and the page
-document's `version` are versioned separately, as described above.
+| `@wocart/theme` | definitions, validation, page documents, resolution, rich text, the manifest, languages and messages |
+| `@wocart/theme/astro` | the read cache, the manifest and styles endpoints, the preview target |
+| `@wocart/theme/astro/InstanceView.astro`, `Blocks.astro`, `Block.astro`, `ThemeStyles.astro` | the reference renderer |
+| `@wocart/theme/image-service` | `mediaImageService` — resizes store images through the store's media delivery |
+| `@wocart/theme/preview` | the preview bridge, for a theme's preview page |
+| `@wocart/theme/lifecycle`, `@wocart/theme/messages` | small browser modules: binding behaviour across page swaps, messages and plurals |
+
+[CHANGELOG.md](./CHANGELOG.md) lists every release.
 
 ## License