@unoverse-platform/studio 0.1.89 → 0.1.91

package/vendor/base/src/boot.ts

@@ -0,0 +1,245 @@
+/**
+ * Boot report — ONE readout at the end of startup, instead of a line per thing loaded.
+ *
+ * Boot used to narrate itself: 84 node ticks, 24 credential ticks, 27 "local wins"
+ * lines, each registration announcing itself as it happened. Two problems with that.
+ * It reads as noise rather than as a product, and a real failure (the plugin-state
+ * fetch that fails silently below) sits in the middle of it styled exactly like a
+ * success tick, so nobody sees it.
+ *
+ * The rule here: COUNT the healthy, NAME the anomalous. A node that loaded is a
+ * number; a node that was skipped, shadowed, disabled or missing metadata is a line
+ * with its name on it. Nothing diagnostic is lost, because the per-item detail is
+ * still emitted at debug level (LOG_LEVEL=debug) and the full catalog is one
+ * `GET /nodes` away.
+ *
+ * Collect from anywhere during boot, print once from index.ts.
+ */
+
+const DEBUG = (process.env.LOG_LEVEL ?? "").toLowerCase() === "debug";
+
+// The readout is a product surface: labels recede, values read, addresses invite the
+// click. One accent, no boxes, and everything still greps clean because whole segments
+// are wrapped rather than words. NO_COLOR is the standard opt-out.
+const COLOR = !process.env.NO_COLOR;
+const paint = (code: string) => (s: string) => (COLOR ? `\x1b[${code}m${s}\x1b[0m` : s);
+const bold = paint("1");
+const dim = paint("2");
+const cyan = paint("36");
+const yellow = paint("33");
+const red = paint("31");
+
+type Notice = { level: "warn" | "error"; text: string };
+type Endpoint = { label: string; url: string; note?: string };
+
+const state = {
+  startedAt: Date.now(),
+  packages: 0,
+  nodes: [] as string[],
+  credentials: [] as string[],
+  credentialsSkipped: 0,
+  components: null as { node: string; count: number } | null,
+  manifests: null as { nodes: number; credentials: number; shadowed: string[]; disabled: string[] } | null,
+  pluginStates: 0,
+  pluginStateError: null as string | null,
+  pluginsLocalWin: [] as string[],
+  pluginsFromNpm: [] as string[],
+  pluginsDisabled: [] as string[],
+  auth: null as string | null,
+  redis: null as string | null,
+  engine: null as string | null,
+  watching: null as string | null,
+  endpoints: [] as Endpoint[],
+  notices: [] as Notice[],
+  printed: false,
+};
+
+/** Per-item detail, kept for LOG_LEVEL=debug. Silent otherwise. */
+function detail(line: string): void {
+  if (DEBUG) console.log(line);
+}
+
+export const boot = {
+  packages(n: number) {
+    state.packages = n;
+    detail(`[boot] discovered ${n} node packages`);
+  },
+
+  node(type: string) {
+    state.nodes.push(type);
+    detail(`[boot]   node ${type}`);
+  },
+
+  credential(name: string, skipped = false) {
+    if (skipped) {
+      // First-wins is the DESIGNED behaviour for a shared credential (several AWS
+      // packages legitimately declare awsCredential), so it is not a warning and
+      // never belonged in the readout. It was 48 warning lines a boot.
+      state.credentialsSkipped++;
+      detail(`[boot]   credential ${name} already registered, kept the first`);
+      return;
+    }
+    state.credentials.push(name);
+    detail(`[boot]   credential ${name}`);
+  },
+
+  components(node: string, count: number) {
+    state.components = { node, count };
+  },
+
+  manifests(m: { nodes: number; credentials: number; shadowed: string[]; disabled: string[] }) {
+    state.manifests = m;
+  },
+
+  pluginStates(n: number) {
+    // Loaded once at boot and again after the engine comes up; the count is the same
+    // fact both times, so the report holds one of it rather than printing twice.
+    state.pluginStates = n;
+  },
+
+  /**
+   * A failed read of the plugin state table. Not a notice on its own: in merged mode the
+   * first read races the engine binding :4101 and is retried. It becomes a notice only
+   * if no state was ever loaded, which is the case where plugins really are missing.
+   */
+  pluginStateFetchFailed(message: string) {
+    state.pluginStateError = message;
+    detail(`[boot]   plugin state read failed: ${message}`);
+  },
+
+  pluginLocalWin(name: string, installedVersion?: string) {
+    state.pluginsLocalWin.push(name);
+    detail(`[boot]   ${name}: local source wins over npm${installedVersion ? ` (npm has ${installedVersion})` : ""}`);
+  },
+
+  pluginFromNpm(name: string, source = "npm") {
+    state.pluginsFromNpm.push(name);
+    detail(`[boot]   ${name}: loaded from ${source}`);
+  },
+
+  pluginDisabled(name: string) {
+    state.pluginsDisabled.push(name);
+  },
+
+  auth(posture: string) {
+    state.auth = posture;
+  },
+
+  redis(status: string) {
+    state.redis = status;
+  },
+
+  engine(where: string) {
+    state.engine = where;
+  },
+
+  /** Manifest hot reload is a dev affordance worth one line, because it changes what a save does. */
+  watching(dir: string) {
+    state.watching = dir;
+  },
+
+  endpoint(label: string, url: string, note?: string) {
+    state.endpoints.push({ label, url, note });
+  },
+
+  /**
+   * Addresses are listed in the order someone reaches for them, not the order the
+   * listeners happened to bind. Studio is what a person opens; the internal runtime is
+   * what a machine calls.
+   */
+  endpointOrder: ["Studio", "MCP", "Runtime", "Builder MCP"],
+
+  notice(level: "warn" | "error", text: string) {
+    state.notices.push({ level, text });
+  },
+
+  /**
+   * True until the report prints. Loaders that run BOTH at boot and later (the manifest
+   * watcher, install/uninstall) ask this: during boot they hand their result to the
+   * report, afterwards they log it themselves, because a reload with nothing else on
+   * screen is a real event and should say so.
+   */
+  isBooting() {
+    return !state.printed;
+  },
+
+  /** Everything the report knows, for a status route or a test. */
+  snapshot() {
+    return { ...state };
+  },
+
+  print() {
+    if (state.printed) return;
+    state.printed = true;
+    const ready = ((Date.now() - state.startedAt) / 1000).toFixed(1);
+
+    const rows: Array<[string, string]> = [];
+    rows.push(["Nodes", `${state.nodes.length} registered from ${state.packages} packages`]);
+    if (state.manifests) {
+      const m = state.manifests;
+      const parts = [`${m.nodes} loaded`];
+      if (m.shadowed.length) parts.push(`${m.shadowed.length} shadowed by code`);
+      if (m.disabled.length) parts.push(`${m.disabled.length} disabled`);
+      rows.push(["Manifests", parts.join(", ")]);
+    }
+    // The skipped count is every re-declaration of a credential that already exists,
+    // which is the shared-credential design working. It is a debug fact, not a headline.
+    rows.push(["Credentials", `${state.credentials.length} types`]);
+    if (state.components) rows.push(["Components", `${state.components.count} in one ${state.components.node} node`]);
+    if (state.pluginStates) {
+      const parts = [`${state.pluginStates} states`];
+      if (state.pluginsLocalWin.length) parts.push(`${state.pluginsLocalWin.length} local over npm`);
+      if (state.pluginsFromNpm.length) parts.push(`${state.pluginsFromNpm.length} from npm`);
+      if (state.pluginsDisabled.length) parts.push(`${state.pluginsDisabled.length} disabled`);
+      rows.push(["Plugins", parts.join(", ")]);
+    }
+    if (state.engine) rows.push(["Engine", state.engine]);
+    if (state.redis) rows.push(["Redis", state.redis]);
+    // Last row before the addresses, because it qualifies every one of them.
+    if (state.auth) rows.push(["Auth", state.auth]);
+    // Trimmed to the repo-relative path: absolute would be the longest string in the
+    // block, and the identifying part is the tail. cwd is not usable for this because
+    // the server is started from several directories (turbo, docker, the CLI).
+    if (state.watching)
+      rows.push(["Watching", `${state.watching.replace(/^.*?(?=apps\/)/, "")}, manifests reload on save`]);
+
+    const labelWidth = Math.max(...rows.map((r) => r[0].length), ...state.endpoints.map((e) => e.label.length));
+    const urlWidth = Math.max(0, ...state.endpoints.map((e) => e.url.length));
+    // Pad BEFORE painting: ANSI codes have width in padEnd's eyes and none on screen.
+    const out: string[] = ["", `  ${bold("unoverse")}    ${dim(`ready in ${ready}s`)}`, ""];
+    for (const [label, value] of rows) out.push(`  ${dim(label.padEnd(labelWidth))}   ${value}`);
+    if (state.endpoints.length) {
+      const rank = (l: string) => {
+        const i = boot.endpointOrder.indexOf(l);
+        return i === -1 ? boot.endpointOrder.length : i;
+      };
+      state.endpoints.sort((a, b) => rank(a.label) - rank(b.label));
+      out.push("");
+      for (const e of state.endpoints) {
+        out.push(`  ${dim(e.label.padEnd(labelWidth))}   ${cyan(e.note ? e.url.padEnd(urlWidth) : e.url)}${e.note ? `   ${dim(e.note)}` : ""}`);
+      }
+    }
+
+    // Anomalies are the point of the readout, so they sit at the bottom where the eye
+    // lands and they are the only thing here that is not a count.
+    if (state.pluginStateError && !state.pluginStates)
+      state.notices.push({
+        level: "error",
+        text: `no plugin state could be read (${state.pluginStateError}), so npm-installed packages did not load`,
+      });
+
+    const anomalies = [
+      ...state.notices.map((n) => `  ${n.level === "error" ? red("✗") : yellow("!")}  ${n.text}`),
+      ...(state.manifests?.shadowed.length
+        ? [`  ${yellow("!")}  code wins over manifest for: ${state.manifests.shadowed.join(", ")}`]
+        : []),
+      ...(state.pluginsDisabled.length
+        ? [`  ${yellow("!")}  disabled, so not loaded: ${state.pluginsDisabled.join(", ")}`]
+        : []),
+    ];
+    if (anomalies.length) out.push("", ...anomalies);
+    out.push("");
+    if (!DEBUG) out.push(dim("  LOG_LEVEL=debug lists every node, credential and package as it loads."), "");
+    console.log(out.join("\n"));
+  },
+};

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

