@wocart/theme 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,79 @@ All notable changes to `@wocart/theme` are recorded here. The package follows
 major version, and an export is marked `@deprecated` for at least one minor
 release before a major removes it.
 
+## 1.5.0 — 2026-10-18
+
+The editor-facing contract: everything a visual editor needs to discover and
+edit a theme, from its manifest alone.
+
+### Added
+
+- **Field kinds** `image` (`MediaReference`: the object key in the store's
+  media, never a URL, with per-language `alt`, size and focal point),
+  `richtext` (`RichTextDocument`, a closed JSON format with `formats`),
+  `list` (items `{ id, props }`, `min`/`max`, `itemLabel`, default items),
+  `product` and `category` (a handle or slug), and `step` on `number`.
+  `richTextToHtml`, `richTextToPlainText`, `RICH_TEXT_FORMATS`.
+- `checkFieldValue(field, value)`: the writer's strict check of one value.
+- `optionLabels` on a `select` field: the words an editor shows for each
+  option, per language; the stored value stays the option.
+- **Pages and templates**: `SurfaceSpec.pageType` (the storefront's page
+  types; a resource page type makes a reusable template), alternates
+  (`product.compact`), and `SurfaceSpec.document`, the theme's default.
+- `capabilities.surfaces` and `isInsertableOn(component, surface)`.
+- **Presets** on a component, built with `instantiatePreset`.
+- `ComponentInstance.hidden`: kept in the document, not rendered.
+- `PageData.theme` provenance; issue codes `invalid-provenance` and
+  `theme-mismatch`.
+- `ThemeDefinition.content`: the theme's packs; every `contentKey` must exist
+  in each, and the manifest carries them.
+- **Document operations**: `insertInstance`, `removeInstance`,
+  `moveInstance`, `duplicateInstance`, `setInstanceProps`,
+  `setInstanceHidden`, `findInstance`, `newInstanceId`, and `checkPageData`,
+  the strict check of a whole document before saving it.
+- `manifestCatalog(manifest)`: the catalog every data function takes, from a
+  manifest — an editor never needs the theme's code.
+- `ThemeManifest.sdkVersion`, `content` and per-component `presets`;
+  `THEME_SDK_VERSION`.
+- `themeManifestEndpoint(theme)` (`@wocart/theme/astro`) and
+  `THEME_MANIFEST_PATH`: the manifest as a prerendered build artifact; an
+  invalid manifest fails the build.
+- `diffThemeManifests(previous, next)`: which changes between two versions of
+  a theme are breaking for saved data, and which only add.
+- **Preview**: `ThemeDefinition.preview` and `ThemeManifest.preview`;
+  `THEME_PREVIEW_PATH`, `PREVIEW_PROTOCOL_VERSION` and the protocol's message
+  types; `<InstanceView preview>` marks each instance with comments
+  (`previewStartMarker`, `previewEndMarker`, `parsePreviewMarker`); and the
+  `@wocart/theme/preview` entry, `startPreviewBridge` and
+  `PREVIEW_SECTION_LOAD_EVENT`, the preview page's side of the protocol.
+
+### Changed
+
+- `FieldKind`, `FieldDefinition`, `PageDataIssueCode`,
+  `ThemeDefinitionIssueCode` and `ThemeManifestIssueCode` have new members: an
+  exhaustive `switch` over them needs the new cases.
+- `ComponentSpec.presets` and `ThemeManifest.content` are always present in a
+  manifest (`[]` and `{}` when none); `validateThemeManifest` normalizes a
+  manifest made before 1.5.0 the same way.
+- An empty `content` map declares no packs, as an absent one does.
+- A manifest made before 1.5.0 reads as `preview: false`.
+
+## 1.4.0 — 2026-10-18
+
+### Added
+
+- `@wocart/theme/image-service`: `mediaImageService(() => mediaDomain)`, an
+  Astro image service that resizes media-domain images with Cloudflare Image
+  Resizing on the media domain itself, so a storefront on Cloudflare and one
+  on Vercel get the same URLs and edge cache. Other images are served as they
+  are; the domain is read per image, so one build serves every store.
+  `mediaImageParams` maps an Astro transform to the resizing options (Astro's
+  `fit` in Cloudflare's words).
+
+### Changed
+
+- The `@wocart/storefront` peer range is now `^1.14.0` (`mediaImageUrl`).
+
 ## 1.3.0 — 2026-10-17
 
 ### Added

package/README.md

@@ -14,6 +14,10 @@ Astro renderer.
   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
@@ -34,9 +38,11 @@ Node 22.12 or newer.
 
 | Import | What it holds |
 | --- | --- |
-| `@wocart/theme` | definitions, validation, page documents, resolution, the manifest, languages and messages — framework-neutral |
-| `@wocart/theme/astro` | `createReadCache` and the `RendererIssue` type |
+| `@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), the preview markers and the `RendererIssue` type |
 | `@wocart/theme/astro/InstanceView.astro` | the reference renderer component |
+| `@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)) |
 
 ## Use
 
