@selvajs/ui 6.0.0-beta.7 → 6.0.0

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

@@ -2,13 +2,13 @@ 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.
+ * Adaptive solving indicator: measures solve durations and adjusts its
+ * visibility delay from the running average.
  *
- * - 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)
+ * - Average under FAST_THRESHOLD_MS: never shown, so quick solves don't flicker
+ * - Average over SLOW_THRESHOLD_MS: shown immediately
+ * - Between the two: shown after a proportional slice of ANIMATION_DELAY
+ * - First solve: shown immediately, there is no history yet
  */
 export function createSolvingIndicator(isSolving: () => boolean): { readonly show: boolean } {
 	const { FAST_THRESHOLD_MS, SLOW_THRESHOLD_MS, HISTORY_SIZE, ANIMATION_DELAY } =

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

@@ -1,40 +1,27 @@
-// The Svelte binding for a Solve Session.
-//
-// The session itself lives in `@selvajs/solve/client` and is framework-free: it
-// exposes plain getters plus a `subscribe()` seam. That makes it usable headless, but a
-// plain getter read inside Svelte markup is NOT reactive — nothing tells the component to
-// re-run. This adapter closes that gap: it subscribes once, bumps a `$state` version
-// counter on every notification, and reads that counter inside each getter so any
-// component touching one re-runs when the session changes.
-//
-// The counter (rather than mirroring each field into its own `$state`) keeps this a pure
-// republish: no field list to keep in sync as the session grows, and no risk of a mirrored
-// copy drifting from the source of truth.
+// A version counter, rather than mirroring each field into its own `$state`, keeps this a
+// pure republish: no field list to keep in sync as the session grows, and no mirrored copy
+// that can drift from the source of truth.
 
 import type { SolveSession, SolveSessionArgs } from '@selvajs/solve/client';
 import { createSolveSession } from '@selvajs/solve/client';
 
 /**
- * Wraps a Solve Session so its state reads reactively inside Svelte components.
+ * Wraps a Solve Session so its state reads reactively inside Svelte components. Use this in
+ * a component, never `createSolveSession` directly: the raw session's getters return correct
+ * values but never re-render.
  *
- * Returns the same `SolveSession` surface — every method delegates untouched, and every
- * getter additionally depends on the version counter. Callers use it exactly like the
- * session it wraps.
- *
- * Must be called during component initialization (it uses `$effect` to manage the
- * subscription, so teardown follows the owning component's lifecycle).
+ * Must be called during component initialization — the subscription is managed by `$effect`,
+ * so teardown follows the owning component's lifecycle.
  */
 export function useSolveSession(args: SolveSessionArgs): SolveSession {
 	const session = createSolveSession(args);
 
-	// Bumped on every session notification. Reading it inside a getter is what registers
-	// the dependency; the value itself is never meaningful.
+	// Reading this inside a getter is what registers the dependency; the value never matters.
 	let version = $state(0);
 
 	$effect(() => {
-		// Re-read on mount and unsubscribe on teardown. The session outlives no component
-		// here — it is created alongside this adapter — so dropping the subscription is the
-		// whole cleanup.
+		// The session is created alongside this adapter and outlives no other component, so
+		// dropping the subscription is the whole cleanup.
 		return session.subscribe(() => {
 			version += 1;
 		});

package/src/lib/constants.ts

@@ -1,10 +1,10 @@
 export const APP_DEFAULTS = {
 	// File upload limits
 	// TEMP (dev): raised 150 MB → 300 MB so large dev file-widget inputs aren't
-	// blocked client-side. The server request cap (COMPUTE_REQUEST_MAX_BYTES) was
-	// bumped to 300 MB to match, but base64 inflates a raw file by ~4/3, so a
-	// full 300 MB upload still won't fit the 300 MB request body. Revert to 150
-	// before release.
+	// blocked client-side. The server request cap (COMPUTE_REQUEST_MAX_BYTES)
+	// still defaults to 210 MB, and base64 inflates a raw file by ~4/3, so
+	// anything over ~157 MB is rejected with a 413 after the client accepts it.
+	// Revert to 150 before release.
 	FILE_UPLOAD: {
 		MAX_SIZE_MB: 300,
 		MAX_SIZE_BYTES: 300 * 1024 * 1024

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

@@ -3,27 +3,22 @@ import type { Snippet } from 'svelte';
 import type { SupportedTypes } from '@selvajs/schemas';
 
 // Carries the host app's slot renderer down to InputControl without threading a
-// prop through every layout layer (ComputeApp → AppLayout → TabLayout →
-// TabContent → Group → InputControl).
+// prop through every layout layer.
 //
 // An input with source.kind === 'client' and source.client.presentation === 'slot'
-// reserves its cell but renders nothing itself. Instead Selva invokes this snippet
-// so the host can render its own element (e.g. an "Edit JSON" button, or a custom
-// picker). Selva never interprets what the host renders. The host may COMMIT a value
-// back via `onValueChange`, which flows into the solve exactly like any built-in
-// widget's change.
+// reserves its cell but renders nothing itself. Selva invokes this snippet instead
+// so the host can render its own element (an "Edit JSON" button, a custom picker)
+// and never interprets what comes back.
 
 export interface ClientSlotArgs {
 	/** Grasshopper parameter instance GUID (LayoutItem.paramId / SchemaInput.id). */
 	inputId: string;
 	displayName: string;
-	/** The current value held for this input (e.g. the prefilled JSON), if any. */
 	value: unknown;
 	/**
-	 * Commit a value for this input. Identical channel to a built-in widget's change
-	 * — the value lands in the solve session and is sent to Compute on the next solve.
-	 * `forceSolve` requests a solve even in manual-solve mode (system reconciliation).
-	 * Lets a slot be an interactive control (a custom picker), not just a display cell.
+	 * Commit a value for this input — the same channel a built-in widget's change uses, so a
+	 * slot can be an interactive control rather than just a display cell. `forceSolve`
+	 * requests a solve even in manual-solve mode.
 	 */
 	onValueChange: (value: SupportedTypes, forceSolve?: boolean) => void;
 }

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

@@ -2,19 +2,17 @@ import { getContext, setContext, type Component } from 'svelte';
 import { SvelteMap } from 'svelte/reactivity';
 
 /**
- * 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
+ * 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: Component<P>;
-	/** Called on every render — return reactive state to keep footer in sync. */
+	/**
+	 * Re-invoked on every render. Return reactive state — `() => ({ status: s.status })` —
+	 * or the footer never updates.
+	 */
 	getProps: () => P;
 	position: 'left' | 'right';
 	priority: number;

package/src/lib/external/storage.ts

@@ -1,6 +1,5 @@
-// Moved to `@selvajs/solve/client`, where the Solve Session that hydrates from it
-// now lives. Re-exported here to keep the published `@selvajs/ui/external` sub-path — and
-// the pre-step producer routes that import it — working unchanged.
+// Moved to @selvajs/solve/client, beside the Solve Session that hydrates from it.
+// Re-exported to keep the published `@selvajs/ui/external` sub-path working unchanged.
 
 export {
 	writeExternalValue,

package/src/lib/i18n/localeContext.svelte.ts

@@ -1,14 +1,8 @@
 import { getContext, setContext } from 'svelte';
 import { type Locale, type ViewerMessages, messagesFor, DEFAULT_LOCALE } from './messages';
 
-// ============================================================================
-// Viewer locale context
-// ============================================================================
-//
-// Carries the current UI locale down to the viewer and its panels without
-// threading a `lang` prop through every layer. The value is a getter so the
-// host can back it with reactive state — flip the language and the viewer
-// re-renders live.
+// Carries the UI locale down to the viewer and its panels without threading a
+// `lang` prop through every layer.
 //
 // Resolution order for any consuming component:
 //   explicit `lang` prop  →  nearest locale context  →  English default
@@ -16,21 +10,19 @@ import { type Locale, type ViewerMessages, messagesFor, DEFAULT_LOCALE } from '.
 // Two ways to provide it:
 //   - Standalone: <Viewer lang="de" /> — Viewer provides the context itself.
 //   - In an app: call setLocaleContext(() => app.locale) once at the root; the
-//     viewer (and anything else) reads it. selva later wires its Paraglide
-//     locale in here.
+//     viewer (and anything else) reads it.
 
 const LOCALE_CONTEXT_KEY = Symbol('viewer-locale-context');
 
 export interface LocaleContext {
-	/** Current locale. Called reactively — return reactive state to enable live switching. */
 	readonly locale: Locale;
-	/** Resolved message catalog for the current locale. */
 	readonly messages: ViewerMessages;
 }
 
 /**
- * Provide the locale to descendants. Pass a getter so a reactive source (a
- * `$state`, a store, the app's Paraglide locale) keeps consumers in sync.
+ * Provide the locale to descendants. Pass a getter, not a value: it is re-read on every
+ * consumer render, so a reactive source (a `$state`, the app's Paraglide locale) switches
+ * the language live.
  */
 export function setLocaleContext(getLocale: () => Locale | undefined): void {
 	const ctx: LocaleContext = {
@@ -45,9 +37,8 @@ export function setLocaleContext(getLocale: () => Locale | undefined): void {
 }
 
 /**
- * Read the locale context. Falls back to an English-only context when no
- * provider exists (e.g. a primitive used in isolation), so consumers never
- * need a null check.
+ * Falls back to an English-only context when no provider exists (a primitive used in
+ * isolation), so consumers never need a null check.
  */
 export function getLocaleContext(): LocaleContext {
 	return (

package/src/lib/i18n/messages.ts

@@ -2,14 +2,9 @@
 // Viewer message catalog (library-owned strings)
 // ============================================================================
 //
-// These are the strings @selvajs/ui renders itself in the 3D viewer and its
-// panels — tool menu, view presets, scene manager, metadata dialog. They are
-// NOT the strings that come from a Grasshopper definition (mesh/layer/metadata
-// names): those live in the user's .gh file and can't be translated here.
-//
-// The library ships English + German. A host app can switch locale at runtime
-// via the locale context (see ./localeContext.svelte.ts) — e.g. selva feeds its
-// own Paraglide locale in. With no provider, components fall back to English.
+// Only the strings @selvajs/ui renders itself. Names coming from a Grasshopper
+// definition — meshes, layers, metadata keys — live in the user's .gh file and
+// cannot be translated here.
 
 export type Locale = 'en' | 'de';
 
@@ -22,9 +17,7 @@ export interface ViewerMessages {
 	views: string;
 	measure: string;
 	grid: string;
-	/** "Display" submenu label — groups render style + edges. */
 	display: string;
-	/** Edges show/hide toggle label. */
 	edges: string;
 	sceneManager: string;
 	screenshot: string;

package/src/lib/index.ts

@@ -1,31 +1,28 @@
-// Layout components (page chrome: shell, header, footer, nav)
+// The in-monorepo barrel: everything public.ts publishes, plus the design system,
+// page chrome, contexts and utils that never ship to npm. Reached via the
+// "selva-source" export condition.
+
 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 './schema/dynamic-value-list';
 export * from './schema/traversal';
 export * from './compute/solving.svelte';
 
-// Solve Session seam. The session itself now lives in `@selvajs/solve/client`
-// (framework-free); `useSolveSession` is this package's Svelte binding, which republishes
-// the session's subscribe() notifications as rune state so its getters read reactively in
-// markup. Re-exported so transports outside this package — e.g. plugin-ui's WebSocket
-// driver — can satisfy SolveDriver and drive a session. See CONTEXT.md.
+// Solve Session seam. Re-exported so transports outside this package — e.g.
+// plugin-ui's WebSocket driver — can satisfy SolveDriver and drive a session.
+// See CONTEXT.md.
 export { useSolveSession } from './compute/useSolveSession.svelte';
 export {
 	createSolveSession,
@@ -36,7 +33,7 @@ export {
 	type SolveReporter
 } from '@selvajs/solve/client';
 
-// External-input transit storage (used by routes that wire pre-step producers)
+// Pre-step producer transit storage
 export {
 	writeExternalValue,
 	readExternalValue,
@@ -46,12 +43,10 @@ export {
 	type ExternalInput
 } from '@selvajs/solve/client';
 
-// Contexts & Composables
 export * from './contexts/footerContext.svelte';
 export * from './contexts/clientSlotContext.svelte';
 export * from './composables/useFooterItem.svelte';
 
-// Utils (cn function)
 export * from './utils';
 export { randomId } from './utils/randomId';
 

package/src/lib/public.ts

@@ -1,40 +1,24 @@
-// ============================================================================
-// Published public API of @selvajs/ui
-// ============================================================================
+// The only surface npm consumers of @selvajs/ui see. package.json maps the "."
+// export's `svelte`/`types` conditions at this file's build output.
 //
-// This is the ONLY surface npm consumers of @selvajs/ui see (package.json maps
-// the "." export's `svelte`/`types` conditions at this file's build output).
-//
-// Scope: the compute-app SDK — everything an external host app needs to embed a
-// Grasshopper-driven app (ComputeApp), drive solves, and wire pre-step
-// producers. Verified against real external host apps: they import
-// ComputeApp + its types, the solve seam, and the external-input storage
-// helpers. Nothing else.
-//
-// Deliberately NOT public: design-system primitives (Button, Card, Dialog, …),
-// page-chrome layout (AppShell, SideNav, …), toast/Toaster, ThemeSwitcher,
-// DataTable, contexts/composables, cn/randomId. These remain importable from
-// the full barrel (./index.ts) INSIDE the monorepo via the "@selvajs/source"
-// export condition, but never ship to npm. If an external consumer ever needs a
-// primitive directly, promote it here explicitly rather than re-exporting the
-// whole primitives barrel.
+// Design-system primitives, page chrome, toasts, DataTable, contexts and small
+// utils stay out on purpose: they remain importable from ./index.ts inside the
+// monorepo via the "selva-source" export condition, but never ship to npm.
+// Promote a symbol here explicitly rather than re-exporting a whole barrel.
 
-// Compute app (schema + viewer + solve controls composed into a runnable app)
+// 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';
 
-// Standalone 3D viewer. Render Grasshopper meshes on their own, outside a
-// ComputeApp host — external apps drive it directly with a `meshes` array and
-// an optional `viewerConfig`. Pass `lang` to localize its chrome, or provide a
-// locale context (setLocaleContext) at the host root to drive it app-wide.
+// Standalone 3D viewer: renders Grasshopper meshes outside a ComputeApp host,
+// driven directly with a `meshes` array and an optional `viewerConfig`.
 export { default as Viewer, type ViewerConfig } from './components/viewer/Viewer.svelte';
 
 // Viewer app seam. `onViewerReady` (on <Viewer> and <ComputeApp>) hands over the
 // live three.js viewer, so a host can draw its own content into the same scene as
-// the solve results — a point cloud, draft lines, annotations — and register
-// pointer tools that claim clicks ahead of object selection. Re-exported from
-// @selvajs/visualization/render so hosts can annotate without depending on it
-// directly; `three` stays a peer dep of that package either way.
+// the solve results and register pointer tools that claim clicks ahead of object
+// selection. Re-exported from @selvajs/visualization/render so hosts can annotate
+// without depending on it directly; `three` stays a peer dep of that package either way.
 export type {
 	ThreeViewer,
 	PointerTool,
@@ -47,10 +31,9 @@ export type {
 } from '@selvajs/visualization/render';
 export { appSource, isHostOwned, isOwnedBy, pointerToNdc } from '@selvajs/visualization/render';
 
-// Viewer localization. The library renders English + German chrome; switch at
-// runtime by passing `lang` to <Viewer> or by setting a reactive locale context
-// once at the host root (e.g. feed in an app-wide Paraglide locale). Does not
-// translate Grasshopper-sourced names/metadata.
+// Viewer localization: English + German chrome, switched by passing `lang` to
+// <Viewer> or by setting a reactive locale context once at the host root.
+// Does not translate Grasshopper-sourced names/metadata.
 export type { Locale, ViewerMessages } from './i18n/messages';
 export { VIEWER_MESSAGES, DEFAULT_LOCALE, messagesFor } from './i18n/messages';
 export {
@@ -59,14 +42,13 @@ export {
 	type LocaleContext
 } from './i18n/localeContext.svelte';
 
-// Full-screen states a host app renders
+// Full-screen states a host app renders.
 export { default as ErrorScreen } from './components/ErrorScreen.svelte';
 
-// Solve Session seam (transport-agnostic value/lifecycle state machine + its
-// driver interface). The session lives in `@selvajs/solve/client` and is
+// Solve Session seam, for hosts driving a session themselves rather than
+// embedding <ComputeApp>. The session lives in `@selvajs/solve/client` and is
 // framework-free; `useSolveSession` is the Svelte binding that makes its getters
-// read reactively inside components. A host embedding <ComputeApp> needs neither —
-// both are re-exported for hosts driving a session themselves. See CONTEXT.md.
+// read reactively inside components. See CONTEXT.md.
 export { useSolveSession } from './compute/useSolveSession.svelte';
 export {
 	createSolveSession,
@@ -77,8 +59,8 @@ export {
 	type SolveReporter
 } from '@selvajs/solve/client';
 
-// Client-slot context type (host apps render their own cell for client-sourced
-// inputs, and may commit a value back via ClientSlotArgs.onValueChange).
+// Client-slot context: host apps render their own cell for client-sourced inputs,
+// and may commit a value back via ClientSlotArgs.onValueChange.
 export type { ClientSlotArgs, ClientSlot } from './contexts/clientSlotContext.svelte';
 
 // Pre-step producer transit storage (host apps wire producers via these).
@@ -91,7 +73,7 @@ export {
 	type ExternalInput
 } from '@selvajs/solve/client';
 
-// Schema utilities a ComputeApp host reasonably needs to read/shape values.
+// Schema utilities a ComputeApp host needs to read/shape values.
 export * from './schema/defaults';
 export * from './schema/traversal';
 export * from './schema/dynamic-value-list';

package/src/lib/schema/defaults.ts

@@ -1,4 +1,3 @@
-// Moved to @selvajs/schemas so server-side callers can share it without pulling
-// in the UI package. Re-exported here to keep existing `@selvajs/ui` importers
-// working.
+// Moved to @selvajs/schemas so server-side callers can share it without pulling in the
+// UI package. Re-exported to keep existing @selvajs/ui importers working.
 export { getDefaultValue } from '@selvajs/schemas';

package/src/lib/schema/dynamic-value-list.ts

@@ -41,12 +41,11 @@ function coercePayload(value: unknown): DynamicValueListPayload | null {
 }
 
 // Memoizes string-payload coercion. In compute mode the payload arrives as a JSON
-// string — potentially several MB for a large options list — and the options map is
-// derived from `values` (TabLayout), so it recomputes on EVERY value change. Without
-// memoization each keystroke/output-merge re-parses megabytes and allocates a fresh
-// options object, whose new identity re-renders the entire dropdown subtree; with a
-// 6.4 MB payload this was measured driving a tab out of memory. Map keys use
-// SameValueZero, so an identical response string from a later solve also hits.
+// string — several MB for a large options list — and the options map is derived from
+// `values` (TabLayout), so it recomputes on EVERY value change. Unmemoized, each
+// keystroke re-parses megabytes and allocates a fresh options object whose new
+// identity re-renders the whole dropdown subtree; a 6.4 MB payload drove a tab OOM.
+// Map keys use SameValueZero, so an identical string from a later solve also hits.
 const coerceCache = new Map<string, DynamicValueListPayload | null>();
 const COERCE_CACHE_MAX = 8;
 
@@ -62,10 +61,9 @@ function coercePayloadMemo(value: unknown): DynamicValueListPayload | null {
 	}
 	const parseStart = performance.now();
 	const parsed = coercePayload(value);
-	// Diagnostic: an expensive parse should happen ONCE per distinct solve result.
-	// If this line storms in the console, payload memoization is being defeated
-	// (e.g. payload strings differing per recompute) — the pre-memoization churn
-	// pattern that could OOM a tab.
+	// An expensive parse should happen ONCE per distinct solve result. If this line
+	// storms the console, memoization is being defeated (payload strings differing
+	// per recompute) — the churn pattern that could OOM a tab.
 	if (value.length > 256 * 1024) {
 		const optionCount = parsed?.options ? Object.keys(parsed.options).length : 0;
 		console.info(
@@ -90,11 +88,11 @@ interface DynamicValueListSource {
 /**
  * Every dynamicValueList output reference in the schema.
  *
- * Canonical location is `schema.outputs[]` — the plugin's SchemaSynchronizer enforces that every
- * dynamicValueList layout item is mirrored there (see CanonicalizeDynamicValueListOutputs). We ALSO
- * scan the layout purely as back-compat defense for schemas persisted by an older plugin that lacked
- * that invariant; for current schemas the layout pass finds nothing new.
- * Deduped by id, outputs[] winning so the canonical record's targetInputId takes precedence.
+ * Canonical location is `schema.outputs[]` — the plugin's SchemaSynchronizer mirrors every
+ * dynamicValueList layout item there (`CanonicalizeDynamicValueListOutputs`). The layout scan is
+ * back-compat defense for schemas persisted by an older plugin that lacked that invariant; on
+ * current schemas it finds nothing new. Deduped by id, `outputs[]` winning so the canonical
+ * record's targetInputId takes precedence.
  */
 function collectDynamicValueListSources(schema: UISchema): DynamicValueListSource[] {
 	const byId = new Map<string, DynamicValueListSource>();

package/src/lib/schema/param-exporter.ts

@@ -107,11 +107,9 @@ export function validateSavedState(
 }
 
 /**
- * The subset of a preset's parameters that can safely be applied to the current schema:
- * every param that still exists as an input. A param that no longer exists is dropped
- * (it's the same condition `validateSavedState` flags as an error), so this derives its
- * own "loadable" rule from the schema rather than re-reading validation issues — no
- * coupling to how sentinel ids are encoded.
+ * Params the current schema no longer has are dropped. That's the same condition
+ * `validateSavedState` flags as an error, but the rule is re-derived from the schema here
+ * rather than read back off the issue list — nothing couples to how sentinel ids are encoded.
  */
 export function extractLoadableValues(
 	savedState: ParameterPreset,
@@ -127,23 +125,18 @@ export function extractLoadableValues(
 	return values;
 }
 
-/** The full outcome of loading a preset: what to apply, plus the diagnostics to surface. */
 export interface PresetLoadResult {
-	/** Values safe to apply now (params that still exist). */
+	/** Safe to apply now — the params that still exist in the schema. */
 	values: Record<string, unknown>;
-	/** All validation issues (errors + warnings) for the load dialog. */
+	/** Errors and warnings both, for the load dialog. */
 	issues: ValidationIssueMessage[];
 	/** No issues at all — load silently. */
 	isValid: boolean;
-	/** No blocking errors — load is allowed (warnings are fine). */
+	/** No errors — warnings alone still allow the load. */
 	canLoad: boolean;
 }
 
-/**
- * Single entry point for applying a preset: validates against the current schema and, in
- * the same pass, computes the loadable values. Callers get one object instead of
- * threading a validation result back into a separate extraction step.
- */
+/** Validates and computes the loadable values in one pass, so callers thread one object. */
 export function loadPreset(savedState: ParameterPreset, currentSchema: UISchema): PresetLoadResult {
 	const validation = validateSavedState(savedState, currentSchema);
 	return {
@@ -161,8 +154,8 @@ export function exportStateAsJson(savedState: ParameterPreset): void {
 
 	const link = document.createElement('a');
 	link.href = URL.createObjectURL(blob);
-	// .slvp = Selva parameter preset. Import accepts legacy .sps files too — the content is
-	// identical JSON, only the writer's extension changed.
+	// .slvp = Selva parameter preset. Import still accepts the pre-rename .sps — same JSON,
+	// only the writer's extension changed.
 	link.download = `${safeName}_${date}.slvp`;
 	link.click();
 	URL.revokeObjectURL(link.href);

package/src/lib/schema/traversal.ts

@@ -1,5 +1,4 @@
-// Schema layout traversal now lives in @selvajs/schemas (next to the types it walks) so
-// any package depending on the schema can traverse it without pulling in @selvajs/ui.
-// Re-exported here to keep it part of @selvajs/ui's published surface for existing
-// consumers.
+// Moved to @selvajs/schemas, next to the types it walks, so any package depending on the
+// schema can traverse it without pulling in @selvajs/ui. Re-exported to keep existing
+// @selvajs/ui importers working.
 export { getGroups, getLayoutItems, getInputItems, type InputLayoutItem } from '@selvajs/schemas';

package/src/lib/schema/visibility-rules.ts

@@ -84,19 +84,15 @@ export function evaluateVisibility(
 	return actionFn(met, defaultValue);
 }
 
-/**
- * Stable key for a layout item: `paramId` for inputs/outputs, `id` for linebreaks.
- * Mirrors the key the renderers use in their `{#each}` blocks.
- */
+/** Must stay identical to the key the renderers use in their `{#each}` blocks. */
 export function itemKey(item: LayoutItem): string {
 	return item.type === 'linebreak' ? item.id : item.paramId;
 }
 
 /**
- * Evaluates every item's visibility once against the current values, keyed by itemKey.
- * Callers that touch the same items more than once per render (column layout + cell
- * render, plus the default-value sweep) read from this single map instead of
- * re-evaluating per access — one source of truth for "what's visible right now".
+ * Evaluates each item once per render. Callers that touch the same item several times
+ * (column layout, then cell render, then the default-value sweep) read this map instead of
+ * re-evaluating, so they can't disagree about what's visible mid-render.
  */
 export function buildVisibilityMap(
 	items: LayoutItem[],

package/src/lib/types/actionButton.ts

@@ -1,31 +1,7 @@
-/**
- * Defines an action button for use in the UI.
- *
- * @example
- * ```typescript
- * const saveButton: ActionButton = {
- *   id: 'save-btn',
- *   label: 'Save Changes',
- *   icon: SaveIcon,
- *   variant: 'default',
- *   size: 'lg',
- *   onclick: async () => {
- *     await saveData();
- *     showNotification('Saved!');
- *   }
- * };
- * ```
- *
- * @property id - Unique identifier for this button
- * @property label - Display text shown on the button
- * @property icon - Optional icon component to display alongside the label
- * @property variant - Button styling variant (controls color/appearance)
- * @property size - Button size preset
- * @property onclick - Callback function executed when clicked; can be async
- */
 export interface ActionButton {
 	id: string;
 	label: string;
+	/** A Svelte component, rendered before the label. */
 	icon?: any;
 	variant?: 'default' | 'outline' | 'destructive' | 'secondary' | 'ghost';
 	size?: 'default' | 'sm' | 'lg';

package/src/lib/types/presetLabels.ts

@@ -1,7 +1,6 @@
 /**
- * Overridable UI strings for the parameter-preset manager (Save/Load flow) and
- * footer copyright text. All optional — unset keys fall back to the English
- * defaults in `DEFAULT_PRESET_LABELS`. Pass a partial object to localize.
+ * Overridable UI strings for the parameter-preset manager. Pass a partial object to localize;
+ * unset keys fall back to `DEFAULT_PRESET_LABELS`.
  */
 export interface PresetLabels {
 	// Toolbar buttons