@unoverse-platform/studio 0.1.90 → 0.1.91

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"];
+}

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

@@ -0,0 +1,164 @@
+/**
+ * REFERENCE, DON'T COPY — the served form that ships each atom once.
+ *
+ * `expandRefs` specialises every Ref into an inline copy, so a shared button travels
+ * inside every definition that uses it, on every page load. This is the other form: the
+ * definition with its `Ref` nodes LEFT ALONE, plus one copy of each atom they name.
+ *
+ * Split from expand.ts 2026-08-30; the rules are unchanged.
+ */
+import type { UnoverseDefinition } from "../../model.js";
+import { loadDefinition } from "../load.js";
+import { inheritState } from "./inherit.js";
+import type { AnyNode } from "./refs.js";
+
+export function referencedDefinition(def: UnoverseDefinition, contextOrg?: string): UnoverseDefinition {
+  const defs: Record<string, AnyNode> = {};
+  const inherit: Record<string, unknown> = {};
+  // Depth-first over the tree, collecting each named atom ONCE. An atom may itself Ref
+  // another, so collected atoms are walked too — otherwise the client resolves an atom
+  // and finds a reference it was never sent.
+  const collect = (node: AnyNode | undefined): void => {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) return node.forEach(collect);
+    if (node.type === "Ref" && typeof node.ref === "string") {
+      const name = node.ref;
+      if (!(name in defs)) {
+        // The referenced piece in its OWN referenced form, with its references merged up
+        // into the same flat map. The client threads `defs` through every recursion, so a
+        // Ref inside a referenced piece resolves against the same map. Storing these
+        // EXPANDED instead was the difference between product-card costing 17 KB + 173 KB
+        // and 17 KB + a handful: it references `document`, and an expanded document drags
+        // in every copy this exists to remove.
+        const piece =
+          loadDefinition(name, "atom", "referenced") ?? loadDefinition(name, "component", "referenced", contextOrg ?? def.org);
+        if (piece?.root) {
+          defs[name] = piece.root as AnyNode;
+          // Same inheritance as the expanded form. The client resolves the Ref itself here,
+          // but `defs` carries roots only — state never travels node-side, so it has to be
+          // merged onto the definition server-side or a referenced-mode host keeps the bug
+          // the expanded form no longer has.
+          inheritState(inherit, piece);
+          for (const [k, v] of Object.entries((piece.defs ?? {}) as Record<string, AnyNode>)) if (!(k in defs)) defs[k] = v;
+          collect(piece.root as AnyNode);
+        }
+      }
+    }
+    if (Array.isArray(node.children)) node.children.forEach(collect);
+    if (node.item) collect(node.item as AnyNode);
+    if (node.cases && typeof node.cases === "object") for (const k of Object.keys(node.cases)) collect(node.cases[k] as AnyNode);
+    if (node.frame) collect(node.frame as AnyNode);
+    if (node.fallback) collect(node.fallback as AnyNode);
+  };
+  // EVERY TREE THE DEFINITION SHIPS, not just `root`. A template's arrangements live in
+  // `layouts`, and they are the whole payload — a chat template's `root` is a stub. Walking
+  // `root` alone deduplicated nothing at all for templates: measured on bpp-chat,
+  // whose four layouts include the SAME 7 KB chrome file, the referenced form came back 11%
+  // smaller instead of the ~70% every component saw.
+  const trees = () => [def.root, ...Object.values(def.layouts ?? {})] as AnyNode[];
+  trees().forEach(collect);
+  if (Object.keys(inherit).length) def = { ...def, state: { ...inherit, ...((def.state as Record<string, unknown>) ?? {}) } };
+
+  // REPEATS ARE REFERENCES TOO, wherever they came from.
+  //
+  // Hoisting named atoms only fixes duplication that went through a `Ref`. A template
+  // composes its arrangements with `$include`, which is copied just as literally: a chat
+  // layout shipping four arrangements carried four copies of the same chrome, 35 KB of a
+  // 44 KB payload, and not one byte of it was an atom.
+  //
+  // So this is structural: any subtree appearing more than once becomes ONE entry plus
+  // references to it. Identical trees render identically, and the client resolves a
+  // parameterless reference by cloning, so nothing about meaning changes. Counted ACROSS
+  // the trees, because the repetition that matters most is one arrangement against another.
+  // SCOPED TO THIS DEFINITION, because `defs` is not this definition's map alone: every
+  // referenced piece merges ITS names up into the same flat namespace above. Generated
+  // names used to be a counter restarting at 0 for every definition, so a template's
+  // `shared:0` and a component's `shared:0` were the same key. The component's landed
+  // first, the template's store was skipped as "already there", and the template's chunk
+  // was handed a pointer to the component's — silently, since a collision looks exactly
+  // like a chunk already stored. Observed live 2026-08-23: bpp-chat's chrome resolved to
+  // bpp/text-chat's, so the `appWidth: chat` it carried never reached the client and the
+  // app sized wrong. Nothing errored; a chunk simply became a different chunk.
+  const hoisted = hoistRepeats(trees(), defs, `${def.org ? `${def.org}/` : ""}${def.name}`);
+  if (hoisted.length) {
+    const [root, ...layouts] = hoisted;
+    def = { ...def, root };
+    if (def.layouts) def.layouts = Object.fromEntries(Object.keys(def.layouts).map((k, i) => [k, layouts[i]]));
+  }
+
+  return Object.keys(defs).length ? ({ ...def, defs } as UnoverseDefinition) : def;
+}
+
+/**
+ * Replace every repeated subtree, across ALL of a definition's trees, with a reference to
+ * one copy. Returns the rewritten trees in the order given.
+ *
+ * Counting spans the whole set rather than each tree alone, because the duplication that
+ * dominates a template is one ARRANGEMENT against another: four layouts that each include
+ * the same chrome share nothing within themselves and everything between themselves.
+ *
+ * Top-down, so the LARGEST repeated tree is hoisted and its children ride inside it rather
+ * than being hoisted separately: hoisting a child first would leave the parent's copies
+ * differing only in that child's reference, and they would stop matching each other.
+ *
+ * `MIN` exists because a reference costs about 40 bytes; hoisting a 60-byte node makes the
+ * payload bigger and the tree harder to read for nothing.
+ */
+function hoistRepeats(roots: AnyNode[], defs: Record<string, AnyNode>, scope: string): AnyNode[] {
+  const MIN = 700; // bytes: comfortably larger than the reference that replaces it
+  const counts = new Map<string, number>();
+  const count = (node: unknown): void => {
+    if (Array.isArray(node)) return node.forEach(count);
+    if (!node || typeof node !== "object") return;
+    const n = node as AnyNode;
+    if (n.type && n.type !== "Ref") {
+      const j = JSON.stringify(n);
+      if (j.length >= MIN) counts.set(j, (counts.get(j) ?? 0) + 1);
+    }
+    for (const v of Object.values(n)) if (v && typeof v === "object") count(v);
+  };
+  roots.forEach(count);
+
+  const repeated = new Map<string, string>(); // serialized tree → its reference name
+  let i = 0;
+  // `shared:<definition>:<n>` — the definition segment is what makes a generated name mean
+  // ONE chunk in the flat map every referenced piece also writes into.
+  for (const [j, n] of counts) if (n > 1) repeated.set(j, `shared:${scope}:${(i++).toString(36)}`);
+  if (!repeated.size) return [];
+
+  const swap = (node: unknown): unknown => {
+    if (Array.isArray(node)) return node.map(swap);
+    if (!node || typeof node !== "object") return node;
+    const n = node as AnyNode;
+    if (n.type && n.type !== "Ref") {
+      const name = repeated.get(JSON.stringify(n));
+      if (name) {
+        // The first sighting becomes the stored copy, with ITS OWN repeats hoisted, so a
+        // shape repeated inside a repeated shape collapses too.
+        if (!(name in defs)) {
+          const stored = JSON.parse(JSON.stringify(n)) as AnyNode;
+          defs[name] = stored;
+          for (const [k, v] of Object.entries(stored)) if (v && typeof v === "object") stored[k] = swap(v) as AnyNode;
+        }
+        return { type: "Ref", ref: name };
+      }
+    }
+    for (const [k, v] of Object.entries(n)) if (v && typeof v === "object") n[k] = swap(v) as AnyNode;
+    return n;
+  };
+  // A whole tree can itself be a repeat (two arrangements that are the same), so the
+  // returned value is used rather than relying on in-place rewriting.
+  return roots.map((r) => swap(r) as AnyNode);
+}
+
+
+// ---- Folder composition: inline `{ "$include": "name" }` from sibling files ----
+//
+// A template can be a FOLDER (apps/chatlayout/) of multiple data files, so
+// UX pieces live in their own files (chatlayout + user-turn + …). Any
+// `{ "$include": "user-turn" }` node is replaced by the parsed content of
+// `<folder>/user-turn.{yaml,json}` (recursively). All UX stays as served data — the SDK
+// receives one fully-assembled tree.
+//
+// `$include` values are EXTENSION-LESS by design, so a partial can be converted from JSON
+// to YAML without touching any file that references it.

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

