@selvajs/ui 5.0.1 → 6.0.0-beta.0

package/src/lib/compute/solveMemo.test.ts

@@ -1,220 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import * as THREE from 'three';
-import { createSolveMemo, stableInputKey } from './solveMemo';
-import type { SolveResult } from '../types/solveFn';
-
-// Pins the client-side result memo (M2): stable keying across key order, LRU recency and
-// eviction, hit/miss semantics, and clear(). The driver wiring is pinned separately in
-// createSolveSession.test.ts.
-
-const result = (tag: string): SolveResult => ({ outputs: { out: tag } });
-
-/** A mesh-bearing result — the shape that exposed audit C1. */
-function meshResult(tag: string): SolveResult {
-	const mesh = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshBasicMaterial());
-	mesh.name = tag;
-	return { outputs: { out: tag }, meshes: [mesh] };
-}
-
-/** Mirrors `clearScene`'s disposal of whatever the viewer currently holds. */
-function disposeLikeViewer(res: SolveResult | undefined): void {
-	res?.meshes?.forEach((m: THREE.Object3D) =>
-		m.traverse((child) => {
-			const r = child as Partial<THREE.Mesh> & THREE.Object3D;
-			r.geometry?.dispose();
-			const mat = r.material;
-			if (!mat) return;
-			(Array.isArray(mat) ? mat : [mat]).forEach((m) => m.dispose());
-		})
-	);
-}
-
-/**
- * Count `dispose()` calls across ALL geometries for the duration of a test.
- *
- * The memo stores a private clone, so watching the object handed to `set` would prove
- * nothing — the retained copy is deliberately unreachable. Spying the prototype observes
- * disposal of whichever instance the memo actually owns, which is the real invariant:
- * an entry leaving the map must release its buffers.
- */
-function countDisposals(): { count: () => number; restore: () => void } {
-	const original = THREE.BufferGeometry.prototype.dispose;
-	let n = 0;
-	THREE.BufferGeometry.prototype.dispose = function (this: THREE.BufferGeometry) {
-		n++;
-		return original.call(this);
-	};
-	return {
-		count: () => n,
-		restore: () => {
-			THREE.BufferGeometry.prototype.dispose = original;
-		}
-	};
-}
-
-describe('stableInputKey', () => {
-	it('is insensitive to object key order', () => {
-		expect(stableInputKey({ a: 1, b: 2 })).toBe(stableInputKey({ b: 2, a: 1 }));
-	});
-
-	it('sorts keys at every level (nested objects)', () => {
-		expect(stableInputKey({ o: { x: 1, y: 2 } })).toBe(stableInputKey({ o: { y: 2, x: 1 } }));
-	});
-
-	it('distinguishes different values', () => {
-		expect(stableInputKey({ a: 1 })).not.toBe(stableInputKey({ a: 2 }));
-	});
-
-	it('preserves array order (arrays are ordered)', () => {
-		expect(stableInputKey({ a: [1, 2] })).not.toBe(stableInputKey({ a: [2, 1] }));
-	});
-
-	it('handles null and primitive values', () => {
-		expect(stableInputKey({ a: null, b: 'x', c: true })).toBe(
-			stableInputKey({ c: true, b: 'x', a: null })
-		);
-	});
-});
-
-describe('createSolveMemo', () => {
-	it('returns undefined on a miss', () => {
-		const memo = createSolveMemo();
-		expect(memo.get({ a: 1 })).toBeUndefined();
-	});
-
-	it('round-trips a stored result by equal inputs regardless of key order', () => {
-		const memo = createSolveMemo();
-		memo.set({ a: 1, b: 2 }, result('r'));
-		expect(memo.get({ b: 2, a: 1 })).toEqual(result('r'));
-	});
-
-	it('caches errored results (a complete, deterministic solve outcome)', () => {
-		const memo = createSolveMemo();
-		const errored: SolveResult = { outputs: {}, errors: ['boom'] };
-		memo.set({ a: 1 }, errored);
-		expect(memo.get({ a: 1 })).toEqual(errored);
-	});
-
-	it('evicts the least-recently-used entry past capacity', () => {
-		const memo = createSolveMemo(2);
-		memo.set({ k: 1 }, result('1'));
-		memo.set({ k: 2 }, result('2'));
-		memo.set({ k: 3 }, result('3')); // evicts k:1
-		expect(memo.get({ k: 1 })).toBeUndefined();
-		expect(memo.get({ k: 2 })).toEqual(result('2'));
-		expect(memo.get({ k: 3 })).toEqual(result('3'));
-	});
-
-	it('a get refreshes recency, protecting the entry from eviction', () => {
-		const memo = createSolveMemo(2);
-		memo.set({ k: 1 }, result('1'));
-		memo.set({ k: 2 }, result('2'));
-		memo.get({ k: 1 }); // k:1 now most-recent
-		memo.set({ k: 3 }, result('3')); // evicts k:2, not k:1
-		expect(memo.get({ k: 1 })).toEqual(result('1'));
-		expect(memo.get({ k: 2 })).toBeUndefined();
-	});
-
-	it('re-setting an existing key updates the value without growing size', () => {
-		const memo = createSolveMemo(1);
-		memo.set({ k: 1 }, result('old'));
-		memo.set({ k: 1 }, result('new'));
-		expect(memo.get({ k: 1 })).toEqual(result('new'));
-	});
-
-	it('clear() drops every entry', () => {
-		const memo = createSolveMemo();
-		memo.set({ a: 1 }, result('r'));
-		memo.clear();
-		expect(memo.get({ a: 1 })).toBeUndefined();
-	});
-});
-
-// Audit C1. The memo caches whole SolveResults, including live three.js objects, but the
-// viewer's `clearScene` disposes the meshes it is handed on the next scene update. Every
-// pre-existing test above used mesh-free results, so nothing caught it.
-describe('createSolveMemo — GPU object ownership (audit C1)', () => {
-	it('serves a usable mesh after the viewer disposed the one it was given', () => {
-		const memo = createSolveMemo();
-		const stored = meshResult('a');
-		memo.set({ k: 1 }, stored);
-
-		// Solve 1 renders: the viewer owns and (on the next update) disposes these meshes.
-		const first = memo.get({ k: 1 })!;
-		disposeLikeViewer(first);
-
-		// Slider returns to the same value → memo hit. The served mesh must be renderable,
-		// not the corpse the viewer just disposed.
-		const second = memo.get({ k: 1 })!;
-		const geo = (second.meshes![0] as THREE.Mesh).geometry;
-		expect(geo.attributes.position).toBeDefined();
-		expect(second.meshes![0]).not.toBe(first.meshes![0]);
-	});
-
-	it('never hands the same mesh instance to two consumers', () => {
-		// The scene takes ownership of what it is given (updateScene → scene.add), so two
-		// hits handing out one instance means a double-add and a shared disposal fate.
-		const memo = createSolveMemo();
-		memo.set({ k: 1 }, meshResult('a'));
-		expect(memo.get({ k: 1 })!.meshes![0]).not.toBe(memo.get({ k: 1 })!.meshes![0]);
-	});
-
-	it('preserves non-mesh result fields on a hit', () => {
-		const memo = createSolveMemo();
-		const stored: SolveResult = { ...meshResult('a'), errors: ['e'], warnings: ['w'] };
-		memo.set({ k: 1 }, stored);
-		const hit = memo.get({ k: 1 })!;
-		expect(hit.outputs).toEqual({ out: 'a' });
-		expect(hit.errors).toEqual(['e']);
-		expect(hit.warnings).toEqual(['w']);
-	});
-
-	it('releases GPU memory when an entry is evicted', () => {
-		const memo = createSolveMemo(1);
-		memo.set({ k: 1 }, meshResult('a'));
-
-		const spy = countDisposals();
-		try {
-			memo.set({ k: 2 }, meshResult('b')); // evicts k:1
-			expect(spy.count()).toBe(1);
-		} finally {
-			spy.restore();
-		}
-		expect(memo.get({ k: 1 })).toBeUndefined();
-	});
-
-	it('releases GPU memory on clear() (definition switch)', () => {
-		const memo = createSolveMemo();
-		memo.set({ k: 1 }, meshResult('a'));
-		memo.set({ k: 2 }, meshResult('b'));
-
-		const spy = countDisposals();
-		try {
-			memo.clear();
-			expect(spy.count()).toBe(2);
-		} finally {
-			spy.restore();
-		}
-	});
-
-	it('releases the old value when a key is overwritten', () => {
-		const memo = createSolveMemo();
-		memo.set({ k: 1 }, meshResult('old'));
-
-		const spy = countDisposals();
-		try {
-			memo.set({ k: 1 }, meshResult('new'));
-			expect(spy.count()).toBe(1);
-		} finally {
-			spy.restore();
-		}
-		expect(memo.get({ k: 1 })!.outputs).toEqual({ out: 'new' });
-	});
-
-	it('handles mesh-free results without touching disposal paths', () => {
-		const memo = createSolveMemo(1);
-		memo.set({ k: 1 }, result('1'));
-		memo.set({ k: 2 }, result('2')); // evicts k:1 — must not throw
-		expect(memo.get({ k: 2 })).toEqual(result('2'));
-	});
-});

