@selvajs/ui 0.9.0

package/dist/compute/computeThrottle.svelte.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare function createComputeThrottle<T>(computeFn: (values: T, signal: AbortSignal) => Promise<void>, options?: ComputeThrottleOptions): {
+    trigger: (values: T) => void;
+    readonly isComputing: boolean;
+    readonly hasPending: boolean;
+    cancel: () => void;
+};
+export {};

package/dist/compute/computeThrottle.svelte.js

@@ -0,0 +1,70 @@
+/**
+ * Fallback per-solve abort timeout (ms) when the caller doesn't pass one.
+ * Used only by callers without a deployment-specific limit (e.g. builder-app
+ * over WebSocket); compute-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(computeFn, options = {}) {
+    const { timeout = DEFAULT_TIMEOUT_MS } = options;
+    let isComputing = $state(false);
+    let pendingValues = $state(null);
+    let currentAbortController = null;
+    function abortCurrent() {
+        currentAbortController?.abort();
+        currentAbortController = null;
+    }
+    async function executeCompute(values) {
+        abortCurrent();
+        currentAbortController = new AbortController();
+        const { signal } = currentAbortController;
+        const timeoutId = setTimeout(() => currentAbortController?.abort(), timeout);
+        isComputing = true;
+        try {
+            await computeFn(values, signal);
+        }
+        catch (err) {
+            if (!(err instanceof Error && err.name === 'AbortError')) {
+                throw err;
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+            isComputing = false;
+            currentAbortController = null;
+            if (pendingValues !== null) {
+                const next = pendingValues;
+                pendingValues = null;
+                executeCompute(next);
+            }
+        }
+    }
+    function trigger(values) {
+        if (isComputing) {
+            pendingValues = values;
+        }
+        else {
+            executeCompute(values);
+        }
+    }
+    function cancel() {
+        pendingValues = null;
+        abortCurrent();
+    }
+    return {
+        trigger,
+        get isComputing() {
+            return isComputing;
+        },
+        get hasPending() {
+            return pendingValues !== null;
+        },
+        cancel
+    };
+}

package/dist/compute/solving.svelte.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Creates an adaptive solving indicator that measures actual solve durations
+ * and adjusts its visibility delay accordingly.
+ *
+ * - Fast solves (<200ms avg): indicator never shown (avoids flicker)
+ * - Slow solves (>600ms avg): indicator shown immediately
+ * - In between: indicator shown after a proportional delay
+ * - First solve: shows immediately (no history yet)
+ */
+export declare function createSolvingIndicator(isSolving: () => boolean): {
+    readonly show: boolean;
+};

package/dist/compute/solving.svelte.js

@@ -0,0 +1,68 @@
+import { untrack } from 'svelte';
+import { APP_DEFAULTS } from '../constants';
+/**
+ * Creates an adaptive solving indicator that measures actual solve durations
+ * and adjusts its visibility delay accordingly.
+ *
+ * - Fast solves (<200ms avg): indicator never shown (avoids flicker)
+ * - Slow solves (>600ms avg): indicator shown immediately
+ * - In between: indicator shown after a proportional delay
+ * - First solve: shows immediately (no history yet)
+ */
+export function createSolvingIndicator(isSolving) {
+    const { FAST_THRESHOLD_MS, SLOW_THRESHOLD_MS, HISTORY_SIZE, ANIMATION_DELAY } = APP_DEFAULTS.SOLVING_INDICATOR;
+    let show = $state(false);
+    let timeout = null;
+    let solveStartTime = null;
+    const solveHistory = [];
+    $effect(() => {
+        const solving = isSolving();
+        untrack(() => {
+            if (solving) {
+                solveStartTime = performance.now();
+                const avg = solveHistory.length === 0
+                    ? Infinity
+                    : solveHistory.reduce((a, b) => a + b, 0) / solveHistory.length;
+                if (solveHistory.length > 0 && avg < FAST_THRESHOLD_MS)
+                    return;
+                const delay = avg === Infinity || avg >= SLOW_THRESHOLD_MS
+                    ? 0
+                    : ((avg - FAST_THRESHOLD_MS) / (SLOW_THRESHOLD_MS - FAST_THRESHOLD_MS)) *
+                        ANIMATION_DELAY;
+                if (!timeout) {
+                    if (delay === 0) {
+                        show = true;
+                    }
+                    else {
+                        timeout = setTimeout(() => {
+                            show = true;
+                            timeout = null;
+                        }, delay);
+                    }
+                }
+            }
+            else {
+                if (solveStartTime !== null) {
+                    solveHistory.push(performance.now() - solveStartTime);
+                    if (solveHistory.length > HISTORY_SIZE)
+                        solveHistory.shift();
+                    solveStartTime = null;
+                }
+                if (timeout) {
+                    clearTimeout(timeout);
+                    timeout = null;
+                }
+                show = false;
+            }
+        });
+        return () => {
+            if (timeout)
+                clearTimeout(timeout);
+        };
+    });
+    return {
+        get show() {
+            return show;
+        }
+    };
+}

