@unoverse-platform/studio 0.1.26 → 0.1.27

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,

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):

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

@@ -0,0 +1,252 @@
+/**
+ * TEMPLATE DERIVATIONS — the pure template-tier brain (framework-agnostic).
+ *
+ * Everything a template "decides" is DERIVED here from the store, never stored:
+ * the active layout (name-sync), the active view (with the pinned/guest-control
+ * law), which pointers a reaction surface selects, which views are claimed, and
+ * the app's declared width. `StreamedUnoverseTemplate` (the React binding) calls
+ * these; a platform port (Flutter/Swift/Kotlin) re-implements its own binding and
+ * calls the SAME derivations — this file IS the port list for the template tier.
+ *
+ * No React, no DOM: these functions read (def, store) and return values. Guarded
+ * by server/tests/sdk/sdk-core-portable.test.ts.
+ */
+import type { ComponentStore } from "./store";
+import type { UnoverseDefinition, UnoverseNode } from "./types";
+
+/**
+ * THE PUBLIC AXIS (STATE_MODEL v2 §2): a component's public state lives in its slice
+ * under `view`; `defaultState` is the read-compatible legacy alias during migration.
+ * Every derivation reads through these two helpers so the alias lives in ONE place.
+ */
+export const viewOf = (slice: Record<string, unknown> | null | undefined): string | undefined => {
+  const v = slice?.view ?? slice?.defaultState;
+  return typeof v === "string" ? v : undefined;
+};
+
+/** Is a `select.where` field the public axis? Accepts both spellings during migration. */
+export const isViewField = (f: unknown): boolean => f === "view" || f === "defaultState";
+
+/**
+ * THE TEMPLATE'S DECLARED ORDER (STATE_MODEL v2 §5 rule 5) — its priority ladder and
+ * arrival-scan order. Served from the manifest's `stateOrder`. Legacy defs without one
+ * fall back to the v1 claim set (layout names + surface claims) with v1 recency
+ * semantics — see resolveActiveView.
+ */
+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);
+  return [...legacy];
+}
+
+/** A width literal is passed through only when it plausibly IS a width (contains a
+ *  digit — "320px", "40%", "calc(...)"). An unresolvable NAME returns undefined so
+ *  it can never emit invalid CSS (or an invalid native constraint). */
+export const cssWidth = (w: unknown): string | undefined => (typeof w === "string" && /\d/.test(w) ? w : undefined);
+
+/** The author's declared prop defaults (def.props[k].default) → a flat data object. Content, not policy. */
+export 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. */
+export 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` on the public axis. One instance renders
+ * in exactly ONE placeholder (STATE_MODEL v2 §5 rule 6): a view a surface shows must
+ * not also render in the flow; a view nothing claims stays in the flow (the fallback).
+ * 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> {
+  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" && 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);
+  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>, def?: UnoverseDefinition | null): 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 (isViewField(claim?.field) && 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: the app = core + the ACTIVE state's panel. The active state
+  // comes from the ONE shared derivation (resolveActiveView) — this function used to
+  // keep its own recency loop, and the two copies diverged once (blank panel); never
+  // re-introduce a private loop here. Pass `def` so the v2 ladder applies; without it
+  // the derivation runs in legacy mode over this tree's surface claims.
+  const active = resolveActiveView(def, store, new Set(surfaces.keys())).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(" + ")})`;
+}
+
+/**
+ * THE TEMPLATE'S STATE OWNS ITS LAYOUT (STATE_MODEL v2 §5 rules 1+4). The active
+ * layout resolves from the active STATE's declaration — `layouts` is keyed by state
+ * name (the same-name convention), falling back to `defaultLayout` when no state is
+ * active. A layout is never addressable on its own. 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);
+  return layouts[view] ?? layouts[def.defaultLayout ?? "main"] ?? def.root;
+}
+
+/**
+ * THE TEMPLATE'S ACTIVE STATE — the ONE derivation every consumer shares.
+ *
+ * v2 (STATE_MODEL §5 rule 5): with a declared `stateOrder` the template walks ITS OWN
+ * order top-down and enters the first of its states that ANY hosted component's view
+ * currently matches. Priority is list position, nothing else; ties within one state
+ * go to the most recent write (`limit: 1` law). Without a `stateOrder` (legacy defs)
+ * the v1 rule applies: latest surfaced view among `validViews` wins.
+ *
+ * PURE PRIORITY (final ruling, 2026-08-09): the ladder alone decides — no pinned
+ * flag, no guest-control override. Order the ladder by PROMINENCE (a state the
+ * guest taps into ranks above the state it came from: focus > detail > rail) and
+ * every interaction resolves by the same walk. Layout choice and surface gating
+ * MUST both read this function — two loops that each derive "the active state"
+ * disagree eventually, and the whole panel goes blank.
+ */
+export function resolveActiveView(
+  def: UnoverseDefinition | null | undefined,
+  store: ComponentStore,
+  validViews?: Set<string>,
+): { view: string; byGuest: boolean } {
+  const order = def?.stateOrder?.length ? def.stateOrder : undefined;
+  const valid = order ? new Set(order) : (validViews ?? new Set(orderedClaims(def)));
+  // One pass over the timeline: the best (latest) match per view.
+  const best = new Map<string, { at: number; byGuest: boolean }>();
+  for (const turn of store.getResponses())
+    for (const p of turn.components) {
+      const { chatId, nodeId } = store.split(p);
+      const v = viewOf(store.get(chatId, nodeId) as Record<string, unknown>);
+      if (!v || !valid.has(v)) continue;
+      const t = store.touchOf(p);
+      const b = best.get(v);
+      if (!b || t > b.at) best.set(v, { at: t, byGuest: store.interactionTouchOf(p) >= t });
+    }
+  if (order) {
+    // THE LADDER: first declared state with any match wins. No word is special.
+    for (const name of order) {
+      const b = best.get(name);
+      if (b) return { view: name, byGuest: b.byGuest };
+    }
+    return { view: "", byGuest: false };
+  }
+  // Legacy recency: the latest matched view wins.
+  let view = "";
+  let byGuest = false;
+  let at = -1;
+  for (const [v, b] of best)
+    if (b.at > at) {
+      at = b.at;
+      view = v;
+      byGuest = b.byGuest;
+    }
+  return { view, byGuest };
+}
+
+/** Resolve a ComponentSlot's `select` against the store → ordered pointers. */
+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 slice = store.get(chatId, nodeId) as Record<string, unknown>;
+      // The public axis reads through the alias (view ?? defaultState); other fields raw.
+      const v = isViewField(field) ? viewOf(slice) : slice[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;
+}

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