@@ -0,0 +1,18 @@
+/**
+ * Unoverse definition store — the FAÇADE. Split 2026-08-30 into organised
+ * subfolders (owner: files stay ~500-800 lines, folders group by concern);
+ * every existing import of `definitions/definitions.js` keeps working.
+ *
+ *   registry/homes.ts    where every kind lives; ref → folder resolution
+ *   registry/catalog.ts  listing, app manifests, state order, workbench views
+ *   model.ts             the served shapes + kind/word normalizers
+ *   load/load.ts         loadDefinition — the load core
+ *   load/expand.ts       Ref/atom composition, $include, state inheritance
+ *   load/compile/        the component-tree and template compilers, one file per job
+ */
+export * from "./registry/homes.js";
+export * from "./registry/catalog.js";
+export * from "./model.js";
+export * from "./load/load.js";
+export * from "./load/expand/index.js";
+export * from "./load/compile/index.js";

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

@@ -0,0 +1,45 @@
+/**
+ * The design system as an INSTALLED PACKAGE, wherever the HOST put it.
+ *
+ * Every other tier in `definitions.ts` and `theme.ts` is a path under the content home,
+ * which is the developer's own project. That is right for a universe, where the design
+ * system is installed INTO the deployment, and wrong for Studio, which is a TOOL run
+ * against somebody else's folder. Studio depends on `@unoverse-platform/marketplace`, so
+ * it already carries the design system in its own node_modules, and then went looking for
+ * it in a project that will never have one.
+ *
+ * A new Studio project therefore had NO design system at all: zero components, zero atoms,
+ * no foundation styles (measured against an empty home: 17 components and 30 atoms resolve
+ * with this, none without). Primitives still render, so the scaffolded Welcome component
+ * looks fine and hides it; the failure surfaces later, on the first `Card` or token. And it
+ * is silent either way, because both callers fall through to a path rather than raising.
+ *
+ * ASKED OF NODE rather than walked, so it is found from wherever the host is installed.
+ * NOT a dependency: `marketplace` depends on THIS package, so declaring it would be a
+ * cycle. Absent is a normal answer (a universe resolves from a tier above), hence the
+ * catch, and the answer is memoized because a failed resolve is the expensive case.
+ *
+ * ITS OWN MODULE so `definitions.ts` and `theme.ts` share one implementation without
+ * importing each other. They resolve different kinds out of the same bundle
+ * (components/atoms, and styles), and two copies of this would drift into two answers
+ * about where the design system is.
+ *
+ * SEARCHED LAST by both callers, after every project-local tier, so nothing changes for a
+ * host that already resolves: this fires only where the alternative was nothing at all.
+ */
+import { join, dirname } from "path";
+import { createRequire } from "module";
+
+let cached: string | null | undefined;
+
+/** The bundle's `definitions/` folder, or null when the package is not installed. */
+export function packagedDesignSystem(): string | null {
+  if (cached !== undefined) return cached;
+  try {
+    const pkg = createRequire(import.meta.url).resolve("@unoverse-platform/marketplace/package.json");
+    cached = join(dirname(pkg), "definitions");
+  } catch {
+    cached = null;
+  }
+  return cached;
+}

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