@unoverse-platform/studio 0.1.90 → 0.1.91

package/vendor/base/src/definitions/fsCache.ts

@@ -0,0 +1,128 @@
+/**
+ * mtime-validated definition file cache.
+ *
+ * The definition + theme stores (definitions.ts, theme.ts) read the same small rx/ files
+ * on EVERY MCP resource read/list and every theme fetch — and a single
+ * `listDefinitions()` re-reads the same atoms once per composing component. Re-reading +
+ * re-parsing them per request is the server's hottest avoidable cost.
+ *
+ * This caches the PARSED value keyed by absolute path, re-reading ONLY when the file's
+ * mtime changes. So hot-reload still works (edit a definition, refresh → mtime moves →
+ * re-parse), but a steady-state request pays a single `stat()` instead of open+read+parse.
+ *
+ * Returned objects are SHARED, not cloned — callers that MUTATE the parsed value MUST
+ * clone first (the definition loader does, to expand atom `Ref`s in place); theme reads
+ * are read-only. Call only for files known to exist (callers already guard with existsSync);
+ * `statSync` throws on a missing path.
+ *
+ * ---
+ *
+ * FORMAT: rx definitions are authored as `.yaml` OR `.json` and the two are
+ * interchangeable everywhere. YAML is the authoring format (it carries comments and reads
+ * without punctuation noise); JSON stays the WIRE format, because definitions are served
+ * verbatim as MCP resources to clients that `JSON.parse` them. Nothing downstream of this
+ * module knows which extension a definition was authored in.
+ *
+ * YAML parses to the same data model, so the JSON Schema at `rx/_schema/` validates both
+ * with no change. `$schema` is stripped on read: an editor needs the pointer in the file,
+ * a client must never receive it in the payload.
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from "fs";
+import { join } from "path";
+import { parse as parseYaml } from "yaml";
+
+/** Authored definition extensions, in RESOLUTION ORDER. `.yaml` wins so a converted file
+ *  takes precedence over a `.json` left behind mid-migration. `defPath` is the only place
+ *  that order is applied — never re-implement it at a call site. */
+export const DEF_EXTS = [".yaml", ".json"] as const;
+
+const cache = new Map<string, { mtimeMs: number; data: unknown }>();
+
+/** Parsed definition for `path`, cached until the file's mtime changes. Parser is chosen
+ *  by extension; `$schema` (an editor affordance, never wire data) is dropped. */
+export function readDefCached<T = any>(path: string): T {
+  const mtimeMs = statSync(path).mtimeMs;
+  const hit = cache.get(path);
+  if (hit && hit.mtimeMs === mtimeMs) return hit.data as T;
+  const text = readFileSync(path, "utf8");
+  const parsed = path.endsWith(".yaml") ? parseYaml(text) : JSON.parse(text);
+  if (parsed && typeof parsed === "object" && "$schema" in parsed) delete (parsed as Record<string, unknown>).$schema;
+  cache.set(path, { mtimeMs, data: parsed });
+  return parsed as T;
+}
+
+/**
+ * Resolve an EXTENSION-LESS definition path to the file that actually exists, or
+ * undefined. `defPath(dir, "card")` finds `card.yaml` then `card.json`.
+ *
+ * Every definition lookup goes through here so the migration stays invisible: a folder may
+ * hold YAML and JSON side by side while it is being converted. Authoring BOTH for one name
+ * is an error the linter reports — this resolver silently prefers `.yaml` rather than
+ * failing, because a half-converted tree must keep serving.
+ */
+export function defPath(dir: string, name: string): string | undefined {
+  for (const ext of DEF_EXTS) {
+    const p = join(dir, name + ext);
+    if (existsSync(p)) return p;
+  }
+  return undefined;
+}
+
+/** True when `file` is an authored definition (either format). Replaces the
+ *  `endsWith(".json")` filters that used to gate directory scans. */
+export const isDefFile = (file: string): boolean => DEF_EXTS.some((e) => file.endsWith(e));
+
+/** A definition filename without its extension: `welcome.yaml` → `welcome`. */
+export const defName = (file: string): string => file.replace(/\.(yaml|json)$/, "");
+
+const textCache = new Map<string, { mtimeMs: number; text: string }>();
+
+/** File text for `path`, cached until the file's mtime changes. Same contract as
+ *  readDefCached — for large non-JSON reads (e.g. the single-file webSDK bundle)
+ *  that would otherwise sync-read megabytes off disk per request. */
+export function readTextCached(path: string): string {
+  const mtimeMs = statSync(path).mtimeMs;
+  const hit = textCache.get(path);
+  if (hit && hit.mtimeMs === mtimeMs) return hit.text;
+  const text = readFileSync(path, "utf8");
+  textCache.set(path, { mtimeMs, text });
+  return text;
+}
+
+/**
+ * Change signature over a set of directories: every definition file's name+mtime,
+ * recursing into subdirectories (definition folders carry `states/` etc. — all
+ * shallow). A stat sweep is tens of µs for the rx/ dirs — versus re-running full
+ * token/definition resolution per request. Missing dirs contribute their absence
+ * (so creating one invalidates).
+ *
+ * MUST cover both extensions: a signature that only saw `.json` would leave every YAML
+ * edit invisible to hot reload, and the staleness would look like a caching bug rather
+ * than a missing filter.
+ */
+export function dirSignature(dirs: string[]): string {
+  const parts: string[] = [];
+  const walk = (dir: string) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory()) walk(join(dir, e.name));
+      else if (isDefFile(e.name)) parts.push(`${dir}/${e.name}:${statSync(join(dir, e.name)).mtimeMs}`);
+    }
+  };
+  for (const dir of dirs) {
+    if (!existsSync(dir)) parts.push(`${dir}:absent`);
+    else walk(dir);
+  }
+  return parts.join(";");
+}
+
+const computed = new Map<string, { sig: string; value: unknown }>();
+
+/** Memoize `compute()` under `key`, re-running only when `sig` changes.
+ *  Returned values are SHARED — callers must not mutate them. */
+export function cachedBySignature<T>(key: string, sig: string, compute: () => T): T {
+  const hit = computed.get(key);
+  if (hit && hit.sig === sig) return hit.value as T;
+  const value = compute();
+  computed.set(key, { sig, value });
+  return value;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * rx DEFINITIONS: components, templates, atoms, themes.
+ *
+ * The other half of "read the YAML and make it mean something". `manifests/` turns node
+ * YAML into a runnable node; this turns rx YAML into the components, templates and tokens
+ * an interface is assembled from.
+ *
+ * IT LIVES HERE SO STUDIO CAN BE PUBLISHED. These four files sat in the platform server, so
+ * anything outside this monorepo that wanted to list or render rx content had to reach into
+ * `apps/unoverse/server/src` — which nothing installed from npm can do. Studio was blocked
+ * on exactly that.
+ *
+ * READING, not rendering. These read rx off disk; `@unoverse/sdk` renders it. The split
+ * matters: the SDK is a dumb renderer and must stay one.
+ */
+export { resolveStringTemplate } from "../template/StringTemplateResolver.js";
+export * from "./definitions.js";
+export * from "./theme.js";
+export * from "./inputs.js";

package/vendor/base/src/definitions/inputs.ts

@@ -0,0 +1,30 @@
+/**
+ * THE single derivation of "which definition props are workflow INPUTS".
+ *
+ * A node's `configSchema` is derived FROM the component's `props`, and that derivation has
+ * to live in ONE place so node synthesis, the workbench CONTROLS panel and the server never
+ * disagree. Consumers do not re-decide what an input is.
+ *
+ * IMPLEMENTED HERE, not re-exported. This file used to be a single line pulling it out of
+ * `@unoverse-platform/plugin-base`, which made the new runtime depend on the legacy node
+ * library it exists to replace. Backwards, and it would have travelled into every consumer
+ * of this package as a real npm dependency.
+ *
+ * `plugin-base` still carries its own copy, for the TypeScript nodes that import it. A
+ * knowing duplicate: eight lines of a rule that has not changed, and that copy dies with the
+ * last code node. THIS is the canonical one.
+ *
+ * The rule (mirroring the design system's `workflowInput`): a prop is an input when it
+ * declares `input: true`. A definition declaring NO `input` flags at all makes every prop an
+ * input, which is back-compat for the single-object components that legitimately expose all
+ * of them.
+ */
+export interface InputPropLike {
+  input?: boolean;
+}
+
+export function inputPropKeys(props: Record<string, InputPropLike> | undefined): string[] {
+  const entries = Object.entries(props ?? {});
+  const explicit = entries.some(([, p]) => p?.input !== undefined);
+  return entries.filter(([, p]) => (explicit ? p?.input === true : true)).map(([k]) => k);
+}

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

@@ -0,0 +1,80 @@
+/**
+ * The COMPONENT-TREE compiler: `states:` → the served projections.
+ * Split from compile.ts into this folder 2026-09-02; the rules are unchanged.
+ */
+
+import type { UnoverseDefinition } from "../../model.js";
+
+/** STATE MODEL v2 compile for a COMPONENT def (both authored forms — folder and
+ *  FLAT single-file, unified 2026-08-29): the tree (top-level `states:`; legacy
+ *  `state.view`) becomes the served projections (publicStates / initialView /
+ *  stateTree), the flat scalars the render scope reads, and the SYNTHESIZED root
+ *  where none is authored. */
+export function compileComponentTree(def: UnoverseDefinition): void {
+  // THE RULED FORM (2026-08-29): the tree lives at TOP-LEVEL `states:`
+  // like every kind; `state.view` is the legacy wrapper, still read.
+  const topStates = (def as unknown as { states?: unknown }).states;
+  const topForm = topStates && typeof topStates === "object" && !Array.isArray(topStates)
+    ? { states: topStates as Record<string, never> }
+    : undefined;
+  const tree = (topForm ?? (def.state as Record<string, unknown> | undefined)?.view) as
+    | {
+        initial?: unknown;
+        states?: Record<string, { on?: unknown; initial?: unknown; states?: Record<string, unknown> } | null>;
+      }
+    | undefined;
+  if (!(tree && typeof tree === "object" && tree.states && typeof tree.states === "object")) return;
+  const names = Object.keys(tree.states);
+  const initial = typeof tree.initial === "string" ? tree.initial : names[0];
+  def.publicStates = names;
+  def.initialView = initial;
+  // The nested projection viewers render from (never scan layouts for it).
+  def.stateTree = names.map((n) => {
+    const s = (tree.states as Record<string, { layout?: unknown; on?: unknown; initial?: unknown; states?: Record<string, { layout?: unknown } | null> } | null>)[n];
+    const entry: NonNullable<UnoverseDefinition["stateTree"]>[number] = { name: n };
+    if (s && typeof s === "object") {
+      if (typeof s.layout === "string") entry.layout = s.layout;
+      if (typeof s.on === "string") entry.on = s.on;
+      if (typeof s.initial === "string") entry.initial = s.initial;
+      if (s.states && typeof s.states === "object")
+        entry.states = Object.entries(s.states).map(([k, v]) => ({
+          name: k,
+          ...(v && typeof v === "object" && typeof v.layout === "string" ? { layout: v.layout } : {}),
+        }));
+    }
+    return entry;
+  });
+  // ONE AXIS ON A MIGRATED SLICE. The manifest's `defaultState` is seeded above
+  // for legacy components; a component with a tree has already said where it
+  // arrives, so the alias is dropped here rather than shipped alongside `view`.
+  // Two spellings on one slice is how a stale reader keeps working by accident:
+  // it reads the alias, sees the ARRIVAL state forever, and never notices the
+  // component moved. (The manifest keeps the key: at app level it is the load
+  // mode the router branches on, a different axis with the same name.)
+  // STARTING VALUES (owner ruling 2026-08-29 late): the authored home is
+  // `values:` — the initial values of keys the component writes (the
+  // setValue vocabulary). `state:` scalars are the legacy spelling,
+  // still read; either way the SERVED shape is unchanged (def.state).
+  const rawValues = (def as unknown as { values?: unknown }).values;
+  const { defaultState: _legacyAlias, view: _legacyTree, ...legacyScalars } = (def.state ?? {}) as Record<string, unknown>;
+  const authored =
+    rawValues && typeof rawValues === "object" && !Array.isArray(rawValues)
+      ? (rawValues as Record<string, unknown>)
+      : legacyScalars;
+  delete (def as unknown as Record<string, unknown>).values;
+  // ORDER IS THE PRIORITY, at BOTH levels (2026-08-15). The first state
+  // declared is the one the component arrives in, and the first substate
+  // declared is the step its `on` axis starts on. An `initial` key said the
+  // same thing a second time and was free to contradict the list, which is
+  // how a component could declare one arrival and ship another. It is still
+  // READ where a def has not been swept, and lint-forbidden in rx.
+  const flat: Record<string, unknown> = { ...authored, state: initial };
+  delete (def as unknown as Record<string, unknown>).states; // the tree compiled; the raw block never rides the served def
+  for (const s of Object.values(tree.states))
+    if (s && typeof s === "object" && typeof s.on === "string") {
+      const subs = s.states && typeof s.states === "object" ? Object.keys(s.states) : [];
+      const step = typeof s.initial === "string" ? s.initial : subs[0];
+      if (step) flat[s.on] = step;
+    }
+  def.state = flat;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * The COMPILERS, one file per job (split from compile.ts 2026-09-02, mirroring
+ * the expand/ split of 2026-08-30):
+ *
+ *   component.ts   a component's `states:` tree → served projections
+ *   sections.ts    a template layout's three words → wire claims + sections
+ *   template.ts    a template's states (folder) or root (block) → layouts/previews
+ */
+
+export { compileComponentTree } from "./component.js";
+export { expandTemplateSections } from "./sections.js";
+export { synthesizeTemplateRoot } from "./template.js";

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";