@@ -29,7 +29,15 @@ export interface UnoverseNode {
    *  own params, drawn from the data already in scope right here. The SDK only produces
    *  the event; where it goes is the channel's business. */
   analytics?: AnalyticsSpec;
-  placeholder?: string; // Input: empty-field copy (content, not style)
+  placeholder?: string; // Input/Select: empty-field copy (content, not style)
+  /** Input: WHAT THE FIELD IS, handed to the platform (`date`, `tel`, `file`, `url`, …) so
+   *  it offers its own picker or keypad. The same class of generic constraint as
+   *  `maxLength` and `inputMode`: the SDK holds no list of types and no opinion about
+   *  them, and a definition never hand-rolls a calendar out of Boxes. */
+  inputType?: string;
+  /** Select: the closed set to choose from, as `{ value, label }` entries or plain
+   *  strings. Bound via `bind.options`, or literal for a set that never changes. */
+  options?: unknown[];
   /** Box: keep the scroll pinned to the newest content — smooth-scroll to the end when
    *  content grows (new turn or streaming text), unless the user has scrolled up. Generic
    *  scroll-container behavior, opt-in via data (e.g. the conversation state's scroll box). */
@@ -117,16 +125,21 @@ export interface UnoverseDefinition {
    *  microapp has an EMPTY (or absent) props block. */
   props?: Record<string, unknown>;
   /** INTERNAL state + initial values — the keys the component's own actions write
-   *  (step, phase, its defaultState signal). Never external, never workbench controls;
-   *  merged into the render scope beneath the live slice. */
+   *  (step, phase, its `view` on the public axis; `defaultState` is the legacy alias).
+   *  Never external, never workbench controls; merged into the render scope beneath
+   *  the live slice. */
   state?: Record<string, unknown>;
   root: UnoverseNode;
-  /** TEMPLATE LAYOUTS (name-sync, docs/design/05): present only when the template
-   *  ships multiple layouts/ files. Each is a full arrangement; the active one is
-   *  the layout whose NAME matches the latest surfaced component view, falling back
-   *  to `defaultLayout`. Absent → classic single-layout behavior via `root`. */
+  /** TEMPLATE LAYOUTS (STATE_MODEL v2 §5 rule 1): a state OWNS its layout, and this
+   *  map is keyed by STATE NAME (the same-name convention). The active entry is the
+   *  active state's (resolveActiveView → the stateOrder ladder), falling back to
+   *  `defaultLayout`. Absent → classic single-layout behavior via `root`. */
   layouts?: Record<string, UnoverseNode>;
   defaultLayout?: string;
+  /** THE DECLARED STATE ORDER (STATE_MODEL v2 §5 rules 3+5) — the template's priority
+   *  ladder and arrival-scan order, served from the manifest. First entry outranks
+   *  all below it; no name is special. Absent → legacy v1 recency semantics. */
+  stateOrder?: string[];
 }
 
 // ---- The interaction vocabulary (UNOVERSE_SPEC.md §2e-3) ----

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

@@ -0,0 +1,127 @@
+// The ThinkingOrb component. One shared clock (performance.now) keeps
+// every mounted orb in phase; each instance runs its own rAF loop but
+// pauses automatically while offscreen (IntersectionObserver) or when
+// the tab is hidden (visibilitychange). Reduced-motion users get a
+// static representative frame that still follows the live theme.
+
+import { useEffect, useRef } from 'react';
+import { MODE_DRAWS } from './engine/registry';
+import { setInk } from './engine/core';
+import { resolvePreset } from './presets';
+import { useReducedMotion, useResolvedDark } from './theme';
+import type { OrbSize, ThinkingOrbProps } from './types';
+
+const LABELS: Record<string, string> = {
+  working: 'Working…',
+  searching: 'Searching…',
+  solving: 'Solving…',
+  listening: 'Listening…',
+  connecting: 'Connecting…',
+  weaving: 'Weaving…',
+  composing: 'Composing…',
+  breathing: 'Thinking…',
+  shaping: 'Shaping…'
+};
+
+export function ThinkingOrb({
+  state = 'working',
+  size = 64,
+  theme = 'auto',
+  speed = 1,
+  paused = false,
+  ink = null,
+  style,
+  'aria-label': ariaLabel,
+  ...rest
+}: ThinkingOrbProps & { ink?: [number, number, number] | null }) {
+  const ref = useRef<HTMLCanvasElement | null>(null);
+  const dark = useResolvedDark(theme, ref);
+  const reduced = useReducedMotion();
+
+  useEffect(() => {
+    const canvas = ref.current;
+    if (!canvas) return;
+    const dpr = Math.min(2, (typeof devicePixelRatio !== 'undefined' && devicePixelRatio) || 1);
+    canvas.width = Math.round(size * dpr);
+    canvas.height = Math.round(size * dpr);
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+
+    // LOCAL EXTENSION (Unoverse): `size` is any positive number — the canvas and
+    // draw run at the true size (the engine's radiusScale compensates), while the
+    // TUNING snaps to the nearest of the two baked presets (20 inline / 64 avatar).
+    const preset: OrbSize = size <= 32 ? 20 : 64;
+    const { mode, speed: baseSpeed, opts } = resolvePreset(state, preset);
+    const draw = MODE_DRAWS[mode];
+    const effSpeed = baseSpeed * speed;
+
+    const frame = (tSec: number) => {
+      // Ink is a module-level current (frames are synchronous); set per frame so
+      // orbs with different brand tokens on one page never bleed into each other.
+      setInk(ink);
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+      ctx.clearRect(0, 0, size, size);
+      draw(ctx, size, tSec, dark, opts);
+    };
+
+    // reduced motion → one static, deterministic frame
+    if (reduced) {
+      frame(0.6);
+      return;
+    }
+
+    let raf = 0;
+    let running = false;
+    const loop = () => {
+      frame((performance.now() / 1000) * effSpeed);
+      if (running) raf = requestAnimationFrame(loop);
+    };
+    const start = () => {
+      if (running || paused) return;
+      running = true;
+      raf = requestAnimationFrame(loop);
+    };
+    const stop = () => {
+      running = false;
+      cancelAnimationFrame(raf);
+    };
+
+    // draw at least one frame even when paused/offscreen
+    frame((performance.now() / 1000) * effSpeed);
+
+    // pause offscreen + on hidden tabs — free when not visible
+    let visible = true;
+    const io =
+      typeof IntersectionObserver !== 'undefined'
+        ? new IntersectionObserver(([entry]) => {
+            visible = entry.isIntersecting;
+            if (visible && document.visibilityState !== 'hidden') start();
+            else stop();
+          })
+        : null;
+    io?.observe(canvas);
+    const onVis = () => {
+      if (document.visibilityState === 'hidden') stop();
+      else if (visible) start();
+    };
+    document.addEventListener('visibilitychange', onVis);
+    if (!io) start();
+
+    return () => {
+      stop();
+      io?.disconnect();
+      document.removeEventListener('visibilitychange', onVis);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- ink compared by value: a tuple is a fresh identity every render
+  }, [state, size, dark, speed, paused, reduced, ink?.join(",")]);
+
+  return (
+    <canvas
+      ref={ref}
+      role="img"
+      aria-label={ariaLabel ?? LABELS[state]}
+      style={{ width: size, height: size, display: 'block', ...style }}
+      {...rest}
+    />
+  );
+}

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

@@ -0,0 +1,50 @@
+// Braid: three strands plait around the sphere — the "weaving" state.
+// Each strand runs pole to pole on a helix, and a radial breathing term
+// makes them trade places, reading as the over/under of a plait.
+
+import type { Dot, ModeDraw } from './types';
+import { fibDir, frac, makeProj, paint, radiusScale } from './core';
+
+export const drawBraid: ModeDraw = (ctx, size, t, dark, o) => {
+  const cx = size / 2;
+  const cy = size / 2;
+  const R = (size / 2) * 0.76;
+  const pt = makeProj(t * 0.4, 0.3, cx, cy, 1);
+  const rs = radiusScale(size, o.rsPow ?? 0.6);
+
+  const dots: Dot[] = [];
+  const ghostN = o.ghostN ?? 150;
+  for (let i = 0; i < ghostN; i++) {
+    const d = fibDir(i, ghostN);
+    const [px, py, z] = pt(d[0] * R, d[1] * R, d[2] * R);
+    const depth = (z / R + 1) / 2;
+    dots.push({ x: px, y: py, z, r: 0.8 * rs, white: 0.78, a: 0.1 + 0.22 * depth });
+  }
+
+  const strandN = o.strandN ?? 52;
+  const turns = o.turns ?? 3;
+  for (let s = 0; s < 3; s++) {
+    const phase = (s / 3) * 2 * Math.PI;
+    for (let i = 0; i < strandN; i++) {
+      // u walks pole to pole; the frac() drift slides the whole strand along
+      const u = (frac(i / strandN + t * 0.045) * 2 - 1) * 0.96;
+      const surf = Math.sqrt(Math.max(0, 1 - u * u));
+      const endFade = Math.min(1, (1 - Math.abs(u)) / 0.1);
+      const a = u * Math.PI * turns + phase;
+      // radial breathing: strands trade places — the over/under of a plait
+      const weave = 1 + 0.075 * Math.sin(u * Math.PI * turns * 2 + phase * 2 + t * 0.8);
+      const rr = surf * R * weave;
+      const [px, py, zr] = pt(Math.cos(a) * rr, u * R * weave, Math.sin(a) * rr);
+      const depth = (zr / R + 1) / 2;
+      dots.push({
+        x: px,
+        y: py,
+        z: zr,
+        r: ((o.rBase ?? 1.2) + (o.rDepth ?? 1.8) * depth) * rs,
+        white: 0.55 - 0.45 * depth,
+        a: endFade * (0.45 + 0.55 * depth)
+      });
+    }
+  }
+  paint(ctx, dots, dark, o.rMin);
+};