@unoverse-platform/studio 0.1.102 → 0.1.104

package/vendor/sdk/lib/dom/region.ts

@@ -0,0 +1,195 @@
+/**
+ * A REGION: a part of the page whose shape is worked out from the store on every update (what
+ * a slot holds, a place, a mounted template, the conversation). It is described as data, a
+ * `Region`, and a region view brings the page to that description, keeping whatever it can:
+ * a component that stays in the list keeps its elements, and a tree that keeps its key is
+ * updated in place.
+ */
+import type { UnoverseNode } from "../core/types";
+import type { CssStyle } from "../style";
+import { setChildren, setStyle } from "./element";
+import { renderNode } from "./render";
+import type { Data, RenderCtx, View } from "./types";
+
+/** Something a region holds whole (a component instance): its elements, and its end. */
+export interface Leaf {
+  readonly nodes: Node[];
+  destroy(): void;
+}
+
+/** What a slot inside a tree draws, worked out from the node and its data. */
+export type SlotCompute = (node: UnoverseNode, data: Data) => Region;
+
+export type Region =
+  | { kind: "none" }
+  /** A definition subtree, drawn with these facts; its slots are worked out by `slot`. */
+  | { kind: "tree"; key: string; node: UnoverseNode; data: Data; ctx: Pick<RenderCtx, "theme" | "onAction" | "defs">; slot?: SlotCompute }
+  /** Instances by key. `flip`: each sits in a measuring box and slides when the order changes. */
+  | { kind: "list"; key: string; flip: boolean; items: { key: string; make(): Leaf; refresh(leaf: Leaf): void }[] }
+  /** A plain box around regions. */
+  | { kind: "box"; key: string; style: CssStyle; parts: Region[] }
+  /** Elements the host made (a host's own chrome). */
+  | { kind: "nodes"; key: string; nodes: Node[] };
+
+const NONE: Region = { kind: "none" };
+
+export interface RegionView {
+  readonly nodes: Node[];
+  set(region: Region): void;
+  destroy(): void;
+}
+
+/** A slot whose content is a region, worked out again on every update. */
+function slotView(doc: Document, mounted: RenderCtx["mounted"], holder: { slot?: SlotCompute }, node: UnoverseNode, data: Data): View {
+  const rv = regionView(doc, mounted);
+  const view: View = {
+    get nodes() {
+      return rv.nodes;
+    },
+    update(n, d) {
+      rv.set(holder.slot ? holder.slot(n, d) : NONE);
+    },
+    destroy: () => rv.destroy(),
+  };
+  view.update(node, data);
+  return view;
+}
+
+export function regionView(doc: Document, mounted: RenderCtx["mounted"]): RegionView {
+  let current: Region = NONE;
+  let destroyCurrent = () => {};
+  let nodesOf = (): Node[] => [];
+  let updateCurrent: (r: Region) => void = () => {};
+
+  const build = (r: Region) => {
+    destroyCurrent();
+    current = r;
+    switch (r.kind) {
+      case "none":
+        nodesOf = () => [];
+        destroyCurrent = () => {};
+        updateCurrent = () => {};
+        return;
+      case "nodes": {
+        let nodes = r.nodes;
+        nodesOf = () => nodes;
+        destroyCurrent = () => {};
+        updateCurrent = (n) => void (nodes = (n as Extract<Region, { kind: "nodes" }>).nodes);
+        return;
+      }
+      case "tree": {
+        const holder: { slot?: SlotCompute } = { slot: r.slot };
+        const ctx: RenderCtx = { doc, mounted, ...r.ctx };
+        // A slot exists only while the region names how to fill it.
+        const withSlot = () => (ctx.slot = holder.slot ? (n, d) => slotView(doc, mounted, holder, n, d) : undefined);
+        withSlot();
+        const view = renderNode(r.node, r.data, ctx);
+        nodesOf = () => view.nodes;
+        destroyCurrent = () => view.destroy();
+        updateCurrent = (n) => {
+          const t = n as Extract<Region, { kind: "tree" }>;
+          Object.assign(ctx, t.ctx);
+          holder.slot = t.slot;
+          withSlot();
+          view.update(t.node, t.data);
+        };
+        return;
+      }
+      case "box": {
+        const el = doc.createElement("div");
+        const parts: RegionView[] = [];
+        nodesOf = () => [el];
+        destroyCurrent = () => parts.forEach((p) => p.destroy());
+        updateCurrent = (n) => {
+          const b = n as Extract<Region, { kind: "box" }>;
+          setStyle(el, b.style);
+          b.parts.forEach((p, i) => (parts[i] ??= regionView(doc, mounted)).set(p));
+          for (const p of parts.splice(b.parts.length)) p.destroy();
+          setChildren(el, parts.flatMap((p) => p.nodes));
+        };
+        updateCurrent(r);
+        return;
+      }
+      case "list": {
+        const leaves = new Map<string, { leaf: Leaf; box?: HTMLDivElement }>();
+        let order: string[] = [];
+        let flip = r.flip;
+        // FLIP: what was where, by key, to slide a reorder from.
+        const positions = new Map<string, { left: number; top: number }>();
+        let lastOrder = "";
+        const slide = () => {
+          const nextOrder = order.join(" ");
+          // The guest's reduce-motion setting wins: reorders land instantly.
+          const reduced = typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+          // ANIMATE ONLY A REORDER: chrome growing above or a scroll shifts every position a
+          // little, and playing that back made cards wobble while the guest typed.
+          const moved = !reduced && lastOrder !== "" && lastOrder !== nextOrder;
+          for (const key of order) {
+            const box = leaves.get(key)?.box;
+            if (!box) continue;
+            const pos = { left: box.offsetLeft, top: box.offsetTop };
+            const prev = positions.get(key);
+            positions.set(key, pos);
+            const dx = prev && moved ? prev.left - pos.left : 0;
+            const dy = prev && moved ? prev.top - pos.top : 0;
+            if (dx || dy) {
+              box.style.transition = "none";
+              box.style.transform = `translate(${dx}px, ${dy}px)`;
+              requestAnimationFrame(() => {
+                box.style.transition = "transform 240ms ease";
+                box.style.transform = "";
+              });
+            }
+          }
+          for (const key of positions.keys()) if (!leaves.has(key)) positions.delete(key);
+          lastOrder = nextOrder;
+        };
+        nodesOf = () => order.flatMap((k) => {
+          const e = leaves.get(k)!;
+          return e.box ? [e.box] : e.leaf.nodes;
+        });
+        destroyCurrent = () => leaves.forEach((e) => e.leaf.destroy());
+        updateCurrent = (n) => {
+          const l = n as Extract<Region, { kind: "list" }>;
+          flip = l.flip;
+          const keep = new Set(l.items.map((i) => i.key));
+          for (const [k, e] of leaves) if (!keep.has(k)) {
+            e.leaf.destroy();
+            leaves.delete(k);
+          }
+          for (const item of l.items) {
+            let e = leaves.get(item.key);
+            if (!e) {
+              e = { leaf: item.make() };
+              leaves.set(item.key, e);
+            } else item.refresh(e.leaf);
+            if (flip) {
+              e.box ??= doc.createElement("div");
+              setChildren(e.box, e.leaf.nodes);
+            } else e.box = undefined;
+          }
+          order = l.items.map((i) => i.key);
+          if (flip) mounted(slide);
+        };
+        updateCurrent(r);
+        return;
+      }
+    }
+  };
+
+  return {
+    get nodes() {
+      return nodesOf();
+    },
+    set(r) {
+      if (r.kind === current.kind && (r.kind === "none" || (r as { key: string }).key === (current as { key: string }).key)) updateCurrent(r);
+      else build(r);
+    },
+    destroy() {
+      destroyCurrent();
+      current = NONE;
+      nodesOf = () => [];
+      destroyCurrent = () => {};
+    },
+  };
+}

