@selvajs/ui 5.0.1 → 6.0.0-beta.0

package/dist/compute/solve-session-core.js

@@ -1,87 +0,0 @@
-// Pure, framework-free transition logic for a Solve Session (see CONTEXT.md).
-//
-// This module holds the value/lifecycle state machine with no Svelte runes and no
-// transport: how values are seeded (including client-sourced hydration), when a value
-// change should dispatch a solve vs. defer it, and what a reported solve result does to
-// the flags. The reactive wrapper in createSolveSession.svelte.ts is a thin shell over
-// these functions; everything testable lives here.
-import { getDefaultValue } from '../schema/defaults';
-import { getExternalInputs } from '../external/storage';
-/**
- * Builds the initial `values` map for a schema. Non-client inputs get their declared
- * default (falling back to the paramType default); client-sourced inputs are hydrated
- * from `read` and left absent when no stored value exists so the missing-inputs panel
- * can detect them. Outputs are seeded to null.
- */
-export function buildInitialValues(schema, scopeKey, read) {
-    const clientSet = new Set(getExternalInputs(schema).map((e) => e.paramId));
-    const values = {};
-    for (const input of schema.inputs) {
-        if (clientSet.has(input.id)) {
-            const stored = read({ scopeKey, inputId: input.id });
-            if (stored !== undefined)
-                values[input.id] = stored;
-            continue;
-        }
-        values[input.id] = input.default ?? getDefaultValue(input.paramType);
-    }
-    for (const output of schema.outputs) {
-        values[output.id] = null;
-    }
-    return values;
-}
-/**
- * Initial lifecycle flags. Manual-solve schemas (instanceSolve === false) start dirty
- * so the user must explicitly calculate; auto-solve schemas start clean.
- */
-export function makeInitialFlags(instanceSolve) {
-    const manual = instanceSolve === false;
-    return { hasPendingChanges: manual, hasNeverSolved: manual };
-}
-/**
- * Records a single value change and decides whether it should dispatch a solve now.
- * Auto-solve mode dispatches immediately; manual mode defers (records the pending value
- * and raises the dirty flag) and never dispatches.
- */
-export function applyValueChange(state, id, value, instanceSolve) {
-    state.values[id] = value;
-    if (instanceSolve === false) {
-        state.pendingValues[id] = value;
-        state.hasPendingChanges = true;
-        return { state, shouldSolve: false };
-    }
-    return { state, shouldSolve: true };
-}
-/**
- * Projects the session's live values down to solve INPUTS. Solve outputs are merged
- * into the same values map after each solve (applySolveResult) so widgets like
- * dynamic value lists can read them — but they are not solve inputs, and echoing
- * them back to the driver re-uploads potentially MB-sized payloads (a measured
- * 6.4 MB options list) that no backend reads. Every transport gets this projection
- * for free by going through the session's dispatch.
- */
-export function pickInputValues(schema, values) {
-    if (!schema?.inputs)
-        return values;
-    const picked = {};
-    for (const input of schema.inputs) {
-        if (input.id in values)
-            picked[input.id] = values[input.id];
-    }
-    return picked;
-}
-/**
- * Merges a reported solve result into the state and clears the post-solve lifecycle
- * flags. Missing result arrays are treated as empty.
- */
-export function applySolveResult(state, result) {
-    state.error = '';
-    state.computeErrors = result.errors ?? [];
-    state.computeWarnings = result.warnings ?? [];
-    state.meshes = result.meshes ?? [];
-    Object.assign(state.values, result.outputs);
-    state.pendingValues = {};
-    state.hasPendingChanges = false;
-    state.hasNeverSolved = false;
-    return state;
-}

package/dist/compute/solveMemo.d.ts

@@ -1,22 +0,0 @@
-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 declare function stableInputKey(values: Record<string, unknown>): string;
-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 declare function createSolveMemo(max?: number): SolveMemo;

package/dist/compute/solveMemo.js

