@octanejs/thinking-orbs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @octanejs/thinking-orbs
+
+Octane binding for [`thinking-orbs`](https://www.npmjs.com/package/thinking-orbs) — dotted thought-orb loading indicators for AI and agent UIs.
+
+```sh
+npm install @octanejs/thinking-orbs
+pnpm add @octanejs/thinking-orbs
+```
+
+## Usage
+
+```tsx
+import { ThinkingOrb } from '@octanejs/thinking-orbs';
+
+function Status() {
+  return <ThinkingOrb state="searching" size={64} />;
+}
+```
+
+## Compatibility
+
+Pinned to `thinking-orbs@0.2.0`. The framework-neutral canvas engine is reused verbatim; `ThinkingOrb` is reimplemented in `.tsrx`.
+
+## Known differences
+
+None documented yet.
+
+## Tests
+
+Organized per the hook-form / react-parity contract:
+
+- `tests/conformance/` — package-authored contract tests (ordinary CI shards)
+- `tests/differential/` — Octane vs React oracle (dedicated project + `globalSetup`)
+- Vitest projects declare `testExecution.group: 'react-parity'` on parity-owned lanes

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@octanejs/thinking-orbs",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "description": "thinking-orbs for the octane renderer — dotted thought-orb loading indicators for AI and agent UIs.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/thinking-orbs"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "octane": "0.1.50"
+  },
+  "devDependencies": {
+    "@tsrx/react": "^0.2.61",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "thinking-orbs": "0.2.0",
+    "vitest": "^4.1.10",
+    "octane": "0.1.50"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/ThinkingOrb.tsrx

@@ -0,0 +1,109 @@
+// Ported from thinking-orbs@0.2.0 src/ThinkingOrb.tsx
+// (https://github.com/Jakubantalik/thinking-orbs).
+import { useEffect, useRef } from 'octane';
+import { MODE_DRAWS } from './engine/registry';
+import { resolvePreset } from './presets';
+import { useReducedMotion, useResolvedDark } from './theme';
+import type { 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,
+	style,
+	'aria-label': ariaLabel,
+	...rest
+}: ThinkingOrbProps) {
+	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;
+		const context = ctx;
+
+		const { mode, speed: baseSpeed, opts } = resolvePreset(state, size);
+		const draw = MODE_DRAWS[mode];
+		const effSpeed = baseSpeed * speed;
+
+		function frame(tSec: number): void {
+			context.setTransform(dpr, 0, 0, dpr, 0, 0);
+			context.clearRect(0, 0, size, size);
+			draw(context, size, tSec, dark, opts);
+		}
+
+		if (reduced) {
+			frame(0.6);
+			return;
+		}
+
+		let raf = 0;
+		let running = false;
+		function loop(): void {
+			frame((performance.now() / 1000) * effSpeed);
+			if (running) raf = requestAnimationFrame(loop);
+		}
+		function start(): void {
+			if (running || paused) return;
+			running = true;
+			raf = requestAnimationFrame(loop);
+		}
+		function stop(): void {
+			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);
+		function onVis(): void {
+			if (document.visibilityState === 'hidden') stop();
+			else if (visible) start();
+		}
+		document.addEventListener('visibilitychange', onVis);
+		if (!io) start();
+
+		return () => {
+			stop();
+			io?.disconnect();
+			document.removeEventListener('visibilitychange', onVis);
+		};
+	}, [state, size, dark, speed, paused, reduced]);
+
+	return <canvas
+		ref={ref}
+		role="img"
+		aria-label={ariaLabel ?? LABELS[state]}
+		style={{ width: size, height: size, display: 'block', ...style }}
+		{...rest}
+	/>;
+}

package/src/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/src/engine/core.ts