package/vendor/sdk/lib/dom/render.ts

@@ -0,0 +1,177 @@
+/**
+ * ════════════════════════════════════════════════════════════════════════════
+ *  THE DISPATCHER, IN PLAIN DOM: UnoverseNode → View.   ⛔ NO REACT ⛔
+ * ════════════════════════════════════════════════════════════════════════════
+ *
+ *  This file draws nothing. It walks the tree and hands each node to one primitive in
+ *  ./primitives (or ./markdown), deciding exactly what ../render.tsx decides: visibleWhen,
+ *  skeleton, appWidth, Ref, Switch, Each and the slot types. A raw element belongs in a
+ *  primitive, never here.
+ *
+ *  A node's View is built once and updated in place. When an update changes WHAT a node
+ *  draws (a Switch branch of another type, a node that hides), its primitive is replaced;
+ *  otherwise the same elements are kept, so focus, scroll and a half-typed draft survive.
+ *
+ *  The two laws hold here as in the whole SDK: own zero style values (every value is
+ *  served), own zero UX shape (a composite is a definition, never a primitive).
+ * ════════════════════════════════════════════════════════════════════════════
+ */
+import type { UnoverseNode } from "../core/types";
+import { visible, selectCase } from "../core/conditions";
+import { cssWidth } from "../core/apps";
+import { resolveRef } from "../core/refs";
+import { boxView, buttonView, iconView, imageView, inputView, orbView, selectView, skeletonView, textView, unknownView, type Prim } from "./primitives";
+import { markdownView } from "./markdown";
+import type { Data, RenderCtx, View } from "./types";
+
+type Kind = "none" | "skeleton-box" | "Skeleton" | "Icon" | "Orb" | "Input" | "Markdown" | "slot" | "box" | "Text" | "Image" | "Select" | "Button" | "Unknown";
+
+const SLOT_TYPES = new Set(["ComponentSlot", "Timeline", "Template", "Place"]);
+// The places whose `appWidth` sizes their FRAME (the app draws it), not a box of their own.
+const FRAMED_PLACES = new Set(["ComponentSlot", "Template", "Place"]);
+const BOX_TYPES = new Set(["Box", "Stack", "Row", "Column", "Each"]);
+
+/** What a node draws, after its visibility, its loading state, its references and its branch. */
+function resolve(node: UnoverseNode, data: Data, ctx: RenderCtx): { kind: Kind; node: UnoverseNode; variant?: string } {
+  for (;;) {
+    // visibleWhen: a bare field is a truthiness test, an object a Condition (core/conditions.ts).
+    if (node.visibleWhen != null && !visible(node.visibleWhen, data)) return { kind: "none", node };
+    // `skeleton: true`: while the bound field has no data, its ghost inside the node's own box.
+    if (node.skeleton) {
+      const field = node.bind?.value ?? node.bind?.src ?? node.bind?.items;
+      if (field && !visible(field, data)) {
+        const variant = node.type === "Image" ? "image" : node.type === "Each" ? "card" : "text";
+        return { kind: "skeleton-box", node, variant };
+      }
+    }
+    // STATE-OWNED SIZING: a plain node's `appWidth` fixes the panel's box. Slot places keep
+    // theirs, since it applies to their frame.
+    const panelW = (node as { appWidth?: string }).appWidth;
+    if (panelW && !FRAMED_PLACES.has(node.type)) {
+      const w = cssWidth(ctx.theme.appSize?.[panelW] ?? panelW);
+      if (w) node = { ...node, appWidth: undefined, style: { ...(node.style ?? {}), width: w, flex: "0 0 auto" } } as UnoverseNode;
+    }
+    if (node.type === "Ref") {
+      // REFERENCE, NOT COPY (core/refs.ts). An unknown name draws nothing.
+      const resolved = resolveRef(node, ctx.defs?.[String((node as { ref?: string }).ref ?? "")]);
+      if (!resolved) return { kind: "none", node };
+      node = resolved;
+      continue;
+    }
+    if (node.type === "Switch") {
+      // Exactly one branch, the case matching `data[on]`; no wrapper element.
+      const branch = selectCase(node, data);
+      if (!branch) return { kind: "none", node };
+      node = branch;
+      continue;
+    }
+    if (SLOT_TYPES.has(node.type)) return { kind: ctx.slot ? "slot" : "none", node };
+    if (BOX_TYPES.has(node.type)) return { kind: "box", node };
+    switch (node.type) {
+      case "Skeleton":
+      case "Icon":
+      case "Orb":
+      case "Input":
+      case "Markdown":
+      case "Text":
+      case "Image":
+      case "Select":
+      case "Button":
+        return { kind: node.type, node };
+      default:
+        return { kind: "Unknown", node };
+    }
+  }
+}
+
+/** Where an `Each` item sits, and the item itself as the scope (a non-object item is `value`). */
+const scopeOf = (item: unknown, i: number): Data => {
+  const base = { index: i, position: i + 1 };
+  return item != null && typeof item === "object" && !Array.isArray(item) ? { ...base, ...(item as Data) } : { ...base, value: item };
+};
+
+const PRIMS: Partial<Record<Kind, (ctx: RenderCtx) => Prim>> = {
+  Skeleton: skeletonView,
+  Icon: iconView,
+  Orb: orbView,
+  Input: inputView,
+  Markdown: markdownView,
+  box: boxView,
+  "skeleton-box": boxView,
+  Text: textView,
+  Image: imageView,
+  Select: selectView,
+  Button: buttonView,
+  Unknown: unknownView,
+};
+
+/** Draw one definition node: the View for it, already filled with `data`. */
+export function renderNode(node: UnoverseNode, data: Data, ctx: RenderCtx): View {
+  let kind: Kind | null = null;
+  let prim: Prim | null = null;
+  let slot: View | null = null;
+  let ghost: ReturnType<typeof skeletonView> | null = null;
+  const kids: View[] = [];
+
+  const clear = () => {
+    prim?.destroy();
+    slot?.destroy();
+    for (const k of kids.splice(0)) k.destroy();
+    prim = slot = ghost = null;
+  };
+
+  /** Bring the children up to `specs`, by position. */
+  const fillKids = (specs: [UnoverseNode, Data][]): Node[] => {
+    specs.forEach(([n, d], i) => {
+      if (kids[i]) kids[i].update(n, d);
+      else kids[i] = renderNode(n, d, ctx);
+    });
+    for (const k of kids.splice(specs.length)) k.destroy();
+    return kids.flatMap((k) => k.nodes);
+  };
+
+  const view: View = {
+    get nodes() {
+      return slot ? slot.nodes : (prim?.nodes ?? []);
+    },
+    update(n0, data) {
+      const r = resolve(n0, data, ctx);
+      if (r.kind !== kind) {
+        clear();
+        kind = r.kind;
+        if (kind === "slot") slot = ctx.slot!(r.node, data);
+        else prim = PRIMS[kind]?.(ctx) ?? null;
+        if (kind === "skeleton-box") ghost = skeletonView(ctx);
+      } else if (kind === "slot") slot?.update(r.node, data);
+      const n = r.node;
+      switch (kind) {
+        case "none":
+        case "slot":
+          return;
+        case "skeleton-box":
+          ghost!.variant(r.variant);
+          prim!.update({ type: "Box", style: n.style } as UnoverseNode, data, ghost!.nodes);
+          return;
+        case "box": {
+          if (n.type === "Each") {
+            // Literal `items` is the fallback for a static list in the definition; bind wins.
+            const src = n.bind?.items ? data[n.bind.items] : n.items;
+            const items = Array.isArray(src) ? src : [];
+            const tpl = typeof n.item === "object" ? n.item : undefined;
+            prim!.update(n, data, tpl ? fillKids(items.map((item, i) => [tpl, scopeOf(item, i)])) : fillKids([]));
+          } else prim!.update(n, data, fillKids((n.children ?? []).map((c) => [c, data])));
+          return;
+        }
+        case "Button":
+        case "Unknown":
+          prim!.update(n, data, fillKids(kind === "Button" && !n.children?.length ? [] : (n.children ?? []).map((c) => [c, data])));
+          return;
+        default:
+          prim!.update(n, data);
+      }
+    },
+    destroy: clear,
+  };
+  view.update(node, data);
+  return view;
+}

