@unoverse-platform/studio 0.1.25 → 0.1.27

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

@@ -0,0 +1,162 @@
+// Density profiles + the multiplier machinery that scales them. The base
+// rows are inkform's `fine` profiles; each shipped preset (state × size)
+// applies count / radius multipliers on top, resolved once per mount.
+
+export interface ModeOpts {
+  [key: string]: number | undefined;
+}
+
+// 2-D lattices (rings × dots-per-ring) come in pairs — each side takes
+// √scale so the TOTAL dot count scales by `scale`; flat lists scale
+// linearly. `iconD` sets the morph outline's sampling density.
+const COUNT_PAIRS: ReadonlyArray<readonly [string, string]> = [
+  ['latRings', 'lonDensity'],
+  ['rings', 'lonDensity'],
+  ['lanes', 'segs']
+];
+const COUNT_KEYS = ['orbitN', 'ghostN', 'nodeN', 'strandN', 'signals'] as const;
+const ICON_DENSITY_KEYS = ['iconD'] as const;
+
+// Every key that sets a dot's rendered radius — scaling all of them keeps
+// a dot's near/far falloff intact while shrinking or growing the mark.
+const RADIUS_KEYS = [
+  'rBase',
+  'rDepth',
+  'rActive',
+  'rDot',
+  'ghostR',
+  'partR',
+  'partRDepth',
+  'nodeR',
+  'nodeRDepth'
+] as const;
+
+export function scaleCounts(opts: ModeOpts, scale: number): ModeOpts {
+  const out: ModeOpts = { ...opts };
+  const done = new Set<string>();
+  const rt = Math.sqrt(scale);
+  for (const [a, b] of COUNT_PAIRS) {
+    const va = out[a];
+    const vb = out[b];
+    if (va != null && vb != null && !done.has(a) && !done.has(b)) {
+      out[a] = Math.max(2, Math.round(va * rt));
+      out[b] = Math.max(2, Math.round(vb * rt));
+      done.add(a);
+      done.add(b);
+    }
+  }
+  for (const k of COUNT_KEYS) {
+    const v = out[k];
+    // 0 means the mode opted out of that layer entirely (ring has no ghost
+    // sphere) — scaling must not resurrect it as a single stray dot
+    if (v != null && v !== 0 && !done.has(k)) out[k] = Math.max(1, Math.round(v * scale));
+  }
+  for (const k of ICON_DENSITY_KEYS) {
+    const v = out[k];
+    if (v != null) out[k] = Math.max(0.02, v * scale);
+  }
+  return out;
+}
+
+export function scaleRadii(opts: ModeOpts, scale: number): ModeOpts {
+  const out: ModeOpts = { ...opts };
+  for (const k of RADIUS_KEYS) {
+    const v = out[k];
+    if (v != null) out[k] = v * scale;
+  }
+  // remember the multiplier itself — spacing-derived radii (the morph
+  // outline) use it, since they aren't based on any single radius key
+  out.rSizeMul = (out.rSizeMul ?? 1) * scale;
+  return out;
+}
+
+/** Base (fine) profiles per mode, before preset multipliers. */
+export const BASE_PROFILES: Record<string, ModeOpts> = {
+  globe: {
+    latRings: 17,
+    lonDensity: 44,
+    rBase: 0.6,
+    rDepth: 1.7,
+    rBoost: 1.0,
+    inkFar: 0.62,
+    inkSpan: 0.54,
+    rsPow: 0.6,
+    rMin: 0.3
+  },
+  orbits: {
+    orbitN: 12,
+    ghostN: 40,
+    ghostR: 0.9,
+    ghostA: 0.5,
+    particles: 3,
+    partR: 1.2,
+    partRDepth: 1.6,
+    rsPow: 0.6,
+    rMin: 0.3
+  },
+  rubik: {
+    latRings: 15,
+    lonDensity: 40,
+    moveCount: 14,
+    rBase: 0.6,
+    rDepth: 1.7,
+    rActive: 0.3,
+    inkFar: 0.62,
+    inkSpan: 0.54,
+    rsPow: 0.6,
+    rMin: 0.3
+  },
+  wave: {
+    rings: 15,
+    lonDensity: 40,
+    rBase: 0.6,
+    rDepth: 1.7,
+    rsPow: 0.6,
+    rMin: 0.3
+  },
+  web: {
+    nodeN: 30,
+    thr: 0.72,
+    signals: 5,
+    nodeR: 1.4,
+    nodeRDepth: 1.8,
+    lineW: 0.8,
+    rsPow: 0.6,
+    rMin: 0.3
+  },
+  braid: {
+    strandN: 52,
+    turns: 3.0,
+    ghostN: 150,
+    rBase: 1.2,
+    rDepth: 1.8,
+    rsPow: 0.6,
+    rMin: 0.3
+  },
+  ribbon: {
+    lanes: 5,
+    segs: 88,
+    ghostN: 150,
+    rBase: 1.1,
+    rDepth: 1.7,
+    rsPow: 0.6,
+    rMin: 0.3
+  },
+  // ring shares ribbon's painter; faceOn cancels the camera tilt and moves
+  // the undulation onto the radius, and there is no ghost sphere behind it
+  ring: {
+    lanes: 5,
+    segs: 88,
+    ghostN: 0,
+    faceOn: 1,
+    rBase: 1.1,
+    rDepth: 1.7,
+    rsPow: 0.6,
+    rMin: 0.3
+  },
+  morph: {
+    rDot: 0.021,
+    iconD: 1,
+    rMin: 0.25
+  }
+};

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

