selva-shared 0.8.3 → 0.8.5

package/README.md

@@ -43,3 +43,5 @@ Types are generated from `packages/schemas/ui-schema.json`. After modifying the
 ```bash
 cd packages/schemas && pnpm run generate:all
 ```
+
+cd packages/shared && pnpm publish --no-git-checks

package/dist/components/AppLayout.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import type { UISchema, SupportedTypes } from '../types/generated';
+	import type { ActionButton } from '../types/actionButton';
 	import { ChevronUp } from '@lucide/svelte';
 	import Viewer from './Viewer.svelte';
 	import CalculateButton from './ui/CalculateButton.svelte';
@@ -25,6 +26,9 @@
 		values: Record<string, unknown>;
 		onValueChange: (id: string, val: SupportedTypes) => void | Promise<void>;
 		onLoadValues?: () => void | Promise<void>;
+		stateManagerActions?: ActionButton[];
+		showSaveButton?: boolean;
+		showLoadButton?: boolean;
 	}
 
 	let {
@@ -38,7 +42,10 @@
 		oncalculate = () => {},
 		values = $bindable({}),
 		onValueChange,
-		onLoadValues
+		onLoadValues,
+		stateManagerActions = [],
+		showSaveButton = true,
+		showLoadButton = true
 	}: Props = $props();
 
 	// ── Layout flags ─────────────────────────────────────────────────────────────