package/vendor/sdk/lib/dom/theme.ts

@@ -0,0 +1,38 @@
+/**
+ * The theme, fetched from the server by name (the SDK owns zero token values), and its
+ * webfonts registered in the document.
+ */
+import type { ResolvedTheme } from "../core/types";
+
+/** What reads a theme: the MCP client, or anything that answers the same call. */
+export interface ThemeSource {
+  readTheme(name: string): Promise<ResolvedTheme>;
+}
+
+/**
+ * Ensure the theme's webfont stylesheets are loaded ONCE in the document head.
+ * `theme.fonts` is SERVED DATA (`fonts.stylesheets` in an org's styles) — the SDK
+ * authors no font choices, it just registers what the server serves. Fonts must live
+ * at document level: a shadow root cannot register @font-face, but faces declared in
+ * the document apply inside shadow trees via the font cascade.
+ */
+export function ensureFontStylesheets(theme: ResolvedTheme | null, doc: Document | undefined = typeof document !== "undefined" ? document : undefined): void {
+  if (!theme?.fonts?.length || !doc) return;
+  for (const href of theme.fonts) {
+    if (doc.head.querySelector(`link[data-unoverse-font="${CSS.escape(href)}"]`)) continue;
+    const link = doc.createElement("link");
+    link.rel = "stylesheet";
+    link.href = href;
+    link.setAttribute("data-unoverse-font", href);
+    doc.head.appendChild(link);
+  }
+}
+
+/** The named theme; an unknown name falls back to the neutral `light`, so a pack without a
+ *  theme still renders. */
+export function fetchTheme(client: ThemeSource, name: string): Promise<ResolvedTheme> {
+  return client.readTheme(name).catch((e) => {
+    if (name === "light") throw e;
+    return client.readTheme("light");
+  });
+}

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

