@selvajs/ui 4.3.0 → 4.5.0

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

@@ -0,0 +1,106 @@
+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

@@ -0,0 +1,188 @@
+// 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 {
+	buildInitialValues,
+	makeInitialFlags,
+	applyValueChange,
+	applySolveResult,
+	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;
+}
+
+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. */
+	setValue(id: string, value: unknown): 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() {
+		args.driver.solve($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) {
+			const { shouldSolve } = applyValueChange(state, id, value, currentSchema?.instanceSolve);
+			if (shouldSolve) dispatch();
+		},
+
+		solve() {
+			dispatch();
+		},
+
+		loadValues(incoming) {
+			Object.assign(state.values, incoming);
+			if (currentSchema?.instanceSolve !== false) {
+				dispatch();
+			} else {
+				state.hasPendingChanges = true;
+			}
+		},
+
+		rebuild(schema, scopeKey) {
+			currentSchema = schema;
+			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 {
+	const throttle = createComputeThrottle<Record<string, unknown>>(async (values, signal) => {
+		try {
+			const result = await onSolve(values, signal);
+			if (signal.aborted) return;
+			getReporter().report(result);
+		} catch (err) {
+			if (signal.aborted) return;
+			getReporter().reportError(err instanceof Error ? err.message : String(err));
+		}
+	}, options);
+
+	return {
+		solve(values) {
+			throttle.trigger(values);
+		},
+		cancel() {
+			throttle.cancel();
+		},
+		get isSolving() {
+			return throttle.isComputing;
+		}
+	};
+}

package/src/lib/compute/solve-session-core.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'vitest';
+import {
+	buildInitialValues,
+	makeInitialFlags,
+	applyValueChange,
+	applySolveResult,
+	type SolveSessionState
+} from './solve-session-core';
+import type { UISchema } from '@selvajs/schemas';
+
+// These tests pin the lifecycle state machine that used to live inline in
+// ComputeApp.svelte: how values are seeded (incl. client-sourced hydration), when a
+// value change should dispatch a solve vs. defer it, and what a reported solve result
+// does to the flags. Reactivity is NOT exercised here — that's the thin rune wrapper's
+// job. This is the pure decision layer.
+
+// Minimal schema factory. `inputs`/`outputs` are the flat lists ComputeApp reads;
+// `layout` is what getExternalInputs walks for client-sourced inputs.
+function schema(partial: {
+	inputs?: { id: string; paramType: string; default?: unknown }[];
+	outputs?: { id: string }[];
+	clientInputs?: string[]; // ids that carry source.kind === 'client'
+	instanceSolve?: boolean;
+}): UISchema {
+	const clientSet = new Set(partial.clientInputs ?? []);
+	const items = (partial.inputs ?? []).map((i) => ({
+		type: 'input',
+		id: i.id,
+		paramId: i.id,
+		displayName: i.id,
+		...(clientSet.has(i.id) ? { source: { kind: 'client' } } : {})
+	}));
+	return {
+		id: 'test-schema',
+		name: 'Test',
+		instanceSolve: partial.instanceSolve,
+		inputs: partial.inputs ?? [],
+		outputs: partial.outputs ?? [],
+		layout: { type: 'flat', groups: [{ items }] }
+	} as unknown as UISchema;
+}
+
+describe('buildInitialValues', () => {
+	it('seeds non-client inputs from default, falling back to paramType default', () => {
+		const s = schema({
+			inputs: [
+				{ id: 'a', paramType: 'number', default: 5 },
+				{ id: 'b', paramType: 'text' } // no default -> getDefaultValue('text') === ''
+			],
+			outputs: [{ id: 'out' }]
+		});
+		const v = buildInitialValues(s, 'scope', () => undefined);
+		expect(v.a).toBe(5);
+		expect(v.b).toBe('');
+		expect(v.out).toBe(null); // outputs always seeded null
+	});
+
+	it('hydrates client-sourced inputs from the reader, leaving them undefined when absent', () => {
+		const s = schema({
+			inputs: [
+				{ id: 'c', paramType: 'text', default: 'should-be-ignored' },
+				{ id: 'd', paramType: 'text', default: 'also-ignored' }
+			],
+			clientInputs: ['c', 'd']
+		});
+		const read = (ref: { inputId: string }) => (ref.inputId === 'c' ? 'stored-c' : undefined);
+		const v = buildInitialValues(s, 'scope', read);
+		expect(v.c).toBe('stored-c');
+		// Absent client value stays undefined (NOT the default) so the missing-inputs
+		// panel can detect it.
+		expect('d' in v).toBe(false);
+	});
+});
+
+describe('makeInitialFlags', () => {
+	it('starts pending+never-solved when instanceSolve === false', () => {
+		expect(makeInitialFlags(false)).toEqual({ hasPendingChanges: true, hasNeverSolved: true });
+	});
+	it('starts clean when instanceSolve is true or absent', () => {
+		expect(makeInitialFlags(true)).toEqual({ hasPendingChanges: false, hasNeverSolved: false });
+		expect(makeInitialFlags(undefined)).toEqual({
+			hasPendingChanges: false,
+			hasNeverSolved: false
+		});
+	});
+});
+
+function state(overrides: Partial<SolveSessionState> = {}): SolveSessionState {
+	return {
+		values: {},
+		error: '',
+		computeErrors: [],
+		computeWarnings: [],
+		meshes: [],
+		pendingValues: {},
+		hasPendingChanges: false,
+		hasNeverSolved: false,
+		...overrides
+	};
+}
+
+describe('applyValueChange', () => {
+	it('in auto-solve mode, records the value and asks to dispatch', () => {
+		const s = state({ values: { a: 1 } });
+		const out = applyValueChange(s, 'a', 2, /* instanceSolve */ true);
+		expect(out.state.values.a).toBe(2);
+		expect(out.shouldSolve).toBe(true);
+		expect(out.state.hasPendingChanges).toBe(false);
+	});
+
+	it('in manual mode, defers: records pending + sets the flag, no dispatch', () => {
+		const s = state({ values: { a: 1 } });
+		const out = applyValueChange(s, 'a', 2, /* instanceSolve */ false);
+		expect(out.state.values.a).toBe(2);
+		expect(out.state.pendingValues.a).toBe(2);
+		expect(out.state.hasPendingChanges).toBe(true);
+		expect(out.shouldSolve).toBe(false);
+	});
+});
+
+describe('applySolveResult', () => {
+	it('merges outputs into values and clears the lifecycle flags', () => {
+		const s = state({
+			values: { a: 1, out: null },
+			pendingValues: { a: 1 },
+			hasPendingChanges: true,
+			hasNeverSolved: true,
+			error: 'stale'
+		});
+		const out = applySolveResult(s, {
+			outputs: { out: 42 },
+			errors: ['e'],
+			warnings: ['w'],
+			meshes: [{ id: 'm' }]
+		});
+		expect(out.values.out).toBe(42);
+		expect(out.values.a).toBe(1);
+		expect(out.computeErrors).toEqual(['e']);
+		expect(out.computeWarnings).toEqual(['w']);
+		expect(out.meshes).toEqual([{ id: 'm' }]);
+		expect(out.pendingValues).toEqual({});
+		expect(out.hasPendingChanges).toBe(false);
+		expect(out.hasNeverSolved).toBe(false);
+		expect(out.error).toBe('');
+	});
+
+	it('treats missing result arrays as empty', () => {
+		const out = applySolveResult(state(), { outputs: {} });
+		expect(out.computeErrors).toEqual([]);
+		expect(out.computeWarnings).toEqual([]);
+		expect(out.meshes).toEqual([]);
+	});
+});

package/src/lib/compute/solve-session-core.ts

@@ -0,0 +1,102 @@
+// 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 type { UISchema } from '@selvajs/schemas';
+import { getDefaultValue } from '../schema/defaults';
+import { getExternalInputs, type ExternalValueRef } from '../external/storage';
+import type { SolveResult } from '../types/solveFn';
+
+export interface SolveSessionState {
+	values: Record<string, unknown>;
+	error: string;
+	computeErrors: string[];
+	computeWarnings: string[];
+	meshes: unknown[];
+	/** Values changed since the last solve, in manual (instanceSolve === false) mode. */
+	pendingValues: Record<string, unknown>;
+	hasPendingChanges: boolean;
+	hasNeverSolved: boolean;
+}
+
+/** Reads a previously produced client-sourced value, or undefined if absent. */
+export type ExternalReader = (ref: ExternalValueRef) => unknown | undefined;
+
+/**
+ * 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: UISchema,
+	scopeKey: string,
+	read: ExternalReader
+): Record<string, unknown> {
+	const clientSet = new Set(getExternalInputs(schema).map((e) => e.paramId));
+	const values: Record<string, unknown> = {};
+	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: boolean | undefined): {
+	hasPendingChanges: boolean;
+	hasNeverSolved: boolean;
+} {
+	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: SolveSessionState,
+	id: string,
+	value: unknown,
+	instanceSolve: boolean | undefined
+): { state: SolveSessionState; shouldSolve: boolean } {
+	state.values[id] = value;
+	if (instanceSolve === false) {
+		state.pendingValues[id] = value;
+		state.hasPendingChanges = true;
+		return { state, shouldSolve: false };
+	}
+	return { state, shouldSolve: true };
+}
+
+/**
+ * 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: SolveSessionState, result: SolveResult): SolveSessionState {
+	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/src/lib/constants.ts

@@ -9,8 +9,6 @@ export const APP_DEFAULTS = {
 	TIMEOUTS: {
 		/** Duration to show solving state (ms) */
 		SOLVE_STATE_DURATION: 3500,
-		/** Parameter export callback delay (ms) */
-		PARAM_EXPORT_DELAY: 100,
 		/** Drawer open/close animation duration (ms) — matches the CSS transition. */
 		DRAWER_ANIMATION_MS: 350
 	},

package/src/lib/contexts/footerContext.svelte.ts

@@ -1,11 +1,21 @@
-import { getContext, setContext } from 'svelte';
+import { getContext, setContext, type Component } from 'svelte';
 import { SvelteMap } from 'svelte/reactivity';
 
-export interface FooterItem {
+/**
+ * A footer item registered by a descendant of the root layout. `component` + `position`
+ * are fixed at registration; the renderer re-invokes `getProps` reactively, so return
+ * reactive state from it (e.g. `() => ({ status: myState.status })`) to keep the footer
+ * in sync.
+ *
+ * Generic over the component's props `P` so registration is type-checked at the call
+ * site. The store holds a heterogeneous mix of items, so its map widens `P` to
+ * `Record<string, unknown>` at the boundary.
+ */
+export interface FooterItem<P extends Record<string, unknown> = Record<string, unknown>> {
 	id: string;
-	component: any;
-	/** Called on every render — return reactive state to keep footer in sync */
-	getProps: () => Record<string, any>;
+	component: Component<P>;
+	/** Called on every render — return reactive state to keep footer in sync. */
+	getProps: () => P;
 	position: 'left' | 'right';
 	priority: number;
 	onClick?: () => void;
@@ -13,13 +23,10 @@ export interface FooterItem {
 
 export interface FooterStore {
 	items: SvelteMap<string, FooterItem>;
-	register(
-		id: string,
-		component: any,
-		getProps: () => Record<string, any>,
-		position?: 'left' | 'right',
-		priority?: number,
-		onClick?: () => void
+	/** Register (or replace) a footer item. `position`/`priority` default to 'left'/0. */
+	register<P extends Record<string, unknown>>(
+		item: Omit<FooterItem<P>, 'position' | 'priority'> &
+			Partial<Pick<FooterItem<P>, 'position' | 'priority'>>
 	): void;
 	unregister(id: string): void;
 }
@@ -31,8 +38,16 @@ export function initializeFooterContext(): FooterStore {
 
 	const store: FooterStore = {
 		items,
-		register(id, component, getProps, position = 'left', priority = 0, onClick) {
-			items.set(id, { id, component, getProps, position, priority, onClick });
+		register(item) {
+			const { id, component, getProps, position = 'left', priority = 0, onClick } = item;
+			items.set(id, {
+				id,
+				component: component as Component<Record<string, unknown>>,
+				getProps: getProps as () => Record<string, unknown>,
+				position,
+				priority,
+				onClick
+			});
 		},
 		unregister(id) {
 			items.delete(id);