@unoverse-platform/studio 0.1.27 → 0.1.29

package/local/plugin.ts

@@ -368,7 +368,12 @@ export function localStudioHost(): Plugin {
               // Apps are addressed both ways (unoverse://apps/<org>/<id> and
               // unoverse://templates/<org>/<id>); both load the template kind.
               const kind = /\/(apps|templates)\//.test(uri) ? "template" : /\/atoms\//.test(uri) ? "atom" : "component";
-              const ref = uri.replace(/^unoverse:\/\/(components|atoms|apps|templates)\//, "");
+              // A trailing `@form` is a request for a VARIANT of the definition, not part of
+              // its name. This door did not know that convention and looked up the whole
+              // string, so every component read as `<name>@refs` answered "definition not
+              // found". Strip any variant: this route serves the one form it has, which is
+              // also the only form the server serves.
+              const ref = uri.replace(/^unoverse:\/\/(components|atoms|apps|templates)\//, "").replace(/@[a-z]+$/, "");
               const d = c.loadDefinition(ref, kind);
               return d ? json(res, d) : json(res, { error: `definition not found: ${uri}` }, 404);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unoverse-platform/studio",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "type": "module",
   "description": "Unoverse Studio: the local authoring app. Reads your own rx/ folder, no backend.",
   "scripts": {

package/screens/TemplatesView.tsx

@@ -988,7 +988,7 @@ export function TemplatesView({
                   // in-page store is dead there and computeAppWidth against it lies.
                   width: liveIsNative
                     ? (nativeWidth ?? "100%")
-                    : (computeAppWidth(resolveActiveLayout(selectedDef as never, store), store, theme?.appSize) ?? "100%"),
+                    : (computeAppWidth(resolveActiveLayout(selectedDef as never, store), store, theme?.appSize, selectedDef as never) ?? "100%"),
                   margin: "0 auto",
                   transition: "width 200ms",
                   ...((selectedDef?.fluidHeight ?? true) ? { height: "100%" } : {}),

package/vendor/sdk/appEngine.tsx

@@ -21,6 +21,7 @@ import {
   setAnalyticsContext,
   setAnalyticsDebug,
   type UseVoiceServiceConfig,
+  type UnoverseDefinition,
 } from "./lib";
 
 export interface AppConfig {
@@ -56,7 +57,14 @@ export function AppEngine(cfg: AppConfig) {
   // STATE-OWNED WIDTH (rx data): the layout root's `appWidth` = the core surface's
   // constant width; an occupied panel slot's `appWidth` adds to it (computeAppWidth).
   // No declared width → the host keeps its own default. There is no other path.
-  const [def, setDef] = useState<{ root?: unknown; org?: string; layouts?: Record<string, unknown>; defaultLayout?: string } | null>(null);
+  // THE WHOLE DEFINITION, not a chosen four fields. This used to keep `{root, org, layouts,
+  // defaultLayout}` and drop everything else, which is a whitelist that silently loses each
+  // field the contract gains. It was dropping `stateOrder`, `publicStates`, `initialView`
+  // and `stateTree`, quietly running the v2 ladder in legacy mode, and it dropped `defs`
+  // too: with shared pieces unreachable, the core panel's `appWidth` went uncounted and the
+  // app's width collapsed to the open surface's remainder term, which is negative, so the
+  // app rendered 0 pixels wide and blank.
+  const [def, setDef] = useState<UnoverseDefinition | null>(null);
   const lastWidthRef = useRef<string | undefined>(undefined);
   // Named app sizes resolve via the served theme (theme.appSize), like every token.
   const theme = useUnoverseTheme(client, def ? (def.org ? `${def.org}/light` : "light") : null);
@@ -82,8 +90,7 @@ export function AppEngine(cfg: AppConfig) {
       .connect()
       .then(() => client.readDefinition(`unoverse://templates/${templateId}`))
       .then((d) => {
-        const t = d as { root?: unknown; org?: string; layouts?: Record<string, unknown>; defaultLayout?: string } | null;
-        if (alive) setDef(t ? { root: t.root, org: t.org, layouts: t.layouts, defaultLayout: t.defaultLayout } : null);
+        if (alive) setDef(d ?? null);
       })
       .catch((e) => console.error("[app] template read failed:", e));
     return () => {
@@ -114,7 +121,7 @@ export function AppEngine(cfg: AppConfig) {
     const report = () => {
       // NAME-SYNC: width is computed off the ACTIVE layout (multi-layout templates
       // swap whole arrangements); single-layout defs resolve to their root.
-      const w = computeAppWidth(resolveActiveLayout(def as never, store), store, theme?.appSize, def as never);
+      const w = computeAppWidth(resolveActiveLayout(def, store), store, theme?.appSize, def);
       if (w && w !== lastWidthRef.current) {
         lastWidthRef.current = w;
         window.parent?.postMessage({ type: "unoverse:size", width: w }, "*");

package/vendor/sdk/lib/UnoverseComponent.tsx

@@ -83,6 +83,10 @@ export function UnoverseComponent({ client, uri, data, store, chatId, nodeId, ex
   // LIVE SOURCE. The hook runs either way (hooks cannot be conditional) and no-ops without a
   // store, so one component serves both paths without a wrapper deciding for it.
   const live = useUnoverseInstance(store, chatId, nodeId);
+  // The BARE URI, deliberately. This asked for the referenced form (`@refs`) while that
+  // form existed; it is withdrawn (server resources.ts refForm), so asking for it now only
+  // spreads a suffix that every door has to know how to strip. Studio's own local
+  // definition route did not, and answered "definition not found" for every component.
   const resolvedUri = store ? (live.type ? `unoverse://components/${live.type}` : null) : (uri ?? null);
   const sourceData = store ? (extraData ? { ...(live.data ?? {}), ...extraData } : live.data) : data;
   // No theme passed → fetch it from the server (the SDK owns zero token values). The
@@ -179,7 +183,9 @@ export function UnoverseComponent({ client, uri, data, store, chatId, nodeId, ex
   // host owns isolation, so apply it here on a `display:contents` wrapper (out of layout while
   // its inherited props cascade) — the design-system baseline either way.
   const keyframes = <style>{keyframesCss(activeTheme)}</style>;
-  const tree = renderNode(def.root, merged, handleAction, activeTheme);
+  // The shared pieces this definition NAMES travel beside it and are threaded through
+  // every recursion, so a reference nested in a Switch branch or an Each item resolves too.
+  const tree = renderNode(def.root, merged, handleAction, activeTheme, undefined, undefined, def.defs);
   // The isolation container MIRRORS the component root's declared sizing intent (§4a:
   // the component owns its size; the host responds). A root that declares
   // `height: "full"` needs a definite chain — the container passes the host's height

package/vendor/sdk/lib/core/client.ts

@@ -28,6 +28,17 @@ export class UnoverseClient {
   private connecting: Promise<void> | null = null;
   private cache = new Map<string, UnoverseDefinition>();
   private themeCache = new Map<string, ResolvedTheme>();
+  /**
+   * IN-FLIGHT reads, so N askers cost ONE request.
+   *
+   * The caches above are written only after `await`, so every instance mounting in the
+   * same tick missed and issued its own identical `resources/read`: ten cards of one type
+   * meant ten copies of that definition over the wire, and on a link where a round trip
+   * costs 300ms they queue behind each other. Sharing the PROMISE is the whole fix; the
+   * value cache still serves everything after the first resolve.
+   */
+  private inflight = new Map<string, Promise<UnoverseDefinition>>();
+  private themeInflight = new Map<string, Promise<ResolvedTheme>>();
 
   constructor(
     private readonly url: string,
@@ -118,12 +129,21 @@ export class UnoverseClient {
   async readDefinition(uri: string): Promise<UnoverseDefinition> {
     const cached = this.cache.get(uri);
     if (cached) return cached;
-    const res = await this.withSession(() => this.client.readResource({ uri }));
-    const first = res.contents[0] as { text?: string };
-    if (!first?.text) throw new Error(`No definition content for ${uri}`);
-    const def = JSON.parse(first.text) as UnoverseDefinition;
-    this.cache.set(uri, def);
-    return def;
+    const pending = this.inflight.get(uri);
+    if (pending) return pending;
+    const read = (async () => {
+      const res = await this.withSession(() => this.client.readResource({ uri }));
+      const first = res.contents[0] as { text?: string };
+      if (!first?.text) throw new Error(`No definition content for ${uri}`);
+      const def = JSON.parse(first.text) as UnoverseDefinition;
+      this.cache.set(uri, def);
+      return def;
+    })();
+    this.inflight.set(uri, read);
+    // Cleared either way: a failed read must not be remembered as pending forever, or the
+    // next asker waits on a promise that will never resolve again.
+    read.finally(() => this.inflight.delete(uri));
+    return read;
   }
 
   /**
@@ -133,12 +153,19 @@ export class UnoverseClient {
   async readTheme(name = "light"): Promise<ResolvedTheme> {
     const cached = this.themeCache.get(name);
     if (cached) return cached;
-    const res = await this.withSession(() => this.client.readResource({ uri: `unoverse://theme/${name}` }));
-    const first = res.contents[0] as { text?: string };
-    if (!first?.text) throw new Error(`No theme content for ${name}`);
-    const theme = JSON.parse(first.text) as ResolvedTheme;
-    this.themeCache.set(name, theme);
-    return theme;
+    const pending = this.themeInflight.get(name);
+    if (pending) return pending;
+    const read = (async () => {
+      const res = await this.withSession(() => this.client.readResource({ uri: `unoverse://theme/${name}` }));
+      const first = res.contents[0] as { text?: string };
+      if (!first?.text) throw new Error(`No theme content for ${name}`);
+      const theme = JSON.parse(first.text) as ResolvedTheme;
+      this.themeCache.set(name, theme);
+      return theme;
+    })();
+    this.themeInflight.set(name, read);
+    read.finally(() => this.themeInflight.delete(name));
+    return read;
   }
 
   /** List available theme names (e.g. ["light", "dark"]) from the server. */

package/vendor/sdk/lib/core/index.ts

@@ -60,3 +60,6 @@ export {
 
 // The shared "react to state" predicate (visibleWhen / Switch / style.when).
 export { matches, visible, selectCase } from "./conditions";
+// REFERENCE, DON'T COPY: specialising a `Ref` against a shared definition, so the design
+// system travels once instead of being pasted into every definition that uses it.
+export { resolveRef } from "./refs";

package/vendor/sdk/lib/core/refs.ts

@@ -0,0 +1,117 @@
+/**
+ * REFERENCE, DON'T COPY — resolving a `Ref` at render time.
+ *
+ * A design system's whole promise is "define once, use everywhere". Until now the server
+ * kept that promise by INLINING: every `Ref` was replaced with a specialised copy of the
+ * atom before serving, so the browser received one flat tree with the same button, the
+ * same field, pasted in at every use. Measured on the estate at the time this landed:
+ * 1259 KB served where 224 KB of distinct structure existed, and one card
+ * (`sab/product-card`) weighed 361 KB because it referenced a document that itself
+ * carried six copies of an eleven-branch field switch. Every page load paid it again,
+ * because MCP reads go over POST and no browser cache can hold them.
+ *
+ * A `Ref` is a PURE FUNCTION of the atom and the reference's own parameters:
+ *
+ *     resolve(atom, { props, with, style, action, visibleWhen }) → tree
+ *
+ * `props` remaps the atom's field names onto the host's; `with` bakes per-use literals in;
+ * style, action and visibleWhen override. Nothing in that needs a server, which is why it
+ * belongs here: the definition then carries the reference (tiny) and the atom travels once
+ * and is cached by URI, shared by every definition that names it.
+ *
+ * PORTABLE BRAIN (UNOVERSE_SDK_PORTING §1): this is core, so every SDK port implements the
+ * same resolution and the fixtures prove they agree. A port that resolves `with` differently
+ * renders different copy from the same definition, which is exactly the class of drift the
+ * conformance suite exists to catch.
+ *
+ * A 1:1 port of the server's expansion (packages/base/src/definitions/definitions.ts:
+ * remapFields / applyLiterals / applyStyleLiterals / expandNode's Ref branch). The two must
+ * stay in step while the server still inlines for older clients.
+ */
+import type { UnoverseNode } from "./types";
+
+type AnyNode = Record<string, any>;
+
+/** Deep clone. The atom is CACHED and shared, so specialising it in place would poison
+ *  every other user of that atom with one host's literals. */
+const clone = <T,>(v: T): T => JSON.parse(JSON.stringify(v)) as T;
+
+/** `props` remaps the atom's OWN field names to the host's fields, everywhere a field name
+ *  can appear: binds, both spellings of `visibleWhen`, and `style.when` predicates. */
+function remapFields(node: AnyNode, propMap: Record<string, string>): void {
+  if (node.bind) for (const k of Object.keys(node.bind)) if (propMap[node.bind[k]]) node.bind[k] = propMap[node.bind[k]];
+  if (typeof node.visibleWhen === "string" && propMap[node.visibleWhen]) node.visibleWhen = propMap[node.visibleWhen];
+  // The OBJECT form remaps too. A guard is a guard whichever way it is written; carrying
+  // only the string form left an atom testing its own prop name after the host remapped it,
+  // so the guard read an absent key and the branch never showed.
+  if (node.visibleWhen && typeof node.visibleWhen === "object" && !Array.isArray(node.visibleWhen)) {
+    const g = node.visibleWhen as { field?: string };
+    if (typeof g.field === "string" && propMap[g.field]) g.field = propMap[g.field];
+  }
+  // `style.when` is the same predicate wearing a different hat: an atom whose LOOK is
+  // data-driven must follow its host's field for the same reason.
+  const when = (node.style as AnyNode | undefined)?.when;
+  if (Array.isArray(when)) {
+    for (const v of when as { field?: string }[]) if (v && typeof v.field === "string" && propMap[v.field]) v.field = propMap[v.field];
+  }
+  if (Array.isArray(node.children)) node.children.forEach((c: AnyNode) => remapFields(c, propMap));
+  if (node.template) remapFields(node.template as AnyNode, propMap);
+  if (node.cases && typeof node.cases === "object") for (const k of Object.keys(node.cases)) remapFields(node.cases[k] as AnyNode, propMap);
+}
+
+/** `{{name}}` substitution at any depth of a style object: a radial's `at`, a `when`
+ *  clause's `apply`. Only the top level was walked once, and a nested one reached the
+ *  renderer verbatim. */
+function applyStyleLiterals(style: unknown, lits: Record<string, unknown>): void {
+  if (Array.isArray(style)) return style.forEach((v) => applyStyleLiterals(v, lits));
+  if (!style || typeof style !== "object") return;
+  const s = style as AnyNode;
+  for (const k of Object.keys(s)) {
+    const v = s[k];
+    if (typeof v === "string" && v.includes("{{")) s[k] = v.replace(/\{\{(\w[\w.]*)\}\}/g, (m, f) => (f in lits ? String(lits[f]) : m));
+    else if (v && typeof v === "object") applyStyleLiterals(v, lits);
+  }
+}
+
+/** `with` resolves an atom's BINDINGS to literal content: a bound attribute becomes a
+ *  hardcoded one, and a guard on a truthy literal is satisfied statically and dropped. */
+function applyLiterals(node: AnyNode, lits: Record<string, unknown>): void {
+  if (node.bind) {
+    for (const attr of Object.keys(node.bind)) {
+      const field = node.bind[attr];
+      if (typeof field === "string" && field in lits) {
+        node[attr] = lits[field];
+        delete node.bind[attr];
+      }
+    }
+    if (Object.keys(node.bind).length === 0) delete node.bind;
+  }
+  if (typeof node.visibleWhen === "string" && node.visibleWhen in lits) {
+    if (lits[node.visibleWhen]) delete node.visibleWhen; // statically satisfied
+    // a falsy literal KEEPS the (now never-true) guard, so the node stays hidden
+  }
+  if (node.style && typeof node.style === "object") applyStyleLiterals(node.style as AnyNode, lits);
+  if (Array.isArray(node.children)) node.children.forEach((c: AnyNode) => applyLiterals(c, lits));
+  if (node.template) applyLiterals(node.template as AnyNode, lits);
+  if (node.cases && typeof node.cases === "object") for (const k of Object.keys(node.cases)) applyLiterals(node.cases[k] as AnyNode, lits);
+}
+
+/**
+ * Specialise `atomRoot` for one `Ref`. Returns a NEW tree; the atom is untouched.
+ *
+ * Returns null when the atom is not available, and the caller renders nothing rather than
+ * a broken box: a missing atom is a serving problem, and a hole is easier to diagnose than
+ * a mystery element.
+ */
+export function resolveRef(refNode: UnoverseNode, atomRoot: UnoverseNode | undefined | null): UnoverseNode | null {
+  if (!atomRoot) return null;
+  const n = refNode as AnyNode;
+  const root = clone(atomRoot) as AnyNode;
+  remapFields(root, (n.props ?? {}) as Record<string, string>);
+  if (n.with && typeof n.with === "object") applyLiterals(root, n.with as Record<string, unknown>);
+  // The reference's own overrides win: these are the per-host facts an atom cannot carry.
+  if (n.visibleWhen) root.visibleWhen = n.visibleWhen;
+  if (n.action) root.action = n.action;
+  if (n.style) root.style = { ...((root.style as AnyNode) ?? {}), ...(n.style as AnyNode) };
+  return root as UnoverseNode;
+}

package/vendor/sdk/lib/core/store.ts

@@ -196,6 +196,31 @@ export class ComponentStore {
     if (changed) this.bump();
   }
 
+  /**
+   * A HIGHER STATE CLEARS THE STATES BELOW IT (STATE_MODEL §5, THE SEVEN RULES rule 4) —
+   * when a DELIVERY put it there. Every component sitting in a lower-ranked state releases
+   * its claim, so rule 6's re-walk finds nothing below and lands on the BASE. The caller
+   * decides delivery-vs-guest (`resolveActiveView().byGuest`): the guest's own navigation
+   * clears nothing, or closing a page would have nothing to return to.
+   *
+   * Retracts to `inline`, not through `retractSlice`: that helper targets the slice's
+   * declared initial, and a card whose initial IS the lower state would re-claim it on
+   * the next walk and never settle.
+   */
+  cancelBelow(active: string, order: string[]): void {
+    const below = new Set(order.slice(order.indexOf(active) + 1));
+    if (order.indexOf(active) < 0 || !below.size) return;
+    let changed = false;
+    for (const [key, slice] of this.data) {
+      if (slice.lifetime === "conversation") continue;
+      if (!below.has((slice.view ?? slice.defaultState) as string)) continue;
+      this.data.set(key, { ...slice, ...("defaultState" in slice ? { defaultState: "inline" } : { view: "inline" }) });
+      this.touches.set(key, ++this.touchSeq);
+      changed = true;
+    }
+    if (changed) this.bump();
+  }
+
   closeSurfaces(): void {
     let changed = false;
     for (const [key, slice] of this.data) {

package/vendor/sdk/lib/core/templates.ts

@@ -36,8 +36,9 @@ export const isViewField = (f: unknown): boolean => f === "view" || f === "defau
 export function orderedClaims(def: UnoverseDefinition | null | undefined): string[] {
   if (def?.stateOrder?.length) return def.stateOrder;
   const legacy = new Set<string>(Object.keys(def?.layouts ?? {}));
-  if (def?.layouts) for (const l of Object.values(def.layouts)) collectSurfacedViews(l, legacy);
-  else if (def?.root) collectSurfacedViews(def.root, legacy);
+  const defs = def?.defs as Record<string, unknown> | undefined;
+  if (def?.layouts) for (const l of Object.values(def.layouts)) collectSurfacedViews(l, legacy, defs);
+  else if (def?.root) collectSurfacedViews(def.root, legacy, defs);
   return [...legacy];
 }
 
@@ -77,18 +78,27 @@ export function formatRelative(ts?: number): string {
  * v2 note: with a declared `stateOrder` this is only the per-layout slot inventory;
  * the CLAIM list itself is orderedClaims().
  */
-export function collectSurfacedViews(node: unknown, out: Set<string> = new Set()): Set<string> {
+export function collectSurfacedViews(node: unknown, out: Set<string> = new Set(), defs?: Record<string, unknown>): Set<string> {
   if (Array.isArray(node)) {
-    for (const n of node) collectSurfacedViews(n, out);
+    for (const n of node) collectSurfacedViews(n, out, defs);
     return out;
   }
   if (!node || typeof node !== "object") return out;
   const n = node as Record<string, unknown>;
+  // A REFERENCED definition is a GRAPH, so a structural walk has to follow the edges. The
+  // chrome shared by four arrangements travels once, and the slots that claim views live
+  // INSIDE it — stopping at the reference would report that nothing claims anything, and
+  // every surfaced component would fall back into the flow.
+  if (n.type === "Ref" && typeof n.ref === "string") {
+    const piece = defs?.[n.ref];
+    if (piece) collectSurfacedViews(piece, out, defs);
+    return out;
+  }
   const sel = n.select as { where?: { field?: string; eq?: unknown } } | undefined;
   if (n.type === "ComponentSlot" && isViewField(sel?.where?.field) && typeof sel?.where?.eq === "string") {
     out.add(sel.where.eq);
   }
-  for (const v of Object.values(n)) if (v && typeof v === "object") collectSurfacedViews(v, out);
+  for (const v of Object.values(n)) if (v && typeof v === "object") collectSurfacedViews(v, out, defs);
   return out;
 }
 
@@ -121,7 +131,15 @@ export function computeAppWidth(root: unknown, store: ComponentStore, appSize?:
       return;
     }
     if (!node || typeof node !== "object") return;
-    const n = node as Record<string, unknown> & { appWidth?: string; type?: string; select?: { where?: { field?: string; eq?: unknown } } };
+    const n = node as Record<string, unknown> & { appWidth?: string; type?: string; ref?: string; select?: { where?: { field?: string; eq?: unknown } } };
+    // Follow references: the width-bearing panels of a referenced form live inside the
+    // shared pieces, so stopping here would size the app from the arrangement's skeleton
+    // alone (see collectSurfacedViews for the same reason, stated once).
+    if (n.type === "Ref" && typeof n.ref === "string") {
+      const piece = (def?.defs as Record<string, unknown> | undefined)?.[n.ref];
+      if (piece) walk(piece);
+      return;
+    }
     if (n !== r) {
       if (n.type === "ComponentSlot") {
         const claim = n.select?.where;

package/vendor/sdk/lib/core/types.ts

@@ -121,6 +121,16 @@ export interface UnoverseDefinition {
    *  theme (`unoverse://theme/{org}/light`). Universal components carry no org. */
   org?: string;
   description?: string;
+  /**
+   * REFERENCE, DON'T COPY: the shared pieces this definition NAMES, by ref name, each
+   * shipped once instead of pasted at every use.
+   *
+   * NEVER PRESENT TODAY. The server withdrew the referenced form (server resources.ts
+   * `refForm`) after it left an app rendering zero pixels wide, and no client asks for it.
+   * The field and `resolveRef` stay because the resolution is correct and proven; what is
+   * missing is end-to-end proof and an answer for every client version in the estate.
+   */
+  defs?: Record<string, UnoverseNode>;
   /** EXTERNAL contract — the rare workflow-fed inputs (`input: true`). A contained
    *  microapp has an EMPTY (or absent) props block. */
   props?: Record<string, unknown>;

package/vendor/sdk/lib/orb/ThinkingOrb.tsx

@@ -20,7 +20,11 @@ const LABELS: Record<string, string> = {
   weaving: 'Weaving…',
   composing: 'Composing…',
   breathing: 'Thinking…',
-  shaping: 'Shaping…'
+  shaping: 'Shaping…',
+  halo: 'Waiting…',
+  sonar: 'Listening…',
+  shimmer: 'Thinking…',
+  pulse: 'Responding…'
 };
 
 export function ThinkingOrb({

package/vendor/sdk/lib/orb/engine/core.ts

@@ -113,6 +113,16 @@ function shade(w: number, dark: boolean): [number, number, number] {
   return [0, 1, 2].map((i) => Math.round(base[i] + (mixTo - base[i]) * w)) as [number, number, number];
 }
 
+/**
+ * LOCAL (Unoverse): the shaded ink as a CSS colour, for modes that STROKE rather than
+ * stipple (engine/rings). Same depth language as `paint` — `white` 0 is full ink, 1 is
+ * the substrate — so a stroked mode and a dotted one read as the same material.
+ */
+export function inkCss(white: number, dark: boolean, alpha: number): string {
+  const [r, g, b] = shade(Math.min(1, Math.max(0, white)), dark);
+  return `rgba(${r},${g},${b},${alpha})`;
+}
+
 /**
  * Painter: z-sort far→near, matte depth-shaded dots. On dark substrates the
  * ink value is mirrored (1 - white) so near dots read bright — the same

package/vendor/sdk/lib/orb/engine/registry.ts

@@ -9,8 +9,15 @@ import { drawMorph } from './morph';
 import { drawOrbits } from './orbits';
 import { drawRibbon } from './ribbon';
 import { drawWeb } from './web';
+// LOCAL (Unoverse): the annular modes — see ./rings.
+import { drawHalo, drawRipple, drawShimmer } from './rings';
 
 export const MODE_DRAWS: Record<ModeKey, ModeDraw> = {
+  halo: drawHalo,
+  sonar: drawRipple,
+  // pulse shares ripple's painter — the `dir` profile flag mirrors it outward
+  pulse: drawRipple,
+  shimmer: drawShimmer,
   orbits: drawOrbits,
   globe: drawGlobe,
   rubik: drawRubik,

package/vendor/sdk/lib/orb/engine/rings.ts

@@ -0,0 +1,239 @@
+/**
+ * RING MODES — a LOCAL Unoverse addition to the vendored thinking-orbs engine.
+ * Kept in its own file so an upstream update never conflicts with it.
+ *
+ * WHY THESE EXIST. Every vendored mode draws a full 3-D sphere, which is right when the
+ * orb IS the subject. Put a face in the middle and the sphere stops being the subject:
+ * you see the leftover rim of a globe fighting the portrait. These modes are ANNULAR BY
+ * CONSTRUCTION — every mark lives between `rIn` and `rOut`, so the centre is empty by
+ * design and the animation frames the face instead of colliding with it.
+ *
+ * THE MATERIAL IS LIGHT, NOT INK. An earlier version bent the engine's halftone language
+ * into a circle and produced a ring of beads: hard-edged, evenly spaced, mechanically
+ * distributed — a loading spinner, not a presence. The premium reference (Apple's
+ * Intelligence glow) is built by one technique: the same path stroked several times, each
+ * pass wider, blurrier and fainter than the last, so a crisp core sits inside a bloom of
+ * its own light. That is `glow()`. Everything else is which path, and how it moves.
+ *
+ * NOTHING MAY LOOK LIKE A SPINNER. A bright head chasing a tail around a circle is the
+ * single most dated shape in this space, so no mode owns a travelling OBJECT. Where a
+ * mode needs direction, the LIGHT moves through a still form (a conic gradient sweeping
+ * its luminance) rather than a mark moving along a path — the difference between a lamp
+ * behind a curtain and a torch on a track.
+ *
+ * House style otherwise: no perfect circles (radii warp under drifting low-frequency
+ * noise), no countable frequencies (rates are incommensurate, so patterns never repeat on
+ * a beat), and no pass at full strength — the ring reads as light around the subject,
+ * never as chrome on top of it.
+ *
+ * Blur is `shadowBlur`, deliberately: `ctx.filter` is unsupported in older Safari and the
+ * vendored engine avoids it on purpose, whereas a shadow at zero offset is a real blurred
+ * copy of the stroke and works everywhere the rest of this engine runs.
+ */
+import { inkCss, vnoise } from './core';
+import type { ModeDraw } from './types';
+import type { ModeOpts } from './profiles';
+
+const TAU = Math.PI * 2;
+
+/** The annulus a ring mode may draw in, plus a scale factor off the 200px reference. */
+function band(size: number, o: ModeOpts) {
+  const c = size / 2;
+  const R = size / 2;
+  // Defaults clear a face occupying ~0.56 of the box (avatar-orb's 112px in 200px) and
+  // its shadow; `rIn`/`rOut` retune the band for any other face ratio.
+  const rIn = R * (o.rIn ?? 0.62);
+  const rOut = R * (o.rOut ?? 0.97);
+  return { cx: c, cy: c, rIn, rOut, rMid: (rIn + rOut) / 2, span: (rOut - rIn) / 2, s: size / 200 };
+}
+
+type Band = ReturnType<typeof band>;
+/** How a pass paints at a given alpha — a flat ink, or a gradient that varies round the ring. */
+type PaintAt = (alpha: number) => string | CanvasGradient;
+
+/**
+ * THE GLOW. One path, stroked four times: a wide, heavily blurred, nearly transparent
+ * bloom first, then progressively tighter and stronger passes, ending on a thin crisp
+ * core. Painted in that order so the core lands on top of its own halo.
+ */
+function glow(
+  ctx: CanvasRenderingContext2D,
+  path: () => void,
+  w: number,
+  alpha: number,
+  paintAt: PaintAt,
+  shadowAt: (alpha: number) => string,
+): void {
+  const passes = [
+    { lw: w * 3.4, blur: 26, a: alpha * 0.14 },
+    { lw: w * 2.1, blur: 14, a: alpha * 0.26 },
+    { lw: w * 1.25, blur: 6, a: alpha * 0.5 },
+    { lw: w * 0.5, blur: 0, a: alpha },
+  ];
+  ctx.lineCap = 'round';
+  ctx.lineJoin = 'round';
+  for (const p of passes) {
+    if (p.a < 0.004) continue;
+    ctx.save();
+    ctx.beginPath();
+    path();
+    ctx.lineWidth = Math.max(0.4, p.lw);
+    ctx.strokeStyle = paintAt(p.a);
+    if (p.blur) {
+      ctx.shadowBlur = p.blur * (w / 3);
+      // a shadow takes a colour, never a gradient — so it uses the flat ink
+      ctx.shadowColor = shadowAt(p.a);
+    }
+    ctx.stroke();
+    ctx.restore();
+  }
+}
+
+/** Flat ink of a given depth — the ordinary case. */
+const flat = (white: number, dark: boolean): PaintAt => (a) => inkCss(white, dark, a);
+
+/**
+ * A conic gradient whose luminance peaks once and falls away round the ring, so the ring
+ * is brighter on one side without anything travelling along it. `at` rotates the peak.
+ * Falls back to flat ink where `createConicGradient` is unavailable (older Safari), which
+ * costs the directionality and nothing else.
+ */
+function sweepPaint(ctx: CanvasRenderingContext2D, b: Band, white: number, dark: boolean, at: number, floor = 0.14): PaintAt {
+  const make = (ctx as unknown as { createConicGradient?: (a: number, x: number, y: number) => CanvasGradient })
+    .createConicGradient;
+  if (typeof make !== 'function') return flat(white, dark);
+  return (alpha) => {
+    const g = make.call(ctx, at, b.cx, b.cy);
+    const STOPS = 16;
+    for (let i = 0; i <= STOPS; i++) {
+      const f = i / STOPS;
+      // cos² window: full at the peak, easing to `floor` on the far side, seamless at the wrap
+      const env = ((Math.cos(f * TAU) + 1) / 2) ** 2;
+      g.addColorStop(f, inkCss(white, dark, alpha * (floor + (1 - floor) * env)));
+    }
+    return g;
+  };
+}
+
+/** A closed curve through `pts`, smoothed with quadratics through the midpoints. */
+function closedCurve(ctx: CanvasRenderingContext2D, pts: Array<[number, number]>): void {
+  const n = pts.length;
+  const mx = (a: [number, number], b: [number, number]): [number, number] => [
+    (a[0] + b[0]) / 2,
+    (a[1] + b[1]) / 2,
+  ];
+  const start = mx(pts[n - 1], pts[0]);
+  ctx.moveTo(start[0], start[1]);
+  for (let i = 0; i < n; i++) {
+    const p = pts[i];
+    const m = mx(p, pts[(i + 1) % n]);
+    ctx.quadraticCurveTo(p[0], p[1], m[0], m[1]);
+  }
+  ctx.closePath();
+}
+
+/** Sample a warped ring: radius = rMid + span · f(angle). */
+function ringPts(b: Band, n: number, f: (a: number, i: number) => number): Array<[number, number]> {
+  const pts: Array<[number, number]> = [];
+  for (let i = 0; i < n; i++) {
+    const a = (i / n) * TAU;
+    const rr = b.rMid + b.span * f(a, i);
+    pts.push([b.cx + Math.cos(a) * rr, b.cy + Math.sin(a) * rr]);
+  }
+  return pts;
+}
+
+/**
+ * `halo` — a soft aura, breathing. Two slow lobes drift against each other under a
+ * noise wander, so the form is never a circle and never repeats on a countable beat.
+ * Nothing arrives, nothing leaves: for an assistant at rest.
+ */
+export const drawHalo: ModeDraw = (ctx, size, t, dark, o) => {
+  const b = band(size, o);
+  const breathe = 0.5 + 0.5 * Math.sin(t * 0.5);
+  const pts = ringPts(b, Math.round(o.samples ?? 88), (a, i) => {
+    const lobes = Math.sin(a * 2 + t * 0.33) * 0.34 + Math.sin(a * 3 - t * 0.21) * 0.22;
+    const wander = (vnoise(i * 0.05, t * 0.16) - 0.5) * 0.9;
+    return 0.3 * lobes + 0.22 * wander + 0.16 * (breathe - 0.5);
+  });
+  const white = o.white ?? 0.26;
+  glow(ctx, () => closedCurve(ctx, pts), (o.w ?? 3) * b.s, 0.34 + 0.2 * breathe, flat(white, dark), flat(white, dark) as (a: number) => string);
+};
+
+/**
+ * `sonar` / `pulse` — concentric rings of light, travelling INWARD (`dir: -1`) or
+ * OUTWARD (`dir: +1`). One painter, two meanings, because they are the same gesture
+ * mirrored: rings arriving are sound reaching a listener, rings leaving are a voice
+ * carrying. Each swells and settles over its life so none ever pops into existence.
+ */
+export const drawRipple: ModeDraw = (ctx, size, t, dark, o) => {
+  const b = band(size, o);
+  const waves = Math.round(o.waves ?? 2);
+  const rate = o.rate ?? 0.2;
+  const out = (o.dir ?? -1) > 0;
+  const white = o.white ?? 0.32;
+  const ink = flat(white, dark);
+  // a still, very faint seat where the rings are born (outward) or land (inward)
+  const seat = out ? b.rIn + b.span * 0.15 : b.rMid + b.span * 0.55;
+  glow(ctx, () => ctx.arc(b.cx, b.cy, seat, 0, TAU), (o.w ?? 2.4) * b.s, 0.07, ink, ink as (a: number) => string);
+  for (let w = 0; w < waves; w++) {
+    const f = (((t * rate + w / waves) % 1) + 1) % 1; // 0 → 1 over a wave's life
+    const rr = out ? b.rIn + (b.rOut - b.rIn) * f : b.rOut - (b.rOut - b.rIn) * f;
+    const fade = Math.sin(Math.PI * f) ** 1.3; // eases in AND out
+    if (fade < 0.02) continue;
+    const pts = ringPts(b, Math.round(o.samples ?? 72), (a) => (rr - b.rMid) / b.span + Math.sin(a * 2 - t * 0.3) * 0.1);
+    glow(ctx, () => closedCurve(ctx, pts), (o.w ?? 2.6) * b.s, (o.peak ?? 0.3) * fade, ink, ink as (a: number) => string);
+  }
+};
+
+/**
+ * `shimmer` — thinking. NOT a mark going round: the ring holds still (drifting only as
+ * every mode here drifts) and its LUMINANCE moves, two conic sweeps at incommensurate,
+ * counter-rotating rates passing through each other. Where they coincide the ring
+ * brightens for a moment and then the moment passes. Reads as something being considered,
+ * with no spinner anywhere in it.
+ */
+export const drawShimmer: ModeDraw = (ctx, size, t, dark, o) => {
+  const b = band(size, o);
+  const white = o.white ?? 0.2;
+  const ink = flat(white, dark) as (a: number) => string;
+  const rate = o.rate ?? 0.5;
+  const peak = o.peak ?? 0.46;
+  const samples = Math.round(o.samples ?? 84);
+  // THREE rings at different radii, each lit by its own sweep at its own rate. One ring
+  // varying in brightness is too quiet to read as activity; three at incommensurate rates
+  // drift through each other, so bright regions build and part without ever lining up
+  // twice the same way. Depth does the work a faster spin would otherwise be asked to do.
+  const layers = [
+    { seat: 0, rate: rate, alpha: 1, w: 1 },
+    { seat: -0.62, rate: -rate * 0.61, alpha: 0.62, w: 0.72 },
+    { seat: 0.6, rate: rate * 0.37, alpha: 0.52, w: 0.66 },
+  ];
+  for (const L of layers) {
+    const phase = t * L.rate;
+    const pts = ringPts(b, samples, (a, i) => {
+      // the ring SWELLS where its light is — luminance and form move together, which is
+      // what makes it read as one lit object rather than a texture over a circle
+      const lit = ((Math.cos(a - phase) + 1) / 2) ** 2;
+      const lobes = Math.sin(a * 2 + t * 0.19) * 0.26 + Math.sin(a * 3 - t * 0.13) * 0.16;
+      const wander = (vnoise(i * 0.05 + L.seat * 7, t * 0.1) - 0.5) * 0.6;
+      return L.seat * 0.42 + 0.2 * lobes + 0.16 * wander + 0.22 * lit;
+    });
+    glow(
+      ctx,
+      () => closedCurve(ctx, pts),
+      (o.w ?? 2.8) * b.s * L.w,
+      peak * L.alpha,
+      sweepPaint(ctx, b, white, dark, phase, 0.05),
+      ink,
+    );
+  }
+};
+
+/** Base profiles for the ring modes (same role as engine/profiles BASE_PROFILES). */
+export const RING_PROFILES: Record<string, ModeOpts> = {
+  halo: { samples: 88, w: 3, white: 0.26 },
+  sonar: { samples: 72, waves: 2, rate: 0.2, dir: -1, w: 2.6, white: 0.32, peak: 0.3 },
+  pulse: { samples: 72, waves: 3, rate: 0.26, dir: 1, w: 2.6, white: 0.3, peak: 0.34 },
+  shimmer: { samples: 84, rate: 0.5, w: 2.8, white: 0.2, peak: 0.46 },
+};

package/vendor/sdk/lib/orb/presets.ts

@@ -5,6 +5,7 @@
 
 import type { ModeOpts } from './engine/profiles';
 import { BASE_PROFILES, scaleCounts, scaleRadii } from './engine/profiles';
+import { RING_PROFILES } from './engine/rings';
 import type { OrbSize, OrbState } from './types';
 
 export type ModeKey =
@@ -16,7 +17,12 @@ export type ModeKey =
   | 'braid'
   | 'ribbon'
   | 'ring'
-  | 'morph';
+  | 'morph'
+  // LOCAL (Unoverse): annular modes for framing a face — engine/rings.ts
+  | 'halo'
+  | 'sonar'
+  | 'shimmer'
+  | 'pulse';
 
 export const STATE_TO_MODE: Record<OrbState, ModeKey> = {
   working: 'orbits',
@@ -27,9 +33,46 @@ export const STATE_TO_MODE: Record<OrbState, ModeKey> = {
   weaving: 'braid',
   composing: 'ribbon',
   breathing: 'ring',
-  shaping: 'morph'
+  shaping: 'morph',
+  // LOCAL (Unoverse): each annular state maps 1:1 to its own painter.
+  halo: 'halo',
+  sonar: 'sonar',
+  shimmer: 'shimmer',
+  pulse: 'pulse'
 };
 
+/**
+ * THE ENERGY STANDARD (local to Unoverse).
+ *
+ * `speed: 1` must mean ONE felt pace across the whole vocabulary, or a design decision
+ * taken against one state is wrong for the next — which is exactly what a shared knob on
+ * a design-system component promises. The unit is a VISUAL CYCLE: the time for a mode's
+ * dominant motion to come back round (a swell to travel, a wave to arrive, a head to lap).
+ *
+ * The annular modes are solved to it exactly (see their block below). The vendored sphere
+ * modes keep their author's relative tuning — hand-made per mode and better than anything
+ * re-derived blind — scaled by ONE factor, because that tuning was made for an orb that IS
+ * the subject at chat-avatar scale; behind a face, or beside content, it reads hot.
+ */
+const CYCLE_SECONDS = 4;
+/**
+ * A state that is DOING something earns more energy than one at rest — waiting and
+ * listening are receptive and should sit still; thinking and responding are work in
+ * progress and read as stalled at the resting pace. Same standard, shorter cycle.
+ */
+const ACTIVE_CYCLE = 2.5;
+const SPHERE_CALM = 0.45;
+
+/**
+ * Solve a mode's baked speed from its OWN dominant rate, so one cycle lands on the
+ * standard. `turns` is what the rate is measured against — a full revolution for motion
+ * around the ring, or 1 for a mode whose rate is already "lives per unit t" (sonar).
+ * Retuning a rate constant in engine/rings only means updating the number passed here.
+ */
+const solve = (ratePerT: number, turns = 2 * Math.PI, cycle = CYCLE_SECONDS) => turns / (ratePerT * cycle);
+/** Inline scale reads a touch quicker — a small mark needs more motion to register. */
+const SMALL = 1.2;
+
 interface Preset {
   speed: number;
   count: number;
@@ -74,6 +117,37 @@ const PRESETS: Record<ModeKey, Record<OrbSize, Preset>> = {
   morph: {
     64: { speed: 2.405, count: 0.702, size: 0.395, extra: { spread: 1.45 } },
     20: { speed: 2.08, count: 0.53, size: 1.011, extra: { spread: 1.45 } }
+  },
+  // LOCAL (Unoverse): the annular set, tuned to THE STANDARD above rather than by eye.
+  // Each speed is solved, not guessed, from that mode's own dominant rate so one visual
+  // cycle lands on CYCLE_SECONDS: halo breathes at 0.5, a sonar wave lives 1/0.2, a
+  // shimmer sweep laps at 0.5, a pulse wave lives 1/0.26. Change a rate constant in
+  // engine/rings and the only edit here is the number handed to solve(). Resting states
+  // (halo, sonar) use CYCLE_SECONDS; working ones (shimmer, pulse) use ACTIVE_CYCLE.
+  // At inline scale the band is a few px wide, so samples drop and strokes thin.
+  // `count`/`size` stay 1: scaleCounts/scaleRadii only know the vendored modes' key
+  // names, so a multiplier would silently do nothing to a ring mode's samples/w.
+  halo: {
+    64: { speed: solve(0.5), count: 1, size: 1 },
+    20: { speed: solve(0.5) * SMALL, count: 1, size: 1, extra: { rIn: 0.5, rOut: 0.98, samples: 56, w: 2.2 } }
+  },
+  sonar: {
+    // rate is "lives per unit t", not an angle — so it solves against 1 turn, not 2π
+    64: { speed: solve(0.2, 1), count: 1, size: 1 },
+    20: { speed: solve(0.2, 1) * SMALL, count: 1, size: 1, extra: { rIn: 0.44, rOut: 0.98, samples: 48, waves: 2, w: 2 } }
+  },
+  shimmer: {
+    64: { speed: solve(0.5, 2 * Math.PI, ACTIVE_CYCLE), count: 1, size: 1 },
+    20: {
+      speed: solve(0.5, 2 * Math.PI, ACTIVE_CYCLE) * SMALL,
+      count: 1,
+      size: 1,
+      extra: { rIn: 0.5, rOut: 0.98, samples: 56, w: 2.2 }
+    }
+  },
+  pulse: {
+    64: { speed: solve(0.26, 1, ACTIVE_CYCLE), count: 1, size: 1 },
+    20: { speed: solve(0.26, 1, ACTIVE_CYCLE) * SMALL, count: 1, size: 1, extra: { rIn: 0.44, rOut: 0.98, samples: 48, waves: 2, w: 2 } }
   }
 };
 
@@ -93,12 +167,15 @@ export function resolvePreset(state: OrbState, size: OrbSize): Resolved {
 
   const mode = STATE_TO_MODE[state];
   const preset = PRESETS[mode][size];
-  let opts: ModeOpts = { ...BASE_PROFILES[mode] };
+  let opts: ModeOpts = { ...(BASE_PROFILES[mode] ?? RING_PROFILES[mode]) };
   if (preset.count !== 1) opts = scaleCounts(opts, preset.count);
   if (preset.size !== 1) opts = scaleRadii(opts, preset.size);
   if (preset.extra) opts = { ...opts, ...preset.extra };
 
-  const resolved: Resolved = { mode, speed: preset.speed, opts };
+  // The sphere set is pulled into the ring set's energy band; the ring set is already
+  // solved to it, so it passes through untouched (see THE ENERGY STANDARD).
+  const speed = preset.speed * (RING_PROFILES[mode] ? 1 : SPHERE_CALM);
+  const resolved: Resolved = { mode, speed, opts };
   cache.set(key, resolved);
   return resolved;
 }

package/vendor/sdk/lib/orb/types.ts

@@ -11,6 +11,13 @@ import type { CSSProperties, CanvasHTMLAttributes } from 'react';
  * - `composing`  — an undulating multi-band sash
  * - `breathing`  — a face-on ring slowly morphing
  * - `shaping`    — a dotted outline morphs circle → triangle → square
+ *
+ * Plus the LOCAL (Unoverse) ANNULAR set — drawn only in a ring with the centre left
+ * empty, for framing an avatar's face rather than colliding with it (engine/rings.ts):
+ * - `halo`       — a soft aura breathing, its form drifting off-circle
+ * - `sonar`      — soft rings of light arriving inward, the shape of sound reaching you
+ * - `shimmer`    — luminance sweeping through a still ring, a thought being turned over
+ * - `pulse`      — rings of light leaving outward, the shape of a voice carrying
  */
 export type OrbState =
   | 'working'
@@ -21,7 +28,11 @@ export type OrbState =
   | 'weaving'
   | 'composing'
   | 'breathing'
-  | 'shaping';
+  | 'shaping'
+  | 'halo'
+  | 'sonar'
+  | 'shimmer'
+  | 'pulse';
 
 /**
  * Rendered size in CSS pixels. Exactly two tuned presets ship:

package/vendor/sdk/lib/primitives.tsx

@@ -349,20 +349,25 @@ export function ButtonView({ node, data, theme, onAction, children }: { node: Un
  * bindable), `size` (64 avatar / 20 inline), `speed`, `theme` override.
  * Unknown/unbound state degrades to "working", never a crash.
  */
-const ORB_STATES = new Set(["working", "searching", "solving", "listening", "connecting", "weaving", "composing", "breathing", "shaping"]);
+const ORB_STATES = new Set(["working", "searching", "solving", "listening", "connecting", "weaving", "composing", "breathing", "shaping", "halo", "sonar", "shimmer", "pulse"]);
 export function OrbView({ node, data, theme }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme }): ReactNode {
   const n = node as UnoverseNode & { state?: string; size?: number | string; speed?: number | string; theme?: string };
   // Every knob is data-driven OR literal, like Icon: `bind.<knob>` wins, the attribute is the fallback.
   const knob = (name: "state" | "size" | "speed") =>
     (node.bind?.[name] ? (data[node.bind[name] as string] as string | number | undefined) : undefined) ?? n[name];
   const raw = knob("state") as string | undefined;
-  const state = raw && ORB_STATES.has(raw) ? (raw as OrbState) : "working";
+  // UNKNOWN NAME → the calm ANNULAR fallback, never the sphere. A bad/stale name is an
+  // authoring or version mismatch, and the orb most often sits behind a face: degrading
+  // to `working` threw 3-D particles across the portrait (the loudest mode in the set) to
+  // signal a problem the viewer cannot act on. `halo` is quiet, ring-shaped, and wrong in
+  // no context — a mismatch should look calm, not broken.
+  const state = raw && ORB_STATES.has(raw) ? (raw as OrbState) : "halo";
   const size = Number(knob("size")) > 0 ? Number(knob("size")) : 64;
   const speed = Number(knob("speed")) > 0 ? Number(knob("speed")) : 1;
   const orbTheme: OrbTheme = n.theme === "dark" || n.theme === "light" ? n.theme : "auto";
   // Brand ink comes from the STYLE vocabulary (`color: <token>`), never a prop — LAW 1:
   // a definition names a token, the theme serves the value, the engine tints toward it.
-  const css = styleToCss(node.style ?? {}, theme);
+  const css = styleToCss(node.style ?? {}, theme, data);
   return <ThinkingOrb state={state} size={size as OrbSize} speed={speed} theme={orbTheme} ink={cssColorToRgb(css.color as string | undefined)} style={css} />;
 }
 

package/vendor/sdk/lib/render.tsx

@@ -36,6 +36,7 @@
 import type { ReactNode } from "react";
 import type { ActionSpec, ResolvedTheme, UnoverseNode } from "./core";
 import { visible, selectCase, cssWidth } from "./core";
+import { resolveRef } from "./core/refs";
 import { BoxView, TextView, ImageView, ButtonView, UnknownView, SkeletonView, InputView, SelectView, MarkdownView, IconView, OrbView } from "./primitives";
 
 // The style + animation interpreter lives in ./style; re-exported so consumers keep
@@ -91,6 +92,12 @@ export function renderNode(
   theme: ResolvedTheme,
   key?: React.Key,
   slot?: SlotResolver,
+  /**
+   * The shared pieces this definition REFERENCES, by name. Present only when the server
+   * sends references instead of inlining copies of them; absent for every definition
+   * served the old way, in which case no `Ref` reaches this function at all.
+   */
+  defs?: Record<string, UnoverseNode>,
 ): ReactNode {
   // visibleWhen — conditional visibility (§2e-3). A bare field name is a truthiness test
   // (an empty array counts as empty); an object is a `Condition` (eq/ne/in, or truthy) so
@@ -141,13 +148,26 @@ export function renderNode(
   if (node.type === "Markdown") return <MarkdownView key={key} node={node} data={data} theme={theme} />;
   if (node.type === "ComponentSlot" || node.type === "Timeline") return slot ? slot(node, key) : null;
 
+  // `Ref` — REFERENCE, NOT COPY. The design system's shared pieces travel once and are
+  // cached; a definition names one and specialises it here (core/refs.ts: `props` remap,
+  // `with` literals, style/action/visibleWhen overrides). This is what stops a button
+  // being re-sent inside every definition that uses it.
+  //
+  // A Ref only arrives when the server sent references, so this branch is inert for
+  // anything served the old, inlined way. An unknown name renders NOTHING rather than a
+  // broken box: a hole is easier to diagnose than a mystery element.
+  if (node.type === "Ref") {
+    const resolved = resolveRef(node, defs?.[String((node as { ref?: string }).ref ?? "")]);
+    return resolved ? renderNode(resolved, data, onAction, theme, key, slot, defs) : null;
+  }
+
   // `Switch` — control flow: render EXACTLY ONE branch, the case matching `data[on]`
   // (else `cases.default`, else nothing). The declarative whole-view swap (wizard step,
   // inline↔focused) — mutually exclusive in one place, vs. a `visibleWhen` per branch. No
   // wrapper element: it is transparent, like an `if`, delegating straight to the branch.
   if (node.type === "Switch") {
     const branch = selectCase(node, data);
-    return branch ? renderNode(branch, data, onAction, theme, key, slot) : null;
+    return branch ? renderNode(branch, data, onAction, theme, key, slot, defs) : null;
   }
 
   // `Each` — control flow: map a bound array (bind.items) → the `template` subtree once
@@ -175,7 +195,7 @@ export function renderNode(
         ? { ...base, ...(item as Record<string, unknown>) }
         : { ...base, value: item };
     };
-    const rendered = tpl ? items.map((item, i) => renderNode(tpl, scopeOf(item, i), onAction, theme, i, slot)) : null;
+    const rendered = tpl ? items.map((item, i) => renderNode(tpl, scopeOf(item, i), onAction, theme, i, slot, defs)) : null;
     return (
       <BoxView key={key} node={node} data={data} theme={theme}>
         {rendered}
@@ -184,7 +204,7 @@ export function renderNode(
   }
 
   // Element primitives → dispatch. Children are rendered here (control flow) and handed down.
-  const kids = (node.children ?? []).map((c, i) => renderNode(c, data, onAction, theme, i, slot));
+  const kids = (node.children ?? []).map((c, i) => renderNode(c, data, onAction, theme, i, slot, defs));
   switch (node.type) {
     case "Box":
     case "Stack":

package/vendor/sdk/lib/template.tsx

@@ -141,12 +141,6 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
       }
   }, [def, store, structureVersion]);
 
-  // THE SEVEN RULES (2026-08-09) need no effect here: a higher state MASKS the ones
-  // below (rule 4 — the ladder alone decides what shows; lower states refresh
-  // silently underneath via the store's arrival supersession), and releasing the top
-  // state is just the ladder looking again (rule 6). The earlier cancellation WRITE
-  // (cancelBelow) was superseded by this pure-masking ruling and deleted.
-
   // STATE OWNS LAYOUT (STATE_MODEL v2): the tree this template presents — the active
   // state's layout (multi-layout templates), else the classic root. The resolved node
   // is a stable per-def object, so downstream memos key off it.
@@ -158,10 +152,28 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
   // instance → one placeholder).
   const surfacedViews = useMemo(() => {
     const views = new Set<string>(orderedClaims(def));
-    if (activeRoot) collectSurfacedViews(activeRoot, views);
+    if (activeRoot) collectSurfacedViews(activeRoot, views, def?.defs as Record<string, unknown> | undefined);
     return views;
   }, [activeRoot, def]);
 
+  // RULE 4: the winner clears the states below it — WHEN A DELIVERY PUT IT THERE.
+  // An arrival taking a higher rung means the screen has moved on, so stale claims below
+  // it let go and rule 6's re-walk lands on the base. The guest's own navigation is not
+  // that: tapping a rail card to open its page must leave the rail's claims intact, or
+  // closing the page has nothing to return to. Priority still decides what SHOWS in both
+  // cases; this only decides what gets thrown away. Derived above the loading guards so
+  // this stays a hook, and off the SAME derivation the render path uses.
+  const ladder = def ? resolveActiveView(def, store, surfacedViews) : { view: "", byGuest: false };
+  useEffect(() => {
+    if (ladder.view && !ladder.byGuest) store.cancelBelow(ladder.view, orderedClaims(def));
+    // `structureVersion`: EVERY arrival re-runs this, not only the ones that change the
+    // winner. A card landing while a higher state is ALREADY active would otherwise keep
+    // its claim forever — the walk never re-ran — and closing the higher state dropped
+    // straight onto it (observed: a rail still there after a focus surface closed, because
+    // the card's render landed two seconds after the finder took focus). `cancelBelow`
+    // only bumps when it changed something, so this settles in one extra pass.
+  }, [ladder.view, ladder.byGuest, def, store, structureVersion]);
+
   // Loading/error hints carry NO styling — the SDK owns zero styles.
   if (error) return <div>Unoverse error: {error}</div>;
   if (!def || !theme) return <div>Loading {uri}…</div>;
@@ -235,11 +247,11 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
     // Surfaces never stack; panel combinations cannot exist.
     const claim = node.select?.where;
     if (isViewField(claim?.field) && typeof claim?.eq === "string" && claim.eq !== surfacedView) {
-      return node.fallback ? renderNode(node.fallback, {}, dispatch, theme, key ?? "fallback") : null;
+      return node.fallback ? renderNode(node.fallback, {}, dispatch, theme, key ?? "fallback", undefined, def?.defs) : null;
     }
     const pointers = selectPointers(store, node);
     if (pointers.length === 0) {
-      return node.fallback ? renderNode(node.fallback, {}, dispatch, theme, key ?? "fallback") : null;
+      return node.fallback ? renderNode(node.fallback, {}, dispatch, theme, key ?? "fallback", undefined, def?.defs) : null;
     }
     // `frame` — chrome that exists ONLY because the slot matched (fallback's twin).
     // The frame subtree renders with a slot resolver that serves the outer slot's
@@ -262,7 +274,7 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
       const frame = appWidth
         ? ({ ...node.frame, style: { ...(node.frame.style ?? {}), width: appWidth, flex: "0 0 auto" } } as UnoverseNode)
         : node.frame;
-      return renderNode(frame, store.getTemplateState() as Record<string, unknown>, dispatch, theme, key ?? "frame", innerSlot);
+      return renderNode(frame, store.getTemplateState() as Record<string, unknown>, dispatch, theme, key ?? "frame", innerSlot, def?.defs);
     }
     return pointers.map((p) => leaf(p));
   };
@@ -294,7 +306,7 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
           const turnSlot: SlotResolver = (slotNode, k) => {
             let ptrs = [...shown];
             if (slotNode.select?.limit != null) ptrs = ptrs.slice(0, slotNode.select.limit);
-            if (ptrs.length === 0) return slotNode.fallback ? renderNode(slotNode.fallback, {}, dispatch, theme, k ?? "fb") : null;
+            if (ptrs.length === 0) return slotNode.fallback ? renderNode(slotNode.fallback, {}, dispatch, theme, k ?? "fb", undefined, def?.defs) : null;
             // Pass the turn's streaming state into each component's scope so a streamed
             // component (e.g. StreamingText) can stop its own loading dots when complete.
             const streaming = turn.role === "assistant" && turn.streamingState === "streaming";
@@ -322,7 +334,7 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
                   // inactive → the definition hides it (legacy ChatHistoryItem null-returns).
                   active: turn.streamingState === "streaming" || shown.length > 0,
                 };
-          return renderNode(sub, data, dispatch, theme, turn.id, turnSlot);
+          return renderNode(sub, data, dispatch, theme, turn.id, turnSlot, def?.defs);
         })}
       </div>
     );
@@ -364,7 +376,10 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
   const keyframes = <style>{keyframesCss(theme)}</style>;
   // A layout root never carries `appWidth` (guard-enforced) — panels inside it do.
   const rootNode = (activeRoot ?? def.root) as UnoverseNode;
-  const tree = renderNode(rootNode, rootData, dispatch, theme, undefined, resolve);
+  // The template's own shared pieces, threaded into every branch it draws: chrome, a
+  // slot's fallback, a timeline turn. A reference in any of them resolves against the
+  // same map rather than rendering nothing.
+  const tree = renderNode(rootNode, rootData, dispatch, theme, undefined, resolve, def?.defs);
   // A template is a SURFACE: its render-root fills the box the host gives it, so a root
   // that declares `height: "full"` (DATA) can resolve. This only fills when the host's box
   // is definite-height; when the host sizes to content the 100% resolves to content — so a