@selvajs/ui 5.0.0 → 6.0.0-beta.0

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

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

@@ -1,239 +0,0 @@
-// Reactive Solve Session (see CONTEXT.md): the $state-backed shell over the pure
-// transition logic in solve-session-core.ts. It owns the live values/flags, delegates
-// every transition to the core, and drives solves through a transport-agnostic
-// SolveDriver. A completed solve re-enters via report().
-
-import type { UISchema } from '@selvajs/schemas';
-import { readExternalValue } from '../external/storage';
-import type { SolveFn, SolveResult } from '../types/solveFn';
-import { createComputeThrottle } from './computeThrottle.svelte';
-import { createSolveMemo } from './solveMemo';
-import {
-	buildInitialValues,
-	makeInitialFlags,
-	applyValueChange,
-	applySolveResult,
-	pickInputValues,
-	type SolveSessionState
-} from './solve-session-core';
-
-/**
- * The transport behind a Solve Session. Knows how to start and cancel a solve and
- * reports its in-flight state. It does NOT return outputs — those come back via the
- * session's report() so push transports (WebSocket) fit without contortion.
- */
-export interface SolveDriver {
-	solve(values: Record<string, unknown>): void;
-	cancel(): void;
-	readonly isSolving: boolean;
-	/**
-	 * Drops any cached solve results the driver holds. Optional — only drivers with a
-	 * client-side memo (the request/response driver) implement it. Called on rebuild so a
-	 * definition swap can't serve a stale result from a prior definition's input space.
-	 */
-	clearCache?(): void;
-}
-
-export interface SolveSession {
-	readonly values: Record<string, unknown>;
-	readonly error: string;
-	readonly computeErrors: string[];
-	readonly computeWarnings: string[];
-	readonly meshes: unknown[];
-	readonly hasPendingChanges: boolean;
-	readonly hasNeverSolved: boolean;
-	readonly isSolving: boolean;
-	/**
-	 * Records a value change and dispatches a solve unless the schema is manual-solve.
-	 * `forceSolve` overrides manual mode for system-initiated reconciliation (e.g. a dynamic
-	 * value list pruning a vanished selection), so the output can't lag behind the new value.
-	 */
-	setValue(id: string, value: unknown, forceSolve?: boolean): void;
-	/** Explicit "calculate" — dispatches a solve with the current values. */
-	solve(): void;
-	/** Merges incoming values, then solves (auto) or marks dirty (manual). */
-	loadValues(incoming: Record<string, unknown>): void;
-	/** Re-seed for a new active definition: rebuild values, clear outputs, gate the solve. */
-	rebuild(schema: UISchema, scopeKey: string): void;
-	/** Feed a completed solve result back into the session (called by the driver/host). */
-	report(result: SolveResult): void;
-	/** Report a solve failure (transport/solver error) — surfaces in `error`. */
-	reportError(message: string): void;
-}
-
-export interface SolveSessionArgs {
-	schema: UISchema;
-	scopeKey: string;
-	driver: SolveDriver;
-}
-
-export function createSolveSession(args: SolveSessionArgs): SolveSession {
-	let currentSchema = args.schema;
-
-	const flags = makeInitialFlags(currentSchema?.instanceSolve);
-	const state = $state<SolveSessionState>({
-		values: buildInitialValues(currentSchema, args.scopeKey, readExternalValue),
-		error: '',
-		computeErrors: [],
-		computeWarnings: [],
-		meshes: [],
-		pendingValues: {},
-		hasPendingChanges: flags.hasPendingChanges,
-		hasNeverSolved: flags.hasNeverSolved
-	});
-
-	function dispatch() {
-		// Input values only: outputs merged into state.values (for widgets that read
-		// them, e.g. dynamic value lists) must not be echoed back to the transport.
-		args.driver.solve(pickInputValues(currentSchema, $state.snapshot(state.values)));
-	}
-
-	return {
-		get values() {
-			return state.values;
-		},
-		get error() {
-			return state.error;
-		},
-		get computeErrors() {
-			return state.computeErrors;
-		},
-		get computeWarnings() {
-			return state.computeWarnings;
-		},
-		get meshes() {
-			return state.meshes;
-		},
-		get hasPendingChanges() {
-			return state.hasPendingChanges;
-		},
-		get hasNeverSolved() {
-			return state.hasNeverSolved;
-		},
-		get isSolving() {
-			return args.driver.isSolving;
-		},
-
-		setValue(id, value, forceSolve = false) {
-			const { shouldSolve } = applyValueChange(state, id, value, currentSchema?.instanceSolve);
-			if (shouldSolve || forceSolve) {
-				// A forced solve reconciles the deferred output; clear the dirty flags it raised.
-				if (forceSolve && !shouldSolve) {
-					state.pendingValues = {};
-					state.hasPendingChanges = false;
-				}
-				dispatch();
-			}
-		},
-
-		solve() {
-			dispatch();
-		},
-
-		loadValues(incoming) {
-			Object.assign(state.values, incoming);
-			if (currentSchema?.instanceSolve !== false) {
-				dispatch();
-			} else {
-				state.hasPendingChanges = true;
-			}
-		},
-
-		rebuild(schema, scopeKey) {
-			currentSchema = schema;
-			// Drop the driver's result memo: the new definition has its own input space, so
-			// a matching input key from the prior definition must not serve its stale result.
-			args.driver.clearCache?.();
-			state.meshes = [];
-			state.error = '';
-			state.computeErrors = [];
-			state.computeWarnings = [];
-			state.pendingValues = {};
-			state.values = buildInitialValues(schema, scopeKey, readExternalValue);
-			const f = makeInitialFlags(schema?.instanceSolve);
-			state.hasPendingChanges = f.hasPendingChanges;
-			state.hasNeverSolved = f.hasNeverSolved;
-			if (schema && Object.keys(state.values).length > 0 && schema.instanceSolve !== false) {
-				dispatch();
-			}
-		},
-
-		report(result) {
-			applySolveResult(state, result);
-		},
-
-		reportError(message) {
-			state.error = message;
-		}
-	};
-}
-
-/** The slice of a SolveSession a driver feeds completed/failed solves back into. */
-export interface SolveReporter {
-	report(result: SolveResult): void;
-	reportError(message: string): void;
-}
-
-/**
- * Request/response Solve Driver: wraps createComputeThrottle around a SolveFn and feeds
- * the resolved result back through the reporter. One solve in flight at a time; the
- * latest triggered values win. Used by ComputeApp (Rhino.Compute over HTTP).
- *
- * Because the session and driver reference each other, the host passes the reporter
- * lazily (`() => session`) so it can construct the session with the driver in hand.
- */
-export function createRequestResponseDriver(
-	onSolve: SolveFn,
-	getReporter: () => SolveReporter,
-	options: { timeout?: number } = {}
-): SolveDriver {
-	// M2: a small LRU memoizing completed solves by their input values. A slider dragged
-	// back to a value already solved this session reports instantly without a network
-	// round-trip. The check lives inside the throttled computeFn so the throttle's
-	// latest-wins ordering still holds — a hit only serves after the throttle picks these
-	// values as the ones to run.
-	const memo = createSolveMemo();
-
-	const throttle = createComputeThrottle<Record<string, unknown>>(async (values, signal) => {
-		const cached = memo.get(values);
-		if (cached !== undefined) {
-			if (signal.aborted) return;
-			getReporter().report(cached);
-			return;
-		}
-		try {
-			const result = await onSolve(values, signal);
-			if (signal.aborted) {
-				// Discarded on purpose (superseded/cancelled) — never memoized or reported.
-				console.debug('[Compute/session] solve completed after abort — result discarded');
-				return;
-			}
-			memo.set(values, result);
-			getReporter().report(result);
-		} catch (err) {
-			if (signal.aborted) {
-				console.debug('[Compute/session] solve aborted (superseded, cancelled, or timed out)');
-				return;
-			}
-			// reportError only sets reactive state; without this line a transport
-			// failure leaves no console trace at all.
-			console.warn('[Compute/session] solve failed:', err);
-			getReporter().reportError(err instanceof Error ? err.message : String(err));
-		}
-	}, options);
-
-	return {
-		solve(values) {
-			throttle.trigger(values);
-		},
-		cancel() {
-			throttle.cancel();
-		},
-		get isSolving() {
-			return throttle.isComputing;
-		},
-		clearCache() {
-			memo.clear();
-		}
-	};
-}

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

