@unoverse-platform/studio 0.1.90 → 0.1.92

package/vendor/base/src/definitions/load/compile/sections.ts

@@ -0,0 +1,132 @@
+/**
+ * The SECTION-WORD compiler: a template layout's three words → wire claims +
+ * section projections. Split from compile.ts into this folder 2026-09-02; the
+ * rules are unchanged.
+ */
+
+import type { UnoverseDefinition } from "../../model.js";
+
+/** Expand a template layout's THREE-WORD sections (§9b, 2026-08-29; one director word
+ *  since 2026-09-02) into the wire primitives the renderer already speaks, collecting
+ *  the section projections as it goes. `static:`/`copywriter:` link a component
+ *  (face = its basename) and become a limit-1 claim on that face; `director:` with a
+ *  `component` is a SEARCH place (same limit-1 claim; the grammar rides the section for
+ *  the fill path), and without one it is the open DELIVERY claim — its face is the
+ *  `state:` pin when authored (arrivals are switched in and held), else the owning
+ *  state's name (the free name-match dance). The SDK stays dumb: authors never see
+ *  ComponentSlot/select/where, and the wire never sees the three words. */
+export function expandTemplateSections(
+  node: unknown,
+  owningState: string,
+  templateName: string,
+  out: NonNullable<UnoverseDefinition["sections"]>[string],
+): unknown {
+  if (Array.isArray(node)) return node.map((c) => expandTemplateSections(c, owningState, templateName, out));
+  if (!node || typeof node !== "object") return node;
+  const n = node as Record<string, unknown>;
+  const linked = typeof n.static === "string" ? "static" : typeof n.copywriter === "string" ? "copywriter" : null;
+  if (linked) {
+    const path = String(n[linked]);
+    const face = path.split("/").pop() ?? path;
+    out.push({ kind: linked, face, component: path, ref: `${templateName}/${face}` });
+    const { static: _s, copywriter: _c, ...rest } = n;
+    return {
+      type: "ComponentSlot",
+      select: { from: "all", where: { field: "state", eq: face }, limit: 1 },
+      ...rest,
+    };
+  }
+  // RETIRED VOCABULARY IS A LOUD FAILURE, never a legacy-read (the no-shims law).
+  // `query:` merged into `director:` 2026-09-02 (§9e rule 10b REVERSED); `limit` and
+  // `ask` retired the same day (`pick` is the one cap word; the question is derived,
+  // rule 10d). A stale file fails at load with the fix in the message.
+  if (n.query !== undefined) {
+    throw new Error(`template "${templateName}": the query: word is retired (§9e rule 10b reversed 2026-09-02) — spell the place director: with the same component/items/type/include/pick`);
+  }
+  if (n.director !== undefined && (n.director === null || (typeof n.director === "object" && !Array.isArray(n.director)))) {
+    const d = (n.director ?? {}) as Record<string, unknown>;
+    if (d.limit !== undefined) throw new Error(`template "${templateName}": director limit is retired — the cap word is pick everywhere (§9e rule 9, renamed 2026-09-02)`);
+    if (d.ask !== undefined || d.query !== undefined) throw new Error(`template "${templateName}": a director place never states its question — it is derived (§9e rule 10d): the writing, the page's pool, the component's contract, or the guest's ask`);
+    /**
+     * A SEARCH PLACE (§9e, one word since 2026-09-02) — the director given a component.
+     *
+     * It LINKS the part exactly as `static:`/`copywriter:` do, so the slot is identical: a
+     * limit-1 claim on the part's own face. The content is a search the page runs itself,
+     * before any model has spoken; the QUESTION is never here (rule 10d — the writer's
+     * headings for an `items` place, the page's pool for a gallery, the component's own
+     * contract, or the guest's ask). The layout says only what KIND may answer (`include`)
+     * and how many survive (`pick`); none of it reaches the slot — it rides the section
+     * for the fill path.
+     *
+     * NOTHING DECLARES WHICH PROP TAKES THE ROWS. The schema already says: the prop whose
+     * items require only `ref`. So a searched part keeps BOTH lanes — its refs filled by
+     * search at shell open with no model, its headings and taglines written by the
+     * copywriter afterwards (§9e rule 10). Same part, both lanes, in that order.
+     */
+    if (typeof d.component === "string" && d.component) {
+      const path = String(d.component);
+      const face = path.split("/").pop() ?? path;
+      // AN ITEMS PLACE (§9e rule 10c): the place holds a LIST the writer shapes — each
+      // item's heading arrives WITH its own search, so they can never disagree.
+      //
+      // THE SEARCH WORDS SIT ON THE THING THAT SEARCHES (owner ruling 2026-09-02): each
+      // ITEM searches, so type/include/pick nest INSIDE items: beside min/max, and pick
+      // reads unambiguously as per-item. The flat spelling on an items place is a LOUD
+      // failure — before this, flat `pick` meant two different scopes depending on
+      // whether items: happened to be present.
+      const items = d.items && typeof d.items === "object" && !Array.isArray(d.items) ? (d.items as Record<string, unknown>) : null;
+      if (items && (d.type !== undefined || d.include !== undefined || d.pick !== undefined))
+        throw new Error(
+          `template "${templateName}": an items place nests its search words INSIDE items: (each ITEM searches) — items: { min, max, type, include, pick }`,
+        );
+      const src = items ?? d;
+      out.push({
+        kind: "director",
+        face,
+        component: path,
+        ref: `${templateName}/${face}`,
+        ...(src.type === "discovery" || src.type === "intent" ? { type: src.type } : {}),
+        ...(Array.isArray(src.include) ? { include: src.include.map(String) } : {}),
+        ...(typeof src.pick === "number" ? { pick: src.pick } : {}),
+        ...(items ? { items: { min: Number(items.min) || 1, max: Number(items.max) || 1 } } : {}),
+      });
+      const { director: _d, ...rest } = n;
+      return {
+        type: "ComponentSlot",
+        select: { from: "all", where: { field: "state", eq: face }, limit: 1 },
+        ...rest,
+      };
+    }
+    /**
+     * THE COMPILER ADDRESSES THE PLACE (§9d, ruled 2026-08-31).
+     *
+     * A `director:` place is somewhere things may go — it carries no name, no prose and no
+     * state, because the ONE mind reading the page's brief already knows what the page is.
+     * But a slot still has to select SOMETHING, and two places on one layout may not claim
+     * the same face (the reaction contract's one-view-one-surface rule). So the address is
+     * handed out here, by position, and an author never types a face name.
+     *
+     * An AUTHORED `state:` still wins, for the flat-email case §9b rule 4 names — arrivals
+     * pinned into one declared state — and for any template written before this ruling.
+     */
+    const nth = out.filter((sec) => sec.kind === "director" && !sec.component).length;
+    const face = typeof d.state === "string" ? d.state : nth === 0 ? owningState : `${owningState}-${nth + 1}`;
+    out.push({
+      kind: "director",
+      face,
+      ...(typeof d.state === "string" ? { state: d.state } : {}),
+      ...(typeof d.pick === "number" ? { pick: d.pick } : {}),
+      ...(typeof d.rules === "string" ? { rules: d.rules } : {}),
+      ...(Array.isArray(d.preview) ? { preview: d.preview.map(String) } : {}),
+    });
+    const { director: _d, ...rest } = n;
+    return {
+      type: "ComponentSlot",
+      select: { from: "all", where: { field: "state", eq: face }, ...(typeof d.pick === "number" ? { limit: d.pick } : {}) },
+      ...rest,
+    };
+  }
+  const o: Record<string, unknown> = {};
+  for (const [k2, v] of Object.entries(n)) o[k2] = expandTemplateSections(v, owningState, templateName, out);
+  return o;
+}