package/src/lib/compute/solveMemo.ts

@@ -1,140 +0,0 @@
-// Client-side solve result memo (M2). A small LRU keyed on a stable serialization of
-// the solve INPUTS, sitting in front of the request/response driver. Dragging a slider
-// back to a value already solved this session returns instantly without a network
-// round-trip — killing slider-scrub storms before they leave the browser. It pairs with
-// the throttle's latest-wins abort: the memo only serves values that fully solved, so a
-// hit is always a complete result.
-//
-// GPU ownership (audit C1): a SolveResult carries live three.js objects, and the viewer
-// takes ownership of every mesh array it renders — `updateScene` disposes the previous
-// content on the next update. So the memo can neither hand out its own instances (they'd
-// be disposed under it, then re-added dead on the next hit) nor drop entries silently
-// (their GPU buffers would leak). It therefore keeps private copies, serves a fresh clone
-// per hit, and disposes an entry whenever it leaves the map.
-
-import * as THREE from 'three';
-import type { SolveResult } from '../types/solveFn';
-
-/**
- * Deterministic string key for a set of input values. Object keys are sorted at every
- * level so two logically-equal inputs (built in different key order) collide, matching
- * the server's stable-input keying intent. Values are plain JSON (numbers, strings,
- * booleans, arrays) — the projected solve inputs never contain functions or cycles.
- */
-export function stableInputKey(values: Record<string, unknown>): string {
-	return serialize(values);
-}
-
-function serialize(value: unknown): string {
-	if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
-	if (Array.isArray(value)) return `[${value.map(serialize).join(',')}]`;
-	const obj = value as Record<string, unknown>;
-	const keys = Object.keys(obj).sort();
-	return `{${keys.map((k) => `${JSON.stringify(k)}:${serialize(obj[k])}`).join(',')}}`;
-}
-
-/**
- * Deep-clone a solve's scene objects so the caller owns them outright.
- *
- * `Object3D.clone()` copies the transform hierarchy but SHARES `geometry` and `material`
- * by reference — which is exactly the aliasing that makes a naive clone useless here, so
- * geometry is copied explicitly. Materials are deliberately left shared: the viewer's
- * `clearScene` skips disposing anything in its SHARED_MATERIALS set (module-scope
- * singletons reused across solves), and per-mesh materials are cheap to recreate but
- * expensive to re-compile as new shader programs.
- */
-function cloneSceneObjects(meshes: THREE.Object3D[]): THREE.Object3D[] {
-	return meshes.map((root) => {
-		const copy = root.clone(true);
-		const sources: THREE.Object3D[] = [];
-		root.traverse((child) => sources.push(child));
-		let i = 0;
-		copy.traverse((child) => {
-			const source = sources[i++] as Partial<THREE.Mesh> & THREE.Object3D;
-			const target = child as Partial<THREE.Mesh> & THREE.Object3D;
-			if (source.geometry) target.geometry = source.geometry.clone();
-		});
-		return copy;
-	});
-}
-
-/**
- * Release an entry's GPU buffers. Mirrors `clearScene`'s traversal, minus materials —
- * the memo never owns those (see {@link cloneSceneObjects}), so disposing one here would
- * free a singleton still referenced by live scene content.
- */
-function disposeSceneObjects(result: SolveResult): void {
-	result.meshes?.forEach((root: THREE.Object3D) =>
-		root.traverse((child) => {
-			(child as Partial<THREE.Mesh>).geometry?.dispose();
-		})
-	);
-}
-
-export interface SolveMemo {
-	/** Returns a previously stored result for these inputs, or undefined on a miss. */
-	get(values: Record<string, unknown>): SolveResult | undefined;
-	/** Records a completed solve result under its input key (evicting the LRU tail). */
-	set(values: Record<string, unknown>, result: SolveResult): void;
-	/** Drops every entry — called when the active definition changes. */
-	clear(): void;
-}
-
-/**
- * A bounded LRU memo. `max` caps entries (not bytes); solve results can be large, so the
- * default is deliberately small — this targets the tight slider-scrub loop, not a durable
- * cache. Re-reading an entry refreshes its recency (Map insertion-order LRU).
- */
-export function createSolveMemo(max = 16): SolveMemo {
-	const entries = new Map<string, SolveResult>();
-
-	/** Drop an entry and release its GPU buffers. No-op when the key is absent. */
-	function evict(key: string): void {
-		const entry = entries.get(key);
-		if (entry === undefined) return;
-		entries.delete(key);
-		disposeSceneObjects(entry);
-	}
-
-	return {
-		get(values) {
-			const key = stableInputKey(values);
-			const hit = entries.get(key);
-			if (hit === undefined) return undefined;
-			// Refresh recency: re-insert at the tail.
-			entries.delete(key);
-			entries.set(key, hit);
-			// A memo hit skips the transport entirely, so no other log line fires —
-			// this line is the only trace it wasn't a fresh solve.
-			console.info(`[Compute/memo] HIT — served from client memo (${entries.size}/${max})`);
-			// Clone on the way out: the viewer disposes what it renders, so the retained
-			// entry must never be the instance handed to it (audit C1).
-			if (!hit.meshes?.length) return hit;
-			return { ...hit, meshes: cloneSceneObjects(hit.meshes) };
-		},
-		set(values, result) {
-			const key = stableInputKey(values);
-			// Overwriting a key strands the old value's buffers unless it's disposed first.
-			evict(key);
-			// Store a private copy for the same reason `get` clones: the caller reports this
-			// same object to the viewer, which will dispose it on the next scene update.
-			entries.set(
-				key,
-				result.meshes?.length ? { ...result, meshes: cloneSceneObjects(result.meshes) } : result
-			);
-			while (entries.size > max) {
-				const oldest = entries.keys().next().value;
-				if (oldest === undefined) break;
-				evict(oldest);
-				console.info(`[Compute/memo] evicted LRU entry (cap ${max})`);
-			}
-		},
-		clear() {
-			if (entries.size > 0) {
-				console.info(`[Compute/memo] cleared ${entries.size} entries (definition changed)`);
-			}
-			entries.forEach(disposeSceneObjects);
-			entries.clear();
-		}
-	};
-}

