@selvajs/ui 6.0.0-beta.7 → 6.0.0

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,

package/src/lib/components/viewer/SceneManager.svelte

@@ -14,9 +14,9 @@
 
 	interface Props {
 		/**
-		 * Owned by `Viewer.svelte`, not built here: this panel unmounts when it is closed, and
-		 * hidden objects have to stay hidden — and keep being re-hidden after each solve — while it
-		 * is. Its state is backed by SvelteSets, so mutating one re-renders this list.
+		 * Owned by `Viewer.svelte`, never built here: this panel unmounts when it closes, and hidden
+		 * objects must stay hidden — and be re-hidden after each solve — while it is. Backed by
+		 * SvelteSets, so mutating one re-renders this list.
 		 */
 		outliner: SceneOutliner;
 		sceneVersion?: number;
@@ -24,24 +24,20 @@
 
 	let { outliner, sceneVersion = 0 }: Props = $props();
 
-	// All list logic (content filtering, layer grouping, search, visibility, selection) lives in
-	// @selvajs/visualization/scene. This component only renders it and forwards clicks.
 	// Derived, not destructured: the prop is reassignable, and these must follow it.
 	const hidden = $derived(outliner.visibility.hidden);
 	const selected = $derived(outliner.selection.selected);
 	const collapsed = $derived(outliner.collapsed);
 
-	// Mirrored into runes because the outliner holds them as plain fields, not sets. Both start
-	// fresh: the search box and the shift-anchor are panel state, so reopening the panel clears
-	// them, while hiding and collapse persist in the outliner that outlives it.
+	// Mirrored into runes because the outliner holds these as plain fields, not sets. Both are panel
+	// state, so reopening clears them — unlike hiding and collapse, which the outliner outlives.
 	let searchQuery = $state('');
 	let anchor = $state<string | null>(null);
 
 	$effect(() => outliner.onAnchorChange((next) => (anchor = next)));
 
 	// `scene.children` is a plain array the render layer mutates in place, so a solve bumping
-	// `sceneVersion` is the only signal that content changed. Both derivations below read it, which
-	// is what makes one walk per solve serve every template site that needs the list.
+	// `sceneVersion` is the only signal that content changed — hence the `void` reads below.
 	const sceneObjects = $derived.by(() => {
 		void sceneVersion;
 		return outliner.objects();
@@ -54,12 +50,9 @@
 		return outliner.layerGroups();
 	});
 
-	// Hidden state is keyed by Grasshopper identity, not by uuid, so ask the outliner rather than
-	// looking the object up in the set directly. Touching `hidden` registers the reactive read that
-	// re-renders this row when the eye is clicked.
-	// `SvelteSet.has()` is itself the reactive read, so go through the set rather than calling
-	// `visibility.isHidden` — that reads the set through a plain reference inside the outliner and
-	// would not re-render this row.
+	// `SvelteSet.has()` is the reactive read, so go through the set rather than calling
+	// `visibility.isHidden` — that reaches the set through a plain reference inside the outliner
+	// and returns a correct value that never re-renders this row.
 	const isObjectHidden = (object: THREE.Object3D) => hidden.has(getTrackingKey(object));
 
 	// Same reason: count through the reactive set so the layer's tri-state eye tracks its objects.
@@ -165,7 +158,6 @@
 							onkeydown={(e) =>
 								e.key === 'Enter' && selectObject(object.uuid, e as unknown as MouseEvent)}
 						>
-							<!-- Object visibility toggle -->
 							<button
 								class="rounded p-1 shrink-0 transition-colors hover:bg-muted"
 								onclick={(e) => {
@@ -182,7 +174,6 @@
 								{/if}
 							</button>
 
-							<!-- Object name -->
 							<span
 								class="min-w-0 text-xs flex-1 truncate {isHidden
 									? 'text-muted-foreground line-through'
@@ -191,7 +182,6 @@
 								{getObjectLabel(object)}
 							</span>
 
-							<!-- Type badge -->
 							<span
 								class="rounded px-1 py-0.5 font-medium shrink-0 bg-muted text-[9px] text-muted-foreground/70"
 							>
@@ -203,7 +193,6 @@
 			{/if}
 		{/each}
 
-		<!-- Empty state -->
 		{#if sceneObjects.length === 0}
 			<div class="py-12 flex flex-col items-center justify-center text-center">
 				<EyeOff class="mb-2 h-5 w-5 text-muted-foreground/30" />

package/src/lib/components/viewer/Viewer.svelte

@@ -46,12 +46,7 @@
 		showFullscreenButton?: boolean;
 		showSceneManager?: boolean;
 		showToolsMenu?: boolean;
-		/** Expose the grid show/hide toggle in the tools menu. Grid starts hidden. */
 		showGridToggle?: boolean;
-		/**
-		 * Expose the "Display" submenu (render style picker + edges toggle) in the tools menu.
-		 * Defaults on. Starts on the 'technical' style with edges hidden.
-		 */
 		showDisplayMenu?: boolean;
 		enableMeshClick?: boolean;
 		backgroundColor?: string;
@@ -64,26 +59,18 @@
 		isBlurred?: boolean;
 		drawerOpen?: boolean;
 		viewerConfig?: ViewerConfig;
-		/**
-		 * Branding logo URL. When set, shown as a small watermark in the viewer's
-		 * bottom-right corner. Omitted/empty renders nothing.
-		 */
+		/** Shown as a watermark in the bottom-right corner. */
 		logoUrl?: string;
 		/**
 		 * Hands the live three.js viewer to the host once the canvas is up, for apps drawing their
-		 * own content — `addUserGeometry` (survives solves), `tools.register` (claim clicks before
-		 * selection), `labelLayer`, `cameraController`.
-		 *
-		 * Return a cleanup function to tear down what you added; it runs before the viewer disposes.
-		 * Anything added outside a solve needs `viewer.invalidate()` to repaint — the render loop is
-		 * on-demand.
+		 * own content. Return a cleanup function to tear down what you added; it runs before the
+		 * viewer disposes. Anything added outside a solve needs `viewer.invalidate()` to repaint —
+		 * the render loop is on-demand.
 		 */
 		onViewerReady?: (viewer: ThreeViewer) => void | (() => void);
 		/**
-		 * UI language for the viewer's own chrome (tools menu, panels, dialogs).
-		 * When set, the viewer provides it to its subtree. When omitted, the viewer
-		 * reads the nearest locale context (set by the host app), defaulting to
-		 * English. Does not translate Grasshopper-sourced names/metadata.
+		 * UI language for the viewer's own chrome. Omitted, the viewer reads the nearest locale
+		 * context. Does not translate Grasshopper-sourced names/metadata.
 		 */
 		lang?: Locale;
 	}
@@ -113,13 +100,10 @@
 
 	const config = $derived({ ...defaultViewerConfig, ...viewerConfig });
 
-	// Read any host-provided locale before we (maybe) override it for our subtree.
+	// Read the host's locale before overriding it for our subtree.
 	const hostLocale = getLocaleContext();
 
-	// Resolution order: explicit `lang` prop → host locale context → default.
-	// Provide the resolved value to our subtree so the scene manager and metadata
-	// dialog read the same locale. The getter is re-read reactively, so switching
-	// the `lang` prop (or the host's locale) updates the chrome live.
+	// A getter, not a value: it is re-read reactively, so changing `lang` updates the chrome live.
 	setLocaleContext(() => lang ?? hostLocale.locale);
 	const locale = getLocaleContext();
 	const t = $derived(locale.messages);
@@ -142,10 +126,8 @@
 	let hideButton = $state(false);
 	let sceneManagerOpen = $state(false);
 
-	// The scene outliner lives here rather than inside <SceneManager> because that component is
-	// mounted only while its panel is open. Hidden objects must stay hidden when the panel is
-	// closed — and must be re-hidden after each solve, which nothing would do if the state
-	// unmounted with the panel.
+	// The outliner lives here, not in <SceneManager>: that component mounts only while its panel is
+	// open, and hidden objects must stay hidden — and be re-hidden after each solve — while it is closed.
 	const hiddenObjects = new SvelteSet<string>();
 	const selectedObjects = new SvelteSet<string>();
 	const collapsedLayers = new SvelteSet<string>();
@@ -153,15 +135,12 @@
 	let projection: CameraProjection = $state('perspective');
 	let measureActive = $state(false);
 	let gridVisible = $state(false);
-	// Render style + edge overlays. 'technical' is the default look; edges (crease lines) start off —
-	// both are user-switchable via the Display submenu.
 	let renderStyle: Look = $state('technical');
 	let edgesVisible = $state(false);
 	let selectedMeshMetadata: Record<string, any> | null = $state(null);
 	let selectedMeshName: string | null = $state(null);
 
-	// Render-style options for the Display submenu, derived from the library's LOOKS array — adding or
-	// renaming a look in @selvajs/compute updates this automatically. Label is the value capitalized.
+	// Derived from LOOKS so adding a look in @selvajs/visualization shows up here with no edit.
 	const STYLE_OPTIONS: { look: Look; label: string }[] = LOOKS.map((look) => ({
 		look,
 		label: look.charAt(0).toUpperCase() + look.slice(1)
@@ -192,16 +171,13 @@
 	onMount(() => {
 		if (!canvas) return;
 
-		// Only options that differ from the library defaults. Seed the initial render style (also the
-		// library default, but stated explicitly since it's user-switchable via the Display menu) and
-		// switch off the sun/shadows the technical look doesn't need — flat ambient + HDR image-based
-		// lighting (baseHDR loads by default) carry it. Grid/measure/click are the tools this viewer uses.
+		// Only what differs from the library defaults. The sun and shadows are off because the
+		// technical look doesn't need them — flat ambient plus the HDR environment carry it.
 		const opts: ThreeInitializerOptions = {
 			look: renderStyle,
 			lighting: { enableSunlight: false },
 			render: { enableShadows: false },
 			environment: { backgroundColor: config.backgroundColor },
-			// Build the grid so it can be toggled at runtime, but start hidden (off by default).
 			grid: { enabled: config.showToolsMenu && config.showGridToggle },
 			measure: { enabled: config.showToolsMenu },
 			events: {
@@ -237,8 +213,7 @@
 
 		const renderer = init.renderer;
 
-		// Untracked: the host's setup runs once against this canvas, and reading `meshes` or config
-		// inside it must not re-run onMount's teardown.
+		// Untracked so the host reading `meshes` or config inside its setup can't re-run onMount's teardown.
 		const hostCleanup = untrack(() => onViewerReady?.(init));
 
 		return () => {
@@ -280,9 +255,8 @@
 		setLook(look);
 	}
 
-	// Add/remove crease-edge overlays on the current scene content. applyEdges is idempotent per mesh
-	// (and attaches large meshes' overlays async, off the main thread); clearEdges is its inverse —
-	// it also cancels in-flight attaches and stands down the screen-space fallback for capped meshes.
+	// `applyEdges` is idempotent per mesh, so the repeated calls after each solve add no duplicate
+	// overlays; `clearEdges` is its inverse.
 	function applyEdgeState() {
 		if (!scene) return;
 		if (edgesVisible) applyEdges?.(scene);
@@ -297,18 +271,18 @@
 	$effect(() => {
 		if (scene && camera && controls) {
 			updateScene(scene, meshes, camera, controls, viewerInitialized);
-			// updateScene clears and re-adds all content each solve, so the previous solve's edge
-			// overlays are gone — re-attach them if edges are currently shown. Read the flag untracked:
-			// toggling edges is handled directly by toggleEdges(), so it must not re-trigger a full solve.
+			// Untracked because toggleEdges() already handles the toggle directly — reading
+			// `edgesVisible` tracked here would re-trigger a full solve.
 			untrack(() => {
+				// updateScene discarded the previous solve's overlays along with its content.
 				if (edgesVisible) applyEdges?.(scene!);
-				// Rescale the grid to the new content's extent so cells and fade match the part size.
+				// Rescale the grid so cells and fade match the new content's extent.
 				updateGridScale?.();
-				// The rebuild above also un-hid everything the user had hidden. Re-hide it: the outliner
-				// keys that state on Grasshopper identity, not on the instances just discarded.
+				// The rebuild un-hid everything; the outliner keys hidden state on Grasshopper
+				// identity, not on the instances just discarded, so it can re-hide it.
 				outliner?.applyTo();
 				sceneVersion++;
-				// New solve content — repaint now rather than on the render loop's safety interval.
+				// Repaint now rather than on the render loop's safety interval.
 				invalidate?.();
 			});
 
@@ -373,11 +347,19 @@
 		<!-- `defaultSize` must sum to 100 across the live panes. Panes register a frame before the
 		     group recomputes its layout, so a sum of 115 renders one frame at the raw flex-grow ratio
 		     and is then renormalized — and if the recompute short-circuits on an equal layout, the
-		     scene pane keeps a sliver of its intended width. Hence 85 + 15, and the explicit
-		     id/order so a conditionally-rendered pane keeps its slot. -->
+		     scene pane keeps a sliver of its intended width. Hence 85 + 15, and the explicit id/order
+		     so a conditionally-rendered pane keeps its slot. -->
 		<Resizable.Pane id="viewport" order={1} defaultSize={sceneManagerOpen ? 85 : 100} minSize={40}>
 			<div class="relative h-full w-full" style="touch-action: none;">
-				<canvas class="block h-full w-full" bind:this={canvas}></canvas>
+				<!-- Mesh count of the geometry currently in the scene. The canvas itself is opaque to
+				     the DOM, so this is the only observable proof a solve's geometry decoded and
+				     rendered; e2e asserts on it. -->
+				<canvas
+					class="block h-full w-full"
+					data-testid="viewer-canvas"
+					data-mesh-count={meshes.length}
+					bind:this={canvas}
+				></canvas>
 
 				<div
 					class="inset-0 blur-overlay absolute z-20 {isBlurred
@@ -392,9 +374,8 @@
 				{/if}
 
 				{#if logoUrl}
-					<!-- Branding watermark, bottom-right. Matches the tools menu's
-					     bottom offset so it clears the mobile drawer handle, and is
-					     non-interactive so it never intercepts canvas drags. -->
+					<!-- Bottom offset matches the tools menu so it clears the mobile drawer handle.
+					     Always pointer-events:none so it never intercepts canvas drags. -->
 					<div
 						class="right-4 {isFullscreen ? 'bottom-4' : 'bottom-16 sm:bottom-4'} absolute z-20"
 						style={hideButton
@@ -434,7 +415,6 @@
 									align="start"
 									class="data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 min-w-44 p-1 shadow-md z-10001 rounded-md border bg-popover text-popover-foreground"
 								>
-									<!-- Camera -->
 									<DropdownMenu.Item class={itemClass} onSelect={toggleProjection}>
 										{#if projection === 'perspective'}
 											<Square class="h-4 w-4" />
@@ -482,7 +462,6 @@
 												sideOffset={4}
 												class="min-w-40 p-1 shadow-md z-10001 rounded-md border bg-popover text-popover-foreground"
 											>
-												<!-- Render style: single-choice, current one checked. -->
 												{#each STYLE_OPTIONS as { look, label } (look)}
 													<DropdownMenu.Item
 														closeOnSelect={false}
@@ -498,7 +477,6 @@
 
 												<DropdownMenu.Separator class="my-1 h-px bg-border" />
 
-												<!-- Edges overlay toggle. -->
 												<DropdownMenu.Item
 													closeOnSelect={false}
 													class="{itemClass} {edgesVisible ? 'text-primary' : ''}"
@@ -540,7 +518,6 @@
 										</DropdownMenu.Item>
 									{/if}
 
-									<!-- Scene tools -->
 									{#if config.showSceneManager || config.showScreenshotButton || config.showFullscreenButton}
 										<DropdownMenu.Separator class="my-1 h-px bg-border" />
 									{/if}
@@ -585,7 +562,6 @@
 			</div>
 		</Resizable.Pane>
 
-		<!-- Scene Manager Pane -->
 		{#if sceneManagerOpen && scene && outliner}
 			<Resizable.Handle withHandle />
 			<Resizable.Pane id="scene-manager" order={2} defaultSize={15} minSize={8} maxSize={30}>
@@ -618,7 +594,6 @@
 		border-radius: 0 !important;
 	}
 
-	/* Blur overlay animation */
 	.blur-overlay {
 		pointer-events: none;
 	}

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

@@ -5,7 +5,6 @@ import {
 	FOOTER_CONTEXT_KEY
 } from '$lib/contexts/footerContext.svelte';
 
-/** Config for a footer-item registration; generic over the component's props. */
 export type FooterItemConfig<P extends Record<string, unknown> = Record<string, unknown>> = Omit<
 	FooterItem<P>,
 	'position' | 'priority'
@@ -15,9 +14,9 @@ export type FooterItemConfig<P extends Record<string, unknown> = Record<string,
 /**
  * Register a footer item for the lifetime of the calling component.
  *
- * Registration is deferred to onMount (client-side only) to avoid SSR context errors;
- * it's unregistered on destroy. A no-op when no footer context is present (e.g. a
- * component rendered outside the root layout) or no component is supplied.
+ * Registration waits for onMount so it never runs during SSR, where reading the context
+ * throws. A no-op when no footer context is present (a component rendered outside the root
+ * layout) or no component is supplied.
  */
 export function useFooterItem<P extends Record<string, unknown>>(config: FooterItemConfig<P>) {
 	onMount(() => {