@@ -1,124 +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';
-/**
- * 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) {
-    return serialize(values);
-}
-function serialize(value) {
-    if (value === null || typeof value !== 'object')
-        return JSON.stringify(value) ?? 'null';
-    if (Array.isArray(value))
-        return `[${value.map(serialize).join(',')}]`;
-    const obj = value;
-    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) {
-    return meshes.map((root) => {
-        const copy = root.clone(true);
-        const sources = [];
-        root.traverse((child) => sources.push(child));
-        let i = 0;
-        copy.traverse((child) => {
-            const source = sources[i++];
-            const target = child;
-            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) {
-    result.meshes?.forEach((root) => root.traverse((child) => {
-        child.geometry?.dispose();
-    }));
-}
-/**
- * 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) {
-    const entries = new Map();
-    /** Drop an entry and release its GPU buffers. No-op when the key is absent. */
-    function evict(key) {
-        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/dist/types/solveFn.d.ts

@@ -1,25 +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>;

package/dist/types/solveFn.js

@@ -1 +0,0 @@
-export {};

package/src/lib/compute/computeThrottle.svelte.ts

@@ -1,109 +0,0 @@
-/**
- * Compute throttle utility for managing async compute requests.
- *
- * - Only one request in-flight at a time
- * - Latest values always win (no queue)
- * - AbortController support to cancel stale requests
- * - Configurable timeout with automatic abort
- */
-interface ComputeThrottleOptions {
-	timeout?: number;
-}
-
-/**
- * Fallback per-solve abort timeout (ms) when the caller doesn't pass one.
- * Used only by callers without a deployment-specific limit (e.g. plugin-ui
- * over WebSocket); the selva app supplies `MAX_SOLVE_DURATION_MS` from its
- * server config via `ComputeApp`'s `solveTimeoutMs` prop.
- */
-const DEFAULT_TIMEOUT_MS = 60_000;
-
-/**
- * Creates a throttled compute handler that keeps only one request in-flight.
- * If a new value arrives while one is running, it overwrites the single pending
- * slot — older pending values are dropped. The pending value runs once the
- * current request finishes (or aborts).
- */
-export function createComputeThrottle<T>(
-	computeFn: (values: T, signal: AbortSignal) => Promise<void>,
-	options: ComputeThrottleOptions = {}
-): {
-	trigger: (values: T) => void;
-	readonly isComputing: boolean;
-	readonly hasPending: boolean;
-	cancel: () => void;
-} {
-	const { timeout = DEFAULT_TIMEOUT_MS } = options;
-
-	let isComputing = $state(false);
-	let pendingValues = $state<T | null>(null);
-	let currentAbortController: AbortController | null = null;
-
-	function abortCurrent() {
-		currentAbortController?.abort();
-		currentAbortController = null;
-	}
-
-	async function executeCompute(values: T) {
-		abortCurrent();
-
-		currentAbortController = new AbortController();
-		const { signal } = currentAbortController;
-		const timeoutId = setTimeout(() => {
-			// Cleared in `finally` on every other path, so firing means a genuine
-			// timeout — the only signal for it (the abort itself is swallowed below).
-			console.warn(`[Compute/throttle] solve exceeded ${timeout}ms — aborting`);
-			currentAbortController?.abort();
-		}, timeout);
-
-		isComputing = true;
-		try {
-			await computeFn(values, signal);
-		} catch (err) {
-			// AbortError is expected (timeout or cancel). Non-abort errors must be
-			// handled inside computeFn — re-throwing here would produce an unhandled
-			// rejection because executeCompute is always called fire-and-forget.
-			if (!(err instanceof Error) || (err.name !== 'AbortError' && err.name !== 'TimeoutError')) {
-				console.error('[computeThrottle] unhandled error in computeFn:', err);
-			}
-		} finally {
-			clearTimeout(timeoutId);
-			isComputing = false;
-			currentAbortController = null;
-
-			if (pendingValues !== null) {
-				const next = pendingValues;
-				pendingValues = null;
-				executeCompute(next);
-			}
-		}
-	}
-
-	function trigger(values: T) {
-		if (isComputing) {
-			if (pendingValues !== null) {
-				// Latest-wins: the previously-queued values are dropped, not solved.
-				console.debug('[Compute/throttle] superseded pending solve (latest-wins)');
-			}
-			pendingValues = values;
-		} else {
-			executeCompute(values);
-		}
-	}
-
-	function cancel() {
-		pendingValues = null;
-		abortCurrent();
-	}
-
-	return {
-		trigger,
-		get isComputing() {
-			return isComputing;
-		},
-		get hasPending() {
-			return pendingValues !== null;
-		},
-		cancel
-	};
-}

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

@@ -1,106 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { createComputeThrottle } from './computeThrottle.svelte';
-
-// Pins the throttle state machine: single-in-flight, latest-pending-wins, abort on
-// re-trigger, timeout -> abort, and cancel clearing the pending slot. These are the
-// non-obvious paths (the finally-block re-entry, the abort cleanup) where bugs hide.
-// `computeThrottle.svelte.ts` is a rune module, so these run under the svelte vitest
-// plugin (see vitest.config.ts).
-
-// A controllable computeFn: each call exposes a resolver so the test drives when a
-// solve "finishes", plus records the values and the signal it was given.
-function deferredComputeFn() {
-	const calls: { values: unknown; signal: AbortSignal; resolve: () => void }[] = [];
-	const fn = (values: unknown, signal: AbortSignal) =>
-		new Promise<void>((resolve) => {
-			calls.push({ values, signal, resolve });
-		});
-	return { fn, calls };
-}
-
-const tick = () => new Promise((r) => setTimeout(r, 0));
-
-describe('createComputeThrottle', () => {
-	it('runs immediately when idle and reports isComputing across the call', async () => {
-		const { fn, calls } = deferredComputeFn();
-		const t = createComputeThrottle<number>(fn);
-
-		expect(t.isComputing).toBe(false);
-		t.trigger(1);
-		expect(t.isComputing).toBe(true);
-		expect(calls).toHaveLength(1);
-		expect(calls[0].values).toBe(1);
-
-		calls[0].resolve();
-		await tick();
-		expect(t.isComputing).toBe(false);
-		expect(t.hasPending).toBe(false);
-	});
-
-	it('keeps only one in flight; latest pending value wins, intermediates dropped', async () => {
-		const { fn, calls } = deferredComputeFn();
-		const t = createComputeThrottle<number>(fn);
-
-		t.trigger(1); // runs
-		t.trigger(2); // queued
-		t.trigger(3); // overwrites the single pending slot — 2 is dropped
-		expect(calls).toHaveLength(1);
-		expect(t.hasPending).toBe(true);
-
-		calls[0].resolve(); // first finishes -> pending (3) runs
-		await tick();
-		expect(calls).toHaveLength(2);
-		expect(calls[1].values).toBe(3); // not 2
-		expect(t.hasPending).toBe(false);
-	});
-
-	it('aborts the in-flight request when a new one starts (after the pending re-entry)', async () => {
-		const { fn, calls } = deferredComputeFn();
-		const t = createComputeThrottle<number>(fn);
-
-		t.trigger(1);
-		t.trigger(2); // pending
-		const firstSignal = calls[0].signal;
-
-		calls[0].resolve(); // finishes -> re-enters executeCompute(2), which aborts the (already-cleared) prior
-		await tick();
-		// The second run gets a fresh, non-aborted signal.
-		expect(calls).toHaveLength(2);
-		expect(calls[1].signal.aborted).toBe(false);
-		expect(firstSignal).not.toBe(calls[1].signal);
-	});
-
-	it('cancel() clears the pending slot and aborts the in-flight signal', async () => {
-		const { fn, calls } = deferredComputeFn();
-		const t = createComputeThrottle<number>(fn);
-
-		t.trigger(1);
-		t.trigger(2); // pending
-		expect(t.hasPending).toBe(true);
-
-		t.cancel();
-		expect(t.hasPending).toBe(false);
-		expect(calls[0].signal.aborted).toBe(true);
-
-		// Resolving the aborted call must NOT start the (now-cleared) pending one.
-		calls[0].resolve();
-		await tick();
-		expect(calls).toHaveLength(1);
-	});
-
-	describe('timeout', () => {
-		beforeEach(() => vi.useFakeTimers());
-		afterEach(() => vi.useRealTimers());
-
-		it('aborts the in-flight request when the timeout elapses', async () => {
-			const { fn, calls } = deferredComputeFn();
-			const t = createComputeThrottle<number>(fn, { timeout: 1000 });
-
-			t.trigger(1);
-			expect(calls[0].signal.aborted).toBe(false);
-
-			vi.advanceTimersByTime(1000);
-			expect(calls[0].signal.aborted).toBe(true);
-		});
-	});
-});