@@ -121,7 +128,7 @@
 		{#if showStateManager || (!isMobile && showCalculateButton && schema.instanceSolve === false)}
 			<div class="panel-footer px-3">
 				{#if showStateManager}
-					<StateManager {schema} currentValues={values} onLoadValues={handleLoadValues} />
+					<StateManager {schema} currentValues={values} onLoadValues={handleLoadValues} actions={stateManagerActions} {showSaveButton} {showLoadButton} />
 				{/if}
 				{#if !isMobile && showCalculateButton && schema.instanceSolve === false}
 					<CalculateButton {hasPendingChanges} {hasNeverSolved} {isSolving} {oncalculate} />

package/dist/components/AppLayout.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { UISchema, SupportedTypes } from '../types/generated';
+import type { ActionButton } from '../types/actionButton';
 interface Props {
     schema: UISchema;
     meshes?: any[];
@@ -11,6 +12,9 @@ interface Props {
     values: Record<string, unknown>;
     onValueChange: (id: string, val: SupportedTypes) => void | Promise<void>;
     onLoadValues?: () => void | Promise<void>;
+    stateManagerActions?: ActionButton[];
+    showSaveButton?: boolean;
+    showLoadButton?: boolean;
 }
 declare const AppLayout: import("svelte").Component<Props, {}, "values" | "isViewerFullscreen">;
 type AppLayout = ReturnType<typeof AppLayout>;

package/dist/components/ComputeApp.svelte

@@ -0,0 +1,256 @@
+<script lang="ts">
+	import { untrack } from 'svelte';
+	import { page } from '$app/state';
+	import type { UISchema } from '../types/generated';
+	import type { ActionButton } from '../types/actionButton';
+	import type { SolveFn } from '../types/solveFn';
+	import { getDefaultValue } from '../utils/utils-shared';
+	import { createComputeThrottle } from '../utils/computeThrottle.svelte';
+	import { createSolvingIndicator } from '../utils/solving.svelte';
+	import { useFooterItem } from '../composables/useFooterItem.svelte';
+	import { hexToOklch } from '../utils/color';
+	import PageContainer from './layout/PageContainer.svelte';
+	import PageHeader from './layout/PageHeader.svelte';
+	import AppLayout from './AppLayout.svelte';
+	import StateDisplay from './ui/StateDisplay.svelte';
+
+	// ── Props ────────────────────────────────────────────────────────────────────
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		schema: UISchema;
+		onSolve: SolveFn;
+		definitionKey?: string;
+		title?: string;
+		isEmbedded?: boolean;
+		primaryColor?: string;
+		showModeToggle?: boolean;
+		stateManagerActions?: ActionButton[];
+		showSaveButton?: boolean;
+		showLoadButton?: boolean;
+		footerComponent?: any;
+		footerComponentProps?: () => Record<string, unknown>;
+		footerItemId?: string;
+		footerItemPriority?: number;
+		// Callback to expose the loadValues function to the parent
+		// Usage: bind:loadValues={myLoadFn} or onReady={({ loadValues }) => ...}
+		onReady?: (api: { loadValues: (values: Record<string, unknown>) => void }) => void;
+		// Snippets for custom layout
+		header?: Snippet;
+		children?: Snippet<[{ errors: string[]; warnings: string[] }]>;
+	}
+
+	let {
+		schema,
+		onSolve,
+		definitionKey = '',
+		title,
+		isEmbedded,
+		primaryColor,
+		showModeToggle = false,
+		stateManagerActions = [],
+		showSaveButton = true,
+		showLoadButton = true,
+		footerComponent,
+		footerComponentProps,
+		footerItemId = 'footer-item',
+		footerItemPriority = 0,
+		header,
+		children,
+		onReady
+	}: Props = $props();
+
+	// ── Helpers ──────────────────────────────────────────────────────────────────
+	function createInitialValues(s: UISchema) {
+		const v: Record<string, unknown> = {};
+		for (const input of s.inputs) {
+			v[input.id] = input.default ?? getDefaultValue(input.paramType);
+		}
+		for (const output of s.outputs) {
+			v[output.id] = null;
+		}
+		return v;
+	}
+
+	// ── Core state ───────────────────────────────────────────────────────────────
+	// svelte-ignore state_referenced_locally
+	let values = $state<Record<string, unknown>>(createInitialValues(schema));
+	let error = $state('');
+	let computeErrors = $state<string[]>([]);
+	let computeWarnings = $state<string[]>([]);
+	let meshes = $state<any[]>([]);
+	let pendingValues = $state<Record<string, unknown>>({});
+	// svelte-ignore state_referenced_locally
+	let hasPendingChanges = $state(schema?.instanceSolve === false);
+	// svelte-ignore state_referenced_locally
+	let hasNeverSolved = $state(schema?.instanceSolve === false);
+	let isViewerFullscreen = $state(false);
+
+	// ── Solve logic ──────────────────────────────────────────────────────────────
+	async function performSolveInternal(solveValues: Record<string, unknown>, signal: AbortSignal) {
+		try {
+			error = '';
+			computeErrors = [];
+			computeWarnings = [];
+
+			const result = await onSolve(solveValues, signal);
+
+			if (signal.aborted) return;
+
+			computeErrors = result.errors ?? [];
+			computeWarnings = result.warnings ?? [];
+			meshes = result.meshes ?? [];
+
+			Object.assign(values, result.outputs);
+			pendingValues = {};
+			hasPendingChanges = false;
+			hasNeverSolved = false;
+		} catch (err) {
+			if (err instanceof Error && err.name === 'AbortError') return;
+			error = err instanceof Error ? err.message : String(err);
+		}
+	}
+
+	const computeThrottle = createComputeThrottle<Record<string, unknown>>(performSolveInternal, {
+		timeout: 60000
+	});
+
+	let solving = $derived(computeThrottle.isComputing);
+	const solvingIndicator = createSolvingIndicator(() => solving);
+
+	function performSolve() {
+		computeThrottle.trigger($state.snapshot(values));
+	}
+
+	function loadValues(incoming: Record<string, unknown>) {
+		Object.assign(values, incoming);
+		if (schema?.instanceSolve !== false) {
+			performSolve();
+		} else {
+			hasPendingChanges = true;
+		}
+	}
+
+	$effect(() => {
+		onReady?.({ loadValues });
+	});
+
+	// ── Definition switching ─────────────────────────────────────────────────────
+	let previousDefinitionKey = $state('');
+	let isInitialLoad = $state(true);
+
+	$effect(() => {
+		const _ = definitionKey;
+
+		untrack(() => {
+			if (isInitialLoad) {
+				isInitialLoad = false;
+				previousDefinitionKey = definitionKey;
+				if (schema?.instanceSolve !== false) {
+					performSolve();
+				}
+			} else if (previousDefinitionKey !== definitionKey) {
+				meshes = [];
+				values = createInitialValues(schema);
+				error = '';
+				computeErrors = [];
+				computeWarnings = [];
+				if (schema && Object.keys(values).length > 0) {
+					performSolve();
+				}
+				previousDefinitionKey = definitionKey;
+			}
+		});
+	});
+
+	// ── Handlers ─────────────────────────────────────────────────────────────────
+	async function handleValueChange(id: string, val: unknown) {
+		values[id] = val;
+
+		if (schema?.instanceSolve === false) {
+			pendingValues[id] = val;
+			hasPendingChanges = true;
+			return;
+		}
+
+		performSolve();
+	}
+
+	function handleCalculate() {
+		performSolve();
+	}
+
+	// ── Footer item ──────────────────────────────────────────────────────────────
+	// Use untrack to read these static props without creating reactive dependencies.
+	// footerComponentProps is intentionally NOT untracked — it's a getter called every render.
+	const _footerItemId = untrack(() => footerItemId);
+	const _footerComponent = untrack(() => footerComponent);
+	const _footerItemPriority = untrack(() => footerItemPriority);
+	useFooterItem(
+		_footerItemId,
+		_footerComponent,
+		() => (_footerComponent ? (footerComponentProps?.() ?? {}) : {}),
+		'left',
+		_footerItemPriority
+	);
+
+	// ── Embed + custom style ─────────────────────────────────────────────────────
+	let resolvedIsEmbedded = $derived(isEmbedded ?? page.url.searchParams.get('embed') === 'true');
+	let resolvedPrimaryColor = $derived(primaryColor ?? page.url.searchParams.get('primary'));
+	let customStyle = $derived(
+		resolvedPrimaryColor ? `--primary: ${hexToOklch(resolvedPrimaryColor)}` : ''
+	);
+
+	let pageTitle = $derived(title ?? (schema?.description || schema.name));
+</script>
+
+<div style={customStyle} style:display="contents">
+	{#if children}
+		{@render children({ errors: computeErrors, warnings: computeWarnings })}
+	{:else}
+		<PageContainer errors={computeErrors} warnings={computeWarnings}>
+			{#if header}
+				{@render header()}
+			{:else if !resolvedIsEmbedded}
+				<PageHeader title={pageTitle} {showModeToggle} />
+			{/if}
+
+			<div class="bg-background flex flex-1 flex-col overflow-hidden">
+				{#if error}
+					<div class="flex min-h-100 items-center justify-center p-8">
+						<StateDisplay type="error" size="medium" message={error} />
+					</div>
+				{:else if !schema}
+					<div class="flex min-h-100 items-center justify-center">
+						<StateDisplay type="loading" size="large" message="Loading schema..." />
+					</div>
+				{:else}
+					{#key definitionKey}
+						<AppLayout
+							{schema}
+							{meshes}
+							isSolving={solving}
+							showSolvingIndicator={schema.instanceSolve !== false && solvingIndicator.show}
+							{hasPendingChanges}
+							{hasNeverSolved}
+							bind:isViewerFullscreen
+							bind:values
+							{stateManagerActions}
+						{showSaveButton}
+						{showLoadButton}
+							onValueChange={handleValueChange}
+							oncalculate={handleCalculate}
+							onLoadValues={() => {
+								if (schema?.instanceSolve !== false) {
+									performSolve();
+								} else {
+									hasPendingChanges = true;
+								}
+							}}
+						/>
+					{/key}
+				{/if}
+			</div>
+		</PageContainer>
+	{/if}
+</div>

package/dist/components/ComputeApp.svelte.d.ts

@@ -0,0 +1,31 @@
+import type { UISchema } from '../types/generated';
+import type { ActionButton } from '../types/actionButton';
+import type { SolveFn } from '../types/solveFn';
+import type { Snippet } from 'svelte';
+interface Props {
+    schema: UISchema;
+    onSolve: SolveFn;
+    definitionKey?: string;
+    title?: string;
+    isEmbedded?: boolean;
+    primaryColor?: string;
+    showModeToggle?: boolean;
+    stateManagerActions?: ActionButton[];
+    showSaveButton?: boolean;
+    showLoadButton?: boolean;
+    footerComponent?: any;
+    footerComponentProps?: () => Record<string, unknown>;
+    footerItemId?: string;
+    footerItemPriority?: number;
+    onReady?: (api: {
+        loadValues: (values: Record<string, unknown>) => void;
+    }) => void;
+    header?: Snippet;
+    children?: Snippet<[{
+        errors: string[];
+        warnings: string[];
+    }]>;
+}
+declare const ComputeApp: import("svelte").Component<Props, {}, "">;
+type ComputeApp = ReturnType<typeof ComputeApp>;
+export default ComputeApp;

package/dist/components/StateManager.svelte

@@ -10,13 +10,25 @@
 	} from '../utils/param-exporter';
 	import { Button, Input, Label, Textarea, Dialog, Card } from '../components/ui';
 
+	import type { ActionButton } from '../types/actionButton';
+
 	interface Props {
 		schema: UISchema;
 		currentValues: Record<string, unknown>;
 		onLoadValues: (values: Record<string, unknown>) => void;
+		showSaveButton?: boolean;
+		showLoadButton?: boolean;
+		actions?: ActionButton[];
 	}
 
-	let { schema, currentValues, onLoadValues }: Props = $props();
+	let {
+		schema,
+		currentValues,
+		onLoadValues,
+		showSaveButton = true,
+		showLoadButton = true,
+		actions = []
+	}: Props = $props();
 
 	// Save dialog state
 	let showExportDialog = $state(false);
@@ -127,15 +139,33 @@
 </script>
 
 <div class="gap-2 mb-2 flex items-center justify-center">
-	<Button variant="default" size="sm" onclick={openExportDialog}>
-		<Download class="mr-2 h-4 w-4" />
-		Save State
-	</Button>
-
-	<Button variant="outline" size="sm" onclick={openLoadDialog}>
-		<Upload class="mr-2 h-4 w-4" />
-		Load State
-	</Button>
+	{#if showSaveButton}
+		<Button variant="default" size="sm" onclick={openExportDialog}>
+			<Download class="mr-2 h-4 w-4" />
+			Save State
+		</Button>
+	{/if}
+
+	{#if showLoadButton}
+		<Button variant="outline" size="sm" onclick={openLoadDialog}>
+			<Upload class="mr-2 h-4 w-4" />
+			Load State
+		</Button>
+	{/if}
+
+	{#each actions as action (action.id)}
+		<Button
+			variant={action.variant ?? 'outline'}
+			size={action.size ?? 'sm'}
+			onclick={action.onclick}
+		>
+			{#if action.icon}
+				{@const IconComponent = action.icon}
+				<IconComponent class="mr-2 h-4 w-4" />
+			{/if}
+			{action.label}
+		</Button>
+	{/each}
 
 	<input
 		bind:this={fileInputRef}

package/dist/components/StateManager.svelte.d.ts

@@ -1,8 +1,12 @@
 import type { UISchema } from '../types/generated';
+import type { ActionButton } from '../types/actionButton';
 interface Props {
     schema: UISchema;
     currentValues: Record<string, unknown>;
     onLoadValues: (values: Record<string, unknown>) => void;
+    showSaveButton?: boolean;
+    showLoadButton?: boolean;
+    actions?: ActionButton[];
 }
 declare const StateManager: import("svelte").Component<Props, {}, "">;
 type StateManager = ReturnType<typeof StateManager>;

package/dist/composables/useFooterItem.svelte.js

@@ -1,5 +1,5 @@
-import { onMount, onDestroy } from 'svelte';
-import { useFooter } from '../contexts/footerContext.svelte';
+import { getContext, onMount, onDestroy } from 'svelte';
+import { FOOTER_CONTEXT_KEY } from '../contexts/footerContext.svelte';
 /**
  * Register a footer item component that reactively updates its props.
  * The `getProps` function is called on every render, so returning reactive state
@@ -16,13 +16,15 @@ import { useFooter } from '../contexts/footerContext.svelte';
  */
 export function useFooterItem(id, component, getProps, position = 'left', priority = 0, onClick) {
     onMount(() => {
-        const footer = useFooter();
-        footer.register(id, component, getProps, position, priority, onClick);
+        const store = getContext(FOOTER_CONTEXT_KEY);
+        if (!store || !component)
+            return;
+        store.register(id, component, getProps, position, priority, onClick);
     });
     onDestroy(() => {
         try {
-            const footer = useFooter();
-            footer.unregister(id);
+            const store = getContext(FOOTER_CONTEXT_KEY);
+            store?.unregister(id);
         }
         catch {
             // Context may not exist during SSR cleanup — safe to ignore

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

@@ -13,5 +13,6 @@ export interface FooterStore {
     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

@@ -1,6 +1,6 @@
 import { getContext, setContext } from 'svelte';
 import { SvelteMap } from 'svelte/reactivity';
-const FOOTER_CONTEXT_KEY = Symbol('footer-context');
+export const FOOTER_CONTEXT_KEY = Symbol('footer-context');
 export function initializeFooterContext() {
     const items = new SvelteMap();
     const store = {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { default as PageContainer } from './components/layout/PageContainer.svel
 export { default as PageHeader } from './components/layout/PageHeader.svelte';
 export { default as PageFooter } from './components/layout/PageFooter.svelte';
 export { default as AppLayout } from './components/AppLayout.svelte';
+export { default as ComputeApp } from './components/ComputeApp.svelte';
 export { default as ErrorScreen } from './components/ErrorScreen.svelte';
 export { default as TabLayout } from './components/preview/TabLayout.svelte';
 export { default as InputControl } from './components/preview/InputControl.svelte';
@@ -14,6 +15,7 @@ export { default as SolvingIndicator } from './components/ui/SolvingIndicator.sv
 export { default as ComputeMessages } from './components/ComputeMessages.svelte';
 export * from './features/preview/handlers';
 export * from './features/preview/notifications';
+export * from './utils/color';
 export * from './utils/debounce';
 export * from './utils/utils-shared';
 export * from './utils/file-download';
@@ -25,5 +27,7 @@ export * from './composables/useFooterItem.svelte';
 export { themeStore } from './stores/themeStore.svelte';
 export * from './utils';
 export type * from './types/generated';
+export type { ActionButton } from './types/actionButton';
+export type { SolveFn, SolveResult } from './types/solveFn';
 export { ACCEPTED_FILE_FORMATS } from './types/generated/schema';
 export * from './themes';

package/dist/index.js

@@ -3,6 +3,7 @@ export { default as PageContainer } from './components/layout/PageContainer.svel
 export { default as PageHeader } from './components/layout/PageHeader.svelte';
 export { default as PageFooter } from './components/layout/PageFooter.svelte';
 export { default as AppLayout } from './components/AppLayout.svelte';
+export { default as ComputeApp } from './components/ComputeApp.svelte';
 // Error components
 export { default as ErrorScreen } from './components/ErrorScreen.svelte';
 // Preview components
@@ -20,6 +21,7 @@ export { default as ComputeMessages } from './components/ComputeMessages.svelte'
 export * from './features/preview/handlers';
 export * from './features/preview/notifications';
 // Utilities
+export * from './utils/color';
 export * from './utils/debounce';
 export * from './utils/utils-shared';
 export * from './utils/file-download';

package/dist/types/actionButton.d.ts

@@ -0,0 +1,8 @@
+export interface ActionButton {
+    id: string;
+    label: string;
+    icon?: any;
+    variant?: 'default' | 'outline' | 'destructive' | 'secondary' | 'ghost';
+    size?: 'default' | 'sm' | 'lg';
+    onclick: () => void | Promise<void>;
+}

package/dist/types/actionButton.js

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

package/dist/types/solveFn.d.ts

@@ -0,0 +1,7 @@
+export interface SolveResult {
+    outputs: Record<string, unknown>;
+    meshes?: any[];
+    errors?: string[];
+    warnings?: string[];
+}
+export type SolveFn = (values: Record<string, unknown>, signal: AbortSignal) => Promise<SolveResult>;

package/dist/types/solveFn.js

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

package/dist/utils/color.d.ts

@@ -0,0 +1 @@
+export declare const hexToOklch: (hex: string | null) => string;

package/dist/utils/color.js

@@ -0,0 +1,38 @@
+// Helper to convert hex to OKLCH
+export const hexToOklch = (hex) => {
+    if (!hex)
+        return '';
+    // Normalize hex (remove # if present)
+    const normalized = hex.replace(/^#/, '');
+    // If it's not a valid hex color, return as-is
+    if (!/^[0-9A-Fa-f]{6}$/.test(normalized)) {
+        return hex;
+    }
+    // Parse hex to RGB
+    const r = parseInt(normalized.slice(0, 2), 16) / 255;
+    const g = parseInt(normalized.slice(2, 4), 16) / 255;
+    const b = parseInt(normalized.slice(4, 6), 16) / 255;
+    // Convert RGB to linear RGB
+    const toLinear = (c) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+    const lr = toLinear(r);
+    const lg = toLinear(g);
+    const lb = toLinear(b);
+    // Convert linear RGB to XYZ
+    const x = lr * 0.4124564 + lg * 0.3575761 + lb * 0.1804375;
+    const y = lr * 0.2126729 + lg * 0.7151522 + lb * 0.072175;
+    const z = lr * 0.0193339 + lg * 0.119192 + lb * 0.9503041;
+    // Convert XYZ to OKLab
+    const l_ = Math.cbrt(0.8189330101 * x + 0.3618667424 * y - 0.1288597137 * z);
+    const m_ = Math.cbrt(0.0329845436 * x + 0.9293118715 * y + 0.0361456387 * z);
+    const s_ = Math.cbrt(0.0482003018 * x + 0.2643662691 * y + 0.633851707 * z);
+    const L = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_;
+    const a = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
+    const b_lab = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
+    // Convert to LCH
+    const C = Math.sqrt(a * a + b_lab * b_lab);
+    let H = (Math.atan2(b_lab, a) * 180) / Math.PI;
+    if (H < 0)
+        H += 360;
+    // Format as OKLCH (round to reasonable precision)
+    return `oklch(${L.toFixed(3)} ${C.toFixed(3)} ${H.toFixed(1)})`;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selva-shared",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Shared UI components and utilities for Selva applications",
   "license": "MIT",
   "publishConfig": {

package/src/lib/components/AppLayout.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import type { UISchema, SupportedTypes } from '../types/generated';
+	import type { ActionButton } from '../types/actionButton';
 	import { ChevronUp } from '@lucide/svelte';
 	import Viewer from './Viewer.svelte';
 	import CalculateButton from './ui/CalculateButton.svelte';
@@ -25,6 +26,9 @@
 		values: Record<string, unknown>;
 		onValueChange: (id: string, val: SupportedTypes) => void | Promise<void>;
 		onLoadValues?: () => void | Promise<void>;
+		stateManagerActions?: ActionButton[];
+		showSaveButton?: boolean;
+		showLoadButton?: boolean;
 	}
 
 	let {
@@ -38,7 +42,10 @@
 		oncalculate = () => {},
 		values = $bindable({}),
 		onValueChange,
-		onLoadValues
+		onLoadValues,
+		stateManagerActions = [],
+		showSaveButton = true,
+		showLoadButton = true
 	}: Props = $props();
 
 	// ── Layout flags ─────────────────────────────────────────────────────────────
@@ -121,7 +128,7 @@
 		{#if showStateManager || (!isMobile && showCalculateButton && schema.instanceSolve === false)}
 			<div class="panel-footer px-3">
 				{#if showStateManager}
-					<StateManager {schema} currentValues={values} onLoadValues={handleLoadValues} />
+					<StateManager {schema} currentValues={values} onLoadValues={handleLoadValues} actions={stateManagerActions} {showSaveButton} {showLoadButton} />
 				{/if}
 				{#if !isMobile && showCalculateButton && schema.instanceSolve === false}
 					<CalculateButton {hasPendingChanges} {hasNeverSolved} {isSolving} {oncalculate} />

package/src/lib/components/ComputeApp.svelte

@@ -0,0 +1,256 @@
+<script lang="ts">
+	import { untrack } from 'svelte';
+	import { page } from '$app/state';
+	import type { UISchema } from '../types/generated';
+	import type { ActionButton } from '../types/actionButton';
+	import type { SolveFn } from '../types/solveFn';
+	import { getDefaultValue } from '../utils/utils-shared';
+	import { createComputeThrottle } from '../utils/computeThrottle.svelte';
+	import { createSolvingIndicator } from '../utils/solving.svelte';
+	import { useFooterItem } from '../composables/useFooterItem.svelte';
+	import { hexToOklch } from '../utils/color';
+	import PageContainer from './layout/PageContainer.svelte';
+	import PageHeader from './layout/PageHeader.svelte';
+	import AppLayout from './AppLayout.svelte';
+	import StateDisplay from './ui/StateDisplay.svelte';
+
+	// ── Props ────────────────────────────────────────────────────────────────────
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		schema: UISchema;
+		onSolve: SolveFn;
+		definitionKey?: string;
+		title?: string;
+		isEmbedded?: boolean;
+		primaryColor?: string;
+		showModeToggle?: boolean;
+		stateManagerActions?: ActionButton[];
+		showSaveButton?: boolean;
+		showLoadButton?: boolean;
+		footerComponent?: any;
+		footerComponentProps?: () => Record<string, unknown>;
+		footerItemId?: string;
+		footerItemPriority?: number;
+		// Callback to expose the loadValues function to the parent
+		// Usage: bind:loadValues={myLoadFn} or onReady={({ loadValues }) => ...}
+		onReady?: (api: { loadValues: (values: Record<string, unknown>) => void }) => void;
+		// Snippets for custom layout
+		header?: Snippet;
+		children?: Snippet<[{ errors: string[]; warnings: string[] }]>;
+	}
+
+	let {
+		schema,
+		onSolve,
+		definitionKey = '',
+		title,
+		isEmbedded,
+		primaryColor,
+		showModeToggle = false,
+		stateManagerActions = [],
+		showSaveButton = true,
+		showLoadButton = true,
+		footerComponent,
+		footerComponentProps,
+		footerItemId = 'footer-item',
+		footerItemPriority = 0,
+		header,
+		children,
+		onReady
+	}: Props = $props();
+
+	// ── Helpers ──────────────────────────────────────────────────────────────────
+	function createInitialValues(s: UISchema) {
+		const v: Record<string, unknown> = {};
+		for (const input of s.inputs) {
+			v[input.id] = input.default ?? getDefaultValue(input.paramType);
+		}
+		for (const output of s.outputs) {
+			v[output.id] = null;
+		}
+		return v;
+	}
+
+	// ── Core state ───────────────────────────────────────────────────────────────
+	// svelte-ignore state_referenced_locally
+	let values = $state<Record<string, unknown>>(createInitialValues(schema));
+	let error = $state('');
+	let computeErrors = $state<string[]>([]);
+	let computeWarnings = $state<string[]>([]);
+	let meshes = $state<any[]>([]);
+	let pendingValues = $state<Record<string, unknown>>({});
+	// svelte-ignore state_referenced_locally
+	let hasPendingChanges = $state(schema?.instanceSolve === false);
+	// svelte-ignore state_referenced_locally
+	let hasNeverSolved = $state(schema?.instanceSolve === false);
+	let isViewerFullscreen = $state(false);
+
+	// ── Solve logic ──────────────────────────────────────────────────────────────
+	async function performSolveInternal(solveValues: Record<string, unknown>, signal: AbortSignal) {
+		try {
+			error = '';
+			computeErrors = [];
+			computeWarnings = [];
+
+			const result = await onSolve(solveValues, signal);
+
+			if (signal.aborted) return;
+
+			computeErrors = result.errors ?? [];
+			computeWarnings = result.warnings ?? [];
+			meshes = result.meshes ?? [];
+
+			Object.assign(values, result.outputs);
+			pendingValues = {};
+			hasPendingChanges = false;
+			hasNeverSolved = false;
+		} catch (err) {
+			if (err instanceof Error && err.name === 'AbortError') return;
+			error = err instanceof Error ? err.message : String(err);
+		}
+	}
+
+	const computeThrottle = createComputeThrottle<Record<string, unknown>>(performSolveInternal, {
+		timeout: 60000
+	});
+
+	let solving = $derived(computeThrottle.isComputing);
+	const solvingIndicator = createSolvingIndicator(() => solving);
+
+	function performSolve() {
+		computeThrottle.trigger($state.snapshot(values));
+	}
+
+	function loadValues(incoming: Record<string, unknown>) {
+		Object.assign(values, incoming);
+		if (schema?.instanceSolve !== false) {
+			performSolve();
+		} else {
+			hasPendingChanges = true;
+		}
+	}
+
+	$effect(() => {
+		onReady?.({ loadValues });
+	});
+
+	// ── Definition switching ─────────────────────────────────────────────────────
+	let previousDefinitionKey = $state('');
+	let isInitialLoad = $state(true);
+
+	$effect(() => {
+		const _ = definitionKey;
+
+		untrack(() => {
+			if (isInitialLoad) {
+				isInitialLoad = false;
+				previousDefinitionKey = definitionKey;
+				if (schema?.instanceSolve !== false) {
+					performSolve();
+				}
+			} else if (previousDefinitionKey !== definitionKey) {
+				meshes = [];
+				values = createInitialValues(schema);
+				error = '';
+				computeErrors = [];
+				computeWarnings = [];
+				if (schema && Object.keys(values).length > 0) {
+					performSolve();
+				}
+				previousDefinitionKey = definitionKey;
+			}
+		});
+	});
+
+	// ── Handlers ─────────────────────────────────────────────────────────────────
+	async function handleValueChange(id: string, val: unknown) {
+		values[id] = val;
+
+		if (schema?.instanceSolve === false) {
+			pendingValues[id] = val;
+			hasPendingChanges = true;
+			return;
+		}
+
+		performSolve();
+	}
+
+	function handleCalculate() {
+		performSolve();
+	}
+
+	// ── Footer item ──────────────────────────────────────────────────────────────
+	// Use untrack to read these static props without creating reactive dependencies.
+	// footerComponentProps is intentionally NOT untracked — it's a getter called every render.
+	const _footerItemId = untrack(() => footerItemId);
+	const _footerComponent = untrack(() => footerComponent);
+	const _footerItemPriority = untrack(() => footerItemPriority);
+	useFooterItem(
+		_footerItemId,
+		_footerComponent,
+		() => (_footerComponent ? (footerComponentProps?.() ?? {}) : {}),
+		'left',
+		_footerItemPriority
+	);
+
+	// ── Embed + custom style ─────────────────────────────────────────────────────
+	let resolvedIsEmbedded = $derived(isEmbedded ?? page.url.searchParams.get('embed') === 'true');
+	let resolvedPrimaryColor = $derived(primaryColor ?? page.url.searchParams.get('primary'));
+	let customStyle = $derived(
+		resolvedPrimaryColor ? `--primary: ${hexToOklch(resolvedPrimaryColor)}` : ''
+	);
+
+	let pageTitle = $derived(title ?? (schema?.description || schema.name));
+</script>
+
+<div style={customStyle} style:display="contents">
+	{#if children}
+		{@render children({ errors: computeErrors, warnings: computeWarnings })}
+	{:else}
+		<PageContainer errors={computeErrors} warnings={computeWarnings}>
+			{#if header}
+				{@render header()}
+			{:else if !resolvedIsEmbedded}
+				<PageHeader title={pageTitle} {showModeToggle} />
+			{/if}
+
+			<div class="bg-background flex flex-1 flex-col overflow-hidden">
+				{#if error}
+					<div class="flex min-h-100 items-center justify-center p-8">
+						<StateDisplay type="error" size="medium" message={error} />
+					</div>
+				{:else if !schema}
+					<div class="flex min-h-100 items-center justify-center">
+						<StateDisplay type="loading" size="large" message="Loading schema..." />
+					</div>
+				{:else}
+					{#key definitionKey}
+						<AppLayout
+							{schema}
+							{meshes}
+							isSolving={solving}
+							showSolvingIndicator={schema.instanceSolve !== false && solvingIndicator.show}
+							{hasPendingChanges}
+							{hasNeverSolved}
+							bind:isViewerFullscreen
+							bind:values
+							{stateManagerActions}
+						{showSaveButton}
+						{showLoadButton}
+							onValueChange={handleValueChange}
+							oncalculate={handleCalculate}
+							onLoadValues={() => {
+								if (schema?.instanceSolve !== false) {
+									performSolve();
+								} else {
+									hasPendingChanges = true;
+								}
+							}}
+						/>
+					{/key}
+				{/if}
+			</div>
+		</PageContainer>
+	{/if}
+</div>

package/src/lib/components/StateManager.svelte

@@ -10,13 +10,25 @@
 	} from '../utils/param-exporter';
 	import { Button, Input, Label, Textarea, Dialog, Card } from '../components/ui';
 
+	import type { ActionButton } from '../types/actionButton';
+
 	interface Props {
 		schema: UISchema;
 		currentValues: Record<string, unknown>;
 		onLoadValues: (values: Record<string, unknown>) => void;
+		showSaveButton?: boolean;
+		showLoadButton?: boolean;
+		actions?: ActionButton[];
 	}
 
-	let { schema, currentValues, onLoadValues }: Props = $props();
+	let {
+		schema,
+		currentValues,
+		onLoadValues,
+		showSaveButton = true,
+		showLoadButton = true,
+		actions = []
+	}: Props = $props();
 
 	// Save dialog state
 	let showExportDialog = $state(false);
@@ -127,15 +139,33 @@
 </script>
 
 <div class="gap-2 mb-2 flex items-center justify-center">
-	<Button variant="default" size="sm" onclick={openExportDialog}>
-		<Download class="mr-2 h-4 w-4" />
-		Save State
-	</Button>
-
-	<Button variant="outline" size="sm" onclick={openLoadDialog}>
-		<Upload class="mr-2 h-4 w-4" />
-		Load State
-	</Button>
+	{#if showSaveButton}
+		<Button variant="default" size="sm" onclick={openExportDialog}>
+			<Download class="mr-2 h-4 w-4" />
+			Save State
+		</Button>
+	{/if}
+
+	{#if showLoadButton}
+		<Button variant="outline" size="sm" onclick={openLoadDialog}>
+			<Upload class="mr-2 h-4 w-4" />
+			Load State
+		</Button>
+	{/if}
+
+	{#each actions as action (action.id)}
+		<Button
+			variant={action.variant ?? 'outline'}
+			size={action.size ?? 'sm'}
+			onclick={action.onclick}
+		>
+			{#if action.icon}
+				{@const IconComponent = action.icon}
+				<IconComponent class="mr-2 h-4 w-4" />
+			{/if}
+			{action.label}
+		</Button>
+	{/each}
 
 	<input
 		bind:this={fileInputRef}

package/src/lib/composables/useFooterItem.svelte.ts

@@ -1,5 +1,5 @@
-import { onMount, onDestroy } from 'svelte';
-import { useFooter } from '$lib/contexts/footerContext.svelte';
+import { getContext, onMount, onDestroy } from 'svelte';
+import { type FooterStore, FOOTER_CONTEXT_KEY } from '$lib/contexts/footerContext.svelte';
 
 /**
  * Register a footer item component that reactively updates its props.
@@ -24,14 +24,15 @@ export function useFooterItem(
 	onClick?: () => void
 ) {
 	onMount(() => {
-		const footer = useFooter();
-		footer.register(id, component, getProps, position, priority, onClick);
+		const store = getContext<FooterStore | undefined>(FOOTER_CONTEXT_KEY);
+		if (!store || !component) return;
+		store.register(id, component, getProps, position, priority, onClick);
 	});
 
 	onDestroy(() => {
 		try {
-			const footer = useFooter();
-			footer.unregister(id);
+			const store = getContext<FooterStore | undefined>(FOOTER_CONTEXT_KEY);
+			store?.unregister(id);
 		} catch {
 			// Context may not exist during SSR cleanup — safe to ignore
 		}

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

@@ -24,7 +24,7 @@ export interface FooterStore {
 	unregister(id: string): void;
 }
 
-const FOOTER_CONTEXT_KEY = Symbol('footer-context');
+export const FOOTER_CONTEXT_KEY = Symbol('footer-context');
 
 export function initializeFooterContext(): FooterStore {
 	const items = new SvelteMap<string, FooterItem>();

package/src/lib/index.ts

@@ -3,6 +3,7 @@ export { default as PageContainer } from './components/layout/PageContainer.svel
 export { default as PageHeader } from './components/layout/PageHeader.svelte';
 export { default as PageFooter } from './components/layout/PageFooter.svelte';
 export { default as AppLayout } from './components/AppLayout.svelte';
+export { default as ComputeApp } from './components/ComputeApp.svelte';
 
 // Error components
 export { default as ErrorScreen } from './components/ErrorScreen.svelte';
@@ -25,6 +26,7 @@ export * from './features/preview/handlers';
 export * from './features/preview/notifications';
 
 // Utilities
+export * from './utils/color';
 export * from './utils/debounce';
 export * from './utils/utils-shared';
 export * from './utils/file-download';
@@ -44,6 +46,8 @@ export * from './utils';
 
 // Re-export types from generated schema
 export type * from './types/generated';
+export type { ActionButton } from './types/actionButton';
+export type { SolveFn, SolveResult } from './types/solveFn';
 
 // Re-export constants from generated schema
 export { ACCEPTED_FILE_FORMATS } from './types/generated/schema';

package/src/lib/types/actionButton.ts

@@ -0,0 +1,8 @@
+export interface ActionButton {
+	id: string;
+	label: string;
+	icon?: any;
+	variant?: 'default' | 'outline' | 'destructive' | 'secondary' | 'ghost';
+	size?: 'default' | 'sm' | 'lg';
+	onclick: () => void | Promise<void>;
+}

package/src/lib/types/solveFn.ts

@@ -0,0 +1,11 @@
+export interface SolveResult {
+	outputs: Record<string, unknown>;
+	meshes?: any[];
+	errors?: string[];
+	warnings?: string[];
+}
+
+export type SolveFn = (
+	values: Record<string, unknown>,
+	signal: AbortSignal
+) => Promise<SolveResult>;

package/src/lib/utils/color.ts

@@ -0,0 +1,45 @@
+// Helper to convert hex to OKLCH
+export const hexToOklch = (hex: string | null): string => {
+	if (!hex) return '';
+
+	// Normalize hex (remove # if present)
+	const normalized = hex.replace(/^#/, '');
+
+	// If it's not a valid hex color, return as-is
+	if (!/^[0-9A-Fa-f]{6}$/.test(normalized)) {
+		return hex;
+	}
+
+	// Parse hex to RGB
+	const r = parseInt(normalized.slice(0, 2), 16) / 255;
+	const g = parseInt(normalized.slice(2, 4), 16) / 255;
+	const b = parseInt(normalized.slice(4, 6), 16) / 255;
+
+	// Convert RGB to linear RGB
+	const toLinear = (c: number) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+	const lr = toLinear(r);
+	const lg = toLinear(g);
+	const lb = toLinear(b);
+
+	// Convert linear RGB to XYZ
+	const x = lr * 0.4124564 + lg * 0.3575761 + lb * 0.1804375;
+	const y = lr * 0.2126729 + lg * 0.7151522 + lb * 0.072175;
+	const z = lr * 0.0193339 + lg * 0.119192 + lb * 0.9503041;
+
+	// Convert XYZ to OKLab
+	const l_ = Math.cbrt(0.8189330101 * x + 0.3618667424 * y - 0.1288597137 * z);
+	const m_ = Math.cbrt(0.0329845436 * x + 0.9293118715 * y + 0.0361456387 * z);
+	const s_ = Math.cbrt(0.0482003018 * x + 0.2643662691 * y + 0.633851707 * z);
+
+	const L = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_;
+	const a = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
+	const b_lab = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
+
+	// Convert to LCH
+	const C = Math.sqrt(a * a + b_lab * b_lab);
+	let H = (Math.atan2(b_lab, a) * 180) / Math.PI;
+	if (H < 0) H += 360;
+
+	// Format as OKLCH (round to reasonable precision)
+	return `oklch(${L.toFixed(3)} ${C.toFixed(3)} ${H.toFixed(1)})`;
+};