@wocart/theme 1.5.0 → 2.0.0

package/CHANGELOG.md

@@ -5,6 +5,116 @@ 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.
 
+## 2.0.0 — 2026-10-20
+
+Blocks: components place other components inside them, some fixed by the
+theme's code and some required, and every product page keeps an order form.
+Style: a merchant changes a section's spacing, layout, size and colors, as
+steps and color schemes the SDK turns into CSS. Areas: a header and a footer
+edited once for every page. Fields: hand-picked products and collections,
+display hints, and fields that show only when they apply.
+
+### Breaking
+
+What a 1.x theme or editor may need to change:
+
+- A surface whose `pageType` is `product` must guarantee an order form:
+  require a section that places a component with `role: "order-form"`
+  through fixed or required blocks. A theme without a product surface is
+  unaffected.
+- `blocks` is a reserved prop: no component field may use that key.
+- The reader drops what goes past `THEME_LIMITS` (50 per slot, 50 sections,
+  1,000 instances, 6 levels) and reports `limit-exceeded`.
+- An editor on 1.x rejects a manifest that uses the new field kinds
+  (`style`, `colorScheme`, `colorSchemes`, `productList`, `collectionList`):
+  move an editor to 2.0 before a theme uses them.
+- `ThemeManifest.areas` is always present (a manifest without it reads as
+  none), `InstanceLocation` carries `depth`, and a list item cannot hold
+  `colorSchemes`.
+
+### Added
+
+- Field kinds `style` (panels `spacing`, `layout`, `size`; a value per
+  breakpoint), `colorScheme` and `colorSchemes` (the store's schemes, a theme
+  setting). `ThemeDefinition.style` gives the platform's steps (`s0`–`s12`)
+  and widths their sizes; the manifest carries them.
+- `styleClasses`, `schemeClass`, `themeStyleSheet`, `colorSchemeCss`,
+  `contrastRatio`, `STYLE_BREAKPOINTS`, `STYLE_STEPS`, `STYLE_WIDTHS`,
+  `STYLE_PANELS`, `COLOR_ROLES`, `COLOR_SCHEMES_MAX`, `THEME_STYLES_PATH`;
+  `themeStylesEndpoint` and `@wocart/theme/astro/ThemeStyles.astro`, which
+  adds its inline sheet's hash to a page's Content-Security-Policy.
+- `checkThemeSettings` refuses a scheme picker naming a scheme the store does
+  not have, and a style the theme gives no size; the manifest diff reports a
+  size or panel a theme stops offering as breaking.
+- Areas (`ThemeDefinition.areas`): the parts every page shares, each a
+  document stored as the surface `area:<key>` (`areaSurface`), with
+  `required` and `max`; the manifest carries them and its diff reports an
+  area removed as breaking.
+- Field kinds `productList` and `collectionList`; `display` on `select`
+  (dropdown, radio, segmented) and `number` (input, slider); `inline` on
+  `richtext`, and `richTextToHtml`'s `inline` option.
+- `visibleIf` on any field and `isFieldVisible`, `CONDITION_DEPTH`.
+- `isPreview(blocks)`, for a placeholder a section draws in an editor's
+  preview only.
+- The preview `move` and `restore` patches take `parent`, so reordering
+  blocks inside a component shows at once.
+
+- `placement` on a component: `"section"`, `"block"` or `"both"`, enforced by
+  the document operations.
+- `blocks`, given by the renderer to every component, and the components
+  `@wocart/theme/astro/Blocks.astro` and `@wocart/theme/astro/Block.astro`
+  that place a slot's blocks and a fixed block where the component wants them
+  — any number of slots, where pushed content can fill only one named slot.
+  `hasBlocks(blocks, slot)` and the `BlocksHandle` type.
+- Fixed blocks (`fixed` on a definition, `fixed` on an instance): placed by
+  code, never removed, moved, copied or hidden, rendered with their defaults
+  when a document does not store them. `fixedBlockId`.
+- Required blocks (`required` on a slot or a surface, with `min` and `max`)
+  and `max` on a slot or surface: a required block may move but is never lost,
+  and a document that lacks one renders it anyway.
+- `role: "order-form"` and the rule that every product surface guarantees an
+  order form (`order-form-not-guaranteed`).
+- `THEME_LIMITS`: 50 instances per slot, 50 sections per surface, 1,000
+  instances per document, 6 levels of nesting.
+- `completePage(theme, page)`: a document with everything it must hold, for
+  an editor to open.
+- `resolveSurfaceDocument(theme, surface, saved)`: the saved document or the
+  theme's default for any surface, completed — the policy a theme used to
+  write itself.
+- `removeInstance(theme, page, id)` and `setInstanceHidden(theme, page, id,
+  hidden)`, which keep required blocks.
+- Issue codes `unknown-fixed`, `fixed-type-mismatch`,
+  `missing-required-block`, `limit-exceeded` (reading); `fixed-block`,
+  `required-block`, `not-placeable`, `limit-exceeded` (writing);
+  `invalid-placement`, `invalid-fixed`, `invalid-role`,
+  `order-form-not-guaranteed` (assembly).
+
+### Changed
+
+- The reader drops what goes past the limits, reporting it; documents
+  written so far are far below them.
+- `InstanceLocation` carries `depth`, and `fixed` for a fixed block.
+- A default document written for another surface reports only that.
+
+### Deprecated
+
+- `removeInstance(page, id)` and `setInstanceHidden(page, id, hidden)`: pass
+  the theme first.
+
+## 1.6.0 — 2026-10-19
+
+An editor's change shows on the preview page at once.
+
+### Added
+
+- The preview protocol's `patch` message (`PreviewPatch`): a change the
+  editor has already made — move, duplicate, remove and restore a section,
+  hide or show one, a field's text — shown by the preview bridge on the page
+  as it stands, before the render that follows it. Patches are hints; the
+  render stays the page's truth, and a render already on its way when a
+  patch arrives is dropped so it cannot undo it. A page that does not know
+  patches ignores them. The protocol version stays 1.
+
 ## 1.5.0 — 2026-10-18
 
 The editor-facing contract: everything a visual editor needs to discover and

