@unoverse-platform/studio 0.1.90 → 0.1.92

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

@@ -0,0 +1,487 @@
+/**
+ * Unoverse definition store (v0: flat JSON files under apps/unoverse/design/{components,templates}).
+ *
+ * These are the NEUTRAL primitive+style definitions — NOT the legacy
+ * React UMD bundles in packages/design-system/components. Later this
+ * becomes a DB/Redis store for hot-reload + per-tenant (resources/updated).
+ */
+
+import { readdirSync, existsSync, statSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { packagedDesignSystem } from "../dsPackage.js";
+import { readDefCached, defPath, isDefFile, defName, dirSignature, cachedBySignature } from "../fsCache.js";
+import { NODES_HOME, PLUGINS_DIR, DESIGN_HOME, INSTALLED_HOME, databaseOnly, designDir } from "../../paths.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// server/src -> apps/unoverse
+
+// Split 2026-08-29 (owner: files stay ~500-800 lines): definitions.ts is the
+// load/expand CORE and the public façade; homes.ts = where things live; model.ts =
+// the served shapes + kind words; catalog.ts = listing, manifests, state order.
+
+import { SHARED_DIR, projectDir, listOrgs, appDirs, templateDirs, componentDirs, resolveComponentDirs, componentHit, parseRef } from "../registry/homes.js";
+import type { UnoverseDefinition, ComponentManifest } from "../model.js";
+import type { AppManifest } from "../registry/catalog.js";
+import { normalizeDeclaredKind, defaultLayoutOf } from "../model.js";
+
+import { composeIncludes, expandNode, expandRefs, referencedDefinition, inheritState, mergeInheritedProps } from "./expand/index.js";
+import { compileComponentTree, synthesizeTemplateRoot } from "./compile/index.js";
+type AnyNode = Record<string, any>;
+
+/** Resolve a definition by name (case-insensitive), searching the relevant folder(s).
+ *
+ *  The EXPANDED result (clone + $include composition + Ref inlining — the expensive
+ *  part, run on every MCP read and workbench poll) is memoized on the mtimes of its
+ *  inputs: the def's own file/folder tree plus the atoms dir (any Ref may point at any
+ *  atom). Edit-and-refresh still works — an mtime moves, the signature changes, the
+ *  def re-expands. Returned objects are SHARED: callers must treat them as read-only
+ *  (all current consumers stringify or shallow-spread). */
+export function loadDefinition(
+  ref: string,
+  kind?: "component" | "app" | "atom" | "template",
+  /** "referenced" keeps `Ref` nodes and ships each named atom once in `defs`, for clients
+   *  that resolve references themselves. Default inlines every Ref, as it always has. */
+  mode: "expanded" | "referenced" = "expanded",
+  /** The org of the definition/app doing the asking. A bare component ref resolves in
+   *  this org first (a cloned pack's own refs mean its own components) — without it a
+   *  name two orgs share is an error rather than a guess. */
+  contextOrg?: string,
+): UnoverseDefinition | null {
+  // The two forms are memoized separately: same inputs, different output. Expansion
+  // reads the def's own org (stamped before form runs) so nested bare refs resolve
+  // within the def's org first.
+  const form = (d: UnoverseDefinition) => (mode === "referenced" ? referencedDefinition(d, d.org) : expandRefs(d));
+  const suffix = mode === "referenced" ? ":ref" : "";
+  // Default lookup is for SERVED kinds only (component/app). Atoms are
+  // internal — load them explicitly with kind: "atom" from the composition resolver.
+  const kinds: ("component" | "app" | "atom" | "template")[] = kind ? [kind] : ["component", "app"];
+  const { org: refOrg, name } = parseRef(ref);
+  const lower = name.toLowerCase();
+  for (const k of kinds) {
+    // Atoms live in ONE shared home. Components live in two tiers (marketplace +
+    // org packs). Apps live per org — search the ref's org (or all, bare).
+    // Templates (the Template Model kind) live in two tiers like components.
+    const dirs =
+      k === "app" ? appDirs(refOrg)
+      : k === "component" ? resolveComponentDirs(componentDirs(refOrg), refOrg, lower, contextOrg)
+      : k === "template" ? templateDirs(refOrg)
+      : [{ org: undefined as string | undefined, dir: SHARED_DIR[k] }];
+    for (const { org, dir } of dirs) {
+      // Flat form: <name>.{yaml,json}. The cached parse is SHARED — clone before expanding
+      // (expandRefs/composeIncludes mutate `root` in place); atoms are returned as-is
+      // (their consumers only read + clone the subtree).
+      const path = defPath(dir, lower);
+      if (path) {
+        const raw = readDefCached<UnoverseDefinition>(path);
+        // AN ATOM MAY COMPOSE ANOTHER ATOM, so it expands like everything else. Returning
+        // it raw was safe only while no atom carried a `Ref`: the composition resolver
+        // recurses, so a COMPONENT still drew the whole tree, but the atom served on its
+        // own (Studio's `unoverse://atoms/{name}`) kept a bare `Ref` that renders as
+        // NOTHING — observed live 2026-08-09, a form-toggle with no switch. Cloned before
+        // expanding, because the parsed object is shared and expansion mutates in place.
+        if (k === "atom") {
+          const sig = `${path}:${statSync(path).mtimeMs};${dirSignature([SHARED_DIR.atom])}`;
+          return cachedBySignature(`def:atom:${lower}${suffix}`, sig, () => form(structuredClone(raw)));
+        }
+        const sig = `${path}:${statSync(path).mtimeMs};${dirSignature([SHARED_DIR.atom, SHARED_DIR.component])}`;
+        // The org is stamped BEFORE form so expansion knows whose tree it is walking
+        // (bare nested refs resolve in the def's own org first).
+        return cachedBySignature(`def:${k}:${org ?? ""}:${lower}${suffix}`, sig, () => {
+          const d = Object.assign(structuredClone(raw), org ? { org } : {}) as UnoverseDefinition;
+          normalizeDeclaredKind(d);
+          if (k === "template") synthesizeTemplateRoot(d);
+          // The FLAT single-file form compiles its state tree exactly like the
+          // folder form (unified 2026-08-29 — a template-local part is flat).
+          if (k === "component") compileComponentTree(d);
+          return form(d);
+        });
+      }
+      // Folder form: <name>/<name>.{yaml,json} (+ $include sibling files, states/, …).
+      // A TEMPLATE folder needs no envelope at all: the manifest IS the metadata and
+      // the default layout is the root (standard anatomy — manifest + layouts/ +
+      // components/ + states/). An envelope, when present, remains an override.
+      const folderDir = join(dir, lower);
+      const entry = defPath(folderDir, lower);
+      const manifestPath = defPath(folderDir, "manifest");
+      const manifestOnly = k === "app" && !entry && !!manifestPath;
+      if (entry || manifestOnly) {
+        // The signature must cover EVERYTHING the composed def embeds. An org definition
+        // may `Ref` an org SIBLING (deal-list embeds deal's card at expansion), so the
+        // org's whole components dir rides the signature — without it, editing the
+        // referenced component leaves every referrer serving a stale embedded copy
+        // (observed live 2026-08-25: the deal rail kept the old tile after deal changed).
+        const sig = `${dirSignature([folderDir])};${dirSignature([SHARED_DIR.atom, SHARED_DIR.component])};${org ? dirSignature([join(projectDir(org), "components")]) : ""}`;
+        return cachedBySignature(`def:${k}:${org ?? ""}:${lower}${suffix}`, sig, () => {
+          const def: UnoverseDefinition = manifestOnly
+            ? (() => {
+                // manifestOnly is only true when manifestPath resolved.
+                const m = readDefCached<AppManifest>(manifestPath!);
+                return {
+                  unoverse: "1.0",
+                  kind: "app",
+                  name: lower,
+                  ...(m.description ? { description: m.description } : {}),
+                  ...(m.whenToUse ? { whenToUse: m.whenToUse } : {}),
+                  ...(m.category ? { category: m.category } : {}),
+                  ...(m.service ? { service: m.service } : {}),
+                } as UnoverseDefinition;
+              })()
+            // ...otherwise `entry` resolved (the `if` admits only these two cases).
+            : structuredClone(readDefCached<UnoverseDefinition>(entry!));
+          normalizeDeclaredKind(def);
+          if (org) def.org = org;
+          // APP manifest merge (ONE FOLDER GRAMMAR, owner ruling 2026-08-29): an app
+          // with an ENVELOPE (`<name>.yaml` = the states tree, what the app IS) still
+          // takes its discovery meta and MCP face from the manifest, exactly like a
+          // component. The manifestOnly branch above already injected these for the
+          // legacy envelope-less form.
+          // COMPOSITION CONTEXT SURVIVES THE MERGE (UNOVERSE_AUTHORING §3b, 2026-08-30).
+          // The manifest's `description` is the DISCOVERY subtitle; a definition that an
+          // Agent fills also has something to say about filling the WHOLE of it (a form's
+          // "a value you propose is a suggestion until the applicant confirms it", a
+          // page's "on refinement turns, MERGE"). That used to ride an unbound `brief` on
+          // the layout root; with briefs retired it is the envelope's own `description`,
+          // and this keeps it when the manifest's overwrites it. Authors still write one
+          // word in each file; only the compiler sees the split.
+          const keepComposition = (def: UnoverseDefinition, incoming?: string): void => {
+            if (incoming && def.description && def.description !== incoming)
+              (def as unknown as Record<string, unknown>).brief = def.description;
+          };
+          if (k === "app" && manifestPath && !manifestOnly) {
+            const m = readDefCached<AppManifest & { title?: string; version?: string }>(manifestPath);
+            keepComposition(def, m.description);
+            if (m.description) def.description = m.description;
+            if (m.whenToUse) def.whenToUse = m.whenToUse;
+            if (m.category) def.category = m.category;
+            if (m.title) def.title = m.title;
+            if (m.version) def.version = m.version;
+            if (m.service) (def as unknown as Record<string, unknown>).service = m.service;
+          }
+          // TEMPLATE manifest (STANDARD, like components): the home for discovery
+          // meta and the Studio preview mocks. Manifest wins over the envelope so the
+          // meta has one authoritative home.
+          if (k === "template" && manifestPath) {
+            const m = readDefCached<Record<string, unknown>>(manifestPath);
+            // THE BRIEF IS AUTHORED (§9d): `brief:` on the envelope is the word, and it wins.
+            // `keepComposition` below is the LEGACY rescue for a template written before the
+            // word existed, which said its brief in the envelope's `description` and relied
+            // on the manifest's discovery copy displacing it.
+            if (!(def as unknown as Record<string, unknown>).brief)
+              keepComposition(def, typeof m.description === "string" ? m.description : undefined);
+            for (const key of ["title", "description", "whenToUse", "category", "version"] as const) {
+              if (m[key] != null) (def as unknown as Record<string, unknown>)[key] = m[key];
+            }
+            if (m.preview && typeof m.preview === "object") def.preview = m.preview as Record<string, string[]>;
+            // SPATIAL-CAPABLE, exactly as a component is (§9c, ruled 2026-08-30): a
+            // template is found by what a guest says, through the same projection, the
+            // same registry switch and the same embedded text. The difference is only
+            // where eligibility comes from — a component's manifest is OPTIONAL, so its
+            // presence is the signal; a template's is MANDATORY, so presence says
+            // nothing and the registry row is the whole opt-in (default OFF).
+            def.spatial = true;
+          }
+          // COMPONENT manifest (OPTIONAL — its PRESENCE means "spatial-capable"; a basic
+          // component has none and is never discovered). It is the single home for the
+          // discovery meta (description/whenToUse/title): merged over the def so every
+          // consumer (nodegen, workbench, catalog) reads one merged shape. `spatial: true`
+          // is the projected capability flag — derived from presence, never authored.
+          if (k === "component" && manifestPath) {
+            const m = readDefCached<ComponentManifest>(manifestPath);
+            keepComposition(def, m.description);
+            if (m.description) def.description = m.description;
+            if (m.whenToUse) def.whenToUse = m.whenToUse;
+            if (m.category) def.category = m.category;
+            if (m.title) def.title = m.title;
+            if (m.icon) def.icon = m.icon;
+            if (m.version) def.version = m.version;
+            // The render contract: the manifest's arrival `defaultState` seeds the composed
+            // `state` block, so the SDK (which merges def.state beneath live data) renders
+            // that face on arrival. Falls back to any authored state, else "inline".
+            // (Legacy path — a v2 `state.view` tree below supersedes it: viewOf reads
+            // `view` before `defaultState`, so the compiled scalar wins.)
+            if (m.defaultState)
+              def.state = { ...((def.state as Record<string, unknown>) ?? {}), defaultState: m.defaultState };
+            // A hook's credentials, carried so the canvas offers the same picker a node
+            // gets. A component that fetches declares WHICH credential it needs; the value
+            // is resolved server-side at run time and never reaches this folder.
+            if (Array.isArray((m as { credentials?: unknown }).credentials))
+              def.credentials = (m as { credentials?: unknown[] }).credentials!.map(String);
+            def.spatial = true;
+          }
+          // No authored root → the DEFAULT LAYOUT is the root. The manifest MAY name
+          // it (`layout:`), but the standing law makes the line unnecessary: states
+          // own layouts and DECLARATION ORDER ranks them, so the base defaults to the
+          // FIRST DECLARED STATE. "main" survives only for apps with no states block.
+          const layoutsDir = join(folderDir, "layouts");
+          // THE APP TREE'S HOME is the ENVELOPE (`<name>.yaml` — one folder grammar,
+          // owner ruling 2026-08-29): the states tree is what the app IS. The
+          // manifest's `states:` block is the LEGACY home, still read for unswept
+          // folders, exactly like `kind:`/`defaultState`.
+          type AppStatesRecord = Record<
+            string,
+            { layout?: unknown; preview?: unknown; latch?: unknown; states?: Record<string, unknown> } | null
+          >;
+          const appStates: AppStatesRecord | undefined =
+            k === "app"
+              ? (() => {
+                  const fromEnvelope = entry ? (readDefCached<{ states?: AppStatesRecord }>(entry).states) : undefined;
+                  const fromManifest = manifestPath ? (readDefCached<{ states?: AppStatesRecord }>(manifestPath).states) : undefined;
+                  const s = fromEnvelope ?? fromManifest;
+                  return s && typeof s === "object" && !Array.isArray(s) ? s : undefined;
+                })()
+              : undefined;
+          const defaultLayout = k === "app"
+            ? defaultLayoutOf({ layout: manifestPath ? readDefCached<{ layout?: string }>(manifestPath).layout : undefined, states: appStates })
+            : manifestPath ? defaultLayoutOf(readDefCached<{ layout?: string; states?: unknown }>(manifestPath)) : "main";
+          // THE CONTAINERS (UNOVERSE_INTERFACE_MODEL §4), apps only: pure passthrough of
+          // the manifest's `containers:` block. The SDK resolves a layout's
+          // `type: Container` node against it; Studio seeds each container's own `mock`.
+          // Sources (`workflow`/`query`/`autoTrigger`) ride along as data until
+          // per-container routing lands.
+          if (k === "app" && manifestPath) {
+            const man = readDefCached<{ templates?: unknown; states?: Record<string, unknown> }>(manifestPath);
+            const merged: Record<string, unknown> = {};
+            // The legacy container form (deal-workspace): a top-level `templates:` block.
+            if (man.templates && typeof man.templates === "object" && !Array.isArray(man.templates))
+              Object.assign(merged, man.templates as Record<string, unknown>);
+            // A STATE ENTRY CARRIES ONLY WHAT SEEDS IT (owner ruling 2026-08-28
+            // evening): its `preview`. What a place holds and the judgment granted to
+            // it live on the PLACED NODE in the state's layout — projected below,
+            // after the layouts compose.
+            for (const [sname, sentry] of Object.entries(appStates ?? {})) {
+              if (!sentry || typeof sentry !== "object" || Array.isArray(sentry)) continue;
+              if (Array.isArray((sentry as { preview?: unknown }).preview)) {
+                merged[sname] = { ...(sentry as Record<string, unknown>) };
+                // The per-state spelling ALSO feeds the served preview map, so
+                // every consumer (Studio's walk, the mock synthesizer) sees the
+                // same mocks whichever home authored them. The legacy top-level
+                // map wins per state where both exist.
+                def.preview = { [sname]: (sentry as { preview: string[] }).preview, ...(def.preview ?? {}) };
+              }
+            }
+            if (Object.keys(merged).length) def.templates = merged as NonNullable<typeof def.templates>;
+          }
+          // THE DECLARED PATH WINS (owner ruling 2026-08-29): a state names its
+          // layout as a path relative to the definition folder (`layout:
+          // layouts/standard`) — nothing assumed, subfolders legal. The same-name
+          // resolution below it survives ONLY for the unswept installed tier,
+          // exactly like `kind:`/`defaultState`: legacy, still read, lint-forbidden.
+          const declaredLayouts: Record<string, string> = {};
+          for (const [sname, sentry] of Object.entries(appStates ?? {}))
+            if (sentry && typeof sentry === "object" && typeof sentry.layout === "string" && sentry.layout)
+              declaredLayouts[sname] = sentry.layout;
+          // THE TREE IS THE MACHINE (owner ruling 2026-08-29 late): a component's
+          // root Switch restated the tree, so the compiler SYNTHESIZES it — states
+          // declare layouts, the Switch falls out. An AUTHORED root wins untouched
+          // (a shell beyond the plain Switch is real design: text-chat's moods).
+          if (k === "component" && !def.root) {
+            const cTree = (def as unknown as { states?: Record<string, { layout?: unknown } | null> }).states;
+            if (cTree && typeof cTree === "object" && !Array.isArray(cTree)) {
+              const cases: Record<string, unknown> = {};
+              for (const [sname, sentry] of Object.entries(cTree))
+                if (sentry && typeof sentry === "object" && typeof sentry.layout === "string")
+                  cases[sname] = { $include: sentry.layout };
+              const first = Object.keys(cases)[0];
+              if (first) {
+                if (!("default" in cases)) cases.default = cases[first];
+                def.root = {
+                  type: "Box",
+                  style: { width: "full", container: "inline-size" },
+                  children: [{ type: "Switch", on: "state", cases }],
+                };
+              }
+            }
+          }
+          if (!def.root) {
+            if (declaredLayouts[defaultLayout]) def.root = { $include: declaredLayouts[defaultLayout] };
+            else if (defPath(layoutsDir, defaultLayout)) def.root = { $include: `layouts/${defaultLayout}` };
+          }
+          if (def.root) def.root = composeIncludes(def.root, folderDir);
+          // PROPS EXTRACT (UNOVERSE_MCP_FORMS §Per-field purpose): a long props block may
+          // live in a sibling file — `props: { $include: props }` — with the ordinary
+          // include every layout already uses. Composed here so every reader (schema
+          // compile, synthesize, workbench) sees one flat props map, never the include.
+          if (def.props) def.props = composeIncludes(def.props, folderDir);
+          // TEMPLATE LAYOUTS (name-sync, docs/design/05): a template with MULTIPLE
+          // layouts/ files is a set of full arrangements — the SDK presents the one
+          // whose NAME matches the latest surfaced component view, else the default.
+          // Each is composed+expanded exactly like the root and served as def.layouts.
+          if (k === "app" && existsSync(layoutsDir)) {
+            // ANATOMY UNIFIED (owner ruling 2026-08-22): layouts/ is the template's ONE
+            // drawings folder, so it holds ARRANGEMENTS and the drawings its chrome
+            // includes (substates, shell moods — the retired states/ folder's files).
+            // Only arrangements are served as def.layouts: a drawing some other file
+            // `$include`s is a part, not a presentation the SDK may switch to.
+            const included = new Set<string>();
+            const scanDirs = ["layouts", "components", "states"].map((d) => join(folderDir, d)).filter(existsSync);
+            for (const d of scanDirs)
+              for (const f of readdirSync(d).filter(isDefFile)) {
+                const collect = (n: unknown): void => {
+                  if (Array.isArray(n)) return n.forEach(collect);
+                  if (!n || typeof n !== "object") return;
+                  const inc = (n as { $include?: unknown }).$include;
+                  if (typeof inc === "string" && inc.startsWith("layouts/")) included.add(inc.slice("layouts/".length));
+                  for (const v of Object.values(n)) collect(v);
+                };
+                try {
+                  collect(readDefCached(join(d, f)));
+                } catch {
+                  /* that file lints separately */
+                }
+              }
+            const names = readdirSync(layoutsDir)
+              .filter(isDefFile)
+              .map(defName)
+              .filter((n) => n === defaultLayout || !included.has(n))
+              // A state with a DECLARED path is composed from the declaration below;
+              // its same-name file (when both exist) must not double-serve.
+              .filter((n) => !(n in declaredLayouts));
+            // THE PROPS AN ATOM DRAWN INSIDE A LAYOUT DECLARES (expand.ts,
+            // `inheritProps`): layouts expand HERE, before `expandRefs` sees the root,
+            // so the accumulator has to ride along or every atom-drawn field is missing
+            // from the compiled schema.
+            const fromAtoms: Record<string, Record<string, unknown>> = {};
+            const arrangements: Record<string, unknown> = Object.fromEntries(
+              names.map((n) => [n, expandNode(composeIncludes({ $include: `layouts/${n}` }, folderDir) as AnyNode, undefined, undefined, fromAtoms)]),
+            );
+            // DECLARED PATHS (2026-08-29 ruling): each state's arrangement composes
+            // from its own `layout:` path, keyed by the STATE name — the SDK's
+            // view→layout match is unchanged because keys were always state names.
+            for (const [sname, lpath] of Object.entries(declaredLayouts))
+              arrangements[sname] = expandNode(composeIncludes({ $include: lpath }, folderDir) as AnyNode, undefined, undefined, fromAtoms);
+            mergeInheritedProps(def, fromAtoms);
+            if (Object.keys(arrangements).length > 1) {
+              def.defaultLayout = defaultLayout;
+              def.layouts = arrangements;
+            }
+            // THE PLACED NODE OWNS THE MOUNT (owner ruling 2026-08-28 evening): a
+            // layout's `type: Template` node carries `template:` (what it holds) and
+            // `director:` (the judgment granted to this placement — any placed
+            // template may carry one). Projected onto def.templates keyed by the
+            // node's name, merged over the state entry's own keys (preview), and
+            // stamped with everything the mounted template CLAIMS, so the reaction
+            // ladder can enter the holding state on arrival.
+            //
+            // WHAT IT CLAIMS IS NOT ONLY ITS STATE NAMES (widened 2026-08-30). A
+            // grid-page claims `grid`/`page` because its own states carry its content,
+            // and reading the state names was enough. A rich template's content wears
+            // its SECTIONS' faces instead — Perfect Day's states are just `page`, while
+            // what actually arrives is `hero`, `day-early`, `early`, `late`, `gallery` —
+            // so a state-names-only claim set could never be matched and the holding
+            // state could never activate. The claim set is the union: the template has
+            // something to show when ANY face it draws is on screen.
+            for (const [lname, tree] of Object.entries(def.layouts ?? {})) {
+              const walkMounts = (n: unknown): void => {
+                if (Array.isArray(n)) return n.forEach(walkMounts);
+                if (!n || typeof n !== "object") return;
+                const un = n as { type?: unknown; name?: unknown; template?: unknown; director?: unknown; children?: unknown; frame?: unknown; cases?: Record<string, unknown> };
+                if (un.type === "Template" && typeof un.template === "string" && un.template) {
+                  const pname = typeof un.name === "string" && un.name ? un.name : lname;
+                  const tpl = loadDefinition(un.template, "template");
+                  const base = (def.templates?.[pname] ?? {}) as Record<string, unknown>;
+                  def.templates = {
+                    ...(def.templates ?? {}),
+                    [pname]: { ...base, template: un.template, ...(un.director ? { director: un.director as Record<string, unknown> } : {}), claims: [...new Set([...Object.keys(tpl?.layouts ?? {}), ...Object.values(tpl?.sections ?? {}).flat().map((sec) => sec.face).filter(Boolean)])] },
+                  } as NonNullable<typeof def.templates>;
+                }
+                walkMounts(un.children);
+                walkMounts(un.frame);
+                if (un.cases) Object.values(un.cases).forEach(walkMounts);
+              };
+              walkMounts(tree);
+            }
+          }
+          // STATE MODEL v2 (UNOVERSE_STATE_MODEL §5 rule 5): a template's manifest
+          // `stateOrder` is served on the def — the SDK's priority ladder and
+          // arrival-scan order. Absent → the SDK stays in legacy recency mode.
+          if (k === "app" && manifestPath) {
+            const so = readDefCached<{ stateOrder?: unknown }>(manifestPath).stateOrder;
+            if (Array.isArray(so)) def.stateOrder = so.filter((n): n is string => typeof n === "string");
+          }
+          // THE TEMPLATE TREE (STATE_MODEL v2, template tier — sab checkpoint,
+          // 2026-08-08): the manifest's `states:` block is the template's state
+          // machine, compiled exactly like a component's `state.view` tree:
+          //  - def.stateTree  = the nested projection (viewers render it)
+          //  - def.stateOrder = the REACTION ladder — top-level names minus the
+          //    BASE (the state named for the default layout), in declared order.
+          //    Supersedes an authored `stateOrder`.
+          //  - CONTAINMENT is structural: a base substate (welcome) exists ONLY in
+          //    the base arrangement. Its composed subtree is STRIPPED from every
+          //    other layout — no hand-written guard, the declaration is enforced
+          //    by compilation. (Identified by structural equality: the composed
+          //    states/<name> file IS the inlined node.)
+          if (k === "app" && appStates) {
+            // THE LATCH IS A FACT ABOUT A STATE (MCP guide §The Component Latch, moved off
+            // the manifest 2026-08-31). Projected here for the same reason `preview` is:
+            // the raw states block never rides the served def, so anything a state declares
+            // has to become a projection or it is lost. `def.latches` is what the SDK's
+            // `resolveLatch` looks the wearer's face up in — a state that says nothing here
+            // can never be addressed, and an instance retracting out of an addressable
+            // state drops the pill with nothing to unregister.
+            const latches: NonNullable<UnoverseDefinition["latches"]> = {};
+            for (const [sname, sentry] of Object.entries(appStates)) {
+              const l = (sentry as { latch?: { title?: unknown; icon?: unknown } } | null)?.latch;
+              // TITLE OR NOTHING: the pill's whole content is its title, so a latch without
+              // one draws a nameless pill the guest cannot read. Taking a declared-but-empty
+              // block literally is what makes the authoring slip visible.
+              if (l && typeof l === "object" && typeof l.title === "string" && l.title.trim())
+                latches[sname] = { title: l.title, ...(typeof l.icon === "string" ? { icon: l.icon } : {}) };
+            }
+            if (Object.keys(latches).length) def.latches = latches;
+            // The tree COMPILES into projections; the raw block never rides the
+            // served def (stateTree is the viewers' shape).
+            delete (def as unknown as Record<string, unknown>).states;
+            const mStates = appStates;
+            {
+              const names = Object.keys(mStates);
+              const base = names.includes(defaultLayout) ? defaultLayout : names[0];
+              def.stateTree = names.map((n) => {
+                const s = mStates[n];
+                const entry: NonNullable<UnoverseDefinition["stateTree"]>[number] = { name: n };
+                if (s && typeof s === "object" && s.states && typeof s.states === "object")
+                  entry.states = Object.keys(s.states).map((sub) => ({ name: sub }));
+                return entry;
+              });
+              def.stateOrder = names.filter((n) => n !== base);
+              const baseSubs = Object.keys((mStates[base] as { states?: Record<string, unknown> } | null)?.states ?? {});
+              if (def.layouts && baseSubs.length) {
+                // ANATOMY UNIFIED (owner ruling 2026-08-22): templates carry ONE drawings
+                // folder, like components — a substate's drawing lives in layouts/. The
+                // states/ path remains a LEGACY fallback so an unmigrated installed
+                // template keeps rendering; the lint retires it.
+                const marks = baseSubs
+                  .map((s) => defPath(join(folderDir, "layouts"), `${base}-${s}`) ?? defPath(join(folderDir, "layouts"), s) ?? defPath(join(folderDir, "states"), s))
+                  .filter((p): p is string => Boolean(p))
+                  .map((p) => JSON.stringify(expandNode(composeIncludes(readDefCached(p), folderDir) as AnyNode)));
+                const strip = (node: unknown): unknown => {
+                  if (Array.isArray(node)) return node.filter((c) => !marks.includes(JSON.stringify(c))).map(strip);
+                  if (node && typeof node === "object") {
+                    const out: AnyNode = {};
+                    for (const [k2, v2] of Object.entries(node)) out[k2] = strip(v2);
+                    return out;
+                  }
+                  return node;
+                };
+                for (const n of Object.keys(def.layouts)) if (n !== base) def.layouts[n] = strip(def.layouts[n]);
+              }
+            }
+          }
+          // STATE MODEL v2 (UNOVERSE_STATE_MODEL §5 rules 1+2): an authored
+          // `state.view` TREE is the component's state machine — public states owning
+          // layouts, private substates nested beneath. It COMPILES here; the tree
+          // itself never reaches the render scope:
+          //   - def.publicStates = the public menu (top-level names, tree order)
+          //   - def.initialView  = the declared initial (the retract/fallback base)
+          //   - def.state.view   → the scalar initial (the render scope reads a value)
+          //   - a nested `on` + `initial` pair → its scalar initial (the substep key)
+          if (k === "component") compileComponentTree(def);
+          if (k === "template") synthesizeTemplateRoot(def, folderDir);
+          return k === "atom" ? def : form(def);
+        });
+      }
+    }
+  }
+  return null;
+}
+