@@ -0,0 +1,24 @@
+// Mode key → frame painter. Kept separate from the presets so tree
+// shaking can in principle drop unused modes in custom builds.
+
+import type { ModeKey } from '../presets';
+import type { ModeDraw } from './types';
+import { drawBraid } from './braid';
+import { drawGlobe, drawRubik, drawWave } from './lattice';
+import { drawMorph } from './morph';
+import { drawOrbits } from './orbits';
+import { drawRibbon } from './ribbon';
+import { drawWeb } from './web';
+
+export const MODE_DRAWS: Record<ModeKey, ModeDraw> = {
+  orbits: drawOrbits,
+  globe: drawGlobe,
+  rubik: drawRubik,
+  wave: drawWave,
+  web: drawWeb,
+  braid: drawBraid,
+  ribbon: drawRibbon,
+  // ring shares ribbon's painter — the `faceOn` profile flag switches it
+  ring: drawRibbon,
+  morph: drawMorph
+};

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

@@ -0,0 +1,93 @@
+// Ribbon: an undulating sash of parallel strands rides a great circle —
+// the "composing" state. The tuned preset freezes the 3D tumble
+// (spin 0), leaving the traveling undulation on a fixed band.
+//
+// The same painter also drives "breathing" (ring), via the `faceOn` flag:
+// a face-on circle whose radius — not its out-of-plane offset — undulates,
+// so it reads as a ring slowly morphing rather than a sash in orbit.
+
+import type { Dot, ModeDraw } from './types';
+import { fibDir, makeProj, paint, radiusScale } from './core';
+
+export const drawRibbon: ModeDraw = (ctx, size, t, dark, o) => {
+  const cx = size / 2;
+  const cy = size / 2;
+  const R = (size / 2) * 0.78;
+  // spin scales the 3D tumble; spin=0 freezes the band's orientation,
+  // leaving only the traveling undulation
+  const spin = o.spin ?? 1;
+  const camTilt = 0.3;
+  const pt = makeProj(t * 0.1 * spin, camTilt, 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 });
+  }
+
+  // The band plane, precessing (frozen when spin=0). The projection squashes
+  // the band's great circle vertically by cos(ta + camTilt); face-on sets
+  // ta = -camTilt so that term is 1 and the band reads as a true circle
+  // rather than ribbon's tilted ellipse.
+  const ya = t * 0.24 * spin;
+  const ta = o.faceOn ? -camTilt : 0.55 + 0.3 * Math.sin(t * 0.18) * spin;
+  const ux = Math.cos(ya);
+  const uy = 0;
+  const uz = Math.sin(ya);
+  const vx = -uz * Math.sin(ta);
+  const vy = Math.cos(ta);
+  const vz = ux * Math.sin(ta);
+  // plane normal n = u × v
+  const nx = uy * vz - uz * vy;
+  const ny = uz * vx - ux * vz;
+  const nz = ux * vy - uy * vx;
+
+  // Radial lobes swell past R, so pull the base radius in by (most of) the
+  // wobble amplitude. The silhouette then stays inside the frame however far
+  // the deformation is pushed, while lobes keep getting deeper relative to
+  // the mean radius.
+  const wobAmp = 0.23 * (o.wobMul ?? 1);
+  const baseR = o.faceOn ? R / (1 + 0.85 * wobAmp) : R;
+
+  const baseLanes = o.lanes ?? 5;
+  const segs = o.segs ?? 88;
+  const lanes = Math.max(1, Math.round(baseLanes * (o.bandMul ?? 1)));
+  for (let w = 0; w < lanes; w++) {
+    const laneOff = (w - (lanes - 1) / 2) * 0.075;
+    const edge = Math.abs(w - (lanes - 1) / 2) / Math.max(1, (lanes - 1) / 2);
+    for (let k = 0; k < segs; k++) {
+      const a = (k / segs) * 2 * Math.PI;
+      // the undulation: two traveling waves along the band; wobMul
+      // scales the deformation — 0 is a clean band
+      const wob =
+        (0.16 * Math.sin(a * 3 - t * 1.7 + w * 0.22) + 0.07 * Math.sin(a * 5 + t * 1.1)) * (o.wobMul ?? 1);
+      // A normal-direction wobble is cancelled by the re-normalisation below:
+      // the point lands back on the sphere, so the silhouette is pinned at R
+      // and the deformation can only ever pull dots inward. Face-on instead
+      // modulates the in-plane RADIUS, so lobes genuinely swell outward and
+      // pinch inward. Ribbon keeps the original out-of-plane sash wobble.
+      const radial = o.faceOn ? 1 + wob : 1;
+      const off = o.faceOn ? laneOff : laneOff + wob;
+      const x = ux * Math.cos(a) + vx * Math.sin(a) + nx * off;
+      const y = uy * Math.cos(a) + vy * Math.sin(a) + ny * off;
+      const z = uz * Math.cos(a) + vz * Math.sin(a) + nz * off;
+      const l = Math.sqrt(x * x + y * y + z * z);
+      const rr = baseR * radial;
+      const [px, py, zr] = pt((x / l) * rr, (y / l) * rr, (z / l) * rr);
+      const depth = (zr / R + 1) / 2;
+      dots.push({
+        x: px,
+        y: py,
+        z: zr,
+        r: ((o.rBase ?? 1.1) + (o.rDepth ?? 1.7) * depth) * (1 - 0.25 * edge) * rs,
+        white: 0.52 - 0.44 * depth + 0.18 * edge,
+        a: 0.4 + 0.6 * depth
+      });
+    }
+  }
+  paint(ctx, dots, dark, o.rMin);
+};

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