package/vendor/base/src/definitions/load/compile/template.ts

@@ -0,0 +1,153 @@
+/**
+ * The TEMPLATE-ROOT compiler: a template's states (folder form) or root (a flat
+ * BLOCK) → the served layouts, sections, previews and root. Split from compile.ts
+ * into this folder 2026-09-02; the dead `parts:`/`shapes:` legacy tails (retired
+ * §9b vocabulary no definition authored any more) were deleted in the same move.
+ */
+
+import type { UnoverseDefinition } from "../../model.js";
+import { loadDefinition } from "../load.js";
+import { composeIncludes } from "../expand/index.js";
+import { expandTemplateSections } from "./sections.js";
+
+/**
+ * ONE PREVIEWED INSTANCE'S SEED — `preview ?? default` per prop, the same values the
+ * Components screen has always seeded. An instance seeded with nothing draws as a page of
+ * ghosts, which is how a finished arrangement comes to read as a broken one.
+ *
+ * Shared by both authored forms (a folder's states and a flat block's root): a mock that
+ * differed by which form a template happened to be written in would be a preview nobody
+ * could trust.
+ */
+function seedFor(ref: string, org?: string): Record<string, unknown> | undefined {
+  const part = loadDefinition(ref, "component", "expanded", org);
+  const seed = Object.fromEntries(
+    Object.entries((part?.props ?? {}) as Record<string, { preview?: unknown; default?: unknown; type?: string }>).map(
+      ([k, v]) => [k, v?.preview ?? v?.default ?? (v?.type === "array" ? [] : v?.type === "object" ? {} : "")],
+    ),
+  );
+  return Object.keys(seed).length ? seed : undefined;
+}
+
+/** Stamp a section list's Studio stand-ins: which refs each face previews, seeded
+ *  `preview ?? default` (keyed by REF, because a director band names several and may
+ *  name one twice). A linked part previews ITSELF; a delivery band previews whatever
+ *  its `preview:` names. */
+function seedSections(
+  secs: NonNullable<UnoverseDefinition["sections"]>[string],
+  org: string | undefined,
+  previews: Record<string, string[]>,
+): void {
+  for (const s of secs) {
+    // A LINKED part previews ITSELF — including a director SEARCH place, which carries a
+    // ref since the one-word merge (a kind check here hid every search place's mock the
+    // day the kinds merged). Only an unlinked DELIVERY band previews its `preview:` list.
+    const refs = s.ref ? [s.ref] : s.kind === "director" ? (s.preview ?? []) : [];
+    if (s.ref) previews[s.face] = [s.ref];
+    else if (s.preview?.length) previews[s.face] = s.preview;
+    const seeds: Record<string, Record<string, unknown>> = {};
+    for (const ref of new Set(refs)) {
+      const seed = seedFor(ref, org);
+      if (seed) seeds[ref] = seed;
+    }
+    if (Object.keys(seeds).length) s.seeds = seeds;
+  }
+}
+
+export function synthesizeTemplateRoot(def: UnoverseDefinition, folderDir?: string): void {
+  if (def.root) {
+    /**
+     * A BLOCK — a flat template that declares a DRAWING instead of a tree (2026-08-31).
+     *
+     * Its three words still have to compile. Without this the `director:` line sat in the
+     * served root verbatim, unexpanded and inert: the renderer speaks ComponentSlot and
+     * knows no such word, so a block drew as an empty box wherever it was used (observed
+     * in Studio the moment the first one was authored). The folder form compiles its
+     * sections as it composes each state's layout; the flat form had no such pass.
+     *
+     * Compiled into the SAME projections a one-state template serves, so nothing
+     * downstream has to know which form it was authored in: `layouts`, `defaultLayout`,
+     * `sections`, `publicStates`. The author still writes only `root:`.
+     */
+    if ((def as unknown as { states?: unknown }).states === undefined && def.layouts === undefined) {
+      const secs: NonNullable<UnoverseDefinition["sections"]>[string] = [];
+      const compiled = expandTemplateSections(def.root, def.name, def.name, secs);
+      if (secs.length) {
+        const previews: Record<string, string[]> = {};
+        seedSections(secs, def.org, previews);
+        if (Object.keys(previews).length) def.preview = { ...(def.preview ?? {}), ...previews };
+      }
+      // The projections are built WHETHER OR NOT the root carries section words
+      // (2026-09-02): a pure-arrangement block — `band`, `two-column`, style and an
+      // opening, no fill lane — is still a template, and without a layout Studio drew it
+      // as a blank canvas (observed the day blocks returned). Its own authored children
+      // are its preview.
+      def.root = compiled as UnoverseDefinition["root"];
+      def.layouts = { [def.name]: compiled as never };
+      def.defaultLayout = def.name;
+      if (secs.length) def.sections = { [def.name]: secs };
+      def.publicStates = [def.name];
+      def.initialView = def.name;
+    }
+    return;
+  }
+  // STATES SERVE THE APP-RUNTIME CONTRACT (§9b RULED 2026-08-29): a template's states
+  // compose into def.layouts — sections expanded to wire ComponentSlots, no baked
+  // mocks — with the FIRST state as the base (def.root + defaultLayout) and the rest
+  // as the reaction ladder (def.stateOrder). The SDK then does everything the rules
+  // say: an instance's face change surfaces the name-matched layout, its claim catches
+  // the instance, steps stay contained in the instance's own slice. Studio seeds real
+  // instances from the compiled sections and the same runtime runs.
+  const rawStates = (def as unknown as { states?: unknown }).states;
+  const states: Record<string, { layout?: unknown } | null> =
+    rawStates && typeof rawStates === "object" && !Array.isArray(rawStates)
+      ? (rawStates as Record<string, { layout?: unknown } | null>)
+      : {};
+  const shapeNames = Object.keys(states);
+  if (!folderDir || !shapeNames.length) return;
+  const layouts: Record<string, unknown> = {};
+  const sections: NonNullable<UnoverseDefinition["sections"]> = {};
+  const compiledPreview: Record<string, string[]> = {};
+  // THE LATCH IS A FACT ABOUT A STATE (MCP guide §The Component Latch). Collected on the
+  // same pass as the layouts and stamped as `def.latches`, because `states` is deleted
+  // below: a state that says nothing here can never be addressed, and an instance moving
+  // between states gains and loses the pill with no eviction and nothing to unregister.
+  const latches: NonNullable<UnoverseDefinition["latches"]> = {};
+  for (const name of shapeNames) {
+    const st = (states[name] ?? {}) as Record<string, unknown>;
+    const latch = st.latch as { title?: unknown; icon?: unknown } | undefined;
+    // TITLE OR NOTHING: the pill's whole content is the title, so a latch without one
+    // draws a nameless pill the guest cannot read. Declared but empty is an authoring
+    // slip, and taking it literally is what makes the slip visible.
+    if (latch && typeof latch === "object" && typeof latch.title === "string" && latch.title.trim())
+      latches[name] = { title: latch.title, ...(typeof latch.icon === "string" ? { icon: latch.icon } : {}) };
+    if (typeof st.layout !== "string") continue;
+    const secs: NonNullable<UnoverseDefinition["sections"]>[string] = [];
+    layouts[name] = expandTemplateSections(composeIncludes({ $include: st.layout }, folderDir), name, def.name, secs);
+    sections[name] = secs;
+    // MOCK VALUES TRAVEL WITH THE SECTION — a preview host seeds instances from the wire.
+    seedSections(secs, def.org, compiledPreview);
+  }
+  if (!Object.keys(layouts).length) return;
+  def.layouts = layouts;
+  def.defaultLayout = shapeNames[0];
+  def.stateOrder = shapeNames.slice(1);
+  // THE FACE IT ARRIVES WEARING (2026-08-30). A template's states compiled into
+  // layouts and stopped there, so it carried no `publicStates`/`initialView` — the
+  // two projections that say "this is my interface, and this is the face I arrive
+  // in". Every consumer of a face was therefore blind to it: a preview could not
+  // seed it, a state chip could not activate it, and — the one that matters — an
+  // app's ladder had nothing to react to when a template STREAMED in, so a
+  // discovered page landed inline in the conversation instead of taking its
+  // surface. Stamped exactly as the component tier stamps them, because it is the
+  // same contract: states are the interface, the first declared one is arrival.
+  def.publicStates = shapeNames;
+  def.initialView = shapeNames[0];
+  if (Object.keys(latches).length) def.latches = latches;
+  if (Object.keys(sections).length) def.sections = sections;
+  if (Object.keys(compiledPreview).length) def.preview = { ...(def.preview ?? {}), ...compiledPreview };
+  delete (def as unknown as Record<string, unknown>).states;
+  // The base arrangement, wrapped in a container so responsive columns can
+  // query their surface width in any host.
+  def.root = { type: "Box", style: { width: "full", container: "inline-size" }, children: [layouts[shapeNames[0]]] };
+}

