@wocart/theme 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,480 @@
-# Temporary Holding Version
+# @wocart/theme
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+- **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.
+- **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.
+
+## Install
+
+```sh
+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.
+
+## Entry points
+
+| 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/astro/InstanceView.astro` | the reference renderer component |
+
+## Use
+
+```ts
+import {
+  defineComponent,
+  defineTheme,
+  parsePageData,
+  validateThemeDefinition,
+} from "@wocart/theme";
+import Hero from "./components/Hero.astro";
+
+const hero = defineComponent({
+  type: "hero",
+  component: Hero, // the real .astro component — untouched
+  label: "Hero",
+  fields: [{ key: "heroTitle", kind: "text", label: "Title", contentKey: "heroTitle" }],
+  capabilities: { insertable: true },
+});
+
+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`.
+
+## 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 |
+| `boolean` | boolean | |
+| `select` | one of `options` | `default` must be one of the options |
+| `color` | `#rgb` or `#rrggbb` | anything else (a color name, `url(…)`) is rejected at assembly and reported on read |
+| `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 |
+
+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.
+
+## 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.
+
+## 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",
+//   surfaces: [],                       // declared surfaces (possibly none)
+//   components: { hero: { type, label, group, fields, slots, capabilities } },
+// } — 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-pack values (only `contentKey` references travel — the pack itself stays
+theme-owned), and any write/editing affordance.
+
+### 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.
+
+The SDK does not ship this policy as a function, because the shipped default
+document is theme content.
+
+## 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" — typed: InferSettings<typeof theme>
+```
+
+- **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`.
+- **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
+  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.
+
+Packs stay `Record<string, string>`, so store overrides and the editor treat
+plural forms like any other key.
+
+## Capabilities are advisory
+
+`ComponentDefinition.capabilities` 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
+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 future tooling can
+  reason about upgrades.
+
+## 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([])`.
+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.
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE).

package/dist/astro/InstanceView.astro

@@ -0,0 +1,167 @@
+---
+/**
+ * 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)
+ *            → definition.load (optional, server-only, degrading)
+ *            → <Component {...props}> 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.
+ *
+ * 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 type {
+  ComponentInstance,
+  ReadCache,
+  ThemeDefinition,
+  ThemeRenderContext,
+} from "../types.js";
+import type { StoreClient } from "@wocart/storefront/server";
+
+interface Props {
+  instance: ComponentInstance;
+  theme: ThemeDefinition;
+  context: ThemeRenderContext;
+  storefront: StoreClient;
+  reads: ReadCache;
+  /** Overrides the default reporter (console.warn with a stable prefix). */
+  onIssue?: ((issue: RendererIssue) => void) | undefined;
+}
+
+const { instance, theme, context, storefront, reads, onIssue } = Astro.props as Props;
+
+const report = (issue: RendererIssue): void => {
+  if (onIssue) {
+    onIssue(issue);
+  } else {
+    console.warn(`[@wocart/theme/astro] ${issue.code}: ${issue.message}`);
+  }
+};
+
+const definition = Object.hasOwn(theme.components, instance.type)
+  ? theme.components[instance.type]
+  : undefined;
+if (definition === undefined) {
+  report({
+    code: "unknown-type",
+    message: `"${instance.type}" is not in the theme catalog; nothing rendered`,
+    instanceId: instance.id,
+  });
+}
+
+// The catalog holds the real component reference as `unknown` (the core is
+// framework-neutral). Here it is narrowed to the shape Astro renders.
+type RenderableComponent = (props: Record<string, unknown>) => unknown;
+
+let Component: RenderableComponent | undefined;
+let renderProps: Record<string, unknown> = {};
+let children: ComponentInstance[] = [];
+let firstNamedSlotName: string | undefined;
+let firstNamedSlotChildren: ComponentInstance[] = [];
+
+if (definition !== undefined) {
+  // Only object/function references reach `<Component>`: `null` keeps its
+  // historical `missing-component` degradation, and primitives (usually a
+  // string left behind instead of an import) are reported rather than rendered
+  // into a meaningless tag or thrown at render time.
+  const reference = definition.component;
+  if (
+    reference === undefined ||
+    reference === null ||
+    (typeof reference !== "object" && typeof reference !== "function")
+  ) {
+    report({
+      code: "missing-component",
+      message: `"${instance.type}" has no usable component reference; nothing rendered`,
+      instanceId: instance.id,
+    });
+  } else {
+    const resolved = resolveInstance(definition, instance, {
+      content: context.content,
+      locales: [context.locale, ...(context.fallbackLocales ?? [])],
+    });
+    for (const issue of resolved.issues) {
+      report({
+        code: issue.code,
+        message: issue.message,
+        instanceId: instance.id,
+        path: issue.path,
+      });
+    }
+
+    let loaded: Record<string, unknown> = {};
+    if (definition.load !== undefined) {
+      try {
+        loaded = await definition.load({
+          storefront,
+          context,
+          props: resolved.props,
+          reads,
+        });
+      } catch (error) {
+        report({
+          code: "load-failed",
+          message: `load failed for "${instance.type}": ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+          instanceId: instance.id,
+        });
+      }
+    }
+
+    Component = definition.component as RenderableComponent;
+    renderProps = { ...resolved.props, ...loaded };
+    children = resolved.children;
+
+    const namedEntries = Object.entries(resolved.slots);
+    const first = namedEntries[0];
+    if (first !== undefined) {
+      firstNamedSlotName = first[0];
+      firstNamedSlotChildren = first[1];
+    }
+    for (const [name] of namedEntries.slice(1)) {
+      report({
+        code: "multiple-slots-unsupported",
+        message: `"${instance.type}" has content for named slot "${name}", but the reference renderer fills one named slot per component (Astro compiler constraint); it was not rendered`,
+        instanceId: instance.id,
+      });
+    }
+  }
+}
+---
+{
+  Component !== undefined ? (
+    <Component {...renderProps}>
+      {children.map((child) => (
+        <Astro.self
+          instance={child}
+          theme={theme}
+          context={context}
+          storefront={storefront}
+          reads={reads}
+          onIssue={onIssue}
+        />
+      ))}
+      {firstNamedSlotName !== undefined && (
+        <Fragment slot={firstNamedSlotName}>
+          {firstNamedSlotChildren.map((child) => (
+            <Astro.self
+              instance={child}
+              theme={theme}
+              context={context}
+              storefront={storefront}
+              reads={reads}
+              onIssue={onIssue}
+            />
+          ))}
+        </Fragment>
+      )}
+    </Component>
+  ) : null
+}

package/dist/astro/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `@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).
+ * - `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 type { PageDataIssueCode, ReadCache } from "../types.js";
+export { resolveInstance } from "../instances.js";
+/** One renderer-specific degradation, reported through `onIssue`. */
+export interface RendererIssue {
+    code: PageDataIssueCode | "missing-component" | "load-failed" | "multiple-slots-unsupported";
+    message: string;
+    /** The instance the degradation belongs to. */
+    instanceId: string;
+    /** The resolved instance path when the issue came from page-data gating. */
+    path?: string;
+}
+/**
+ * The per-render `ReadCache`: the first call for a key
+ * runs the loader; later calls in the same render reuse the in-flight or
+ * settled value — including a rejection (failures are shared, not retried per
+ * section). Scope this to ONE page render; it makes no cross-request promises.
+ */
+export declare function createReadCache(): ReadCache;