@@ -0,0 +1,14 @@
+// Engine-level contracts shared by every mode implementation.
+
+import type { ModeOpts } from './profiles';
+
+export type { Dot, Line } from './core';
+
+/** One frame painter: draws a mode into a 2D context at CSS-px `size`. */
+export type ModeDraw = (
+  ctx: CanvasRenderingContext2D,
+  size: number,
+  t: number,
+  dark: boolean,
+  opts: ModeOpts
+) => void;

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

@@ -0,0 +1,98 @@
+// Web: a constellation wires itself — the "connecting" state. Nodes drift
+// on the sphere under slow value noise; any pair closer than `thr` grows an
+// edge, and bright packets run along randomly re-picked node pairs.
+
+import type { Dot, Line, ModeDraw } from './types';
+import { fibDir, frac, hashD, lerp, makeProj, paint, paintLines, radiusScale, vnoise } from './core';
+
+export const drawWeb: ModeDraw = (ctx, size, t, dark, o) => {
+  const cx = size / 2;
+  const cy = size / 2;
+  const R = (size / 2) * 0.8 * (o.spread ?? 1);
+  // note the projector carries the radius as its scale, so node vectors stay
+  // unit-length and distances below are in unit-sphere space
+  const pt = makeProj(t * 0.12, 0.32, cx, cy, R);
+  const rs = radiusScale(size, o.rsPow ?? 0.6);
+
+  const nodeN = o.nodeN ?? 30;
+  const thr = o.thr ?? 0.72;
+  const nodeR = o.nodeR ?? 1.4;
+  const nodeRDepth = o.nodeRDepth ?? 1.8;
+
+  // nodes: fib lattice + slow noise wander, renormalised to the surface
+  const nodes: Array<[number, number, number]> = [];
+  for (let i = 0; i < nodeN; i++) {
+    const d = fibDir(i, nodeN);
+    const x = d[0] + 0.3 * (vnoise(i * 0.31 + 9, t * 0.24) - 0.5) * 2;
+    const y = d[1] + 0.3 * (vnoise(i * 0.53 + 27, t * 0.21) - 0.5) * 2;
+    const z = d[2] + 0.3 * (vnoise(i * 0.77 + 55, t * 0.27) - 0.5) * 2;
+    const l = Math.sqrt(x * x + y * y + z * z);
+    nodes.push([x / l, y / l, z / l]);
+  }
+
+  const lines: Line[] = [];
+  const dots: Dot[] = [];
+
+  // edges between close neighbours, alpha by proximity + depth
+  for (let i = 0; i < nodeN; i++) {
+    for (let j = i + 1; j < nodeN; j++) {
+      const dx = nodes[i][0] - nodes[j][0];
+      const dy = nodes[i][1] - nodes[j][1];
+      const dz = nodes[i][2] - nodes[j][2];
+      const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+      if (dist >= thr) continue;
+      const [x1, y1, z1] = pt(nodes[i][0], nodes[i][1], nodes[i][2]);
+      const [x2, y2, z2] = pt(nodes[j][0], nodes[j][1], nodes[j][2]);
+      const depth = ((z1 + z2) / 2 + 1) / 2;
+      lines.push({
+        x1,
+        y1,
+        x2,
+        y2,
+        white: 0.42,
+        a: (1 - dist / thr) * (0.3 + 0.55 * depth),
+        w: Math.max(0.6, (o.lineW ?? 0.8) * rs)
+      });
+    }
+  }
+
+  for (let i = 0; i < nodeN; i++) {
+    const [px, py, z] = pt(nodes[i][0], nodes[i][1], nodes[i][2]);
+    const depth = (z + 1) / 2;
+    const pulse = 1 + 0.25 * Math.sin(t * 1.4 + i * 2.7);
+    dots.push({
+      x: px,
+      y: py,
+      z,
+      r: (nodeR + nodeRDepth * depth) * pulse * rs,
+      white: 0.55 - 0.45 * depth
+    });
+  }
+
+  // signals: bright packets running between paired nodes
+  const signals = o.signals ?? 5;
+  for (let s = 0; s < signals; s++) {
+    const seg = Math.floor(t * 0.55 + s * 7.31);
+    const a = Math.floor(hashD(seg, s * 3.1 + 1.7) * nodeN);
+    const b = Math.floor(hashD(seg, s * 5.7 + 4.2) * nodeN);
+    if (a === b) continue;
+    const f = frac(t * 0.55 + s * 7.31);
+    const x = lerp(nodes[a][0], nodes[b][0], f);
+    const y = lerp(nodes[a][1], nodes[b][1], f);
+    const z = lerp(nodes[a][2], nodes[b][2], f);
+    const l = Math.max(1e-6, Math.sqrt(x * x + y * y + z * z));
+    const [px, py, zr] = pt(x / l, y / l, z / l);
+    const depth = (zr + 1) / 2;
+    dots.push({
+      x: px,
+      y: py,
+      z: zr,
+      r: (nodeR * 1.5 + nodeRDepth * depth) * rs,
+      white: 0.05,
+      a: 0.5 + 0.5 * depth
+    });
+  }
+
+  paintLines(ctx, lines, dark);
+  paint(ctx, dots, dark, o.rMin);
+};

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

