@unoverse-platform/studio 0.1.26 → 0.1.28

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

@@ -0,0 +1,270 @@
+/**
+ * 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 ?? {}));
+  const defs = def?.defs as Record<string, unknown> | undefined;
+  if (def?.layouts) for (const l of Object.values(def.layouts)) collectSurfacedViews(l, legacy, defs);
+  else if (def?.root) collectSurfacedViews(def.root, legacy, defs);
+  return [...legacy];
+}
+
+/** 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(), defs?: Record<string, unknown>): Set<string> {
+  if (Array.isArray(node)) {
+    for (const n of node) collectSurfacedViews(n, out, defs);
+    return out;
+  }
+  if (!node || typeof node !== "object") return out;
+  const n = node as Record<string, unknown>;
+  // A REFERENCED definition is a GRAPH, so a structural walk has to follow the edges. The
+  // chrome shared by four arrangements travels once, and the slots that claim views live
+  // INSIDE it — stopping at the reference would report that nothing claims anything, and
+  // every surfaced component would fall back into the flow.
+  if (n.type === "Ref" && typeof n.ref === "string") {
+    const piece = defs?.[n.ref];
+    if (piece) collectSurfacedViews(piece, out, defs);
+    return out;
+  }
+  const sel = n.select as { where?: { field?: string; eq?: unknown } } | undefined;
+  if (n.type === "ComponentSlot" && isViewField(sel?.where?.field) && typeof sel?.where?.eq === "string") {
+    out.add(sel.where.eq);
+  }
+  for (const v of Object.values(n)) if (v && typeof v === "object") collectSurfacedViews(v, out, defs);
+  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; ref?: string; select?: { where?: { field?: string; eq?: unknown } } };
+    // Follow references: the width-bearing panels of a referenced form live inside the
+    // shared pieces, so stopping here would size the app from the arrangement's skeleton
+    // alone (see collectSurfacedViews for the same reason, stated once).
+    if (n.type === "Ref" && typeof n.ref === "string") {
+      const piece = (def?.defs as Record<string, unknown> | undefined)?.[n.ref];
+      if (piece) walk(piece);
+      return;
+    }
+    if (n !== r) {
+      if (n.type === "ComponentSlot") {
+        const claim = n.select?.where;
+        // `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). */
@@ -113,20 +121,32 @@ export interface UnoverseDefinition {
    *  theme (`unoverse://theme/{org}/light`). Universal components carry no org. */
   org?: string;
   description?: string;
+  /**
+   * REFERENCE, DON'T COPY: the shared pieces this definition NAMES, by ref name, each
+   * shipped once instead of pasted at every use. Present only when the definition was
+   * read as `<uri>@refs`; the bare URI still serves fully inlined trees, so a renderer
+   * without `Ref` support is never handed one it cannot draw.
+   */
+  defs?: Record<string, UnoverseNode>;
   /** EXTERNAL contract — the rare workflow-fed inputs (`input: true`). A contained
    *  microapp has an EMPTY (or absent) props block. */
   props?: Record<string, unknown>;
   /** 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,131 @@
+// 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…',
+  halo: 'Waiting…',
+  sonar: 'Listening…',
+  shimmer: 'Thinking…',
+  pulse: 'Responding…'
+};
+
+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);
+};

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

@@ -0,0 +1,167 @@
+// Shared primitives for the dotted 3D thought-orbs. Ported from inkform
+// (PlotterLab's HalftoneSphere lineage): honestly 3D — rotated,
+// depth-shaded, z-sorted. Depth is carried by dot size and ink weight
+// alone. Plain 2D canvas fills only: no ctx.filter, no SVG filters, so
+// every mode renders identically in Chrome, Safari and Firefox.
+
+export interface Dot {
+  x: number;
+  y: number;
+  z: number;
+  r: number;
+  /** Ink value: 0 = darkest ink on paper. Mirrored on dark themes. */
+  white: number;
+  a?: number;
+}
+
+/** A stroked edge between two projected points (the `connecting` web). */
+export interface Line {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  /** Ink value, same convention as `Dot.white`. */
+  white: number;
+  a?: number;
+  w: number;
+}
+
+export type Projector = (x: number, y: number, z: number) => [number, number, number];
+
+export function lerp(a: number, b: number, f: number): number {
+  return a + (b - a) * f;
+}
+
+export function frac(x: number): number {
+  return x - Math.floor(x);
+}
+
+/** Value noise on a 2D lattice — smooth, deterministic, cheap. */
+export function vnoise(x: number, y: number): number {
+  const xi = Math.floor(x);
+  const yi = Math.floor(y);
+  let fx = x - xi;
+  let fy = y - yi;
+  fx = fx * fx * (3 - 2 * fx);
+  fy = fy * fy * (3 - 2 * fy);
+  const a = hashD(xi, yi);
+  const b = hashD(xi + 1, yi);
+  const c = hashD(xi, yi + 1);
+  const d = hashD(xi + 1, yi + 1);
+  return a + (b - a) * fx + (c - a) * fy + (a - b - c + d) * fx * fy;
+}
+
+/** Deterministic hash in [0, 1). */
+export function hashD(a: number, b: number): number {
+  const h = Math.sin(a * 12.9898 + b * 78.233) * 43758.5453;
+  return h - Math.floor(h);
+}
+
+/** Stable directions on a unit sphere (Fibonacci lattice). */
+export function fibDir(i: number, n: number): [number, number, number] {
+  const golden = Math.PI * (3 - Math.sqrt(5));
+  const y = 1 - (2 * (i + 0.5)) / n;
+  const rad = Math.sqrt(1 - y * y);
+  const a = i * golden;
+  return [rad * Math.cos(a), y, rad * Math.sin(a)];
+}
+
+/** Shortest signed angular distance, wrapped to (-π, π]. */
+export function angleDelta(a: number, b: number): number {
+  return Math.atan2(Math.sin(a - b), Math.cos(a - b));
+}
+
+/** Shared spin + tilt + orthographic projection. */
+export function makeProj(yaw: number, tilt: number, cx: number, cy: number, scale: number): Projector {
+  const st = Math.sin(tilt);
+  const ct = Math.cos(tilt);
+  const sy = Math.sin(yaw);
+  const cyw = Math.cos(yaw);
+  return (x, y, z) => {
+    const x1 = x * cyw + z * sy;
+    const z1 = -x * sy + z * cyw;
+    const y1 = y * ct - z1 * st;
+    const z2 = y * st + z1 * ct;
+    return [cx + x1 * scale, cy - y1 * scale, z2];
+  };
+}
+
+/**
+ * LOCAL EXTENSION (Unoverse): an optional brand INK the painters tint toward.
+ * The upstream engine paints matte grayscale only; the design system's LAW 1
+ * says every colour is a served token, so the host resolves its `color` token
+ * and hands the rgb here before each frame. null = the upstream neutral ink.
+ * A module-level current-ink is safe because frames draw synchronously.
+ */
+let INK: [number, number, number] | null = null;
+export function setInk(rgb: [number, number, number] | null): void {
+  INK = rgb;
+}
+/** Depth-shaded channel: neutral grayscale, or the ink mixed toward the substrate. */
+function shade(w: number, dark: boolean): [number, number, number] {
+  if (!INK) {
+    const g = Math.round((dark ? 1 - w : w) * 255);
+    return [g, g, g];
+  }
+  // Light substrate: near dots (w→0) are pure ink, far dots fade to paper.
+  // Dark substrate: the ink is pre-lightened so it pops, far dots fade to black.
+  const [r, g, b] = INK;
+  const mixTo = dark ? 0 : 255;
+  const base: [number, number, number] = dark
+    ? [r + (255 - r) * 0.35, g + (255 - g) * 0.35, b + (255 - b) * 0.35]
+    : [r, g, b];
+  return [0, 1, 2].map((i) => Math.round(base[i] + (mixTo - base[i]) * w)) as [number, number, number];
+}
+
+/**
+ * LOCAL (Unoverse): the shaded ink as a CSS colour, for modes that STROKE rather than
+ * stipple (engine/rings). Same depth language as `paint` — `white` 0 is full ink, 1 is
+ * the substrate — so a stroked mode and a dotted one read as the same material.
+ */
+export function inkCss(white: number, dark: boolean, alpha: number): string {
+  const [r, g, b] = shade(Math.min(1, Math.max(0, white)), dark);
+  return `rgba(${r},${g},${b},${alpha})`;
+}
+
+/**
+ * Painter: z-sort far→near, matte depth-shaded dots. On dark substrates the
+ * ink value is mirrored (1 - white) so near dots read bright — the same
+ * depth language on an inverted substrate.
+ */
+export function paint(ctx: CanvasRenderingContext2D, dots: Dot[], dark: boolean, rMin = 0.3): void {
+  dots.sort((a, b) => a.z - b.z);
+  for (const d of dots) {
+    const alpha = d.a ?? 1;
+    if (alpha < 0.02) continue;
+    const w = Math.min(1, Math.max(0, d.white));
+    const [r, g, b] = shade(w, dark);
+    ctx.fillStyle = `rgba(${r},${g},${b},${alpha})`;
+    ctx.beginPath();
+    ctx.arc(d.x, d.y, Math.max(rMin, d.r), 0, Math.PI * 2);
+    ctx.fill();
+  }
+}
+
+/** Stroke pass for edge-based modes. Runs before `paint` so nodes sit on top. */
+export function paintLines(ctx: CanvasRenderingContext2D, lines: Line[], dark: boolean): void {
+  for (const l of lines) {
+    const alpha = l.a ?? 1;
+    if (alpha < 0.02) continue;
+    const w = Math.min(1, Math.max(0, l.white));
+    const [r, g, b] = shade(w, dark);
+    ctx.strokeStyle = `rgba(${r},${g},${b},${alpha})`;
+    ctx.lineWidth = l.w;
+    ctx.beginPath();
+    ctx.moveTo(l.x1, l.y1);
+    ctx.lineTo(l.x2, l.y2);
+    ctx.stroke();
+  }
+}
+
+/**
+ * Dot radii were tuned for a 300pt frame; sub-linear scaling keeps small
+ * spinners legible. Lower pow = radii shrink less with size.
+ */
+export function radiusScale(size: number, pow: number): number {
+  return (size / 300) ** pow;
+}