@@ -0,0 +1,36 @@
+/**
+ * The plain-DOM renderer's two shapes: a View (what a node puts on the page) and the render
+ * context passed down the walk (the theme, the action handler, slots, shared pieces).
+ */
+import type { ResolvedTheme, UnoverseNode } from "../core/types";
+import type { ActionHandler } from "../actions";
+
+export type Data = Record<string, unknown>;
+
+/** What one definition node puts on the page, kept up to date in place. */
+export interface View {
+  /** The DOM nodes this view puts in its parent, in order: none while hidden. */
+  readonly nodes: Node[];
+  update(node: UnoverseNode, data: Data): void;
+  destroy(): void;
+}
+
+/** Fills a `ComponentSlot`, `Timeline`, `Template` or `Place` (the page layer, step 3). */
+export type SlotResolver = (node: UnoverseNode, data: Data) => View | null;
+
+/** A parsed markdown element: a tag, its props and its children, or a run of text. */
+export type MarkdownTree = string | { tag: string; props: Record<string, unknown>; children: MarkdownTree[] };
+
+export interface RenderCtx {
+  doc: Document;
+  theme: ResolvedTheme;
+  onAction?: ActionHandler;
+  slot?: SlotResolver;
+  /** The shared pieces a definition references by name (`Ref`). */
+  defs?: Record<string, UnoverseNode>;
+  /**
+   * Work that needs the element on the page (measuring, observers, the orb's drawing). Run by
+   * whoever puts the view on the page, once it is there.
+   */
+  mounted(fn: () => void): void;
+}

