@unoverse-platform/studio 0.1.25 → 0.1.27

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

@@ -5,6 +5,17 @@
  * SHAPE (values live on the server). Pure types — no runtime, no imports.
  */
 
+/** Report an interaction to the host's analytics (UNOVERSE_ANALYTICS.md). Declared on a
+ *  node beside its `action`. The SDK produces the event and knows nothing about where it
+ *  goes: no vendor, no destination, no identity appears in this shape. */
+export interface AnalyticsSpec {
+  /** The event name. A GA4 standard name where one fits, else `unoverse_`-prefixed. */
+  event: string;
+  /** Sent with it. `{{path}}` resolves against the data scope at the interaction site,
+   *  the same binding an action's `values` already use. */
+  params?: Record<string, unknown>;
+}
+
 // ---- The neutral definition shape (mirrors apps/unoverse/definitions/*.json) ----
 
 export interface UnoverseNode {
@@ -13,7 +24,20 @@ export interface UnoverseNode {
   bind?: Record<string, string>; // target prop -> data field
   visibleWhen?: VisibleWhen; // render only when the condition holds (truthy field, or {field,eq/ne})
   action?: string | ActionSpec; // dispatched on interaction (bare string → server, or a setValue envelope)
-  placeholder?: string; // Input: empty-field copy (content, not style)
+  /** Report this interaction to the host's analytics (UNOVERSE_ANALYTICS.md). Opt-in per
+   *  node: no block, no event. Sits beside `action` because each interaction carries its
+   *  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/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). */
@@ -101,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) ----
@@ -136,6 +165,10 @@ export interface ActionSpec {
   values?: ActionValue[]; // setValue / setTemplateValue patches (the dev's chosen keys)
   send?: string[]; // server route: which scope fields to include (default: all)
   then?: ActionSpec | string; // optional chained follow-up
+  /** Carried here by the renderer, NOT authored on the action: a node declares
+   *  `analytics:` beside `action:`, and the leaf attaches it so the ONE interpreter
+   *  (`dispatchAction`) stays the only place an interaction is understood. */
+  analytics?: AnalyticsSpec;
 }
 
 /** A data condition, evaluated against the render data scope. Pick ONE test:

package/vendor/sdk/lib/index.ts

@@ -30,6 +30,11 @@ export {
   matches,
   visible,
   selectCase,
+  emitAnalytics,
+  setAnalyticsSink,
+  setAnalyticsContext,
+  setAnalyticsDebug,
+  resolveAnalyticsParams,
 } from "./core";
 export type {
   ResolvedTheme,
@@ -56,4 +61,8 @@ export type {
   ServerWorkflowState,
   ServerTemplateData,
   ServerSessionReady,
+  AnalyticsSpec,
+  AnalyticsEvent,
+  AnalyticsContext,
+  AnalyticsSink,
 } from "./core";

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);
+};