@selvajs/ui 6.0.0-beta.7 → 6.0.0

package/README.md

@@ -5,10 +5,9 @@ everything an external host app needs to embed a Grasshopper-driven app, drive s
 pre-step producers.
 
 The design system (`Button`, `Card`, `Dialog`, `AppShell`, …) lives here too, but is **internal to
-the monorepo** — it is reachable from the full barrel via the `@selvajs/source` export condition and
-never ships to npm. [`src/lib/public.ts`](./src/lib/public.ts) is the authoritative list of what a
-published consumer can import; promote a primitive there explicitly rather than assuming it is
-available.
+the monorepo** — reachable from the full barrel via the `selva-source` export condition, and never
+published. [`src/lib/public.ts`](./src/lib/public.ts) is the authoritative list of what a published
+consumer can import.
 
 ## Installation
 
@@ -47,9 +46,8 @@ To drive a solve session yourself rather than letting `ComputeApp` own it:
 import { useSolveSession } from '@selvajs/ui';
 ```
 
-The session itself lives in `@selvajs/solve/client` and is framework-free. Inside a Svelte
-component always use `useSolveSession` — the raw `createSolveSession` factory returns correct
-values that never re-render.
+Inside a Svelte component always use `useSolveSession` — the raw `createSolveSession` factory
+returns correct values that never re-render. See [CONTEXT.md](./CONTEXT.md).
 
 ## Styles
 

package/dist/components/compute/AppLayout.svelte

@@ -38,9 +38,7 @@
 		onListStates?: () => ParameterPreset[] | Promise<ParameterPreset[]>;
 		presetLabels?: Partial<PresetLabels>;
 		viewerConfig?: ViewerConfig;
-		/** Branding logo URL shown as a watermark in the viewer's bottom-right corner. */
 		logoUrl?: string;
-		/** Hands the live three.js viewer to the host. See `Viewer.svelte`. */
 		onViewerReady?: (viewer: ThreeViewer) => void | (() => void);
 	}
 
@@ -79,7 +77,7 @@
 	const hasLeftPanel = $derived(leftTabs.length > 0);
 	const hasRightPanel = $derived(rightTabs.length > 0);
 	const hasSidebar = $derived(hasViewer || hasRightPanel);
-	// Two-panel mode: left + right, no viewer — both panels grow to fill full width
+	// Left + right, no viewer — both panes grow to fill the full width.
 	const isTwoPanelMode = $derived(!hasViewer && hasLeftPanel && hasRightPanel);
 
 	let isMobile = $state(false);
@@ -298,7 +296,7 @@
 		</div>
 	{:else}
 		<div class="min-h-0 flex h-full flex-1">
-			<!-- Left collapsed strip (outside PaneGroup so it has fixed width) -->
+			<!-- Outside PaneGroup so the strip keeps a fixed width. -->
 			{#if leftCollapsed && hasSidebar && hasLeftPanel}
 				<CollapsedPanelStrip
 					side="left"
@@ -317,7 +315,6 @@
 				autoSaveId="selva-layout-{layoutKey}"
 				class="min-h-0 flex-1"
 			>
-				<!-- Left pane -->
 				{#if hasLeftPanel}
 					<Resizable.Pane
 						bind:this={leftPaneRef}
@@ -349,7 +346,6 @@
 					/>
 				{/if}
 
-				<!-- Viewer pane -->
 				{#if hasViewer}
 					<Resizable.Pane order={2} minSize={20} class="min-h-0 mx-1 flex flex-col">
 						<Viewer
@@ -365,7 +361,6 @@
 					</Resizable.Pane>
 				{/if}
 
-				<!-- Right pane -->
 				{#if hasRightPanel}
 					<Resizable.Handle
 						withHandle
@@ -398,7 +393,6 @@
 				{/if}
 			</Resizable.PaneGroup>
 
-			<!-- Right collapsed strip -->
 			{#if rightCollapsed && hasRightPanel}
 				<CollapsedPanelStrip
 					side="right"

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

@@ -22,9 +22,7 @@ interface Props {
     onListStates?: () => ParameterPreset[] | Promise<ParameterPreset[]>;
     presetLabels?: Partial<PresetLabels>;
     viewerConfig?: ViewerConfig;
-    /** Branding logo URL shown as a watermark in the viewer's bottom-right corner. */
     logoUrl?: string;
-    /** Hands the live three.js viewer to the host. See `Viewer.svelte`. */
     onViewerReady?: (viewer: ThreeViewer) => void | (() => void);
 }
 declare const AppLayout: import("svelte").Component<Props, {}, "isViewerFullscreen">;

package/dist/components/compute/ComputeApp.svelte

@@ -27,7 +27,7 @@
 		onSolve: SolveFn;
 		definitionKey?: string;
 		title?: string;
-		/** Branding logo URL shown as a watermark in the viewer's bottom-right corner. Hidden when unset. */
+		/** Watermark shown in the viewer's bottom-right corner. */
 		logo?: string;
 		isEmbedded?: boolean;
 		primaryColor?: string;
@@ -41,55 +41,42 @@
 		onListStates?: () => ParameterPreset[] | Promise<ParameterPreset[]>;
 		/** Partial overrides for the preset-manager UI strings (e.g. for localization). */
 		presetLabels?: Partial<PresetLabels>;
-		/** Name shown in the footer copyright line. Defaults to the brand name ("Selva"). */
+		/** Name in the footer copyright line. Defaults to the brand name ("Selva"). */
 		copyrightName?: string;
 		/** Fully overrides the footer copyright line. `{name}` and `{year}` are substituted. */
 		footerText?: string;
 		/**
-		 * How long one solve may take before the client aborts it (ms). Required: pass
-		 * the same value the server enforces (`COMPUTE_SOLVE_DEADLINE_MS`), so the client
-		 * doesn't abort a solve that would have finished.
+		 * How long one solve may take before the client aborts it (ms). Pass the same value the
+		 * server enforces (`COMPUTE_SOLVE_DEADLINE_MS`), or the client aborts solves that would
+		 * have finished.
 		 */
 		solveDeadlineMs: number;
 		footerComponent?: any;
 		footerComponentProps?: () => Record<string, unknown>;
 		footerItemId?: string;
 		footerItemPriority?: number;
+		// `onReady` fires once, so the result and session are getters rather than snapshots.
 		onReady?: (api: {
 			loadValues: (values: Record<string, unknown>) => void;
-			/**
-			 * The last result reported to the session — the one the viewer is showing, carrying
-			 * `source`/`values` even when a memo hit served it. Null before the first solve.
-			 * A getter, not a snapshot: `onReady` fires once.
-			 */
+			/** What the viewer is showing — carries `source`/`values` even on a memo hit. Null before the first solve. */
 			getLastResult: () => RetainedSolveResult | null;
 			/**
-			 * The live solve session, for hosts driving solves from their own state —
-			 * `setValue`/`solve` to push inputs, `subscribe` to react to results.
-			 *
-			 * A getter for the same reason as `getLastResult`. Values written here go through the
+			 * For hosts driving solves from their own state. Values written here go through the
 			 * same throttle and memo as the UI's, so it's safe to call at interaction rate.
 			 */
 			getSession: () => SolveSession;
 		}) => void;
-		/**
-		 * Hands the live three.js viewer to the host once it mounts, for apps drawing their own
-		 * content alongside solve results. See `Viewer.svelte` for the contract.
-		 */
+		/** Hands the live three.js viewer to the host once it mounts. See `Viewer.svelte` for the contract. */
 		onViewerReady?: (viewer: ThreeViewer) => void | (() => void);
 		headerRight?: Snippet;
 		// Replaces the built-in header; takes precedence over `headerRight`.
 		header?: Snippet;
 		// Scopes sessionStorage for external-input values; falls back to definitionKey then schema.id.
 		externalScopeKey?: string;
-		// Renders client-sourced inputs with presentation === 'slot'; receives { inputId, displayName, value, onValueChange }.
+		// Renders client-sourced inputs with presentation === 'slot'.
 		clientSlot?: ClientSlot;
-		/**
-		 * UI language for the app's own chrome (viewer, panels, status text).
-		 * Provided once here and read by every descendant via locale context.
-		 * Defaults to English when unset. Does not translate schema-authored labels
-		 * or Grasshopper-sourced names/metadata.
-		 */
+		// Language for the app's own chrome, English when unset. Does not translate
+		// schema-authored labels or Grasshopper-sourced names/metadata.
 		lang?: Locale;
 	}
 
@@ -124,33 +111,30 @@
 		lang
 	}: Props = $props();
 
-	// Make the host's client-input slot available to InputControl deep in the tree.
+	// Reaches InputControl deep in the tree.
 	// svelte-ignore state_referenced_locally
 	setClientSlot(clientSlot);
 
-	// Provide the UI locale once for the whole app subtree (viewer, panels, status
-	// text). Resolution: explicit `lang` → any host-provided locale → English. The
-	// getter is re-read reactively, so switching `lang` updates the chrome live.
+	// Resolution: explicit `lang` → host-provided locale → English. Passed as a getter so
+	// switching `lang` updates the chrome live.
 	const hostLocale = getLocaleContext();
 	setLocaleContext(() => lang ?? hostLocale.locale);
 	const t = $derived(getLocaleContext().messages);
 
 	const resolvedScopeKey = $derived(externalScopeKey || definitionKey || schema?.id || '');
 
-	// Solve Session owns the value/lifecycle state machine; the request/response driver
-	// gives it its transport (Rhino.Compute over HTTP via onSolve, throttled). The driver
-	// reads the reporter lazily so it can capture the session it's wired into.
+	// The session owns the value/lifecycle state machine; the driver is its transport. The
+	// session is passed as a getter because the two reference each other.
 	// svelte-ignore state_referenced_locally
 	const driver = createRequestResponseDriver(onSolve, () => session, {
 		solveDeadlineMs,
-		// The driver's result memo caches whole solve results, meshes included — and the viewer
-		// disposes what it renders on the next scene update. `@selvajs/solve` keeps meshes opaque,
-		// so the three.js clone/dispose rules are injected from the renderer that owns them
-		// (audit C1). Without this a memo hit serves an already-disposed mesh.
+		// The driver's memo caches whole solve results, meshes included, and the viewer disposes
+		// what it renders on the next scene update. `@selvajs/solve` keeps meshes opaque, so the
+		// three.js clone/dispose rules come from the renderer that owns them. Without this, a memo
+		// hit serves an already-disposed mesh.
 		meshPolicy,
-		// `session.isSolving` forwards to the driver, which the session can't observe on its
-		// own — republish so the spinner and disabled states track it. Deferred into a
-		// callback, so it reads `session` after initialization rather than during it.
+		// `isSolving` lives on the driver, which the session can't observe — republish so the
+		// spinner and disabled states track it.
 		onChange: () => session.notify()
 	});
 	// svelte-ignore state_referenced_locally
@@ -201,10 +185,8 @@
 		session.solve();
 	}
 
-	// Read static props without creating reactive dependencies (registration is fixed at
-	// mount). footerComponentProps is intentionally read live — it's a getter the renderer
-	// calls every render to keep the footer in sync. The composable no-ops when component
-	// is absent, so the hook itself stays unconditional.
+	// Registration is fixed at mount, so the static props are untracked. `footerComponentProps`
+	// stays live — the renderer calls it every render to keep the footer in sync.
 	useFooterItem({
 		id: untrack(() => footerItemId),
 		component: untrack(() => footerComponent),

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

@@ -12,7 +12,7 @@ interface Props {
     onSolve: SolveFn;
     definitionKey?: string;
     title?: string;
-    /** Branding logo URL shown as a watermark in the viewer's bottom-right corner. Hidden when unset. */
+    /** Watermark shown in the viewer's bottom-right corner. */
     logo?: string;
     isEmbedded?: boolean;
     primaryColor?: string;
@@ -26,14 +26,14 @@ interface Props {
     onListStates?: () => ParameterPreset[] | Promise<ParameterPreset[]>;
     /** Partial overrides for the preset-manager UI strings (e.g. for localization). */
     presetLabels?: Partial<PresetLabels>;
-    /** Name shown in the footer copyright line. Defaults to the brand name ("Selva"). */
+    /** Name in the footer copyright line. Defaults to the brand name ("Selva"). */
     copyrightName?: string;
     /** Fully overrides the footer copyright line. `{name}` and `{year}` are substituted. */
     footerText?: string;
     /**
-     * How long one solve may take before the client aborts it (ms). Required: pass
-     * the same value the server enforces (`COMPUTE_SOLVE_DEADLINE_MS`), so the client
-     * doesn't abort a solve that would have finished.
+     * How long one solve may take before the client aborts it (ms). Pass the same value the
+     * server enforces (`COMPUTE_SOLVE_DEADLINE_MS`), or the client aborts solves that would
+     * have finished.
      */
     solveDeadlineMs: number;
     footerComponent?: any;
@@ -42,36 +42,20 @@ interface Props {
     footerItemPriority?: number;
     onReady?: (api: {
         loadValues: (values: Record<string, unknown>) => void;
-        /**
-         * The last result reported to the session — the one the viewer is showing, carrying
-         * `source`/`values` even when a memo hit served it. Null before the first solve.
-         * A getter, not a snapshot: `onReady` fires once.
-         */
+        /** What the viewer is showing — carries `source`/`values` even on a memo hit. Null before the first solve. */
         getLastResult: () => RetainedSolveResult | null;
         /**
-         * The live solve session, for hosts driving solves from their own state —
-         * `setValue`/`solve` to push inputs, `subscribe` to react to results.
-         *
-         * A getter for the same reason as `getLastResult`. Values written here go through the
+         * For hosts driving solves from their own state. Values written here go through the
          * same throttle and memo as the UI's, so it's safe to call at interaction rate.
          */
         getSession: () => SolveSession;
     }) => void;
-    /**
-     * Hands the live three.js viewer to the host once it mounts, for apps drawing their own
-     * content alongside solve results. See `Viewer.svelte` for the contract.
-     */
+    /** Hands the live three.js viewer to the host once it mounts. See `Viewer.svelte` for the contract. */
     onViewerReady?: (viewer: ThreeViewer) => void | (() => void);
     headerRight?: Snippet;
     header?: Snippet;
     externalScopeKey?: string;
     clientSlot?: ClientSlot;
-    /**
-     * UI language for the app's own chrome (viewer, panels, status text).
-     * Provided once here and read by every descendant via locale context.
-     * Defaults to English when unset. Does not translate schema-authored labels
-     * or Grasshopper-sourced names/metadata.
-     */
     lang?: Locale;
 }
 declare const ComputeApp: import("svelte").Component<Props, {}, "">;

package/dist/components/compute/ParameterPresetManager.svelte

@@ -24,7 +24,7 @@
 		onSaveState?: (state: ParameterPreset) => void | Promise<void>;
 		/** When set, the Load dialog lists these states instead of showing a file input. */
 		onListStates?: () => ParameterPreset[] | Promise<ParameterPreset[]>;
-		/** Partial overrides for UI strings (e.g. for localization). */
+		/** Overrides merged over `DEFAULT_PRESET_LABELS`. */
 		labels?: Partial<PresetLabels>;
 	}
 
@@ -42,21 +42,18 @@
 
 	const t = $derived({ ...DEFAULT_PRESET_LABELS, ...labels });
 
-	// Save dialog state
 	let showExportDialog = $state(false);
 	let exportName = $state('');
 	let exportDescription = $state('');
 	let exportAuthor = $state('');
 	let exportTags = $state('');
 
-	// Import/validation state
 	let showValidationDialog = $state(false);
 	let showLoadDialog = $state(false);
 	let loadResult = $state<PresetLoadResult | null>(null);
 	let loadingPresetName = $state('');
 	let fileInputRef = $state<HTMLInputElement | null>(null);
 
-	// Listed states (when onListStates is provided)
 	let listedStates = $state<ParameterPreset[]>([]);
 	let isLoadingList = $state(false);
 	let listError = $state('');
@@ -90,8 +87,8 @@
 		showExportDialog = false;
 	}
 
-	// Load a preset in one pass, then either apply it directly (no issues) or open the
-	// validation dialog (any errors or warnings). Shared by every load path.
+	// Shared by every load path: applies clean presets directly, routes any errors or
+	// warnings through the validation dialog.
 	function tryLoad(preset: ParameterPreset) {
 		const result = loadPreset(preset, schema);
 		if (result.isValid) {
@@ -114,7 +111,7 @@
 			alert(t.loadImportError + (error as Error).message);
 		}
 
-		// Reset input
+		// Reset so re-picking the same file fires `change` again.
 		input.value = '';
 	}
 
@@ -298,7 +295,6 @@
 
 		{#if loadResult}
 			<div class="gap-4 py-4 grid">
-				<!-- Summary Alert -->
 				{#if loadResult.isValid}
 					<Card.Root class="p-4 border-success/30 bg-success/5">
 						<div class="gap-3 flex items-start">
@@ -341,7 +337,6 @@
 					</Card.Root>
 				{/if}
 
-				<!-- Issues List -->
 				{#if !loadResult.isValid}
 					<div class="space-y-2">
 						<h4 class="text-sm font-medium">{t.validationIssuesHeading}</h4>

package/dist/components/compute/ParameterPresetManager.svelte.d.ts

@@ -12,7 +12,7 @@ interface Props {
     onSaveState?: (state: ParameterPreset) => void | Promise<void>;
     /** When set, the Load dialog lists these states instead of showing a file input. */
     onListStates?: () => ParameterPreset[] | Promise<ParameterPreset[]>;
-    /** Partial overrides for UI strings (e.g. for localization). */
+    /** Overrides merged over `DEFAULT_PRESET_LABELS`. */
     labels?: Partial<PresetLabels>;
 }
 declare const ParameterPresetManager: import("svelte").Component<Props, {}, "">;

package/dist/components/layout/AppShell.svelte

@@ -4,7 +4,6 @@
 	import PageFooter from './PageFooter.svelte';
 
 	interface AppShellProps {
-		// Header
 		showHeader?: boolean;
 		homeUrl?: string;
 		title?: string | null;
@@ -17,21 +16,19 @@
 		subnav?: Snippet;
 		headerClass?: string;
 		/**
-		 * Bring-your-own header. When provided, this renders inside the sticky
-		 * header bar instead of the built-in PageHeader. The bar keeps the
+		 * Replaces the built-in PageHeader inside the sticky header bar. The bar keeps the
 		 * standard `--header-h` height so the fixed-mode layout math is unaffected.
 		 */
 		header?: Snippet;
 
-		// Body layout
-		// 'fixed'  — full viewport, header + body + footer; body owns its own scroll. For app-like pages (builder, preview, library/[guid]).
-		// 'scroll' — sticky header, body fills `100vh - --header-h` and scrolls. For dashboard-style pages.
+		// 'fixed'  — viewport-locked, no page scroll; body owns its own scroll. For app-like
+		//            pages (builder, preview, library/[guid]).
+		// 'scroll' — normal page flow, footer sticks to the bottom. For dashboard-style pages.
 		mode?: 'fixed' | 'scroll';
 
-		// Optional left rail. When present, body becomes flex row: sidenav | main.
+		// When present, body becomes a flex row: sidenav | main.
 		sidenav?: Snippet;
 
-		// Footer (only rendered when `showFooter`)
 		showFooter?: boolean;
 		errors?: string[];
 		warnings?: string[];
@@ -39,7 +36,6 @@
 		footerText?: string;
 		footerChildren?: Snippet;
 
-		// Body content
 		class?: string;
 		bodyClass?: string;
 		children: Snippet;
@@ -70,12 +66,8 @@
 		children
 	}: AppShellProps = $props();
 
-	// Default the footer's copyright owner to the header's brand name when the
-	// caller didn't specify one.
 	const _copyright = $derived(copyrightName ?? brandName);
 
-	// fixed: viewport-locked, no page scroll — body owns its own scroll internally.
-	// scroll: normal page flow, footer sticks to bottom via sticky positioning.
 	const rootClass = $derived(
 		_mode === 'fixed'
 			? `flex flex-col h-screen overflow-hidden bg-background ${className}`

package/dist/components/layout/AppShell.svelte.d.ts

@@ -12,8 +12,7 @@ interface AppShellProps {
     subnav?: Snippet;
     headerClass?: string;
     /**
-     * Bring-your-own header. When provided, this renders inside the sticky
-     * header bar instead of the built-in PageHeader. The bar keeps the
+     * Replaces the built-in PageHeader inside the sticky header bar. The bar keeps the
      * standard `--header-h` height so the fixed-mode layout math is unaffected.
      */
     header?: Snippet;

package/dist/components/layout/EmptyState.svelte

@@ -2,16 +2,15 @@
 	import type { Component, Snippet } from 'svelte';
 
 	interface Props {
-		// Optional icon component (e.g. lucide). Renders at h-8 w-8 above the title.
+		// Renders at h-8 w-8 above the title.
 		icon?: Component<{ class?: string }>;
 		title: string;
 		description?: string;
 		// Vertical breathing room. Most pages want `lg`; tighter contexts (drawer, nested card) use `sm`.
 		size?: 'sm' | 'md' | 'lg';
 		class?: string;
-		// Free-form description (overrides plain `description`). Use when you need rich content like <code>.
+		// Overrides `description`. Use when the text needs rich content like <code>.
 		body?: Snippet;
-		// Buttons / links rendered below.
 		actions?: Snippet;
 	}
 

package/dist/components/layout/PageFooter.svelte

@@ -60,9 +60,7 @@
 <footer
 	class="px-4 gap-4 text-xs h-7 flex shrink-0 items-center justify-between border-t border-border bg-background text-muted-foreground select-none"
 >
-	<!-- Left section: Status items + custom context items -->
 	<div class="gap-4 flex items-center">
-		<!-- Custom left items from context -->
 		{#each leftItems as item (item.id)}
 			<FooterItemRenderer {item} />
 		{/each}
@@ -103,9 +101,7 @@
 		{/if}
 	</div>
 
-	<!-- Right section: Custom items + Copyright -->
 	<div class="gap-4 ml-auto flex items-center">
-		<!-- Custom right items from context -->
 		{#each rightItems as item (item.id)}
 			<FooterItemRenderer {item} />
 		{/each}

package/dist/components/layout/index.js

@@ -1,4 +1,3 @@
-// Layout Components - Page structure and organization
 export { default as AppShell } from './AppShell.svelte';
 export { default as PageHeader } from './PageHeader.svelte';
 export { default as PageContent } from './PageContent.svelte';

package/dist/components/preview/Group.svelte

@@ -47,11 +47,8 @@
 	// One visibility evaluation per item per render; columnStarts and gridItem both read it.
 	const visibilityMap = $derived(buildVisibilityMap(items, values));
 
-	/**
-	 * Compute the column position (0-indexed) where each item starts, accounting
-	 * for spans and linebreak resets. Items hidden by visibility don't consume
-	 * a slot (matching what the renderer does — they're skipped entirely).
-	 */
+	// Hidden items must not consume a slot here, because gridItem skips them entirely —
+	// counting them would offset every following item's column.
 	const columnStarts = $derived.by(() => {
 		const positions: number[] = [];
 		let col = 0;

package/dist/components/preview/ImageOutput.svelte

@@ -21,10 +21,11 @@
 	const ext = $derived(file ? (file.fileType ?? '').toLowerCase() : '');
 	const isSupported = $derived(SUPPORTED_EXTS.has(ext));
 
-	// Build a data URL. Binary formats (PNG/JPG/WEBP/GIF) come through as base64;
-	// SVG arrives as plain UTF-8 XML and must be percent-encoded into the data URL.
-	// Using <img src="..."> isolates SVG scripts (browsers disable scripting in
-	// image-context SVGs), so untrusted SVG content cannot execute against the host.
+	// Binary formats (PNG/JPG/WEBP/GIF) arrive base64; SVG arrives as plain UTF-8 XML
+	// and must be percent-encoded into the data URL.
+	// Rendering through <img src> rather than inlining the SVG is a security choice:
+	// browsers disable scripting in image-context SVGs, so untrusted SVG cannot
+	// execute against the host. Don't switch to {@html} or an inline <svg>.
 	const dataUrl = $derived.by(() => {
 		if (!file || !isSupported) return null;
 		const mime = MIME_BY_EXT[ext] ?? 'application/octet-stream';

package/dist/components/preview/InputControl.svelte

@@ -34,9 +34,9 @@
 		value?: SupportedTypes;
 		displayName?: string;
 		/**
-		 * Commit a value. `forceSolve` requests a solve even in manual-solve mode — used for
-		 * system-initiated reconciliation (e.g. pruning a vanished dynamic-list selection) where
-		 * leaving the previous output on screen would misrepresent the now-changed input.
+		 * `forceSolve` solves even in manual-solve mode. Used for system-initiated changes
+		 * (e.g. pruning a vanished dynamic-list selection), where leaving the previous output
+		 * on screen would misrepresent the input that now sits above it.
 		 */
 		onChange: (paramId: string, value: SupportedTypes, forceSolve?: boolean) => void;
 		disabled?: boolean;
@@ -56,9 +56,8 @@
 	const inputId = $derived(`input-${item.paramId}`);
 	const label = $derived(displayName || item.displayName || item.paramId);
 
-	// Client-sourced input set to render a host element in its place. The 'hidden'
-	// presentation never reaches here (visible:false filters it out upstream), so a
-	// client slot source means presentation === 'slot'.
+	// The 'hidden' presentation never reaches here — visible:false filters it out
+	// upstream — so a client-sourced input here always means presentation === 'slot'.
 	const isClientSlot = $derived.by(() => {
 		const source = (item as { source?: { kind?: string; client?: { presentation?: string } } })
 			.source;
@@ -66,7 +65,7 @@
 	});
 	const clientSlot = getClientSlot();
 
-	// Number range hint — shown next to label for sliders, under the input for plain number fields.
+	// Min/max hint rendered next to the label. `hideRange` lets the author suppress it.
 	const numberRangeHint = $derived.by(() => {
 		if (!isNumberWidget(item)) return null;
 		const cfg = item.config;
@@ -81,8 +80,8 @@
 
 	const showRangeInLabel = $derived(isNumberWidget(item) && numberRangeHint !== null);
 
-	// Dynamic value list: computed options (from the last solve) take precedence over the
-	// author's seed list. Empty until the first solve produces options, unless a default is set.
+	// Options from the last solve win over the author's seed list, so the control is empty
+	// until the first solve unless defaultOptions is set.
 	const dynamicListConfig = $derived(
 		isDynamicValueListWidget(item)
 			? (item.config as DynamicValueListWidgetConfig | undefined)
@@ -109,22 +108,22 @@
 			(dynamicListConfig?.emptyBehavior ?? 'hide') === 'hide'
 	);
 
-	// When a dynamic value list recomputes, a previously-selected value may no longer be an
-	// available option. Prune the stale selection so the control shows a valid option instead
-	// of rendering the orphaned raw value as its own label. This is a system-initiated change
-	// (the user didn't pick the new option), so force a solve — otherwise manual-solve schemas
-	// would keep the prior output on screen, making it look like the auto-picked option produced it.
+	// When a dynamic value list recomputes, the selected value may no longer be an option.
+	// Prune it so the control shows a valid option instead of rendering the orphaned raw
+	// value as its own label. The user didn't pick this, so force a solve — otherwise a
+	// manual-solve schema keeps the prior output on screen, making it look like the
+	// auto-picked option produced it.
 	//
-	// INVARIANT: a dynamic value list must never dispatch an empty/null value to solve. There
-	// is always at least one option, and an empty selection reaches the definition as null/""
-	// — which throws NREs in downstream geometry components (e.g. Bounding Rectangle) and nulls
-	// every output beyond them. So every terminal state below resolves to a valid option; there
-	// is deliberately no "user cleared it, stay empty" path.
+	// INVARIANT: a dynamic value list must never dispatch an empty/null value to solve. An
+	// empty selection reaches the definition as null/"", which throws NREs in downstream
+	// geometry components (e.g. Bounding Rectangle) and nulls every output beyond them.
+	// There is always at least one option, so every terminal state below resolves to one;
+	// there is deliberately no "user cleared it, stay empty" path.
 	//
-	// LOOP BREAKER: a definition whose computed options DEPEND on the selection can oscillate —
-	// auto-pick A → solve → new options exclude A → auto-pick B → solve → … Each cycle force-
-	// solves and re-parses/re-renders the (possibly multi-MB) options, which FREEZES the tab
-	// (each solve result blocks the main thread; the loop never yields). Bound consecutive
+	// LOOP BREAKER: a definition whose computed options DEPEND on the selection can oscillate
+	// — auto-pick A → solve → new options exclude A → auto-pick B → solve → … Each cycle
+	// force-solves and re-parses the (possibly multi-MB) options, freezing the tab: every
+	// solve result blocks the main thread and the loop never yields. Bound consecutive
 	// system-initiated picks; any real user commit resets the budget.
 	const MAX_CONSECUTIVE_AUTO_PICKS = 3;
 	let autoPickCount = 0;
@@ -133,11 +132,11 @@
 		if (!isDynamicValueListWidget(item) || !dynamicListHasOptions) return;
 		const validValues = new Set(Object.values(dynamicListOptions));
 		const firstOption = Object.values(dynamicListOptions)[0];
-		// Already valid → stable; refill the auto-pick budget and stop.
 		const isValid = Array.isArray(value)
 			? value.length > 0 && value.every((v) => typeof v === 'string' && validValues.has(v))
 			: typeof value === 'string' && value !== '' && validValues.has(value);
 		if (isValid) {
+			// Settled on a valid option — refill the budget.
 			autoPickCount = 0;
 			return;
 		}
@@ -151,21 +150,21 @@
 		}
 		if (Array.isArray(value)) {
 			const pruned = value.filter((v) => typeof v === 'string' && validValues.has(v));
-			// Empty (never selected or fully pruned) always falls back to the first option —
-			// a checklist that solves empty produces the same null cascade as a single value.
+			// Empty — never selected or fully pruned — falls back to the first option: a
+			// checklist that solves empty produces the same null cascade as a single value.
 			if (pruned.length !== value.length || value.length === 0) {
 				autoPickCount++;
 				onChange(item.paramId, pruned.length > 0 ? pruned : [firstOption], true);
 			}
 		} else if (typeof value !== 'string' || value === '' || !validValues.has(value)) {
-			// Never-selected or stale single value — fall back to the first option.
+			// Same fallback for a single value: never-selected and stale both resolve, never clear.
 			autoPickCount++;
 			onChange(item.paramId, firstOption, true);
 		}
 	});
 
 	function commit(newValue: SupportedTypes) {
-		// A real user pick re-arms the system fallback (see autoPickCount above).
+		// A real user pick re-arms the auto-pick budget.
 		autoPickCount = 0;
 		value = newValue;
 		onChange(item.paramId, newValue);