package/README.md

@@ -39,8 +39,10 @@ Node 22.12 or newer.
 | 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), the preview markers and the `RendererIssue` type |
+| `@wocart/theme/astro` | `createReadCache`, `themeManifestEndpoint` (the manifest as a build artifact), `hasBlocks`, `isPreview`, `THEME_LIMITS`, `themeStylesEndpoint`, 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)) |
 
@@ -129,7 +131,32 @@ defineComponent({
 | `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 |
+| `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
@@ -269,6 +296,144 @@ 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.
 
+## 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. 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
@@ -297,6 +462,26 @@ 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
@@ -337,11 +522,21 @@ if (!edit.ok) console.log(edit.issue.code, edit.issue.message); // "not-availabl
 
 `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.
+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
@@ -406,15 +601,28 @@ framing window, with `source: "wocart-editor"` and the protocol's `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 |
+| `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`). When the bridge replaces the whole
+dispatched on `document` with `detail.id`) — also for a section a patch
+copied, restored or showed again. 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
@@ -576,8 +784,15 @@ policy is:
    reported through `onIssue`.
 5. **An empty saved document** → honor it. A page the merchant emptied renders empty.
 
-The SDK does not ship this policy as a function, because the shipped default
-document is theme content.
+`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
 

package/dist/astro/Block.astro

@@ -0,0 +1,29 @@
+---
+/**
+ * One fixed block of the component that received `blocks`, where its code
+ * places it: the stored block, or one with its defaults when the document
+ * does not store it. `name` is one the definition's `fixed` lists.
+ *
+ *   <Block of={blocks} name="buy-box" />
+ */
+import InstanceView from "./InstanceView.astro";
+import type { BlocksHandle } from "./index.js";
+
+interface Props {
+  of: BlocksHandle;
+  name: string;
+}
+
+const { of, name } = Astro.props as Props;
+const instance = Object.hasOwn(of.fixed, name) ? of.fixed[name] : undefined;
+if (instance === undefined) {
+  const issue = {
+    code: "unknown-fixed" as const,
+    message: `"${of.owner.type}" places no fixed block "${name}"; declare it in the definition's \`fixed\``,
+    instanceId: of.owner.id,
+  };
+  if (of.render.onIssue) of.render.onIssue(issue);
+  else console.warn(`[@wocart/theme/astro] ${issue.code}: ${issue.message}`);
+}
+---
+{instance !== undefined && <InstanceView instance={instance} {...of.render} />}

package/dist/astro/Blocks.astro

@@ -0,0 +1,23 @@
+---
+/**
+ * The blocks of one slot of the component that received `blocks`, in order,
+ * each through `InstanceView` — so `load`, issues, hidden blocks and preview
+ * markers work the same at every depth. A component may place any
+ * number of its slots this way.
+ *
+ *   <Blocks of={blocks} slot="media" />
+ *   <Blocks of={blocks} />            (the default slot)
+ */
+import InstanceView from "./InstanceView.astro";
+import type { BlocksHandle } from "./index.js";
+
+interface Props {
+  of: BlocksHandle;
+  /** Absent: the default slot. */
+  slot?: string | undefined;
+}
+
+const { of, slot = "default" } = Astro.props as Props;
+const list = Object.hasOwn(of.slots, slot) ? of.slots[slot]! : [];
+---
+{list.map((instance) => <InstanceView instance={instance} {...of.render} />)}