package/src/lib/external/storage.test.ts

@@ -1,99 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import {
-	getExternalInputs,
-	writeExternalValue,
-	readExternalValue,
-	clearExternalValue
-} from './storage';
-import type { UISchema } from '@selvajs/schemas';
-
-// getExternalInputs is the gate the whole client-input feature hangs on: it decides
-// which inputs a producer route must fill. These pin the source.kind === 'client'
-// filter and the displayName fallback. The read/write helpers are also covered with a
-// sessionStorage stub, including the no-storage guard (SSR / node).
-
-const input = (paramId: string, opts: { displayName?: string; source?: { kind: string } } = {}) =>
-	({ type: 'input', paramId, ...opts }) as never;
-
-function schema(items: unknown[]): UISchema {
-	return {
-		layout: { type: 'flat', groups: [{ id: 'g', label: 'g', items }] }
-	} as unknown as UISchema;
-}
-
-describe('getExternalInputs', () => {
-	it('keeps only inputs with source.kind === client', () => {
-		const s = schema([
-			input('a', { source: { kind: 'client' } }),
-			input('b', { source: { kind: 'user' } }),
-			input('c') // no source
-		]);
-		expect(getExternalInputs(s).map((e) => e.paramId)).toEqual(['a']);
-	});
-
-	it('falls back to paramId when displayName is absent', () => {
-		const s = schema([input('a', { source: { kind: 'client' } })]);
-		expect(getExternalInputs(s)[0].displayName).toBe('a');
-	});
-
-	it('uses displayName when present', () => {
-		const s = schema([input('a', { displayName: 'Width', source: { kind: 'client' } })]);
-		expect(getExternalInputs(s)[0].displayName).toBe('Width');
-	});
-});
-
-describe('read/write/clear with a sessionStorage stub', () => {
-	afterEach(() => {
-		vi.unstubAllGlobals();
-	});
-
-	function stubStorage() {
-		const store = new Map<string, string>();
-		vi.stubGlobal('sessionStorage', {
-			getItem: (k: string) => store.get(k) ?? null,
-			setItem: (k: string, v: string) => store.set(k, v),
-			removeItem: (k: string) => store.delete(k)
-		});
-		return store;
-	}
-
-	it('round-trips a value scoped by (scopeKey, inputId)', () => {
-		const store = stubStorage();
-		writeExternalValue({ scopeKey: 's1', inputId: 'p1', value: { x: 1 } });
-		expect(readExternalValue({ scopeKey: 's1', inputId: 'p1' })).toEqual({ x: 1 });
-		expect(store.has('external:s1:p1')).toBe(true);
-	});
-
-	it('scopes values so they do not bleed across scopeKey', () => {
-		stubStorage();
-		writeExternalValue({ scopeKey: 's1', inputId: 'p1', value: 'a' });
-		expect(readExternalValue({ scopeKey: 's2', inputId: 'p1' })).toBeUndefined();
-	});
-
-	it('clear removes the value', () => {
-		stubStorage();
-		writeExternalValue({ scopeKey: 's1', inputId: 'p1', value: 'a' });
-		clearExternalValue({ scopeKey: 's1', inputId: 'p1' });
-		expect(readExternalValue({ scopeKey: 's1', inputId: 'p1' })).toBeUndefined();
-	});
-
-	it('returns undefined for malformed JSON', () => {
-		const store = stubStorage();
-		store.set('external:s1:p1', '{not json');
-		expect(readExternalValue({ scopeKey: 's1', inputId: 'p1' })).toBeUndefined();
-	});
-});
-
-describe('no-storage guard (SSR / node)', () => {
-	it('read returns undefined and write/clear no-op when sessionStorage is absent', () => {
-		// node env: sessionStorage is undefined by default
-		expect(readExternalValue({ scopeKey: 's1', inputId: 'p1' })).toBeUndefined();
-		expect(() => writeExternalValue({ scopeKey: 's1', inputId: 'p1', value: 1 })).not.toThrow();
-		expect(() => clearExternalValue({ scopeKey: 's1', inputId: 'p1' })).not.toThrow();
-	});
-
-	it('ignores empty scopeKey or inputId', () => {
-		expect(readExternalValue({ scopeKey: '', inputId: 'p1' })).toBeUndefined();
-		expect(readExternalValue({ scopeKey: 's1', inputId: '' })).toBeUndefined();
-	});
-});

package/src/lib/types/solveFn.ts

@@ -1,29 +0,0 @@
-/**
- * Result returned from a solve operation.
- *
- * @property outputs - Key-value pairs of computed results
- * @property meshes - Optional array of 3D mesh data generated during computation
- * @property errors - Optional array of error messages that occurred
- * @property warnings - Optional array of warning messages from the computation
- */
-export interface SolveResult {
-	outputs: Record<string, unknown>;
-	meshes?: any[];
-	errors?: string[];
-	warnings?: string[];
-}
-
-/**
- * Function type for running a computation with given input values.
- *
- * Implementations should listen to the abort signal and clean up resources
- * when the signal is triggered (e.g., when the user cancels the operation).
- *
- * @param values - Input parameters for the computation
- * @param signal - AbortSignal to cancel ongoing operations
- * @returns Promise resolving to the computation result
- */
-export type SolveFn = (
-	values: Record<string, unknown>,
-	signal: AbortSignal
-) => Promise<SolveResult>;