@@ -0,0 +1,20 @@
+/**
+ * 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).
+ */
+export { ThinkingOrb } from "./ThinkingOrb";
+export type { ThinkingOrbProps, OrbState, OrbSize, OrbTheme } from "./types";

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

@@ -0,0 +1,104 @@
+// The shipped tunings: nine states × two sizes, baked from the inkform
+// mini-page tuning session. `count`/`size` are multipliers over the base
+// fine profiles; `speed` multiplies the shared clock. Resolved once per
+// (state, size) pair and cached — the render loop sees plain numbers.
+
+import type { ModeOpts } from './engine/profiles';
+import { BASE_PROFILES, scaleCounts, scaleRadii } from './engine/profiles';
+import type { OrbSize, OrbState } from './types';
+
+export type ModeKey =
+  | 'orbits'
+  | 'globe'
+  | 'rubik'
+  | 'wave'
+  | 'web'
+  | 'braid'
+  | 'ribbon'
+  | 'ring'
+  | 'morph';
+
+export const STATE_TO_MODE: Record<OrbState, ModeKey> = {
+  working: 'orbits',
+  searching: 'globe',
+  solving: 'rubik',
+  listening: 'wave',
+  connecting: 'web',
+  weaving: 'braid',
+  composing: 'ribbon',
+  breathing: 'ring',
+  shaping: 'morph'
+};
+
+interface Preset {
+  speed: number;
+  count: number;
+  size: number;
+  /** Extra mode opts merged verbatim after scaling. */
+  extra?: ModeOpts;
+}
+
+const PRESETS: Record<ModeKey, Record<OrbSize, Preset>> = {
+  orbits: {
+    64: { speed: 1.885, count: 1, size: 1 },
+    20: { speed: 3.9, count: 0.238, size: 2.4 }
+  },
+  globe: {
+    64: { speed: 2.015, count: 0.42, size: 1.15, extra: { scanMul: 4.08, dimBase: 0.45 } },
+    20: { speed: 2.665, count: 0.105, size: 1.75, extra: { scanMul: 4.335, dimBase: 0.45 } }
+  },
+  rubik: {
+    64: { speed: 1.82, count: 0.35, size: 1.05 },
+    20: { speed: 1.95, count: 0.088, size: 1.9 }
+  },
+  wave: {
+    64: { speed: 4.388, count: 0.341, size: 1 },
+    20: { speed: 3.998, count: 0.105, size: 1.6 }
+  },
+  web: {
+    64: { speed: 3.315, count: 1.35, size: 0.95 },
+    20: { speed: 6.63, count: 0.25, size: 1.52 }
+  },
+  braid: {
+    64: { speed: 1.625, count: 0.5, size: 1 },
+    20: { speed: 2.75, count: 0.1125, size: 1.36 }
+  },
+  ribbon: {
+    64: { speed: 2.34, count: 0.25, size: 0.85, extra: { spin: 0, bandMul: 3.9, wobMul: 1 } },
+    20: { speed: 3.12, count: 0.051, size: 1.073, extra: { spin: 0, bandMul: 4.94, wobMul: 1 } }
+  },
+  ring: {
+    64: { speed: 3.24, count: 0.25, size: 0.956, extra: { spin: 0, bandMul: 3.627, wobMul: 0.368 } },
+    20: { speed: 3.78, count: 0.028, size: 1.622, extra: { spin: 0, bandMul: 3.968, wobMul: 0.565 } }
+  },
+  morph: {
+    64: { speed: 2.405, count: 0.702, size: 0.395, extra: { spread: 1.45 } },
+    20: { speed: 2.08, count: 0.53, size: 1.011, extra: { spread: 1.45 } }
+  }
+};
+
+export interface Resolved {
+  mode: ModeKey;
+  speed: number;
+  opts: ModeOpts;
+}
+
+const cache = new Map<string, Resolved>();
+
+/** Resolve a (state, size) pair to its mode + fully-scaled draw options. */
+export function resolvePreset(state: OrbState, size: OrbSize): Resolved {
+  const key = `${state}-${size}`;
+  const hit = cache.get(key);
+  if (hit) return hit;
+
+  const mode = STATE_TO_MODE[state];
+  const preset = PRESETS[mode][size];
+  let opts: ModeOpts = { ...BASE_PROFILES[mode] };
+  if (preset.count !== 1) opts = scaleCounts(opts, preset.count);
+  if (preset.size !== 1) opts = scaleRadii(opts, preset.size);
+  if (preset.extra) opts = { ...opts, ...preset.extra };
+
+  const resolved: Resolved = { mode, speed: preset.speed, opts };
+  cache.set(key, resolved);
+  return resolved;
+}

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