@@ -1,168 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import {
-	createSolveSession,
-	createRequestResponseDriver,
-	type SolveDriver,
-	type SolveReporter
-} from './createSolveSession.svelte';
-import type { UISchema } from '@selvajs/schemas';
-import type { SolveResult } from '../types/solveFn';
-
-// Covers the reactive wrapper's dispatch decisions — specifically the `forceSolve` path
-// added for dynamic-value-list reconciliation. The pure transition logic is pinned in
-// solve-session-core.test.ts; this file pins how the rune shell turns those decisions into
-// driver.solve() calls. Rune module, so it runs under the svelte vitest plugin.
-
-function schema(instanceSolve?: boolean): UISchema {
-	return {
-		id: 'test',
-		name: 'Test',
-		instanceSolve,
-		inputs: [{ id: 'a', paramId: 'a', paramType: 'text', default: 'x' }],
-		outputs: [{ id: 'out' }],
-		layout: { type: 'flat', groups: [{ items: [] }] }
-	} as unknown as UISchema;
-}
-
-// Records every solve dispatch with the snapshot of values it received.
-function recordingDriver(): SolveDriver & { solves: Record<string, unknown>[] } {
-	const solves: Record<string, unknown>[] = [];
-	return {
-		solves,
-		solve(values) {
-			solves.push(values);
-		},
-		cancel() {},
-		get isSolving() {
-			return false;
-		}
-	};
-}
-
-describe('createSolveSession.setValue', () => {
-	it('auto-solve mode dispatches on every value change', () => {
-		const driver = recordingDriver();
-		const session = createSolveSession({ schema: schema(true), scopeKey: 's', driver });
-		session.setValue('a', 'y');
-		expect(driver.solves.length).toBe(1);
-		expect(driver.solves[0].a).toBe('y');
-	});
-
-	it('manual mode defers: marks pending, no dispatch', () => {
-		const driver = recordingDriver();
-		const session = createSolveSession({ schema: schema(false), scopeKey: 's', driver });
-		session.setValue('a', 'y');
-		expect(driver.solves.length).toBe(0);
-		expect(session.hasPendingChanges).toBe(true);
-	});
-
-	it('forceSolve dispatches even in manual mode and clears the dirty flags', () => {
-		const driver = recordingDriver();
-		const session = createSolveSession({ schema: schema(false), scopeKey: 's', driver });
-		// Reconcile a system-initiated change (e.g. a pruned dynamic-list selection).
-		session.setValue('a', 'reconciled', true);
-		expect(driver.solves.length).toBe(1);
-		expect(driver.solves[0].a).toBe('reconciled');
-		// The forced solve produces the matching output, so nothing is left pending.
-		expect(session.hasPendingChanges).toBe(false);
-	});
-
-	it('forceSolve in auto mode still dispatches exactly once', () => {
-		const driver = recordingDriver();
-		const session = createSolveSession({ schema: schema(true), scopeKey: 's', driver });
-		session.setValue('a', 'y', true);
-		expect(driver.solves.length).toBe(1);
-	});
-
-	it('never echoes output-keyed values back to the driver', () => {
-		const driver = recordingDriver();
-		const session = createSolveSession({ schema: schema(true), scopeKey: 's', driver });
-		// A solve result merges outputs into the session's values map (how widgets
-		// like dynamic value lists read them) — e.g. a multi-MB options payload.
-		session.report({ outputs: { out: { options: { huge: 'payload' } } } });
-		session.setValue('a', 'y');
-		expect(driver.solves.length).toBe(1);
-		expect(driver.solves[0].a).toBe('y');
-		// The output entry lives in session.values for widgets…
-		expect(session.values.out).toBeDefined();
-		// …but must not travel back through the transport.
-		expect(driver.solves[0]).not.toHaveProperty('out');
-	});
-});
-
-// M2: the request/response driver's client-side result memo. Verifies a slider returning
-// to a solved value serves from memory (no onSolve call) and that a definition rebuild
-// drops the memo so a stale result can't cross the swap.
-describe('createRequestResponseDriver — client memo', () => {
-	// Collects reported results so the memo hit/miss can be observed without a session.
-	function collectingReporter(): SolveReporter & { reports: SolveResult[]; errors: string[] } {
-		const reports: SolveResult[] = [];
-		const errors: string[] = [];
-		return {
-			reports,
-			errors,
-			report: (r) => reports.push(r),
-			reportError: (m) => errors.push(m)
-		};
-	}
-
-	// Lets the throttle's fire-and-forget executeCompute settle.
-	const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
-
-	it('serves a repeated input from the memo without calling onSolve again', async () => {
-		const onSolve = vi.fn(
-			async (values: Record<string, unknown>): Promise<SolveResult> => ({
-				outputs: { echo: values.a }
-			})
-		);
-		const reporter = collectingReporter();
-		const driver = createRequestResponseDriver(onSolve, () => reporter);
-
-		driver.solve({ a: 1 });
-		await flush();
-		driver.solve({ a: 2 });
-		await flush();
-		driver.solve({ a: 1 }); // repeat — should hit the memo
-		await flush();
-
-		expect(onSolve).toHaveBeenCalledTimes(2); // only the two distinct inputs
-		expect(reporter.reports).toHaveLength(3); // but all three solves reported
-		expect(reporter.reports[2]).toEqual({ outputs: { echo: 1 } });
-	});
-
-	it('clearCache drops the memo so the next identical solve re-runs', async () => {
-		const onSolve = vi.fn(async (): Promise<SolveResult> => ({ outputs: {} }));
-		const reporter = collectingReporter();
-		const driver = createRequestResponseDriver(onSolve, () => reporter);
-
-		driver.solve({ a: 1 });
-		await flush();
-		driver.clearCache?.();
-		driver.solve({ a: 1 }); // memo cleared → real solve again
-		await flush();
-
-		expect(onSolve).toHaveBeenCalledTimes(2);
-	});
-
-	it('session.rebuild clears the driver memo (no cross-definition stale hit)', async () => {
-		const onSolve = vi.fn(async (): Promise<SolveResult> => ({ outputs: {} }));
-		const reporter = collectingReporter();
-		let clears = 0;
-		// Wrap the real driver to observe clearCache being invoked from rebuild.
-		const base = createRequestResponseDriver(onSolve, () => reporter);
-		const driver: SolveDriver = {
-			solve: base.solve,
-			cancel: base.cancel,
-			get isSolving() {
-				return base.isSolving;
-			},
-			clearCache() {
-				clears += 1;
-				base.clearCache?.();
-			}
-		};
-		const session = createSolveSession({ schema: schema(true), scopeKey: 's', driver });
-		session.rebuild(schema(true), 's2');
-		expect(clears).toBe(1);
-	});
-});