package/vendor/sdk/lib/index.ts

@@ -1,20 +1,29 @@
-export { UnoverseComponent } from "./UnoverseComponent";
-export type { UnoverseComponentProps } from "./UnoverseComponent";
-export { StreamedUnoverseComponent, useUnoverseInstance } from "./streamed";
-export type { StreamedUnoverseComponentProps } from "./streamed";
-export { StreamedUnoverseApp, INERT_VOICE, selectPointers, computeAppWidth, resolveActiveLayout } from "./app";
-export type { StreamedUnoverseAppProps } from "./app";
-export { renderNode, styleToCss, keyframesCss } from "./render";
-export type { ActionHandler, ActionMeta, SlotResolver } from "./render";
-export { useUnoverseTheme } from "./theme";
-export { IsolatedRoot } from "./isolate";
-export { useUnoverseConnection } from "./connection";
-export type { UnoverseConnectionConfig, UnoverseSessionParams, UnoverseConnection } from "./connection";
-// The `voice` native service (UNOVERSE_SPEC §2e-1 Tier-3). Channel-instantiated; its
-// neutral state is spread into a `service: "voice"` template's scope, its actions
-// dispatched from the template. Audio rides the /ws/gravity WS lane (§5), not MCP.
-export { useVoiceService } from "./voice";
-export type { UseVoiceServiceConfig, VoiceService, VoiceServiceState, VoiceSession, VoiceConnectionStatus } from "./voice";
+/**
+ * The Unoverse SDK's public API. ⛔ NO REACT (web/sdk/CLAUDE.md): screens are data, drawn by
+ * plain DOM. A React host wraps these itself (packages/studio/screens/react/unoverse.tsx).
+ */
+// Drawing: one component, an app or template, and the definition walk itself.
+export { mountComponent } from "./dom/component";
+export type { ComponentMount, ComponentOptions, DefinitionSource } from "./dom/component";
+export { mountApp } from "./dom/app";
+export type { AppMount, AppOptions, VoiceVerbs } from "./dom/app";
+export { renderNode } from "./dom/render";
+export type { View, RenderCtx, SlotResolver } from "./dom/types";
+export { parseMarkdown } from "./dom/markdownParse";
+export { styleToCss, keyframesCss, cssDecls } from "./style";
+export type { CssStyle } from "./style";
+export { nodeAction } from "./actions";
+export type { ActionHandler, ActionMeta } from "./actions";
+export { fetchTheme, ensureFontStylesheets } from "./dom/theme";
+// The live connection (the data plane, §5b).
+export { openConnection, sessionUserId, resolveGuestId } from "./dom/connection";
+export type { UnoverseConnection, UnoverseConnectionConfig, UnoverseSessionParams, ConnectionStatus, ConnectionOptions } from "./dom/connection";
+// The `voice` native service (UNOVERSE_SPEC §2e-1 Tier-3). Its neutral state is spread into a
+// `service: "voice"` template's scope; audio rides the /ws/gravity WS lane (§5), not MCP.
+export { createVoiceService } from "./voiceService";
+export type { VoiceService, VoiceServiceConfig, VoiceServiceState, VoiceSession, VoiceConnectionStatus, VoiceCallState, StartCall } from "./voiceService";
+// The pure template derivations a host reads (app width, the active layout).
+export { selectPointers, computeAppWidth, resolveActiveLayout } from "./core/apps";
 // Re-export core's FULL public API. core is BUNDLED into this package (tsup noExternal), so
 // consumers import EVERYTHING from `@unoverse/sdk` and never depend on a
 // separate `-core` install — eliminating react↔core version/export drift entirely. EXPLICIT

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