package/dist/astro/InstanceView.astro

@@ -5,17 +5,23 @@
  *
  *   instance (skipped when `hidden`) → definition (catalog) → resolveInstance (chain + gating)
  *            → definition.load (optional, server-only, degrading)
- *            → <Component {...props}> with children + one named slot
+ *            → <Component {...props} blocks> with children + one named slot
  *
- * Named slots: the Astro compiler lifts the first slot-attribute expression of
- * a dynamic child expression into the slots-object key, evaluated in component
- * scope — so exactly ONE named slot per instance can be routed generically.
- * Extra named slots with content are reported, never silently dropped.
+ * Blocks: every component receives `blocks`, and places any slot's
+ * blocks with `<Blocks of={blocks} slot>` and its fixed blocks with
+ * `<Block of={blocks} name>` — as many slots as it declares.
+ *
+ * Pushed slots, for components that use `<slot />`: the Astro compiler lifts
+ * the first slot-attribute expression of a dynamic child expression into the
+ * slots-object key, evaluated in component scope — so exactly ONE named slot
+ * per instance can be pushed generically. Extra named slots with content are
+ * reported, never silently dropped. Slot content renders lazily, so a
+ * component that pulls its blocks never renders what was pushed.
  *
  * Server-only. No hydration, no directives, no second component system —
  * the theme's own `.astro` files do all rendering.
  */