package/vendor/base/src/definitions/load/expand/includes.ts

@@ -0,0 +1,27 @@
+/**
+ * `$include` COMPOSITION: a definition's siblings, inlined.
+ *
+ * The authoring-time half of composition — a layout pulls in `components/header`, a state
+ * pulls in a shared shape. Resolved against the definition's own folder, recursively.
+ *
+ * Split from expand.ts 2026-08-30; the rules are unchanged.
+ */
+import { readDefCached, defPath } from "../../fsCache.js";
+import type { AnyNode } from "./refs.js";
+
+export function composeIncludes(value: any, folderDir: string): any {
+  if (Array.isArray(value)) return value.map((v) => composeIncludes(v, folderDir));
+  if (value && typeof value === "object") {
+    if (typeof value.$include === "string") {
+      const incPath = defPath(folderDir, value.$include);
+      // Name the missing include: the raw ENOENT names a `.yaml` that was never meant to
+      // exist, which reads as a resolver bug rather than a broken reference.
+      if (!incPath) throw new Error(`$include "${value.$include}" resolves to no file in ${folderDir}`);
+      return composeIncludes(readDefCached(incPath), folderDir);
+    }
+    const out: AnyNode = {};
+    for (const [k, v] of Object.entries(value)) out[k] = composeIncludes(v, folderDir);
+    return out;
+  }
+  return value;
+}

