@unoverse-platform/studio 0.1.25 → 0.1.27

package/vendor/sdk/lib/primitives.tsx

@@ -23,7 +23,8 @@ import { createElement, useEffect, useMemo, useRef, useState, type CSSProperties
 import Markdown from "markdown-to-jsx";
 import type { ResolvedTheme, UnoverseNode } from "./core";
 import { styleToCss, cssDecls } from "./style";
-import type { ActionHandler } from "./render";
+import { nodeAction, type ActionHandler } from "./render";
+import { ThinkingOrb, type OrbState, type OrbSize, type OrbTheme } from "./orb";
 
 /** Read a bound data field as a string (for Text/Image/Button content). */
 function bound(field: string | undefined, data: Record<string, unknown>): string | undefined {
@@ -332,13 +333,51 @@ export function ImageView({ node, data, theme }: { node: UnoverseNode; data: Rec
 export function ButtonView({ node, data, theme, onAction, children }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme; onAction?: ActionHandler; children?: ReactNode }): ReactNode {
   const { className, styleEls, style, disabled } = nodeChrome(node, data, theme);
   return (
-    <button className={className} style={style} disabled={disabled} data-unoverse-id={inspectId(node)} onClick={() => onAction?.(node.action ?? "click", data)}>
+    <button className={className} style={style} disabled={disabled} data-unoverse-id={inspectId(node)} onClick={() => onAction?.(nodeAction(node, "click"), data)}>
       {styleEls}
       {node.children?.length ? children : bound(node.bind?.label, data)}
     </button>
   );
 }
 
+/**
+ * `Orb` — a procedural "the assistant is doing something" animation, drawn
+ * per-frame on a 2D canvas (see ./orb — vendored thinking-orbs, MIT). This is
+ * the ONE class of motion keyframe data cannot express (per-frame math, depth
+ * occlusion), so like Skeleton's shimmer the drawing lives WITH the primitive;
+ * every authoring decision stays data: `state` (which of the nine animations —
+ * 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"]);
+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";
+  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);
+  return <ThinkingOrb state={state} size={size as OrbSize} speed={speed} theme={orbTheme} ink={cssColorToRgb(css.color as string | undefined)} style={css} />;
+}
+
+/** #rgb / #rrggbb / rgb()/rgba() → an rgb tuple; anything else (gradients, names) → null (neutral ink). */
+function cssColorToRgb(c?: string): [number, number, number] | null {
+  if (!c) return null;
+  const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(c.trim());
+  if (hex) {
+    const h = hex[1].length === 3 ? [...hex[1]].map((x) => x + x).join("") : hex[1];
+    return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16)) as [number, number, number];
+  }
+  const fn = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/i.exec(c.trim());
+  return fn ? [Number(fn[1]), Number(fn[2]), Number(fn[3])] : null;
+}
+
 /** Unknown node type — render children so the tree doesn't break (degenerate fallback). */
 export function UnknownView({ node, theme, children }: { node: UnoverseNode; theme: ResolvedTheme; children?: ReactNode }): ReactNode {
   return (
@@ -432,6 +471,58 @@ export function SkeletonView({ variant = "text", theme }: { variant?: string; th
   );
 }
 
+/**
+ * `Select` — the irreducible `<select>`, like Text→<span> and Input→<input>.
+ *
+ * THE ONE CONTROL THAT CANNOT BE COMPOSED. Every other form field in this platform is
+ * built from Box, Text, Button and Input, as data. A closed set of two hundred countries
+ * is where that stops: laying them out is unusable, filtering them is logic a definition
+ * may not carry, and a hand-rolled menu forfeits the OS picker, type-to-search, keyboard
+ * navigation and screen-reader semantics that the real element gives for nothing.
+ *
+ * It reports a change exactly as a controlled Input does — `onAction("input", { field,
+ * text })` — so the bound field name IS the key the answer lands in, and a select needs no
+ * mechanism the platform does not already have.
+ *
+ * ⛔ NO CHROME HERE. No custom arrow, no popup, no styling: `node.style` is the whole look,
+ * and the options are DATA (`bind.options`, entries of `{ value, label }` or plain
+ * strings). A searchable picker is a different control and does not belong in this one.
+ */
+export function SelectView({ node, data, theme, onAction }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme; onAction?: ActionHandler }): ReactNode {
+  const field = node.bind?.value;
+  const value = field != null ? String(data[field] ?? "") : "";
+  const raw = node.bind?.options ? data[node.bind.options] : (node as { options?: unknown }).options;
+  const options = (Array.isArray(raw) ? raw : []).map((o) =>
+    o != null && typeof o === "object"
+      ? { value: String((o as Record<string, unknown>).value ?? (o as Record<string, unknown>).label ?? ""), label: String((o as Record<string, unknown>).label ?? (o as Record<string, unknown>).value ?? "") }
+      : { value: String(o), label: String(o) },
+  );
+  const { style, disabled } = nodeChrome(node, data, theme);
+  return (
+    <select
+      style={style}
+      disabled={disabled}
+      value={value}
+      data-unoverse-id={inspectId(node)}
+      onChange={(e) => field != null && onAction?.("input", { text: e.target.value, field })}
+    >
+      {/* The placeholder is CONTENT, exactly as it is on an Input: an unanswered select
+          must say what it wants rather than pre-selecting the first option and claiming an
+          answer nobody gave. */}
+      {node.placeholder != null && (
+        <option value="" disabled>
+          {node.placeholder}
+        </option>
+      )}
+      {options.map((o) => (
+        <option key={o.value} value={o.value}>
+          {o.label}
+        </option>
+      ))}
+    </select>
+  );
+}
+
 /**
  * `Input` — single-line composer (the irreducible `<input>`, like Text→<span>).
  * Holds its own draft text (local, not store state); on Enter it fires
@@ -463,6 +554,11 @@ export function InputView({ node, data, theme, onAction }: { node: UnoverseNode;
   // a postal code, "off") and the guess never happens. Generic pass-through: the SDK holds
   // no list of values and no idea what a one-time code is.
   const autoComplete = (node as { autoComplete?: string }).autoComplete;
+  // `type` — WHAT THE FIELD IS, passed to the platform: `date` gets the OS date picker,
+  // `tel` the phone keypad, `file` the file chooser. The same class of generic constraint
+  // as `maxLength` and `inputMode`, and the reason a definition never has to hand-roll a
+  // calendar out of Boxes. The SDK holds no list of types and no opinion about them.
+  const inputType = (node as { inputType?: string }).inputType;
   // `maxLength` is enforced by the element itself, but `inputMode` is only a HINT —
   // a desktop keyboard types straight past it — so the digit rule is applied here.
   const accept = (t: string) => {
@@ -507,7 +603,7 @@ export function InputView({ node, data, theme, onAction }: { node: UnoverseNode;
   const submit = () => {
     const t = value.trim();
     if (!t) return;
-    onAction?.(node.action ?? "submit", { text: t });
+    onAction?.(nodeAction(node, "submit"), { text: t });
     if (field == null) setLocal("");
   };
   const { style, disabled } = nodeChrome(node, data, theme);
@@ -538,13 +634,26 @@ export function InputView({ node, data, theme, onAction }: { node: UnoverseNode;
       ref={el}
       style={style}
       disabled={disabled}
-      value={value}
+      // A file input is never controlled: assigning its value is a security error in every
+      // browser, so the chosen name lives in the data and the element stays uncontrolled.
+      value={inputType === "file" ? undefined : value}
       placeholder={node.placeholder}
+      type={inputType}
       maxLength={maxLength}
       inputMode={numeric ? "numeric" : undefined}
       autoComplete={autoComplete}
       data-uno-advance={advanceOnFill ? "" : undefined}
-      onChange={(e) => setValue(e.target.value)}
+      onChange={(e) => {
+        // A FILE FIELD REPORTS ITS FILES, not its value: the DOM's value for one is a fake
+        // path, and the bytes are the host's business (an upload target, a stored
+        // reference) rather than the renderer's. The SDK states what was chosen and stops.
+        if (inputType === "file") {
+          const picked = Array.from(e.target.files ?? []).map((f) => ({ name: f.name, size: f.size, type: f.type }));
+          if (field != null) onAction?.("input", { text: picked.map((f) => f.name).join(", "), field, files: picked });
+          return;
+        }
+        setValue(e.target.value);
+      }}
       onKeyDown={(e) => {
         // Backspace in an ALREADY-empty field steps back, so correcting a sequence never
         // needs the mouse. A field with content just deletes it (the default).

package/vendor/sdk/lib/render.tsx

@@ -35,8 +35,8 @@
  */
 import type { ReactNode } from "react";
 import type { ActionSpec, ResolvedTheme, UnoverseNode } from "./core";
-import { visible, selectCase } from "./core";
-import { BoxView, TextView, ImageView, ButtonView, UnknownView, SkeletonView, InputView, MarkdownView, IconView } from "./primitives";
+import { visible, selectCase, cssWidth } from "./core";
+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
 // importing it from "./render".
@@ -57,6 +57,22 @@ export interface ActionMeta {
 
 export type ActionHandler = (action: string | ActionSpec, data: Record<string, unknown>, meta?: ActionMeta) => void;
 
+/**
+ * A leaf's action, with the node's declared `analytics` attached (UNOVERSE_ANALYTICS.md).
+ *
+ * Authors write `analytics:` beside `action:` on the node, where the data it reports is
+ * already in scope. The two travel together from here so `dispatchAction` remains the ONE
+ * place an interaction is understood: leaves stay dumb, and no leaf can forget to report.
+ * A node with no `analytics` block passes its action through untouched, unallocated.
+ */
+export function nodeAction(node: UnoverseNode, fallback: string): string | ActionSpec {
+  const action = node.action ?? fallback;
+  if (!node.analytics?.event) return action;
+  return typeof action === "string"
+    ? { type: action, analytics: node.analytics }
+    : { ...action, analytics: node.analytics };
+}
+
 /**
  * Resolves a `ComponentSlot` node against the store (provided by the template
  * renderer). Returns the rendered leaves (or the slot's fallback). Components
@@ -64,9 +80,9 @@ export type ActionHandler = (action: string | ActionSpec, data: Record<string, u
  */
 export type SlotResolver = (node: UnoverseNode, key?: React.Key) => ReactNode;
 
-/** A usable appWidth is CSS ("360px", "min(50vw, 760px)") — an UNRESOLVED size name
- *  has no digits; treat it as absent rather than emitting invalid CSS. */
-export const cssWidth = (w: unknown): string | undefined => (typeof w === "string" && /\d/.test(w) ? w : undefined);
+// cssWidth moved to core/templates.ts (computeAppWidth needs it and core imports
+// nothing from the React layer); re-exported to keep this import path working.
+export { cssWidth };
 
 export function renderNode(
   node: UnoverseNode,
@@ -119,6 +135,8 @@ export function renderNode(
   // through `with` — so without this an atom can be data-driven or literal, never both.
   if (node.type === "Icon")
     return <IconView key={key} name={node.bind?.name ? (data[node.bind.name] as string) : (node.icon ?? node.name)} style={node.style} theme={theme} />;
+  // Orb: procedural thinking/working animation — state is a literal or bound (`bind.state`).
+  if (node.type === "Orb") return <OrbView key={key} node={node} data={data} theme={theme} />;
   if (node.type === "Input") return <InputView key={key} node={node} data={data} theme={theme} onAction={onAction} />;
   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;
@@ -181,6 +199,8 @@ export function renderNode(
       return <TextView key={key} node={node} data={data} theme={theme} />;
     case "Image":
       return <ImageView key={key} node={node} data={data} theme={theme} />;
+    case "Select":
+      return <SelectView key={key} node={node} data={data} theme={theme} onAction={onAction} />;
     case "Button":
       return (
         <ButtonView key={key} node={node} data={data} theme={theme} onAction={onAction}>

package/vendor/sdk/lib/style.ts

@@ -223,17 +223,21 @@ export function cssDecls(css: CSSProperties, important = false): string {
  * into a CSS string, injected ONCE per render root (<style>). This authors zero values —
  * it only structures DATA into `@keyframes uno-<name>{ <stop>{ <prop>:<val> } }`. Adding a
  * new animation = adding a keyframe to rx/ + a `style.animation` ref in a definition. No
- * SDK edit, no new primitive. Keyframe decls use real CSS prop names (transform, opacity…).
+ * SDK edit, no new primitive. Keyframe decls use real CSS prop names, KEBAB-CASE
+ * (`box-shadow`, never `boxShadow`) — that is the canonical authored form, lint-enforced.
+ * Property keys are still kebab-normalized here, exactly as Studio's gallery serializer
+ * does, so the two renderers can never disagree on a key that slips past the lint.
  */
 export function keyframesCss(theme: ResolvedTheme): string {
   const hit = keyframesCache.get(theme);
   if (hit !== undefined) return hit;
   const kf = (theme.keyframes ?? {}) as Record<string, Record<string, Record<string, string>>>;
+  const kebab = (s: string) => s.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase());
   const css = Object.entries(kf)
     .map(
       ([name, stops]) =>
         `@keyframes uno-${name}{${Object.entries(stops)
-          .map(([stop, decls]) => `${stop}{${Object.entries(decls).map(([p, v]) => `${p}:${v}`).join(";")}}`)
+          .map(([stop, decls]) => `${stop}{${Object.entries(decls).map(([p, v]) => `${kebab(p)}:${v}`).join(";")}}`)
           .join("")}}`,
     )
     .join("");

package/vendor/sdk/lib/template.tsx

@@ -13,8 +13,30 @@
  * chat primitives (Conversation/Input/…) come in later slices.
  */
 import { useCallback, useEffect, useMemo, useState, useSyncExternalStore, type CSSProperties, type ReactNode } from "react";
-import { dispatchAction, type ComponentStore, type ResolvedTheme, type UnoverseClient, type UnoverseDefinition, type UnoverseNode } from "./core";
-import { renderNode, styleToCss, keyframesCss, cssWidth, type ActionHandler, type SlotResolver } from "./render";
+import {
+  collectSurfacedViews,
+  cssWidth,
+  dispatchAction,
+  formatRelative,
+  isViewField,
+  orderedClaims,
+  propDefaults,
+  resolveActiveLayout,
+  resolveActiveView,
+  selectPointers,
+  viewOf,
+  type ComponentStore,
+  type ResolvedTheme,
+  type UnoverseClient,
+  type UnoverseDefinition,
+  type UnoverseNode,
+} from "./core";
+import { renderNode, styleToCss, keyframesCss, type ActionHandler, type SlotResolver } from "./render";
+
+// The pure template derivations moved to core/templates.ts (the portable brain —
+// framework-agnostic, guarded by sdk-core-portable.test.ts). Re-exported here so
+// existing consumers keep their import path.
+export { collectSurfacedViews, computeAppWidth, orderedClaims, resolveActiveLayout, resolveActiveView, selectPointers, viewOf } from "./core";
 import { UnoverseComponent } from "./UnoverseComponent";
 import { useUnoverseTheme, ensureFontStylesheets } from "./theme";
 import { IsolatedRoot } from "./isolate";
@@ -49,203 +71,6 @@ const INERT_VOICE: UseVoiceServiceConfig = {
   session: { userId: "", conversationId: "", workflowId: "", targetTriggerNode: "" },
 };
 
-/** The author's declared prop defaults (def.props[k].default) → a flat data object. Content, not policy. */
-function propDefaults(props?: Record<string, unknown>): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(props ?? {})) {
-    if (v && typeof v === "object" && "default" in (v as Record<string, unknown>)) {
-      out[k] = (v as { default: unknown }).default;
-    }
-  }
-  return out;
-}
-
-/** Format a turn timestamp as relative copy ("just now" / "5 min ago"). Neutral
- *  projection of a model value (like `text`), not UX policy. Mirrors legacy
- *  ChatHistoryItem.formatRelativeTime. Empty string when unstamped. */
-function formatRelative(ts?: number): string {
-  if (!ts) return "";
-  const diff = Math.floor((Date.now() - ts) / 1000);
-  if (diff < 60) return "just now";
-  if (diff < 3600) return `${Math.floor(diff / 60)} min ago`;
-  if (diff < 86400) return `${Math.floor(diff / 3600)} hr ago`;
-  return new Date(ts).toLocaleDateString();
-}
-
-/**
- * Walk a template tree and collect every VIEW a reaction surface claims — the `eq`
- * value of each `ComponentSlot.select.where { field: "defaultState" }`. State-selected
- * UI (STATE_MODEL §5b): a component instance renders in exactly ONE placeholder. If a
- * surface shows a given view, the conversation flow (the `inline` placeholder) must NOT
- * also render instances in that view — else the same instance paints twice. A view no
- * surface claims is absent from this set, so it stays in the flow (the fallback).
- * Exported for testing.
- */
-export function collectSurfacedViews(node: unknown, out: Set<string> = new Set()): Set<string> {
-  if (Array.isArray(node)) {
-    for (const n of node) collectSurfacedViews(n, out);
-    return out;
-  }
-  if (!node || typeof node !== "object") return out;
-  const n = node as Record<string, unknown>;
-  const sel = n.select as { where?: { field?: string; eq?: unknown } } | undefined;
-  if (n.type === "ComponentSlot" && sel?.where?.field === "defaultState" && 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);
-  return out;
-}
-
-/**
- * STATE-OWNED APP WIDTH (docs/design/05, layouts era): the app's outer width is
- * declared by its LAYOUT's data, never the manifest. Two declaration points, both
- * the neutral `appWidth` key (a named app size resolved via theme.appSize):
- *   - a plain node's `appWidth` = an always-open panel (the core column) — the
- *     layout's constant term.
- *   - a ComponentSlot surface's `appWidth` = its panel width, counted only while
- *     the surface is OCCUPIED (its view is the active state).
- * The caller passes the ACTIVE layout (resolveActiveLayout) — layout swaps are
- * whole-arrangement swaps, so the width is always the active layout's total.
- * Activation is DERIVED, never stored. No declared width → undefined: the host
- * keeps its own default, the sizing twin of "unmatched view falls back to inline".
- * There is no other path.
- */
-export function computeAppWidth(root: unknown, store: ComponentStore, appSize?: Record<string, string>): string | undefined {
-  // Resolve a declared width: a NAMED SIZE via theme.appSize (like any token), else raw
-  // CSS — guarded so an unresolvable name can never emit invalid CSS.
-  const rw = (w: unknown): string | undefined => cssWidth(typeof w === "string" ? (appSize?.[w] ?? w) : undefined);
-  const r = root as Record<string, unknown> | null | undefined;
-  const widths: string[] = [];
-  // Gather the tree's width-bearing nodes: always-open core panels and the reaction
-  // SURFACES (view → panel width).
-  const surfaces = new Map<string, string | undefined>();
-  const walk = (node: unknown): void => {
-    if (Array.isArray(node)) {
-      for (const c of node) walk(c);
-      return;
-    }
-    if (!node || typeof node !== "object") return;
-    const n = node as Record<string, unknown> & { appWidth?: string; type?: string; select?: { where?: { field?: string; eq?: unknown } } };
-    if (n !== r) {
-      if (n.type === "ComponentSlot") {
-        const claim = n.select?.where;
-        // `appWidth: flex` — the surface takes the REMAINING host space. DATA WINS: an
-        // org may define `flex` as a real appSize token (bpp: calc(100% − chat)) and
-        // that resolves like any name; the marker below is the theme-free fallback,
-        // resolved as "fill the host" when the view is active.
-        if (claim?.field === "defaultState" && typeof claim.eq === "string")
-          surfaces.set(claim.eq, rw(n.appWidth) ?? (n.appWidth === "flex" ? "flex" : undefined));
-      } else if (n.appWidth !== undefined) {
-        const w = rw(n.appWidth);
-        if (w) widths.push(w); // a plain panel (the core column) is ALWAYS open
-      }
-    }
-    for (const v of Object.values(n)) if (v && typeof v === "object") walk(v);
-  };
-  walk(r);
-  // ONE STATE AT A TIME (docs/design/04): the app = core + the ACTIVE state's panel —
-  // the most recently surfaced view. Panel combinations cannot exist, so the width is
-  // always one of a small known set, bounded by construction.
-  let active = "";
-  let activeAt = -1;
-  for (const turn of store.getResponses())
-    for (const p of turn.components) {
-      const { chatId, nodeId } = store.split(p);
-      const view = (store.get(chatId, nodeId) as Record<string, unknown>)?.defaultState;
-      if (typeof view === "string" && surfaces.has(view) && store.touchOf(p) > activeAt) {
-        activeAt = store.touchOf(p);
-        active = view;
-      }
-    }
-  const activePanel = active ? surfaces.get(active) : undefined;
-  // An ACTIVE flex surface fills the host viewport (the host caps at its pane); the
-  // surface flexes into whatever the fixed panels leave.
-  if (activePanel === "flex") return "100%";
-  if (activePanel) widths.push(activePanel);
-  if (!widths.length) return undefined;
-  return widths.length === 1 ? widths[0] : `calc(${widths.join(" + ")})`;
-}
-
-/**
- * TEMPLATE LAYOUTS — name-sync (docs/design/05). A template with `layouts` is a set
- * of full arrangements, the template-tier twin of a component's faces: the ACTIVE
- * layout is the one whose NAME matches the latest surfaced component view, falling
- * back to `defaultLayout` when nothing (or nothing matching) is surfaced. Same
- * derivation as the active state — read off the store, never stored. Single-layout
- * templates (`layouts` absent) resolve to `root`: the classic behavior, untouched.
- */
-export function resolveActiveLayout(def: UnoverseDefinition | null | undefined, store: ComponentStore): UnoverseNode | undefined {
-  if (!def) return undefined;
-  const layouts = def.layouts;
-  if (!layouts) return def.root;
-  const { view } = resolveActiveView(def, store, new Set(Object.keys(layouts)));
-  return layouts[view] ?? layouts[def.defaultLayout ?? "main"] ?? def.root;
-}
-
-/**
- * THE ACTIVE VIEW — the ONE derivation every consumer shares (docs/design/04 + the
- * guest-control law). The latest surfaced component view among `validViews`, with
- * PINNED enforcement: while a pinned layout's view is surfaced, a background arrival
- * cannot displace it — only a guest write anywhere can. Layout choice and surface
- * gating MUST both read this function: two loops that each pick "the latest view"
- * disagree the moment pin overrides one of them — the layout renders view A while
- * every surface inside it gates against view B, and the whole panel goes blank.
- */
-export function resolveActiveView(
-  def: UnoverseDefinition | null | undefined,
-  store: ComponentStore,
-  validViews: Set<string>,
-): { view: string; byGuest: boolean } {
-  let view = "";
-  let at = -1;
-  let byGuest = false;
-  let pinnedView = "";
-  let pinnedAt = -1;
-  for (const turn of store.getResponses())
-    for (const p of turn.components) {
-      const { chatId, nodeId } = store.split(p);
-      const v = (store.get(chatId, nodeId) as Record<string, unknown>)?.defaultState;
-      if (typeof v !== "string" || !validViews.has(v)) continue;
-      const t = store.touchOf(p);
-      if (t > at) {
-        at = t;
-        view = v;
-        byGuest = store.interactionTouchOf(p) >= t;
-      }
-      if ((def?.layouts?.[v] as { pinned?: boolean } | undefined)?.pinned && t > pinnedAt) {
-        pinnedAt = t;
-        pinnedView = v;
-      }
-    }
-  if (pinnedView && view !== pinnedView && !byGuest) return { view: pinnedView, byGuest: false };
-  return { view, byGuest };
-}
-
-/** Resolve a ComponentSlot's `select` against the store → ordered pointers. Exported for testing. */
-export function selectPointers(store: ComponentStore, node: UnoverseNode): string[] {
-  const sel = node.select ?? {};
-  let pointers =
-    sel.from === "all"
-      ? store.getResponses().flatMap((r) => r.components)
-      : (store.latestResponse()?.components ?? []);
-
-  // `where` — select by COMPONENT STATE (the reaction contract, STATE_MODEL §5b): any
-  // component whose own slice matches, ordered newest state-write first so `limit: 1`
-  // = "most recent wins". The generic replacement for type-pinned surfaces — a
-  // template reacts to whatever component enters the state, never to a named type.
-  if (sel.where) {
-    const { field, eq, ne } = sel.where;
-    pointers = pointers.filter((p) => {
-      const { chatId, nodeId } = store.split(p);
-      const v = (store.get(chatId, nodeId) as Record<string, unknown>)[field];
-      return ne !== undefined ? v !== ne : v === eq;
-    });
-    pointers = [...pointers].sort((a, b) => store.touchOf(b) - store.touchOf(a));
-  }
-  if (sel.limit != null) pointers = pointers.slice(0, sel.limit);
-  return pointers;
-}
-
 export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme: themeProp, props, isolate = true, voice: voiceConfig }: StreamedUnoverseTemplateProps) {
   const [def, setDef] = useState<UnoverseDefinition | null>(null);
   const [error, setError] = useState<string | null>(null);
@@ -271,7 +96,7 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
   // to their own slices — so streaming chunks never re-walk the whole template tree.
   // Stable subscribe fn: an inline arrow would tear down + re-create the subscription
   // every render.
-  useSyncExternalStore(
+  const structureVersion = useSyncExternalStore(
     useCallback((cb) => store.subscribe(cb), [store]),
     useCallback(() => store.getStructureVersion(), [store]),
   );
@@ -289,18 +114,51 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
     };
   }, [client, uri]);
 
-  // NAME-SYNC: the tree this template presents — the layout matching the latest
-  // surfaced component view (multi-layout templates), else the classic root. The
-  // resolved node is a stable per-def object, so downstream memos key off it.
+  // ARRIVAL PLACEMENT (STATE_MODEL v2 §5 rule 3): nobody sends a state — the HOST
+  // places the actor at spawn. For each arrived component whose slice has no view yet:
+  //   1. the component's DECLARED INITIAL, if this template has a state for it (the
+  //      component's preference stands whenever the host can honor it);
+  //   2. else the SCAN — the first name in THIS template's declared order that the
+  //      component's public menu (`publicStates`, server-injected at init) also has;
+  //   3. no overlap at all → leave unset: the component wakes in its own initial and
+  //      rides inline (rule 6).
+  // The write is a data merge (never an interaction touch — placement is not the
+  // guest's hand), it happens ONCE per instance (a placed slice has a view), and the
+  // component owns the axis from then on: the template never writes it again.
+  useEffect(() => {
+    const order = def?.stateOrder;
+    if (!order?.length) return;
+    for (const turn of store.getResponses())
+      for (const p of turn.components) {
+        const { chatId, nodeId } = store.split(p);
+        const slice = store.get(chatId, nodeId) as Record<string, unknown> | undefined;
+        if (!slice || viewOf(slice) !== undefined) continue;
+        const menu = Array.isArray(slice.publicStates) ? (slice.publicStates as unknown[]) : undefined;
+        if (!menu) continue;
+        const initial = typeof slice.initialView === "string" ? slice.initialView : undefined;
+        const face = initial && order.includes(initial) ? initial : order.find((s) => menu.includes(s));
+        if (face) store.apply({ type: "COMPONENT_DATA", chatId, nodeId, data: { view: face } });
+      }
+  }, [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.
   const activeRoot = def ? resolveActiveLayout(def, store) : undefined;
 
-  // The set of VIEWS this template's reaction surfaces claim — computed per active
-  // layout: layout NAMES claim their view (name-sync) alongside the surfaces inside.
-  // The timeline uses it to keep a claimed instance out of the flow (one instance → one
-  // placeholder).
+  // The CLAIM set — the states this template reacts to. v2: the declared order
+  // (stateOrder) IS the claim list; legacy defs fall back to layout names + surface
+  // claims. The timeline uses it to keep a claimed instance out of the flow (one
+  // instance → one placeholder).
   const surfacedViews = useMemo(() => {
-    const views = activeRoot ? collectSurfacedViews(activeRoot) : new Set<string>();
-    for (const name of Object.keys(def?.layouts ?? {})) views.add(name);
+    const views = new Set<string>(orderedClaims(def));
+    if (activeRoot) collectSurfacedViews(activeRoot, views);
     return views;
   }, [activeRoot, def]);
 
@@ -326,16 +184,17 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
       if (action === "backToChat") voice.endCall();
     }
     // GUEST CLOSE from TEMPLATE CHROME: a ✕ on the layout itself (a rail/panel header —
-    // not inside a single card) fires the CloseButton atom's `setValue defaultState:"inline"`.
-    // Template chrome has no card slice to write, so that write would be inert; instead it
-    // means "un-surface the current view" → the store retracts every surface to base (the
-    // same reset a new turn runs). A card that closes ITSELF keeps using the plain component
-    // write (real ids), untouched. `then` still chains via dispatchAction below.
+    // not inside a single card) fires the CloseButton atom's `setValue view:"inline"`
+    // (legacy defs write `defaultState`). Template chrome has no card slice to write, so
+    // that write would be inert; instead it means "un-surface the current view" → the
+    // store retracts every surface to its declared base (the same reset a new turn
+    // runs). A card that closes ITSELF keeps using the plain component write (real
+    // ids), untouched. `then` still chains via dispatchAction below.
     if (
       action && typeof action === "object" &&
       (action as { type?: string }).type === "setValue" &&
       (action as { values?: { key?: string; value?: unknown }[] }).values?.some(
-        (v) => v.key === "defaultState" && v.value === "inline",
+        (v) => isViewField(v.key) && v.value === "inline",
       )
     ) {
       store.closeSurfaces();
@@ -375,7 +234,7 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
     // data is untouched and re-presents the moment its state is active again.
     // Surfaces never stack; panel combinations cannot exist.
     const claim = node.select?.where;
-    if (claim?.field === "defaultState" && typeof claim.eq === "string" && claim.eq !== surfacedView) {
+    if (isViewField(claim?.field) && typeof claim?.eq === "string" && claim.eq !== surfacedView) {
       return node.fallback ? renderNode(node.fallback, {}, dispatch, theme, key ?? "fallback") : null;
     }
     const pointers = selectPointers(store, node);
@@ -427,8 +286,8 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
             turn.role === "assistant"
               ? turn.components.filter((p) => {
                   const { chatId, nodeId } = store.split(p);
-                  const view = (store.get(chatId, nodeId) as Record<string, unknown> | undefined)?.defaultState;
-                  return typeof view !== "string" || !surfacedViews.has(view);
+                  const view = viewOf(store.get(chatId, nodeId) as Record<string, unknown> | undefined);
+                  return !view || !surfacedViews.has(view);
                 })
               : [];
           // Slot scoped to this turn's UNCLAIMED components (assistant turns only).

package/vendor/sdk/main.tsx

@@ -29,6 +29,13 @@ function render() {
       templateId={current.templateId}
       userId={current.userId}
       conversationId={current.conversationId}
+      // ANALYTICS (UNOVERSE_ANALYTICS.md). Host-supplied: the same bundle boots inside a
+      // customer's page, our own client, and an MCP app host, and it cannot tell which
+      // from in here. A host that says nothing gets `mcp_app_host`, the one surface with
+      // no parent page to report to, so an unconfigured boot reports as the surface where
+      // events go nowhere rather than mislabelling itself as a customer embed.
+      surface={current.surface ?? "mcp_app_host"}
+      analyticsDebug={current.analyticsDebug}
       // Only claim auth when the host actually sent a token. A fabricated accessor on a
       // tokenless boot made the SDK skip its guest-id substitution (connection.tsx), so
       // the session registered a non-guest id and the public-entry gate refused it.