@selvajs/ui 6.0.0-beta.8 → 6.1.0

package/src/lib/components/compute/ComputeApp.svelte

@@ -15,6 +15,7 @@
 	import { hexToOklch } from '../../utils/color';
 	import AppShell from '../layout/AppShell.svelte';
 	import AppLayout from './AppLayout.svelte';
+	import { type ViewerConfig } from '../viewer/Viewer.svelte';
 	import StateDisplay from '../primitives/StateDisplay.svelte';
 	import { setClientSlot, type ClientSlot } from '../../contexts/clientSlotContext.svelte';
 	import type { Locale } from '../../i18n/messages';
@@ -27,7 +28,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 +42,44 @@
 		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);
+		/** Viewer chrome and defaults. `backgroundColor` and `showSceneManager` are set by the layout. */
+		viewerConfig?: ViewerConfig;
 		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;
 	}
 
@@ -119,38 +109,36 @@
 		header,
 		onReady,
 		onViewerReady,
+		viewerConfig = {},
 		externalScopeKey,
 		clientSlot,
 		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 +189,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),
@@ -257,6 +243,7 @@
 					values={session.values}
 					logoUrl={logo}
 					{onViewerReady}
+					{viewerConfig}
 					{panelActions}
 					{showSaveButton}
 					{showLoadButton}

package/src/lib/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/src/lib/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/src/lib/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/src/lib/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/src/lib/components/layout/index.ts

@@ -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/src/lib/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/src/lib/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/src/lib/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);

package/src/lib/components/preview/OutputDisplay.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import type { OutputLayoutItem } from '@selvajs/schemas';
-	import type { FileData } from '@selvajs/compute/core';
+	import { subFolderSegments, type FileData } from '@selvajs/compute/core';
 	import ChartOutput from './ChartOutput.svelte';
 	import ImageOutput from './ImageOutput.svelte';
 	import {
@@ -23,7 +23,6 @@
 
 	let { item, value, displayName }: Props = $props();
 
-	// --- text/number state ---
 	let copied = $state(false);
 	let copyTimeout: ReturnType<typeof setTimeout>;
 
@@ -47,7 +46,6 @@
 		}
 	}
 
-	// --- file state ---
 	let downloading = $state(false);
 	let downloadError = $state<string | null>(null);
 
@@ -57,7 +55,6 @@
 	const fileCount = $derived(filesArray.length);
 	const totalSize = $derived(filesArray.reduce((sum, f) => sum + getBase64FileSize(f.data), 0));
 
-	// --- folder tree ---
 	type TreeNode =
 		| { type: 'file'; file: FileData }
 		| { type: 'folder'; name: string; children: SvelteMap<string, TreeNode> };
