@unoverse-platform/studio 0.1.26 → 0.1.28

package/vendor/sdk/lib/UnoverseComponent.tsx

@@ -83,7 +83,11 @@ 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);
-  const resolvedUri = store ? (live.type ? `unoverse://components/${live.type}` : null) : (uri ?? null);
+  // `@refs` asks for the REFERENCED form: shared pieces named once and shipped once,
+  // rather than a copy pasted at every use (746 KB became 221 KB across five real
+  // definitions). This client resolves them, so it asks; a client that could not would
+  // render a hole, which is why the bare URI still serves the inlined form.
+  const resolvedUri = store ? (live.type ? `unoverse://components/${live.type}@refs` : 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
   // theme REF comes from the definition itself: a template's `org` names its client's
@@ -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/actions.ts

@@ -63,12 +63,16 @@ export function dispatchAction(
     // Structure-bumping write (not the deferred COMPONENT_DATA path): templates re-resolve
     // their `select.where` slots the moment a component changes its own state (§5b).
     ctx.store.mergeComponentState(ctx.chatId, ctx.nodeId, patch);
-    // A CHANGED LAYOUT IS NEWS. `defaultState` is the view a component is showing, so a
-    // write to it means this instance just entered a different face — the moment an
-    // `onEnterView` hook exists for. Reported on the channel path every other server
-    // action already uses; the server decides whether any hook cares. Nothing to author:
-    // the setValue already carries the fact, so no component repeats it in a `then`.
-    if (ctx.nodeId && "defaultState" in patch) ctx.sendToServer?.("viewEntered", { layout: patch.defaultState });
+    // A CHANGED VIEW IS NEWS. The public axis (`view`, legacy alias `defaultState`) is
+    // the state a component is showing, so a write to it means this instance just
+    // entered a different state — the moment an `onEnterView` hook exists for. Reported
+    // on the channel path every other server action uses; the server decides whether
+    // any hook cares. The payload carries both spellings during the migration (the
+    // server's lifecycle scope historically read `layout`).
+    if (ctx.nodeId && ("view" in patch || "defaultState" in patch)) {
+      const entered = patch.view ?? patch.defaultState;
+      ctx.sendToServer?.("viewEntered", { layout: entered, view: entered });
+    }
   } else if (spec.type === "setTemplateValue") {
     // Write the dev's chosen keys into TEMPLATE state — the template-state twin of setValue.
     // No component scope. The dev builds disclosure / focus / etc. from a key THEY name

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

@@ -28,6 +28,24 @@ export {
 // The action interpreter (§2e-3) — local `setValue` store write + server route.
 export { dispatchAction, resolveValue, type ActionContext } from "./actions";
 
+// The pure template-tier derivations (STATE_MODEL v2: the stateOrder ladder, state-
+// owns-layout resolution, the pinned law, slot selection, claimed views, app width).
+// Framework-agnostic — the React binding (template.tsx) and every platform port call
+// these, never re-derive them.
+export {
+  collectSurfacedViews,
+  computeAppWidth,
+  cssWidth,
+  formatRelative,
+  isViewField,
+  orderedClaims,
+  propDefaults,
+  resolveActiveLayout,
+  resolveActiveView,
+  selectPointers,
+  viewOf,
+} from "./templates";
+
 // Experience analytics (UNOVERSE_ANALYTICS.md) — the SDK emits; the host decides where to.
 export {
   emitAnalytics,
@@ -42,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

@@ -102,6 +102,26 @@ export class ComponentStore {
     this.maxTurns = opts?.maxTurns ?? 100;
   }
 
+  /**
+   * RETRACT ONE SLICE to its declared base (STATE_MODEL v2 §8 item 6). The public
+   * axis is `view` with `defaultState` as the legacy alias; the retract target is the
+   * slice's declared initial (`initialView`, seeded at spawn) falling back to
+   * `"inline"` (the universal fallback). Returns true when the slice changed. This is
+   * the ONE home for the reset every boundary uses (new turn, guest close, template
+   * swap) — never re-hardcode `"inline"` at a call site.
+   */
+  private retractSlice(key: string, slice: Record<string, unknown>): boolean {
+    const current = (slice.view ?? slice.defaultState) as unknown;
+    const base = typeof slice.initialView === "string" ? slice.initialView : "inline";
+    if (typeof current !== "string" || current === base) return false;
+    const next: Record<string, unknown> = { ...slice };
+    if ("view" in next || !("defaultState" in next)) next.view = base;
+    if ("defaultState" in next) next.defaultState = base;
+    this.data.set(key, next);
+    this.touches.set(key, ++this.touchSeq);
+    return true;
+  }
+
   // ============ writes ============
 
   /** The current composer draft (a key in template state). */
@@ -131,12 +151,7 @@ export class ComponentStore {
     // slices persist; only the active VIEW resets) — swapping back re-presents nothing
     // until something surfaces again.
     if (this.activeTemplateName !== null && this.activeTemplateName !== name) {
-      for (const [key, slice] of this.data) {
-        if (typeof slice.defaultState === "string" && slice.defaultState !== "inline") {
-          this.data.set(key, { ...slice, defaultState: "inline" });
-          this.touches.set(key, ++this.touchSeq);
-        }
-      }
+      for (const [key, slice] of this.data) this.retractSlice(key, slice);
     }
     this.activeTemplateName = name;
     this.activeTemplateProps = props;
@@ -152,15 +167,40 @@ export class ComponentStore {
    * calls this when a template-chrome `setValue defaultState:"inline"` fires (a card that
    * closes ITSELF still uses the plain component write; template chrome has no card to hit).
    */
+  /**
+   * ARRIVALS REFRESH THEIR STATE (THE SEVEN RULES, 2026-08-09, rule 5): when a
+   * component ARRIVES into state X (a server placement — never a guest write),
+   * components from EARLIER turns sitting in X retract to inline. New cards
+   * replace the rail's old cards; a new wizard replaces the old wizard — latest
+   * wins, at every rung. Same-turn siblings coexist (one answer's card set is one
+   * delivery, so eviction is keyed by TURN, not by instance). Durable
+   * (`lifetime: "conversation"`) slices opt out, as with every retract. Whether a
+   * refresh is VISIBLE is the ladder's business alone (rule 4: higher states mask;
+   * lower states update silently underneath).
+   */
+  private supersede(arrivingChatId: string, view: unknown): void {
+    if (typeof view !== "string" || !view || view === "inline") return;
+    let changed = false;
+    for (const [key, slice] of this.data) {
+      if (key.startsWith(`${arrivingChatId}:`)) continue; // same turn = same delivery
+      if (slice.lifetime === "conversation") continue;
+      const v = (slice.view ?? slice.defaultState) as unknown;
+      if (v !== view) continue;
+      const next: Record<string, unknown> = { ...slice };
+      if ("view" in next || !("defaultState" in next)) next.view = "inline";
+      if ("defaultState" in next) next.defaultState = "inline";
+      this.data.set(key, next);
+      this.touches.set(key, ++this.touchSeq);
+      changed = true;
+    }
+    if (changed) this.bump();
+  }
+
   closeSurfaces(): void {
     let changed = false;
     for (const [key, slice] of this.data) {
       if (slice.lifetime === "conversation") continue;
-      if (typeof slice.defaultState === "string" && slice.defaultState !== "inline") {
-        this.data.set(key, { ...slice, defaultState: "inline" });
-        this.touches.set(key, ++this.touchSeq);
-        changed = true;
-      }
+      if (this.retractSlice(key, slice)) changed = true;
     }
     if (changed) this.bump();
   }
@@ -212,6 +252,9 @@ export class ComponentStore {
       this.types.set(key, event.component.type);
       this.placeInTimeline(event.chatId, key); // structure: place the pointer ONCE
       this.merge(key, event.component.props ?? {}); // data: seed
+      // Rule 5 — an arrival carrying a public state refreshes that state.
+      const seeded = event.component.props as Record<string, unknown> | undefined;
+      this.supersede(event.chatId, seeded?.view ?? seeded?.defaultState);
     } else {
       // NEW ACTIVITY reads newest-at-the-bottom: if this component is no longer the
       // LAST pointer in its turn (something was placed after it), fresh server data
@@ -225,42 +268,26 @@ export class ComponentStore {
         this.bump();
       }
       this.merge(key, event.data);
+      // Rule 5 — a server data-write that PLACES a component into a public state
+      // (the host's arrival placement rides COMPONENT_DATA) refreshes that state.
+      this.supersede(event.chatId, (event.data as Record<string, unknown> | undefined)?.view ?? (event.data as Record<string, unknown> | undefined)?.defaultState);
     }
   }
 
-  /** Append a user message turn. Response identity = its chatId. */
+  /** Append a user message turn. Response identity = its chatId.
+   *
+   *  RULE 7 (the seven rules, 2026-08-09): typing changes NOTHING by itself. The
+   *  old new-turn reset (`beginExchange`, the "two lifetimes" chat-layer wipe) is
+   *  GONE — only arrivals move the screen (rule 5's same-state refresh) and only
+   *  closings release it (rule 6's ladder re-look). A wizard mid-flow survives the
+   *  guest's next message; a stale rail is cleared by the cards that replace it,
+   *  never by the message that asked for them. */
   addUserMessage(chatId: string, text: string): void {
     this.timeline.push({ role: "user", id: `u${this.seq++}`, chatId, text, createdAt: Date.now() });
-    this.beginExchange();
     this.evict();
     this.bump();
   }
 
-  /**
-   * TWO LIFETIMES, ONE STORE (docs/design/04): CONVERSATION state (turns + each
-   * instance's data — durable, append-only, the stream owns it) vs CHAT state (the
-   * present interaction: each instance's active VIEW, the template's chrome). A new
-   * user turn advances the conversation, so the chat layer returns to its universal
-   * default: every instance goes back to `inline` — surfaces empty, the template
-   * derives its base state, panels retract. Data is untouched; history keeps every
-   * card. (A future durable, conversation-scoped component — a cart, an itinerary —
-   * will opt out of this explicitly; today nothing does.)
-   */
-  private beginExchange(): void {
-    for (const [key, slice] of this.data) {
-      // DURABLE conversation-scoped surface (docs/design/04 §Two lifetimes): the
-      // producer marked the slice `lifetime: "conversation"` (a cart, an itinerary,
-      // a composed page) — it opted out of the new-turn reset and stays surfaced
-      // until replaced, closed, or the template swaps. Generic: a key the producer
-      // wrote, not a UI concept.
-      if (slice.lifetime === "conversation") continue;
-      if (typeof slice.defaultState === "string" && slice.defaultState !== "inline") {
-        this.data.set(key, { ...slice, defaultState: "inline" });
-        this.touches.set(key, ++this.touchSeq);
-      }
-    }
-  }
-
   /**
    * Open (or re-open) the assistant response for chatId in streaming state, WITHOUT
    * attaching a component. Mirrors legacy WORKFLOW_STARTED (processWorkflowState.ts):