package/dist/constants.d.ts

@@ -0,0 +1,28 @@
+export declare const APP_DEFAULTS: {
+    FILE_UPLOAD: {
+        MAX_SIZE_MB: number;
+        MAX_SIZE_BYTES: number;
+    };
+    TIMEOUTS: {
+        /** Duration to show solving state (ms) */
+        SOLVE_STATE_DURATION: number;
+        /** Parameter export callback delay (ms) */
+        PARAM_EXPORT_DELAY: number;
+        /** Viewer initialization delay (ms) */
+        VIEWER_INIT_DELAY: number;
+    };
+    SOLVING_INDICATOR: {
+        /** If solve is faster than this, don't show indicator (ms) */
+        FAST_THRESHOLD_MS: number;
+        /** If solve is slower than this, show indicator immediately (ms) */
+        SLOW_THRESHOLD_MS: number;
+        /** Animation delay for solve indicator (ms) */
+        ANIMATION_DELAY: number;
+        /** Number of solve durations to keep in history for averaging */
+        HISTORY_SIZE: number;
+    };
+    FILE_SIZE: {
+        /** Bytes per kilobyte */
+        BYTES_PER_KB: number;
+    };
+};

package/dist/constants.js

@@ -0,0 +1,32 @@
+export const APP_DEFAULTS = {
+    // File upload limits
+    FILE_UPLOAD: {
+        MAX_SIZE_MB: 150,
+        MAX_SIZE_BYTES: 150 * 1024 * 1024
+    },
+    // Timing & performance thresholds
+    TIMEOUTS: {
+        /** Duration to show solving state (ms) */
+        SOLVE_STATE_DURATION: 3500,
+        /** Parameter export callback delay (ms) */
+        PARAM_EXPORT_DELAY: 100,
+        /** Viewer initialization delay (ms) */
+        VIEWER_INIT_DELAY: 350
+    },
+    // Solving indicator adaptive thresholds
+    SOLVING_INDICATOR: {
+        /** If solve is faster than this, don't show indicator (ms) */
+        FAST_THRESHOLD_MS: 200,
+        /** If solve is slower than this, show indicator immediately (ms) */
+        SLOW_THRESHOLD_MS: 600,
+        /** Animation delay for solve indicator (ms) */
+        ANIMATION_DELAY: 300,
+        /** Number of solve durations to keep in history for averaging */
+        HISTORY_SIZE: 3
+    },
+    // File size formatting
+    FILE_SIZE: {
+        /** Bytes per kilobyte */
+        BYTES_PER_KB: 1024
+    }
+};

package/dist/contexts/footerContext.svelte.d.ts

@@ -0,0 +1,18 @@
+import { SvelteMap } from 'svelte/reactivity';
+export interface FooterItem {
+    id: string;
+    component: any;
+    /** Called on every render — return reactive state to keep footer in sync */
+    getProps: () => Record<string, any>;
+    position: 'left' | 'right';
+    priority: number;
+    onClick?: () => void;
+}
+export interface FooterStore {
+    items: SvelteMap<string, FooterItem>;
+    register(id: string, component: any, getProps: () => Record<string, any>, position?: 'left' | 'right', priority?: number, onClick?: () => void): void;
+    unregister(id: string): void;
+}
+export declare const FOOTER_CONTEXT_KEY: unique symbol;
+export declare function initializeFooterContext(): FooterStore;
+export declare function useFooter(): FooterStore;