package/vendor/base/src/definitions/load/expand/index.ts

@@ -0,0 +1,17 @@
+/**
+ * COMPOSITION — the surface. Split by JOB 2026-08-30, the way `markdown/` and
+ * `agent-mcp/` are: `expand.ts` had grown to five unrelated jobs in one file.
+ *
+ *   refs.ts        inlining a Ref: the field remaps and the `with` literals
+ *   inherit.ts     what an embedded piece carries up (its state, its prop contracts)
+ *   walk.ts        the expansion itself
+ *   referenced.ts  the reference-don't-copy form (each atom shipped once)
+ *   includes.ts    `$include` composition
+ *
+ * Every export keeps its name, so nothing that imports composition had to change.
+ */
+export { remapFields, applyLiterals, type AnyNode } from "./refs.js";
+export { machineryKeys, inheritState, inheritProps, mergeInheritedProps } from "./inherit.js";
+export { expandNode, expandRefs } from "./walk.js";
+export { referencedDefinition } from "./referenced.js";
+export { composeIncludes } from "./includes.js";

package/vendor/base/src/definitions/load/expand/inherit.ts

@@ -0,0 +1,169 @@
+/**
+ * WHAT AN EMBEDDED PIECE CARRIES UP TO ITS HOST.
+ *
+ * A Ref inlines a root into the host's tree, and the inlined nodes read the HOST's slice —
+ * an embedded piece has no slice of its own. So two things have to travel with it: the
+ * starting VALUES it declares (`inheritState`) and the field CONTRACTS its props describe
+ * (`inheritProps`). Both are DEFAULTS ONLY, and the host wins on anything it declares.
+ *
+ * Split from expand.ts 2026-08-30; the rules are unchanged.
+ */
+import type { UnoverseDefinition } from "../../model.js";
+
+/**
+ * A Ref'd COMPONENT's OWN state initials, carried up to the host that embeds it.
+ *
+ * A Ref inlines a root into the host's tree, and the inlined nodes read the HOST's slice —
+ * an embedded component has no slice of its own. So a component that declares where it
+ * starts (`markdown-renderer`: `state: { tab: "0" }`, meaning "the first tab") had that
+ * declaration dropped the moment it was embedded: its `Switch on: tab` tested a key nobody
+ * had ever set and drew nothing, and a `style.when` comparing that key highlighted nothing.
+ * Observed live 2026-08-23 on bpp/lyceum course-card — the tab strip rendered, the body under
+ * it was blank until a tab was clicked, and every host would have had to re-declare a default
+ * belonging to a component it merely embeds.
+ *
+ * DEFAULTS ONLY, HOST WINS: an initial is what the piece starts at, never an override of what
+ * the host says it starts at.
+ *
+ * VALUES TRAVEL, THE STATE MACHINE DOES NOT. A component's served `state` holds two unlike
+ * things: scalars its author wrote (`tab: "0"`) and the keys the v2 tree COMPILE derived from
+ * its state tree — `view`, and one key per `on:` axis, each seeded with its landing substate.
+ * Only the authored scalars are the piece's; the axis keys are its machine, and an embedded
+ * piece has no machine, because it has no slice to run one on.
+ *
+ * Landing this with only `view` excluded broke every chat app in the estate within a day
+ * (2026-08-24). `text-chat` declares one public state with two substates on a `chatState`
+ * axis, which compiles to `chatState: "welcome"`; the apps embed it, inherited that, and their
+ * `Switch on: chatState` matched `welcome` forever instead of falling to the default branch
+ * where the projected conversation facts pick the substate. The timeline could not appear. The
+ * component's own props comment had named the failure in advance: "a non-empty default would
+ * pin the mood forever". `view` was never the special case — the whole compiled machine is.
+ */
+
+export function machineryKeys(def: UnoverseDefinition): Set<string> {
+  // Read off the DEFINITION's own tree rather than a list kept in step by hand: an axis is
+  // machinery because the compile derived it, so the compile's own output names them.
+  const keys = new Set<string>(["state", "view", "defaultState"]);
+  const walk = (entries: NonNullable<UnoverseDefinition["stateTree"]> | undefined): void => {
+    for (const e of entries ?? []) {
+      if (typeof e.on === "string") keys.add(e.on);
+      walk(e.states as NonNullable<UnoverseDefinition["stateTree"]> | undefined);
+    }
+  };
+  walk(def.stateTree);
+  return keys;
+}
+
+export function inheritState(into: Record<string, unknown>, from: UnoverseDefinition | null | undefined): void {
+  const state = from?.state;
+  if (!state || typeof state !== "object" || Array.isArray(state)) return;
+  const machinery = machineryKeys(from!);
+  for (const [k, v] of Object.entries(state as Record<string, unknown>)) {
+    if (machinery.has(k)) continue;
+    if (!(k in into)) into[k] = v;
+  }
+}
+
+/**
+ * A Ref'd atom's PROP CONTRACTS, carried up to the host that embeds it — the twin of
+ * `inheritState`, and for the same reason.
+ *
+ * THE PROP IS THE BRIEF (UNOVERSE_AUTHORING §3b, 2026-08-30). A field's description and
+ * limits used to ride the atom's NODES, so they travelled into the host's tree with the
+ * inlined copy and were remapped to the host's field names for free. Now they live on the
+ * atom's props, and an inlined atom reads the HOST's slice — so the contract has to be
+ * remapped the same way the binds are, or a card composed of atoms compiles to a schema
+ * with nothing in it.
+ *
+ * The atom is the LAW OF A FIELD KIND ("the passage, in Markdown, taken from the source");
+ * the host says what THIS field is for. So: DEFAULTS ONLY, HOST WINS, key by key. A field
+ * pinned to a literal through `with` never arrives at all — it is not a field anyone fills.
+ */
+/** A prop an Agent may write: described, server-hydrated, or a list of such. */
+function writable(spec: Record<string, unknown>): boolean {
+  if (typeof spec.description === "string" && spec.description.trim()) return true;
+  if (spec.hydrate !== undefined) return true;
+  const items = spec.items;
+  if (items && typeof items === "object")
+    return Object.values(items as Record<string, unknown>).some(
+      (v) => v && typeof v === "object" && writable(v as Record<string, unknown>),
+    );
+  return false;
+}
+
+export function inheritProps(
+  into: Record<string, Record<string, unknown>>,
+  atom: UnoverseDefinition | null | undefined,
+  propMap: Record<string, string>,
+  literals: Record<string, unknown>,
+  scope: string[],
+): void {
+  // `preview` rides along because it is DESIGN-TIME ONLY — the mock a piece shows before
+  // any run. A part that composes another and inherits its contract but not its mock
+  // previews as a page of skeletons, which reads as broken rather than unwritten.
+  // `default` deliberately does NOT: that is a real value at render time, and it is the
+  // host's business whether a field has one.
+  // `override` TRAVELS TOO (added 2026-09-01). A field declared CLOSED — hydrated from the
+  // row and never the writer's to improve — was reopened the moment its contract was
+  // inherited: the word was simply missing from this list, so a piece that said "this name
+  // is the venue's" lost that the instant a host drew a list of it. Observed on Perfect
+  // Day's moments the day `chapter` stopped restating the tile's contract: `required` was
+  // still `["ref"]`, but `title` and `description` were back among the properties a model
+  // could send, which is exactly the venue-renaming this flag exists to prevent.
+  const CONTRACT = ["type", "description", "maxLength", "minItems", "maxItems", "items", "hydrate", "optional", "override", "preview"] as const;
+  // AN ATOM INSIDE AN `Each` DESCRIBES THE ITEM, not the page. The scope is the chain of
+  // array props the Ref sits inside, so a `prose` atom drawn once per section lands on
+  // `sections.items.body` — where a brief on its node used to land by being there.
+  let target = into;
+  for (const arr of scope) {
+    const entry = (target[arr] ??= {}) as Record<string, unknown>;
+    entry.type ??= "array";
+    target = (entry.items ??= {}) as Record<string, Record<string, unknown>>;
+  }
+  for (const [name, spec] of Object.entries((atom?.props ?? {}) as Record<string, Record<string, unknown>>)) {
+    if (!spec || typeof spec !== "object" || name in literals) continue;
+    // Only what the atom says is WRITABLE travels: a described field, a hydrated one
+    // (the server fills it), or an array whose ITEMS are either. An atom's plain data
+    // props are its own business — not a contract the host inherits, any more than an
+    // unbriefed node used to be.
+    if (!writable(spec)) continue;
+    const hostName = propMap[name] ?? name;
+    // Several atoms may draw the same field name in different branches of a Switch (a
+    // document's `kind`): the LAST one encountered wins, as it did when the contract rode
+    // the nodes. The host's own declaration still wins over all of them, at the merge.
+    const slot = (target[hostName] ??= {});
+    for (const k of CONTRACT) if (spec[k] !== undefined) slot[k] = spec[k];
+  }
+}
+
+
+/**
+ * Fold the atoms' inherited field contracts (see `inheritProps`) UNDER the definition's
+ * own props. Exported because a component's layouts are expanded at load time, before
+ * `expandRefs` sees the root — an atom drawn inside a layout must reach the props too,
+ * or a page composed of atoms compiles to a schema that knows nothing about its fields.
+ */
+export function mergeInheritedProps(def: UnoverseDefinition, fromAtoms: Record<string, Record<string, unknown>>): void {
+  if (!Object.keys(fromAtoms).length) return;
+  const own = (def.props ?? {}) as Record<string, Record<string, unknown>>;
+  const merged: Record<string, unknown> = {};
+  // The HOST's declaration order first (the page's reading order, which the compiled
+  // schema's property order carries), then anything only an atom knew about. Item shapes
+  // merge a level deeper, so a host that describes one field of a repeated entry does not
+  // erase the atom's law for the rest of it.
+  const fold = (mine: Record<string, unknown>, theirs: Record<string, unknown>): Record<string, unknown> => {
+    const out = { ...theirs, ...mine };
+    const mineItems = mine.items as Record<string, Record<string, unknown>> | undefined;
+    const theirItems = theirs.items as Record<string, Record<string, unknown>> | undefined;
+    if (mineItems && theirItems) {
+      const items: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(mineItems)) items[k] = theirItems[k] ? fold(v, theirItems[k]) : v;
+      for (const [k, v] of Object.entries(theirItems)) if (!(k in items)) items[k] = v;
+      out.items = items;
+    }
+    return out;
+  };
+  for (const [k, v] of Object.entries(own)) merged[k] = v && typeof v === "object" && fromAtoms[k] ? fold(v, fromAtoms[k]) : v;
+  for (const [k, v] of Object.entries(fromAtoms)) if (!(k in merged)) merged[k] = v;
+  def.props = merged as UnoverseDefinition["props"];
+}