@@ -0,0 +1,136 @@
+// 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];
+	};
+}
+
+/**
+ * Painter: z-sort far→near, matte grayscale 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 g = Math.round((dark ? 1 - w : w) * 255);
+		ctx.fillStyle = `rgba(${g},${g},${g},${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 g = Math.round((dark ? 1 - w : w) * 255);
+		ctx.strokeStyle = `rgba(${g},${g},${g},${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;
+}

package/src/engine/lattice.ts

@@ -0,0 +1,210 @@
+// The sphere-lattice modes: globe (searching), rubik (solving) and
+// wave (listening). All draw a lat/long dot field with mode-specific
+// motion, then hand off to the shared z-sorted painter.
+
+import type { Dot, ModeDraw } from './types';
+import { angleDelta, hashD, makeProj, paint, radiusScale } from './core';
+
+// --- the shared solver heartbeat (rubik) ------------------------------
+// Rapid eased moves scramble, then replay in reverse (palindrome) so
+// everything clicks back to solved, rests, repeats.
+
+interface Move {
+	axis: 0 | 1 | 2;
+	lo: number;
+	hi: number;
+	ang: number;
+}
+
+function solveCycle(time: number, count: number, slotDur: number, rest: number) {
+	const cyc = 2 * count * slotDur + rest;
+	const tc = time % cyc;
+	const amount = new Array<number>(count).fill(0);
+	let active = -1;
+	if (tc < 2 * count * slotDur) {
+		const slot = Math.floor(tc / slotDur);
+		const p = (tc - slot * slotDur) / slotDur;
+		const cl = Math.min(1, p / 0.7);
+		const ep = 1 - (1 - cl) ** 3; // machine ease-out
+		if (slot < count) {
+			for (let i = 0; i < slot; i++) amount[i] = 1;
+			amount[slot] = ep;
+			active = slot;
+		} else {
+			const u = 2 * count - 1 - slot;
+			for (let i = 0; i < u; i++) amount[i] = 1;
+			amount[u] = 1 - ep;
+			active = u;
+		}
+	}
+	return { amount, active };
+}
+
+function applyMoves(
+	pt3: [number, number, number],
+	moves: Move[],
+	sc: { amount: number[]; active: number },
+): [number, number, number, boolean] {
+	let [x, y, z] = pt3;
+	let inActive = false;
+	for (let i = 0; i < moves.length; i++) {
+		if (sc.amount[i] <= 0) continue;
+		const mv = moves[i];
+		const coord = mv.axis === 0 ? x : mv.axis === 1 ? y : z;
+		if (coord < mv.lo || coord >= mv.hi) continue;
+		if (i === sc.active) inActive = true;
+		const a = mv.ang * sc.amount[i];
+		const ca = Math.cos(a);
+		const sa = Math.sin(a);
+		if (mv.axis === 0) {
+			const y2 = y * ca - z * sa;
+			z = y * sa + z * ca;
+			y = y2;
+		} else if (mv.axis === 1) {
+			const x2 = x * ca + z * sa;
+			z = -x * sa + z * ca;
+			x = x2;
+		} else {
+			const x2 = x * ca - y * sa;
+			y = x * sa + y * ca;
+			x = x2;
+		}
+	}
+	return [x, y, z, inActive];
+}
+
+function makeMoves(count: number): Move[] {
+	const moves: Move[] = [];
+	for (let i = 0; i < count; i++) {
+		const axis = Math.min(2, Math.floor(hashD(i, 2.3) * 3)) as 0 | 1 | 2;
+		const lo = -1.0 + 0.5 * Math.min(3, Math.floor(hashD(i, 5.9) * 4));
+		const dir = hashD(i, 7.7) < 0.5 ? 1 : -1;
+		moves.push({ axis, lo, hi: lo + 0.5, ang: (dir * Math.PI) / 2 });
+	}
+	return moves;
+}
+
+// --- Globe: lat/long field, a scan meridian sweeps — searching --------
+
+export const drawGlobe: ModeDraw = (ctx, size, t, dark, o) => {
+	const spin = 0.5;
+	const cx = size / 2;
+	const cy = size / 2;
+	const radius = (size / 2) * 0.82;
+	const tilt = 0.4 + 0.06 * Math.sin(t * 0.35);
+	const pt = makeProj(t * spin, tilt, cx, cy, radius);
+	// scan sweeps relative to the spin; scanMul scales that relative rate
+	const scan = t * (spin + (1.7 - spin) * (o.scanMul ?? 1));
+	const rs = radiusScale(size, o.rsPow ?? 0.6);
+	const dimBase = o.dimBase ?? 1;
+
+	const dots: Dot[] = [];
+	const latRings = o.latRings ?? 17;
+	const lonDensity = o.lonDensity ?? 44;
+	for (let li = 0; li <= latRings; li++) {
+		const lat = -Math.PI / 2 + (li / latRings) * Math.PI;
+		const cosLat = Math.cos(lat);
+		const sinLat = Math.sin(lat);
+		const lonCount = Math.max(1, Math.round(Math.abs(cosLat) * lonDensity));
+		for (let lj = 0; lj < lonCount; lj++) {
+			const lon = (lj / lonCount) * 2 * Math.PI;
+			const [px, py, z] = pt(cosLat * Math.cos(lon), sinLat, cosLat * Math.sin(lon));
+			const depth = (z + 1) / 2;
+			// the scan: a moving meridian read as a size ripple, not a shine
+			const d = angleDelta(lon + t * spin, scan);
+			const boost = Math.exp(-(d * d) / 0.18) * Math.max(0, z);
+			dots.push({
+				x: px,
+				y: py,
+				z,
+				r: ((o.rBase ?? 0.6) + (o.rDepth ?? 1.7) * depth + (o.rBoost ?? 1) * boost) * rs,
+				white: (o.inkFar ?? 0.62) - (o.inkSpan ?? 0.54) * depth,
+				// dimBase < 1 fades un-scanned dots so the meridian reads clearly
+				a: dimBase + (1 - dimBase) * Math.min(1, boost),
+			});
+		}
+	}
+	paint(ctx, dots, dark, o.rMin);
+};
+
+// --- Rubik: bands twist in quarter turns, scramble → solve — solving --
+
+export const drawRubik: ModeDraw = (ctx, size, t, dark, o) => {
+	const cx = size / 2;
+	const cy = size / 2;
+	const R = (size / 2) * 0.82;
+	const pt = makeProj(t * 0.55, 0.35 + 0.1 * Math.sin(t * 0.9), cx, cy, R);
+	const rs = radiusScale(size, o.rsPow ?? 0.6);
+	const moveCount = o.moveCount ?? 14;
+	const moves = makeMoves(moveCount);
+	const sc = solveCycle(t, moveCount, 0.42, 1.2);
+
+	const dots: Dot[] = [];
+	const latRings = o.latRings ?? 15;
+	const lonDensity = o.lonDensity ?? 40;
+	for (let li = 0; li <= latRings; li++) {
+		const lat = -Math.PI / 2 + (li / latRings) * Math.PI;
+		const cosLat = Math.cos(lat);
+		const sinLat = Math.sin(lat);
+		const lonCount = Math.max(1, Math.round(Math.abs(cosLat) * lonDensity));
+		for (let lj = 0; lj < lonCount; lj++) {
+			const lon = (lj / lonCount) * 2 * Math.PI;
+			const [x, y, z, inActive] = applyMoves(
+				[cosLat * Math.cos(lon), sinLat, cosLat * Math.sin(lon)],
+				moves,
+				sc,
+			);
+			const [px, py, zr] = pt(x, y, z);
+			const depth = (zr + 1) / 2;
+			// the band being turned inks a touch darker — the "hand"
+			dots.push({
+				x: px,
+				y: py,
+				z: zr,
+				r:
+					((o.rBase ?? 0.6) + (o.rDepth ?? 1.7) * depth + (inActive ? (o.rActive ?? 0.3) : 0)) * rs,
+				white: (o.inkFar ?? 0.62) - (o.inkSpan ?? 0.54) * depth - (inActive ? 0.14 : 0),
+			});
+		}
+	}
+	paint(ctx, dots, dark, o.rMin);
+};
+
+// --- Wave: a waveform rolls through the rings — listening -------------
+
+export const drawWave: ModeDraw = (ctx, size, t, dark, o) => {
+	const cx = size / 2;
+	const cy = size / 2;
+	// 0.76 base × 1.15 — the undulation pulls the sphere inward, so wave read
+	// ~15% smaller than the other lattice modes; scaled up to match them
+	const R = (size / 2) * 0.874;
+	const pt = makeProj(t * 0.18, 0.38, cx, cy, 1);
+	const rs = radiusScale(size, o.rsPow ?? 0.6);
+
+	const dots: Dot[] = [];
+	const rings = o.rings ?? 15;
+	const lonDensity = o.lonDensity ?? 40;
+	for (let ri = 0; ri <= rings; ri++) {
+		const lat = -Math.PI / 2 + (ri / rings) * Math.PI;
+		const cosLat = Math.cos(lat);
+		const sinLat = Math.sin(lat);
+		// two waves, different tempi — organic, never quite repeating
+		const w = 0.62 * Math.sin(t * 2.1 - ri * 0.52) + 0.38 * Math.sin(t * 1.27 + ri * 0.83);
+		const rr = R * (0.88 + 0.105 * w);
+		const lonCount = Math.max(1, Math.round(Math.abs(cosLat) * lonDensity));
+		for (let lj = 0; lj < lonCount; lj++) {
+			const lon = (lj / lonCount) * 2 * Math.PI;
+			const [px, py, z] = pt(cosLat * Math.cos(lon) * rr, sinLat * rr, cosLat * Math.sin(lon) * rr);
+			const depth = (z / R + 1) / 2;
+			const crest = Math.max(0, w);
+			dots.push({
+				x: px,
+				y: py,
+				z,
+				r: ((o.rBase ?? 0.6) + (o.rDepth ?? 1.7) * depth) * (1 + 0.4 * crest) * rs,
+				white: 0.66 - 0.56 * depth - 0.1 * crest,
+			});
+		}
+	}
+	paint(ctx, dots, dark, o.rMin);
+};