package/dist/contexts/footerContext.svelte.js

@@ -0,0 +1,24 @@
+import { getContext, setContext } from 'svelte';
+import { SvelteMap } from 'svelte/reactivity';
+export const FOOTER_CONTEXT_KEY = Symbol('footer-context');
+export function initializeFooterContext() {
+    const items = new SvelteMap();
+    const store = {
+        items,
+        register(id, component, getProps, position = 'left', priority = 0, onClick) {
+            items.set(id, { id, component, getProps, position, priority, onClick });
+        },
+        unregister(id) {
+            items.delete(id);
+        }
+    };
+    setContext(FOOTER_CONTEXT_KEY, store);
+    return store;
+}
+export function useFooter() {
+    const store = getContext(FOOTER_CONTEXT_KEY);
+    if (!store) {
+        throw new Error('useFooter must be called within a component that is a descendant of the root layout');
+    }
+    return store;
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export * from './components/layout';
+export { default as AppLayout } from './components/compute/AppLayout.svelte';
+export { default as ComputeApp } from './components/compute/ComputeApp.svelte';
+export { default as ErrorScreen } from './components/ErrorScreen.svelte';
+export * from './components/primitives';
+export { default as StateDisplay } from './components/primitives/StateDisplay.svelte';
+export { default as Viewer } from './components/viewer/Viewer.svelte';
+export * from './schema/defaults';
+export * from './compute/solving.svelte';
+export * from './contexts/footerContext.svelte';
+export * from './composables/useFooterItem.svelte';
+export * from './utils';
+export type { ActionButton } from './types/actionButton';
+export type { SolveFn } from './types/solveFn';

package/dist/index.js

@@ -0,0 +1,20 @@
+// Layout components (page chrome: shell, header, footer, nav)
+export * from './components/layout';
+// Compute app (schema + viewer + solve controls composed into a runnable app)
+export { default as AppLayout } from './components/compute/AppLayout.svelte';
+export { default as ComputeApp } from './components/compute/ComputeApp.svelte';
+// Error screen
+export { default as ErrorScreen } from './components/ErrorScreen.svelte';
+// Design-system primitives (shadcn-svelte + custom)
+export * from './components/primitives';
+export { default as StateDisplay } from './components/primitives/StateDisplay.svelte';
+// 3D viewer
+export { default as Viewer } from './components/viewer/Viewer.svelte';
+// Utilities
+export * from './schema/defaults';
+export * from './compute/solving.svelte';
+// Contexts & Composables
+export * from './contexts/footerContext.svelte';
+export * from './composables/useFooterItem.svelte';
+// Utils (cn function)
+export * from './utils';

package/dist/schema/defaults.d.ts

@@ -0,0 +1 @@
+export declare function getDefaultValue(paramType: string): unknown;

package/dist/schema/defaults.js

@@ -0,0 +1,13 @@
+export function getDefaultValue(paramType) {
+    switch (paramType) {
+        case 'number':
+        case 'integer':
+            return 0;
+        case 'boolean':
+            return false;
+        case 'text':
+            return '';
+        default:
+            return null;
+    }
+}

package/dist/schema/param-exporter.d.ts

@@ -0,0 +1,15 @@
+import type { UISchema, ParameterPreset, ValidationIssueMessage } from '@selvajs/schemas';
+export declare function createSavedState(schema: UISchema, currentValues: Record<string, unknown>, metadata: {
+    name: string;
+    description?: string;
+    author?: string;
+    tags?: string[];
+}): ParameterPreset;
+export declare function validateSavedState(savedState: ParameterPreset, currentSchema: UISchema): {
+    isValid: boolean;
+    issues: ValidationIssueMessage[];
+    canLoad: boolean;
+};
+export declare function extractLoadableValues(savedState: ParameterPreset, currentSchema: UISchema, validation: ReturnType<typeof validateSavedState>): Record<string, unknown>;
+export declare function exportStateAsJson(savedState: ParameterPreset): void;
+export declare function importStateFromJson(file: File): Promise<ParameterPreset>;

package/dist/schema/param-exporter.js

@@ -0,0 +1,120 @@
+import { APP_DEFAULTS } from '../constants';
+function getGroups(schema) {
+    if (!schema.layout)
+        return [];
+    if (schema.layout.type === 'tabbed')
+        return schema.layout.tabs.flatMap((t) => t.groups ?? []);
+    if (schema.layout.type === 'flat')
+        return schema.layout.groups ?? [];
+    return [];
+}
+export function createSavedState(schema, currentValues, metadata) {
+    const parameters = [];
+    for (const group of getGroups(schema)) {
+        for (const item of group.items ?? []) {
+            if (item.type !== 'input')
+                continue;
+            const value = currentValues[item.paramId];
+            const inputDef = schema.inputs.find((i) => i.id === item.paramId);
+            if (value !== undefined && inputDef) {
+                parameters.push({
+                    paramId: item.paramId,
+                    nickname: inputDef.nickname,
+                    displayName: item.displayName || inputDef.nickname,
+                    paramType: inputDef.paramType,
+                    value,
+                    groupName: group.label
+                });
+            }
+        }
+    }
+    return {
+        id: crypto.randomUUID(),
+        name: metadata.name,
+        description: metadata.description,
+        timestamp: new Date().toISOString(),
+        schemaId: schema.id,
+        documentId: schema.documentId ?? '',
+        projectFileName: schema.projectFileName ?? '',
+        pluginVersion: schema.pluginVersion ?? '',
+        author: metadata.author,
+        tags: metadata.tags ?? [],
+        parameters
+    };
+}
+export function validateSavedState(savedState, currentSchema) {
+    const issues = [];
+    if (savedState.documentId !== (currentSchema.documentId ?? '')) {
+        issues.push({
+            paramId: '__document__',
+            severity: 'error',
+            message: 'Document ID mismatch - this state was saved for a different document',
+            details: { expected: currentSchema.documentId ?? '', actual: savedState.documentId }
+        });
+    }
+    if (savedState.schemaId !== currentSchema.id) {
+        issues.push({
+            paramId: '__schema__',
+            severity: 'warning',
+            message: 'Schema has changed since this state was saved',
+            details: { expected: currentSchema.id, actual: savedState.schemaId }
+        });
+    }
+    for (const paramState of savedState.parameters) {
+        const inputDef = currentSchema.inputs.find((i) => i.id === paramState.paramId);
+        if (!inputDef) {
+            issues.push({
+                paramId: paramState.paramId,
+                severity: 'error',
+                message: `Parameter "${paramState.nickname}" no longer exists in the schema`
+            });
+            continue;
+        }
+        if (inputDef.nickname !== paramState.nickname) {
+            issues.push({
+                paramId: paramState.paramId,
+                severity: 'warning',
+                message: 'Parameter nickname changed',
+                details: { expected: paramState.nickname, actual: inputDef.nickname }
+            });
+        }
+    }
+    const hasErrors = issues.some((i) => i.severity === 'error');
+    return { isValid: issues.length === 0, issues, canLoad: !hasErrors };
+}
+export function extractLoadableValues(savedState, currentSchema, validation) {
+    const errorParamIds = new Set(validation.issues
+        .filter((i) => i.severity === 'error' && !i.paramId.startsWith('__'))
+        .map((i) => i.paramId));
+    const values = {};
+    for (const paramState of savedState.parameters) {
+        const exists = currentSchema.inputs.some((i) => i.id === paramState.paramId);
+        if (!errorParamIds.has(paramState.paramId) && exists) {
+            values[paramState.paramId] = paramState.value;
+        }
+    }
+    return values;
+}
+export function exportStateAsJson(savedState) {
+    const blob = new Blob([JSON.stringify(savedState, null, 2)], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = `${savedState.name.replace(/[^a-z0-9]/gi, '_')}_${savedState.timestamp.split('T')[0].replace(/-/g, '_')}.sps`;
+    link.style.display = 'none';
+    document.body.appendChild(link);
+    setTimeout(() => {
+        link.click();
+        setTimeout(() => {
+            document.body.removeChild(link);
+            URL.revokeObjectURL(url);
+        }, APP_DEFAULTS.TIMEOUTS.PARAM_EXPORT_DELAY);
+    }, 0);
+}
+export async function importStateFromJson(file) {
+    const state = JSON.parse(await file.text());
+    if (!state.id || !state.name || !state.documentId || !state.parameters) {
+        throw new Error('Invalid saved state file format');
+    }
+    return state;
+}

package/dist/schema/visibility-rules.d.ts

@@ -0,0 +1,12 @@
+import type { LayoutItem, VisibilityRule, VisibilityCondition, GroupVisibilityCondition } from '@selvajs/schemas';
+export interface VisibilityResult {
+    visible: boolean;
+    disabled: boolean;
+    defaultValue?: unknown;
+}
+export declare function evaluateRule(rule: VisibilityRule, values: Record<string, unknown>): boolean;
+export declare function evaluateCondition(condition: VisibilityCondition | GroupVisibilityCondition, values: Record<string, unknown>): boolean;
+export declare function evaluateVisibility(item: LayoutItem, values: Record<string, unknown>): VisibilityResult;
+export declare function evaluateGroupVisibility(group: {
+    visibilityCondition?: GroupVisibilityCondition;
+}, values: Record<string, unknown>): boolean;

package/dist/schema/visibility-rules.js

@@ -0,0 +1,63 @@
+const toStringArray = (value) => {
+    if (Array.isArray(value))
+        return value.map(String);
+    if (value === undefined || value === null || value === '')
+        return [];
+    return [String(value)];
+};
+const RULE_OPERATORS = {
+    equals: (a, b) => a === b,
+    notEquals: (a, b) => a !== b,
+    greaterThan: (a, b) => Number(a) > Number(b),
+    lessThan: (a, b) => Number(a) < Number(b),
+    greaterThanOrEqual: (a, b) => Number(a) >= Number(b),
+    lessThanOrEqual: (a, b) => Number(a) <= Number(b),
+    between: (a, _, vals) => vals?.length === 2 && Number(a) >= Number(vals[0]) && Number(a) <= Number(vals[1]),
+    in: (a, _, vals) => vals?.includes(String(a)) ?? false,
+    notIn: (a, _, vals) => !(vals?.includes(String(a)) ?? false),
+    matches: (a, b) => {
+        try {
+            return new RegExp(String(b)).test(String(a));
+        }
+        catch {
+            return false;
+        }
+    },
+    contains: (a, b) => toStringArray(a).includes(String(b)),
+    containsAny: (a, _, vals) => {
+        const arr = toStringArray(a);
+        return vals?.some((v) => arr.includes(String(v))) ?? false;
+    },
+    isEmpty: (a) => toStringArray(a).length === 0,
+    isNotEmpty: (a) => toStringArray(a).length > 0
+};
+export function evaluateRule(rule, values) {
+    const fn = RULE_OPERATORS[rule.operator];
+    return fn ? fn(values[rule.paramId], rule.value, rule.values) : false;
+}
+export function evaluateCondition(condition, values) {
+    const results = condition.rules.map((rule) => evaluateRule(rule, values));
+    return condition.mode === 'any' ? results.some(Boolean) : results.every(Boolean);
+}
+const ACTIONS = {
+    show: (met) => ({ visible: met, disabled: false }),
+    hide: (met, dv) => ({ visible: !met, disabled: false, defaultValue: dv }),
+    disable: (met, dv) => ({ visible: true, disabled: met, defaultValue: met ? dv : undefined })
+};
+export function evaluateVisibility(item, values) {
+    if (item.type === 'linebreak')
+        return { visible: true, disabled: false };
+    if (!item.visibilityCondition?.rules)
+        return { visible: true, disabled: false };
+    const { action = 'show', defaultValue } = item.visibilityCondition;
+    const met = evaluateCondition(item.visibilityCondition, values);
+    const actionFn = ACTIONS[action] ?? ACTIONS.show;
+    return actionFn(met, defaultValue);
+}
+export function evaluateGroupVisibility(group, values) {
+    if (!group.visibilityCondition?.rules)
+        return true;
+    const { action = 'show' } = group.visibilityCondition;
+    const met = evaluateCondition(group.visibilityCondition, values);
+    return action === 'hide' ? !met : met;
+}