@@ -112,18 +118,91 @@ defineComponent({
 | 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 |
+| `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 |
+| `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`; `min`/`max`; `itemLabel` names the item field an editor shows; default items carry their own ids |
 
 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.
+
+### 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.
@@ -190,6 +269,157 @@ A component declares where children may go; the document says what is there.
 displaces an allowed one. The rules travel in the manifest, so an editor can
 offer only valid insertions.
 
+## 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.
+
+## 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.
+
+## 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` or not available on the
+document's surface, a slot that does not take it, an index out of range, a
+cycle, an id already in the document, and a value its field refuses.
+`checkPageData(theme, page)` is the strict check of a whole document before
+saving it; `findInstance` locates an instance.
+
+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`):
+
+| The editor sends | The page answers |
+| --- | --- |
+| — | `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 is dropped |
+| `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 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`). 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.
+
 ## Theme manifest (serializable catalogue)
 
 A `ThemeDefinition` mixes data (types, fields, defaults) with runtime (the live
@@ -204,8 +434,10 @@ 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)
-//   components: { hero: { type, label, group, fields, slots, capabilities } },
+//   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(
@@ -243,9 +475,35 @@ What a validated manifest promises a consumer:
   `validateThemeDefinition` and `validateThemeManifest`, so a manifest derived
   from a valid theme always validates clean.
 
-What it deliberately excludes: implementations and loaders (runtime-only),
-content-pack values (only `contentKey` references travel — the pack itself stays
-theme-owned), and any write/editing affordance.
+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
 
@@ -376,10 +634,13 @@ or a copy system — it only reads the resolved pack the request hands it.
 - **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`.
-- **Typos are checkable, not inferred.** Pass the pack's key set to
-  `validateThemeDefinition(theme, { contentKeys })` and every `contentKey` that
-  is not in it is reported as `unknown-content-key`. Optional and additive:
-  with no options the validator behaves exactly as before, and passing an empty
+- **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
@@ -408,7 +669,7 @@ plural forms like any other key.
 
 ## Capabilities are advisory
 
-`ComponentDefinition.capabilities` is metadata for an **editor/CLI insertion
+`ComponentDefinition.capabilities` (`insertable`, `surfaces`) is metadata for an **editor/CLI insertion
 surface**, not renderer enforcement. Neither `parsePageData` nor
 `resolveInstance` consults it: a saved document containing a component marked
 `insertable: false` still renders, because the render path never second-guesses
@@ -441,15 +702,52 @@ migration engine, by design; what follows is the whole policy:
   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 future tooling can
-  reason about upgrades.
+  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**:
-   `expect(validateThemeDefinition(theme, { contentKeys: Object.keys(pack) })).toEqual([])`.
+1. **The catalog assembles clean** — with its packs declared on the theme,
+   its default documents and presets are checked too:
+   `expect(validateThemeDefinition(theme)).toEqual([])`.
 2. **The manifest survives a JSON round trip**:
    `validateThemeManifest(JSON.parse(JSON.stringify(themeManifest(theme))))`
    returns no issues.

package/dist/astro/InstanceView.astro

@@ -3,7 +3,7 @@
  * The reference renderer: one recursive component that turns a page-data
  * instance into the real theme component it names.
  *
- *   instance → definition (catalog) → resolveInstance (chain + gating)
+ *   instance (skipped when `hidden`) → definition (catalog) → resolveInstance (chain + gating)
  *            → definition.load (optional, server-only, degrading)
  *            → <Component {...props}> with children + one named slot
  *
@@ -15,7 +15,7 @@
  * Server-only. No hydration, no directives, no second component system —
  * the theme's own `.astro` files do all rendering.
  */
-import { resolveInstance, type RendererIssue } from "./index.js";
+import { previewEndMarker, previewStartMarker, resolveInstance, type RendererIssue } from "./index.js";
 import type {
   ComponentInstance,
   ReadCache,
@@ -32,9 +32,14 @@ interface Props {
   reads: ReadCache;
   /** Overrides the default reporter (console.warn with a stable prefix). */
   onIssue?: ((issue: RendererIssue) => void) | undefined;
+  /**
+   * A preview render: each instance's nodes are bracketed with marker
+   * comments an editor's bridge reads. Never set for a shopper's page.
+   */
+  preview?: boolean | undefined;
 }
 
-const { instance, theme, context, storefront, reads, onIssue } = Astro.props as Props;
+const { instance, theme, context, storefront, reads, onIssue, preview = false } = Astro.props as Props;
 
 const report = (issue: RendererIssue): void => {
   if (onIssue) {
@@ -44,10 +49,13 @@ const report = (issue: RendererIssue): void => {
   }
 };
 
-const definition = Object.hasOwn(theme.components, instance.type)
+// A hidden instance stays in the document and renders nothing: no lookup,
+// no `load`, no children.
+const hidden = instance.hidden === true;
+const definition = !hidden && Object.hasOwn(theme.components, instance.type)
   ? theme.components[instance.type]
   : undefined;
-if (definition === undefined) {
+if (definition === undefined && !hidden) {
   report({
     code: "unknown-type",
     message: `"${instance.type}" is not in the theme catalog; nothing rendered`,
@@ -134,7 +142,12 @@ if (definition !== undefined) {
     }
   }
 }
+// Marker text is the protocol's own encoding: ids and types are URI-encoded,
+// so no saved value can close the comment.
+const startMarker = preview ? `<!--${previewStartMarker(instance)}-->` : "";
+const endMarker = preview ? `<!--${previewEndMarker(instance)}-->` : "";
 ---
+{preview && <Fragment set:html={startMarker} />}
 {
   Component !== undefined ? (
     <Component {...renderProps}>
@@ -146,6 +159,7 @@ if (definition !== undefined) {
           storefront={storefront}
           reads={reads}
           onIssue={onIssue}
+          preview={preview}
         />
       ))}
       {firstNamedSlotName !== undefined && (
@@ -158,6 +172,7 @@ if (definition !== undefined) {
               storefront={storefront}
               reads={reads}
               onIssue={onIssue}
+              preview={preview}
             />
           ))}
         </Fragment>
@@ -165,3 +180,4 @@ if (definition !== undefined) {
     </Component>
   ) : null
 }
+{preview && <Fragment set:html={endMarker} />}

package/dist/astro/index.d.ts

@@ -1,21 +1,22 @@
+import type { PageDataIssueCode, ReadCache, ThemeDefinition } from "../types.js";
+export { resolveInstance } from "../instances.js";
+export { previewEndMarker, previewStartMarker } from "../preview-protocol.js";
 /**
- * `@wocart/theme/astro` — the Astro-specific side of the theme SDK.
+ * The theme's manifest as a prerendered endpoint, the file a release and an
+ * editor read (`THEME_MANIFEST_PATH`):
  *
- * Exports:
- * - `createReadCache` — the per-render read sharing the contract requires
- *   (one read per resource per render).
- * - `RendererIssue` — the renderer-specific degradations, reportable via
- *   `InstanceView`'s `onIssue` prop.
- * - `resolveInstance` — re-exported so `InstanceView.astro`'s co-located
- *   import (`./index.js`) resolves identically in the dev source layout and in
- *   the published `dist/astro` layout. Same function as the
- *   root export — never a second implementation.
+ * ```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 renderer component itself:
- * `@wocart/theme/astro/InstanceView.astro`.
+ * The manifest is derived and validated when the module loads, so a theme
+ * whose manifest is invalid fails its build instead of shipping it.
  */
-import type { PageDataIssueCode, ReadCache } from "../types.js";
-export { resolveInstance } from "../instances.js";
+export declare function themeManifestEndpoint(theme: ThemeDefinition): () => Response;
 /** One renderer-specific degradation, reported through `onIssue`. */
 export interface RendererIssue {
     code: PageDataIssueCode | "missing-component" | "load-failed" | "multiple-slots-unsupported";

package/dist/astro/index.js

@@ -1,4 +1,48 @@
+/**
+ * `@wocart/theme/astro` — the Astro-specific side of the theme SDK.
+ *
+ * Exports:
+ * - `createReadCache` — the per-render read sharing the contract requires
+ *   (one read per resource per render).
+ * - `themeManifestEndpoint` — the manifest as a prerendered build artifact.
+ * - `RendererIssue` — the renderer-specific degradations, reportable via
+ *   `InstanceView`'s `onIssue` prop.
+ * - `resolveInstance` — re-exported so `InstanceView.astro`'s co-located
+ *   import (`./index.js`) resolves identically in the dev source layout and in
+ *   the published `dist/astro` layout. Same function as the
+ *   root export — never a second implementation.
+ *
+ * The renderer component itself:
+ * `@wocart/theme/astro/InstanceView.astro`.
+ */
+import { themeManifest, validateThemeManifest } from "../manifest.js";
 export { resolveInstance } from "../instances.js";
+export { previewEndMarker, previewStartMarker } from "../preview-protocol.js";
+/**
+ * The theme's manifest as a prerendered endpoint, the file a release and an
+ * editor read (`THEME_MANIFEST_PATH`):
+ *
+ * ```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 derived and validated when the module loads, so a theme
+ * whose manifest is invalid fails its build instead of shipping it.
+ */
+export function themeManifestEndpoint(theme) {
+    const manifest = themeManifest(theme);
+    const checked = validateThemeManifest(JSON.parse(JSON.stringify(manifest)));
+    if (checked.manifest === null) {
+        const issues = checked.issues.map((issue) => `${issue.path || "<manifest>"} ${issue.code}: ${issue.message}`);
+        throw new Error(`[@wocart/theme] the theme manifest is invalid:\n  ${issues.join("\n  ")}`);
+    }
+    const body = JSON.stringify(manifest);
+    return () => new Response(body, { headers: { "Content-Type": "application/json; charset=utf-8" } });
+}
 /**
  * The per-render `ReadCache`: the first call for a key
  * runs the loader; later calls in the same render reuse the in-flight or