@@ -0,0 +1,83 @@
+// Theme resolution: explicit prop → ancestor data-theme/.dark|.light
+// class (watched live) → prefers-color-scheme (subscribed live).
+// SSR-safe: everything runs in effects; the pre-mount fallback is dark.
+
+import type { RefObject } from 'react';
+import { useEffect, useState } from 'react';
+import type { OrbTheme } from './types';
+
+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;
+}
+
+function systemDark(): boolean {
+  return typeof matchMedia === 'undefined' || matchMedia('(prefers-color-scheme: dark)').matches;
+}
+
+/** Resolve the effective dark/light substrate for a mounted element. */
+export function useResolvedDark(theme: OrbTheme, hostRef: RefObject<Element | null>): boolean {
+  const [dark, setDark] = useState(true);
+
+  useEffect(() => {
+    if (theme === 'dark') {
+      setDark(true);
+      return;
+    }
+    if (theme === 'light') {
+      setDark(false);
+      return;
+    }
+
+    const resolve = () => {
+      const fromTree = ancestorTheme(hostRef.current);
+      setDark(fromTree ?? systemDark());
+    };
+    resolve();
+
+    // live OS/browser theme switches
+    const mq = typeof matchMedia !== 'undefined' ? matchMedia('(prefers-color-scheme: dark)') : null;
+    const onMq = () => resolve();
+    mq?.addEventListener('change', onMq);
+
+    // live app-level toggles: watch class/data-theme flips on ancestors
+    let mo: MutationObserver | null = null;
+    if (typeof MutationObserver !== 'undefined' && hostRef.current) {
+      mo = new MutationObserver(resolve);
+      mo.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ['class', 'data-theme'],
+        subtree: true
+      });
+    }
+
+    return () => {
+      mq?.removeEventListener('change', onMq);
+      mo?.disconnect();
+    };
+  }, [theme, hostRef]);
+
+  return dark;
+}
+
+/** Live `prefers-reduced-motion` — reduced users get a static frame. */
+export function useReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(false);
+  useEffect(() => {
+    if (typeof matchMedia === 'undefined') return;
+    const mq = matchMedia('(prefers-reduced-motion: reduce)');
+    setReduced(mq.matches);
+    const on = (e: MediaQueryListEvent) => setReduced(e.matches);
+    mq.addEventListener('change', on);
+    return () => mq.removeEventListener('change', on);
+  }, []);
+  return reduced;
+}

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