-import { previewEndMarker, previewStartMarker, resolveInstance, type RendererIssue } from "./index.js";
+import { THEME_LIMITS, previewEndMarker, previewStartMarker, resolveInstance, type BlocksHandle, type RendererIssue } from "./index.js";
 import type {
   ComponentInstance,
   ReadCache,
@@ -37,9 +43,11 @@ interface Props {
    * comments an editor's bridge reads. Never set for a shopper's page.
    */
   preview?: boolean | undefined;
+  /** Levels below the page's sections; past `THEME_LIMITS.depth` nothing renders. */
+  depth?: number | undefined;
 }
 
-const { instance, theme, context, storefront, reads, onIssue, preview = false } = Astro.props as Props;
+const { instance, theme, context, storefront, reads, onIssue, preview = false, depth = 0 } = Astro.props as Props;
 
 const report = (issue: RendererIssue): void => {
   if (onIssue) {
@@ -52,10 +60,18 @@ const report = (issue: RendererIssue): void => {
 // 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)
+const tooDeep = depth > THEME_LIMITS.depth;
+if (tooDeep && !hidden) {
+  report({
+    code: "limit-exceeded",
+    message: `"${instance.type}" is nested more than ${THEME_LIMITS.depth} levels below a section; nothing rendered`,
+    instanceId: instance.id,
+  });
+}
+const definition = !hidden && !tooDeep && Object.hasOwn(theme.components, instance.type)
   ? theme.components[instance.type]
   : undefined;
-if (definition === undefined && !hidden) {
+if (definition === undefined && !hidden && !tooDeep) {
   report({
     code: "unknown-type",
     message: `"${instance.type}" is not in the theme catalog; nothing rendered`,
@@ -123,8 +139,14 @@ if (definition !== undefined) {
       }
     }
 
+    const blocks: BlocksHandle = {
+      owner: { id: instance.id, type: instance.type },
+      slots: { ...resolved.slots, default: resolved.children },
+      fixed: resolved.fixed,
+      render: { theme, context, storefront, reads, onIssue, preview, depth: depth + 1 },
+    };
     Component = definition.component as RenderableComponent;
-    renderProps = { ...resolved.props, ...loaded };
+    renderProps = { ...resolved.props, ...loaded, blocks };
     children = resolved.children;
 
     const namedEntries = Object.entries(resolved.slots);
@@ -160,6 +182,7 @@ const endMarker = preview ? `<!--${previewEndMarker(instance)}-->` : "";
           reads={reads}
           onIssue={onIssue}
           preview={preview}
+          depth={depth + 1}
         />
       ))}
       {firstNamedSlotName !== undefined && (
@@ -173,6 +196,7 @@ const endMarker = preview ? `<!--${previewEndMarker(instance)}-->` : "";
               reads={reads}
               onIssue={onIssue}
               preview={preview}
+              depth={depth + 1}
             />
           ))}
         </Fragment>

package/dist/astro/ThemeStyles.astro

@@ -0,0 +1,34 @@
+---
+/**
+ * The theme's style in a page's <head>: the stylesheet of style classes
+ * (served at `THEME_STYLES_PATH` by `themeStylesEndpoint`) and the store's
+ * color schemes as one small inline sheet. On a page with a
+ * Content-Security-Policy, the inline sheet's hash joins the policy, so
+ * `style-src` needs no 'unsafe-inline'.
+ *
+ *   <ThemeStyles schemes={settings.colorSchemes} />
+ */
+import { THEME_STYLES_PATH, colorSchemeCss } from "./index.js";
+import type { ColorScheme } from "../types.js";
+
+interface Props {
+  schemes?: readonly ColorScheme[] | undefined;
+  /** `false` when the theme bundles the style classes itself. */
+  stylesheet?: boolean | undefined;
+}
+
+const { schemes, stylesheet = true } = Astro.props as Props;
+const css = colorSchemeCss(schemes);
+if (css.length > 0) {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(css)));
+  const hash = `sha256-${btoa(String.fromCharCode(...digest))}`;
+  const csp = (Astro as unknown as { csp?: { insertStyleHash?: (hash: string) => void } }).csp;
+  try {
+    csp?.insertStyleHash?.(hash);
+  } catch {
+    // The page renders without a policy.
+  }
+}
+---
+{stylesheet && <link rel="stylesheet" href={THEME_STYLES_PATH} />}
+{css.length > 0 && <style is:inline set:html={css} />}

package/dist/astro/index.d.ts

@@ -1,5 +1,8 @@
-import type { PageDataIssueCode, ReadCache, ThemeDefinition } from "../types.js";
+import type { ComponentInstance, PageDataIssueCode, ReadCache, ThemeDefinition, ThemeRenderContext } from "../types.js";
+import type { StoreClient } from "@wocart/storefront/server";
 export { resolveInstance } from "../instances.js";
+export { THEME_LIMITS } from "../blocks.js";
+export { THEME_STYLES_PATH, colorSchemeCss } from "../style.js";
 export { previewEndMarker, previewStartMarker } from "../preview-protocol.js";
 /**
  * The theme's manifest as a prerendered endpoint, the file a release and an
@@ -17,6 +20,51 @@ export { previewEndMarker, previewStartMarker } from "../preview-protocol.js";
  * whose manifest is invalid fails its build instead of shipping it.
  */
 export declare function themeManifestEndpoint(theme: ThemeDefinition): () => Response;
+/**
+ * The stylesheet of the theme's style classes as a prerendered endpoint, the
+ * file `<ThemeStyles>` links (`THEME_STYLES_PATH`):
+ *
+ * ```ts
+ * // src/pages/wocart-styles.css.ts
+ * import { themeStylesEndpoint } from "@wocart/theme/astro";
+ * import { theme } from "../theme/theme";
+ * export const prerender = true;
+ * export const GET = themeStylesEndpoint(theme);
+ * ```
+ */
+export declare function themeStylesEndpoint(theme: ThemeDefinition): () => Response;
+/**
+ * What the renderer gives every component as `blocks`: its instance's slots
+ * (the default slot under `"default"`), its fixed blocks by name — both
+ * already gated and completed — and what rendering them needs. A component
+ * passes it to `<Blocks>` and `<Block>`; it never needs to read it.
+ */
+export interface BlocksHandle {
+    owner: {
+        id: string;
+        type: string;
+    };
+    slots: Readonly<Record<string, readonly ComponentInstance[]>>;
+    fixed: Readonly<Record<string, ComponentInstance>>;
+    render: {
+        theme: ThemeDefinition;
+        context: ThemeRenderContext;
+        storefront: StoreClient;
+        reads: ReadCache;
+        onIssue: ((issue: RendererIssue) => void) | undefined;
+        preview: boolean;
+        depth: number;
+    };
+}
+/**
+ * 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.
+ */
+export declare function isPreview(blocks: BlocksHandle | undefined): boolean;
+/** Whether a slot holds a block that renders (not hidden), so a component can leave out an empty wrapper. */
+export declare function hasBlocks(blocks: BlocksHandle | undefined, slot?: string): boolean;
 /** One renderer-specific degradation, reported through `onIssue`. */
 export interface RendererIssue {
     code: PageDataIssueCode | "missing-component" | "load-failed" | "multiple-slots-unsupported";