@@ -66,7 +63,7 @@
 		const root = new SvelteMap<string, TreeNode>();
 		for (let i = 0; i < files.length; i++) {
 			const file = files[i];
-			const parts = (file.subFolder || '').split('/').filter(Boolean);
+			const parts = subFolderSegments(file.subFolder);
 			let current = root;
 			for (const part of parts) {
 				if (!current.has(part)) {
@@ -98,7 +95,7 @@
 	const fileTree = $derived(hasSubFolders ? buildTree(filesArray) : null);
 
 	function fullPath(f: FileData): string {
-		const folder = (f.subFolder || '').replace(/^\/+|\/+$/g, '');
+		const folder = subFolderSegments(f.subFolder).join('/');
 		const name = `${f.fileName}${f.fileType ?? ''}`;
 		return folder ? `${folder}/${name}` : name;
 	}

package/src/lib/components/preview/TabLayout.svelte

@@ -36,7 +36,6 @@
 	// Computed value list options keyed by the target input id, derived from solved outputs.
 	const dynamicOptions = $derived(buildDynamicValueListOptions(schema, values));
 
-	// Tab selection
 	$effect(() => {
 		if (requestedTabId && visibleTabs.some((t) => t.id === requestedTabId)) {
 			activeTabId = requestedTabId;
@@ -45,7 +44,7 @@
 		}
 	});
 
-	// Collapsed group initialisation — only sets groups that haven't been seen yet
+	// Seed each group's collapsed state once; re-seeding would discard the user's own toggles.
 	$effect(() => {
 		if (schema.layout.type !== 'tabbed') return;
 		const initial: Record<string, boolean> = {};
@@ -57,7 +56,8 @@
 		if (Object.keys(initial).length > 0) Object.assign(collapsedGroups, initial);
 	});
 
-	// Apply default values when visibility conditions hide or disable an item
+	// A hidden or disabled input still solves, so reset it to its default — otherwise the
+	// value the user last set while it was visible keeps feeding the definition.
 	$effect(() => {
 		if (schema.layout.type !== 'tabbed') return;
 		const updates: Record<string, unknown> = {};

package/src/lib/components/preview/inputs/FileInput.svelte

@@ -21,7 +21,6 @@
 		onChange
 	}: Props = $props();
 
-	// Resolve which modes are actually available
 	let effectiveModes = $derived(
 		allowedInputModes && allowedInputModes.length > 0
 			? allowedInputModes
@@ -29,7 +28,6 @@
 	);
 	let showToggle = $derived(effectiveModes.length > 1);
 
-	// Active mode: default to defaultInputMode if allowed, otherwise first allowed mode
 	let activeMode = $state<'upload' | 'url'>('upload');
 	$effect(() => {
 		const preferred = defaultInputMode ?? 'upload';
@@ -44,7 +42,7 @@
 	let urlError = $state<{ message: string; isCors: boolean; hint?: string } | null>(null);
 	let urlSuccess = $state('');
 
-	// Parse existing value if it's JSON
+	// The committed value is a JSON envelope; rebuild the display state from it.
 	$effect(() => {
 		if (value) {
 			try {
@@ -79,8 +77,7 @@
 	}
 
 	function isCorsError(error: unknown): boolean {
-		// CORS errors surface as a generic TypeError with no useful status code
-		// because the browser blocks the response entirely
+		// The browser blocks the response entirely, so this is all we get — no status code.
 		if (error instanceof TypeError && error.message === 'Failed to fetch') return true;
 		return false;
 	}
@@ -158,9 +155,8 @@
 						return '';
 					}
 				})();
-				// We can't distinguish CORS blocks from non-CORS network errors (404, DNS fail, etc.)
-				// because the browser hides all of them behind the same opaque TypeError.
-				// Give a message that covers both cases.
+				// The opaque TypeError hides CORS blocks and plain network failures (404, DNS)
+				// alike, so the message has to cover both.
 				let hint =
 					'Check that the URL is correct and the file is publicly accessible. If the server requires login, download the file and use the Upload option instead.';
 				if (host.includes('sharepoint.com') || host.includes('onedrive.com')) {
@@ -201,10 +197,11 @@
 			return;
 		}
 
-		// Guard the upload size client-side. The file is base64-embedded into the
-		// compute request body, so an oversize file would otherwise be rejected
-		// server-side with an opaque 413 (see COMPUTE_REQUEST_MAX_BYTES). The URL
-		// import path has the same check; keep the two in sync.
+		// The file is base64-embedded into the compute request body, so without a
+		// client-side cap an oversize file comes back as an opaque 413. This cap is
+		// currently LOOSER than the server's COMPUTE_REQUEST_MAX_BYTES (see the TEMP
+		// note in constants.ts) — some files pass here and still 413. The URL import
+		// path applies the same cap.
 		if (file.size > APP_DEFAULTS.FILE_UPLOAD.MAX_SIZE_BYTES) {
 			alert(
 				`File too large: ${(file.size / 1024 / 1024).toFixed(2)}MB (max ${APP_DEFAULTS.FILE_UPLOAD.MAX_SIZE_MB}MB).`

package/src/lib/components/primitives/field/field-error.svelte

@@ -15,13 +15,11 @@
 	} = $props();
 
 	const hasContent = $derived.by(() => {
-		// has slotted error
 		if (children) return true;
 
-		// no errors
 		if (!errors || errors.length === 0) return false;
 
-		// has an error but no message
+		// A lone error with no message renders an empty alert box — suppress it.
 		if (errors.length === 1 && !errors[0]?.message) {
 			return false;
 		}

package/src/lib/components/primitives/index.ts

@@ -1,5 +1,3 @@
-// UI Primitives - Reusable design system components
-
 // shadcn-svelte components
 export {
 	Button,