@@ -0,0 +1,73 @@
+import type { CSSProperties, CanvasHTMLAttributes } from 'react';
+
+/**
+ * The nine shipped states — each a hand-tuned animation:
+ * - `working`    — particles on tilted orbits
+ * - `searching`  — a scan meridian sweeps a dotted globe
+ * - `solving`    — bands scramble in quarter turns, then click back
+ * - `listening`  — a waveform rolls through latitude rings
+ * - `connecting` — a constellation wires itself, packets running the edges
+ * - `weaving`    — three strands plait around the sphere
+ * - `composing`  — an undulating multi-band sash
+ * - `breathing`  — a face-on ring slowly morphing
+ * - `shaping`    — a dotted outline morphs circle → triangle → square
+ */
+export type OrbState =
+  | 'working'
+  | 'searching'
+  | 'solving'
+  | 'listening'
+  | 'connecting'
+  | 'weaving'
+  | 'composing'
+  | 'breathing'
+  | 'shaping';
+
+/**
+ * Rendered size in CSS pixels. Exactly two tuned presets ship:
+ * 64 (chat-avatar scale) and 20 (inline-text scale). Each size carries
+ * its own dot count, dot size and speed tuning — they are separate
+ * designs, not a scale factor.
+ */
+export type OrbSize = 64 | 20;
+
+/**
+ * Theme mode.
+ *
+ * - `auto` (default) resolves in three layers, live-updating on change:
+ *   1. a `data-theme="dark|light"` attribute or `dark`/`light` class on
+ *      any ancestor (the Tailwind / shadcn convention), watched via
+ *      `MutationObserver`;
+ *   2. otherwise `matchMedia('(prefers-color-scheme: dark)')`,
+ *      subscribed for live OS/browser theme switches;
+ *   3. during SSR (no DOM) the first client render resolves the theme
+ *      before anything is painted — the canvas is client-only.
+ * - `dark` / `light` pin the palette regardless of context.
+ *
+ * Dark renders light ink on the transparent canvas (for dark
+ * backgrounds); light renders dark ink (for light backgrounds).
+ */
+export type OrbTheme = 'auto' | 'dark' | 'light';
+
+/** Props for the ThinkingOrb React component. */
+export interface ThinkingOrbProps extends Omit<CanvasHTMLAttributes<HTMLCanvasElement>, 'style'> {
+  /** Which animation to show. @default 'working' */
+  state?: OrbState;
+
+  /** Tuned size preset — 64 or 20 CSS px. @default 64 */
+  size?: OrbSize;
+
+  /** Theme mode; `auto` detects from the host project. @default 'auto' */
+  theme?: OrbTheme;
+
+  /**
+   * Animation speed multiplier on top of the preset's baked speed.
+   * @default 1
+   */
+  speed?: number;
+
+  /** Freeze the animation on the current frame. @default false */
+  paused?: boolean;
+
+  style?: CSSProperties;
+}