@@ -0,0 +1,106 @@
+/**
+ * INLINING A REF: the remaps and the literals.
+ *
+ * A component composes an atom with `{ type: "Ref", ref: "button", props: {…}, with: {…} }`.
+ * `props` REMAPS the atom's field names onto the host's; `with` resolves them to LITERALS.
+ * Everything here is that one job — nothing in this file knows what a definition is.
+ *
+ * Split from expand.ts 2026-08-30 (it had grown five jobs); the rules are unchanged.
+ */
+
+export type AnyNode = Record<string, any>;
+
+// Remap `{{field}}` data-bindings embedded in STYLE values (e.g. a radial gauge's
+// `radial.at: "{{value}}"`, a progress bar's `width: "{{pct}}"`) — the style-side twin
+// of the bind/visibleWhen remap, so an atom whose look is data-driven is parameterizable.
+function remapStyleBindings(style: AnyNode, propMap: Record<string, string>): void {
+  for (const k of Object.keys(style)) {
+    const v = style[k];
+    if (typeof v === "string" && v.includes("{{")) {
+      style[k] = v.replace(/\{\{(\w[\w.]*)\}\}/g, (m, f) => (propMap[f] ? `{{${propMap[f]}}}` : m));
+    } else if (v && typeof v === "object") {
+      remapStyleBindings(v as AnyNode, propMap); // nested: radial.at, hover, etc.
+    }
+  }
+}
+
+export function remapFields(node: AnyNode, propMap: Record<string, string>): void {
+  // A NESTED `Ref` IS REMAPPED THROUGH ITS OWN `props`. The values of an inner reference's
+  // `props` are field names in THIS tree's scope, so the host's rename has to reach them:
+  // an atom that composes another atom (toggle-row and form-toggle both draw toggle-switch)
+  // otherwise hands the inner one the OUTER atom's prop name, which the host has just
+  // renamed away. The switch then tests an absent key and never draws its ON state — the
+  // control looks right, moves nothing, and says nothing. Same silence as the visibleWhen
+  // object form below, one level deeper.
+  if (node.type === "Ref" && node.props && typeof node.props === "object") {
+    for (const k of Object.keys(node.props as AnyNode)) {
+      const v = (node.props as AnyNode)[k];
+      if (typeof v === "string" && propMap[v]) (node.props as AnyNode)[k] = propMap[v];
+    }
+  }
+  if (node.bind) for (const k of Object.keys(node.bind)) if (propMap[node.bind[k]]) node.bind[k] = propMap[node.bind[k]];
+  if (typeof node.visibleWhen === "string" && propMap[node.visibleWhen]) node.visibleWhen = propMap[node.visibleWhen];
+  // THE OBJECT FORM REMAPS TOO. A guard is a guard whichever way it is written, and only
+  // the string form was carried across: an atom guarding on `{ field: "value", ne: "" }`
+  // kept testing its OWN prop name after the host remapped `value` to its field, so the
+  // guard read an absent key and the branch never showed. Silent, and it bit form-select
+  // the day it was written (2026-08-09).
+  if (node.visibleWhen && typeof node.visibleWhen === "object" && !Array.isArray(node.visibleWhen)) {
+    const g = node.visibleWhen as { field?: string };
+    if (typeof g.field === "string" && propMap[g.field]) g.field = propMap[g.field];
+  }
+  // `when` style variants are the same predicate wearing a different hat: an atom whose
+  // LOOK is data-driven (a switch track filling when `on` is true) must follow its host's
+  // field for the same reason.
+  const when = (node.style as AnyNode | undefined)?.when;
+  if (Array.isArray(when)) {
+    for (const v of when as { field?: string }[]) {
+      if (v && typeof v.field === "string" && propMap[v.field]) v.field = propMap[v.field];
+    }
+  }
+  if (node.style && typeof node.style === "object") remapStyleBindings(node.style as AnyNode, propMap);
+  if (Array.isArray(node.children)) node.children.forEach((c: AnyNode) => remapFields(c, propMap));
+  if (node.item) remapFields(node.item as AnyNode, propMap); // Each item subtree
+  if (node.cases && typeof node.cases === "object") for (const k of Object.keys(node.cases)) remapFields(node.cases[k] as AnyNode, propMap); // Switch branches
+}
+
+// Resolve an atom's bindings to LITERAL content (the Ref's `with` map). A bind entry
+// whose field is a `with` key becomes a hardcoded attribute; a visibleWhen guard on a
+// provided (truthy) key is satisfied statically and dropped; `{{key}}` style bindings
+// take the value. Keys the atom doesn't bind are ignored (harmless).
+/** Substitute `{{name}}` anywhere inside a style object, at any depth. */
+function applyStyleLiterals(style: unknown, lits: Record<string, unknown>): void {
+  if (Array.isArray(style)) return style.forEach((v) => applyStyleLiterals(v, lits));
+  if (!style || typeof style !== "object") return;
+  const s = style as AnyNode;
+  for (const k of Object.keys(s)) {
+    const v = s[k];
+    if (typeof v === "string" && v.includes("{{"))
+      s[k] = v.replace(/\{\{(\w[\w.]*)\}\}/g, (m, f) => (f in lits ? String(lits[f]) : m));
+    else if (v && typeof v === "object") applyStyleLiterals(v, lits);
+  }
+}
+
+export function applyLiterals(node: AnyNode, lits: Record<string, unknown>): void {
+  if (node.bind) {
+    for (const attr of Object.keys(node.bind)) {
+      const field = node.bind[attr];
+      if (typeof field === "string" && field in lits) {
+        node[attr] = lits[field];
+        delete node.bind[attr];
+      }
+    }
+    if (Object.keys(node.bind).length === 0) delete node.bind;
+  }
+  if (typeof node.visibleWhen === "string" && node.visibleWhen in lits) {
+    if (lits[node.visibleWhen]) delete node.visibleWhen; // statically satisfied
+    // falsy literal: keep the (now never-true) guard — the node stays hidden
+  }
+  // Style values may NEST (a radial's `at`, a `when` clause's `apply`), so this walks the
+  // whole style object rather than its top level — a `{{value}}` one level down survived
+  // and reached the renderer verbatim.
+  if (node.style && typeof node.style === "object") applyStyleLiterals(node.style as AnyNode, lits);
+  if (Array.isArray(node.children)) node.children.forEach((c: AnyNode) => applyLiterals(c, lits));
+  if (node.item) applyLiterals(node.item as AnyNode, lits);
+  if (node.cases && typeof node.cases === "object") for (const k of Object.keys(node.cases)) applyLiterals(node.cases[k] as AnyNode, lits);
+}

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