@@ -0,0 +1,139 @@
+// The orb on a canvas, in plain DOM. One shared clock (performance.now) keeps every orb in
+// phase; each runs its own rAF loop, paused while offscreen (IntersectionObserver) or while
+// the tab is hidden. Reduced-motion users get one static frame that still follows the theme.
+// The theme is the explicit one, else an ancestor's data-theme/.dark|.light (watched live),
+// else prefers-color-scheme (subscribed live).
+
+import { MODE_DRAWS } from './engine/registry';
+import { setInk } from './engine/core';
+import { resolvePreset } from './presets';
+import type { OrbSize, OrbState, OrbTheme } from './states';
+
+export type { OrbState, OrbTheme } from './states';
+
+export function ancestorTheme(el: Element | null): boolean | null {
+  let node: Element | null = el;
+  while (node) {
+    const attr = node.getAttribute('data-theme');
+    if (attr === 'dark') return true;
+    if (attr === 'light') return false;
+    if (node.classList.contains('dark')) return true;
+    if (node.classList.contains('light')) return false;
+    node = node.parentElement;
+  }
+  return null;
+}
+
+export function systemDark(): boolean {
+  return typeof matchMedia === 'undefined' || matchMedia('(prefers-color-scheme: dark)').matches;
+}
+
+export interface OrbOptions {
+  state: OrbState;
+  /** Any positive size: the canvas draws at it, the tuning snaps to the nearest preset (20 / 64). */
+  size: number;
+  speed: number;
+  theme: OrbTheme;
+  ink: [number, number, number] | null;
+}
+
+/** Start drawing on a canvas that is on the page; returns the stop. */
+export function startOrb(canvas: HTMLCanvasElement, o: OrbOptions): () => void {
+  let stopDraw = () => {};
+  const resolveDark = () => (o.theme === 'dark' ? true : o.theme === 'light' ? false : (ancestorTheme(canvas) ?? systemDark()));
+  const reducedMq = typeof matchMedia !== 'undefined' ? matchMedia('(prefers-reduced-motion: reduce)') : null;
+  let dark = resolveDark();
+  let reduced = reducedMq?.matches ?? false;
+
+  const draw = () => {
+    stopDraw();
+    stopDraw = drawLoop(canvas, o, dark, reduced);
+  };
+  draw();
+
+  const redraw = () => {
+    const d = resolveDark();
+    const r = reducedMq?.matches ?? false;
+    if (d === dark && r === reduced) return;
+    dark = d;
+    reduced = r;
+    draw();
+  };
+  reducedMq?.addEventListener('change', redraw);
+  const schemeMq = o.theme === 'auto' && typeof matchMedia !== 'undefined' ? matchMedia('(prefers-color-scheme: dark)') : null;
+  schemeMq?.addEventListener('change', redraw);
+  // App-level toggles: class/data-theme flips on ancestors.
+  let mo: MutationObserver | null = null;
+  if (o.theme === 'auto' && typeof MutationObserver !== 'undefined') {
+    mo = new MutationObserver(redraw);
+    mo.observe(document.documentElement, { attributes: true, attributeFilter: ['class', 'data-theme'], subtree: true });
+  }
+  return () => {
+    stopDraw();
+    reducedMq?.removeEventListener('change', redraw);
+    schemeMq?.removeEventListener('change', redraw);
+    mo?.disconnect();
+  };
+}
+
+function drawLoop(canvas: HTMLCanvasElement, o: OrbOptions, dark: boolean, reduced: boolean): () => void {
+  const { size } = o;
+  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 () => {};
+  const preset: OrbSize = size <= 32 ? 20 : 64;
+  const { mode, speed: baseSpeed, opts } = resolvePreset(o.state, preset);
+  const paint = MODE_DRAWS[mode];
+  const effSpeed = baseSpeed * o.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(o.ink);
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    ctx.clearRect(0, 0, size, size);
+    paint(ctx, size, tSec, dark, opts);
+  };
+  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) return;
+    running = true;
+    raf = requestAnimationFrame(loop);
+  };
+  const stop = () => {
+    running = false;
+    cancelAnimationFrame(raf);
+  };
+  frame((performance.now() / 1000) * effSpeed);
+  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);
+  };
+}

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