@@ -0,0 +1,91 @@
+/**
+ * THE EXPANSION WALK: inline every `Ref`, gathering what the pieces carry up.
+ *
+ * One pass over a definition's tree. It calls into `refs.ts` to inline and remap, and into
+ * `inherit.ts` for the state and prop contracts an embedded piece hands its host.
+ *
+ * Split from expand.ts 2026-08-30; the rules are unchanged.
+ */
+import type { UnoverseDefinition } from "../../model.js";
+import { loadDefinition } from "../load.js";
+import { remapFields, applyLiterals, type AnyNode } from "./refs.js";
+import { inheritState, inheritProps, mergeInheritedProps } from "./inherit.js";
+
+export function expandNode(node: AnyNode, contextOrg?: string, inherit?: Record<string, unknown>, props?: Record<string, Record<string, unknown>>, scope: string[] = []): AnyNode {
+  if (node?.type === "Ref") {
+    // A Ref inlines an ATOM (the usual case, rx/atoms). It also resolves a COMPONENT
+    // as a fallback, so a template can embed a shared flat component (e.g. the
+    // ComposerBar chrome) the same way it embeds an atom — the one mechanism for fixed,
+    // always-present chrome. (A component's root is inlined as-is; flat components only.)
+    // The parent definition's org rides along so a bare ref inside an org's own tree
+    // resolves to that org's component when two orgs share the name.
+    //
+    // AND A BLOCK (2026-08-31) — a flat TEMPLATE with no manifest: `pair`, `feature`,
+    // `single`, `rail`, `stack`. §2 always said "a rich template may compose basic ones
+    // inside itself", and this is that sentence, by the mechanism already here rather than
+    // a new one. Inlining is exactly right for it: the block's `director:` places arrive in
+    // the composing page's tree BEFORE its sections compile, so they become real slots and
+    // the page addresses them by position along with its own. Nothing is mounted, nothing
+    // is nested at runtime — the page ends up with the tree it would have had if someone
+    // had drawn the block by hand, which is the point.
+    //
+    // Last in the chain deliberately: atoms and components are the common case, and a
+    // template sharing a name with either keeps the old resolution.
+    const atom =
+      loadDefinition(String(node.ref), "atom") ??
+      loadDefinition(String(node.ref), "component", "expanded", contextOrg) ??
+      loadDefinition(String(node.ref), "template", "expanded", contextOrg);
+    if (!atom?.root) return node; // unknown ref — leave the Ref (renders as a no-op)
+    inheritState(inherit ?? {}, atom);
+    if (props) inheritProps(props, atom, (node.props ?? {}) as Record<string, string>, (node.with ?? {}) as Record<string, unknown>, scope);
+    const root = JSON.parse(JSON.stringify(atom.root)) as AnyNode;
+    remapFields(root, (node.props ?? {}) as Record<string, string>);
+    if (node.with && typeof node.with === "object") applyLiterals(root, node.with as Record<string, unknown>);
+    if (node.visibleWhen) root.visibleWhen = node.visibleWhen;
+    // A Ref may override the atom's `action` — the per-host behaviour the atom can't carry
+    // (e.g. each wizard step's option sets different fields). Parallel to style/visibleWhen.
+    if (node.action) root.action = node.action;
+    if (node.style) root.style = { ...(root.style ?? {}), ...node.style };
+    // THE BLOCK'S OPENING (2026-09-02, blocks returned): a Ref carrying `children:` fills
+    // the inlined root with the CALLER's children — a `band` or `two-column` block styles
+    // the frame, the composing layout says what sits inside. Same override family as
+    // style/action above; a Ref without children keeps the block's own (a complete block).
+    if (Array.isArray(node.children) && node.children.length) root.children = node.children;
+    return expandNode(root, contextOrg, inherit, props, scope); // expand nested refs too
+  }
+  if (Array.isArray(node?.children)) node.children = node.children.map((c: AnyNode) => expandNode(c, contextOrg, inherit, props, scope));
+  // `Each` carries a per-item subtree in `item` (not `children`) — expand it too,
+  // so an atom `Ref` inside a repeated item is inlined like anywhere else.
+  // An `Each`'s `item` draws ONE ITEM, so everything inside it belongs to that
+  // array's item shape (see `inheritProps`).
+  const itemsField = node?.type === "Each" ? (node.bind as AnyNode | undefined)?.items : undefined;
+  if (node?.item) node.item = expandNode(node.item, contextOrg, inherit, props, typeof itemsField === "string" ? [...scope, itemsField] : scope);
+  // `Switch` carries its branches in `cases` (a value→subtree map) — expand each, so an
+  // atom `Ref` inside a Switch branch is inlined like anywhere else (else the branch
+  // renders blank). Parallel to children/item.
+  if (node?.cases && typeof node.cases === "object") {
+    for (const k of Object.keys(node.cases)) node.cases[k] = expandNode(node.cases[k] as AnyNode, contextOrg, inherit, props, scope);
+  }
+  // `ComponentSlot` carries chrome in `frame` (born when the slot matches) and `fallback`
+  // (shown when it doesn't) — both are real child slots, so an atom `Ref` inside them (e.g. a
+  // ✕ CloseButton on a rail/panel frame) must inline like anywhere else, else the Ref survives.
+  if (node?.frame) node.frame = expandNode(node.frame as AnyNode, contextOrg, inherit, props, scope);
+  if (node?.fallback) node.fallback = expandNode(node.fallback as AnyNode, contextOrg, inherit, props, scope);
+  return node;
+}
+
+
+export function expandRefs(def: UnoverseDefinition, contextOrg?: string): UnoverseDefinition {
+  // Whatever the tree embeds declares its own starting values; this is where they land on
+  // the slice those inlined nodes actually read (see `inheritState`). Merged AFTER the
+  // whole tree is walked, and beneath the def's own state, so nothing an author wrote is
+  // touched — including the v2 `state.view` compile, which runs before this.
+  const inherit: Record<string, unknown> = {};
+  // The atoms' own field contracts land here (see `inheritProps`), beneath whatever the
+  // host declared — merged after the walk, so authored props are never touched.
+  const fromAtoms: Record<string, Record<string, unknown>> = {};
+  if (def?.root) def.root = expandNode(def.root as AnyNode, contextOrg ?? def.org, inherit, fromAtoms);
+  if (Object.keys(inherit).length) def.state = { ...inherit, ...((def.state as Record<string, unknown>) ?? {}) };
+  mergeInheritedProps(def, fromAtoms);
+  return def;
+}