@@ -1,20 +1,10 @@
 /**
- * The Orb primitive's drawing engine — VENDORED from `thinking-orbs`
- * (https://github.com/Jakubantalik/thinking-orbs, MIT © 2026 Jakub Antalik),
- * with two LOCAL EXTENSIONS, each marked at its site: free numeric `size`
- * (tuning snaps to the nearest baked preset — ThinkingOrb.tsx) and a brand
- * `ink` the painters tint toward, fed from the served `color` token
- * (engine/core.ts setInk). Nine hand-tuned "assistant is doing something" animations,
- * drawn procedurally on a plain 2D canvas — no WebGL, no filters — which is
- * what makes the spec portable: each native SDK (iOS/Compose/Flutter/RN)
- * reimplements the same draw loops with its platform's own 2D canvas.
- *
- * This is the sanctioned shape for rich motion (the SkeletonView precedent):
- * the SDK owns ONE generic draw behavior; every authoring decision — which
- * state, what size, what speed — stays DATA in the definition (`type: Orb`).
- * Keyframe animations (styles/semantic/keyframes) remain the tool for
- * element motion; the Orb is for pictures computed per-frame, which keyframe
- * interpolation cannot express (no per-frame math, no depth occlusion).
+ * The Orb primitive's drawing engine, VENDORED from `thinking-orbs`
+ * (https://github.com/Jakubantalik/thinking-orbs, MIT © 2026 Jakub Antalik), with two LOCAL
+ * EXTENSIONS, each marked at its site: free numeric `size` (tuning snaps to the nearest baked
+ * preset, canvas.ts) and a brand `ink` the painters tint toward, fed from the served `color`
+ * token (engine/core.ts setInk). Drawn procedurally on a plain 2D canvas, no WebGL, so each
+ * native SDK can reimplement the same draw loops on its platform's own canvas.
  */
-export { ThinkingOrb } from "./ThinkingOrb";
-export type { ThinkingOrbProps, OrbState, OrbSize, OrbTheme } from "./types";
+export { startOrb, type OrbOptions } from "./canvas";
+export type { OrbState, OrbSize, OrbTheme } from "./states";