@selvajs/ui 6.0.0-beta.8 → 6.1.0

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,15 +46,12 @@
 		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;
+		/** Initial state of the edge overlay and its display-menu checkmark. Default false. */
+		showEdges?: boolean;
 	}
 
 	interface Props {
@@ -64,26 +61,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;
 	}
@@ -96,7 +85,8 @@
 		showGridToggle: true,
 		showDisplayMenu: true,
 		enableMeshClick: true,
-		backgroundColor: '#E6E6E6'
+		backgroundColor: '#E6E6E6',
+		showEdges: false
 	};
 
 	let {
@@ -113,13 +103,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 +129,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 +138,13 @@
 	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);
+	// Seeded once, then owned by the menu toggle.
+	let edgesVisible = $state(untrack(() => viewerConfig.showEdges) ?? defaultViewerConfig.showEdges);
 	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 +175,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 +217,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 +259,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 +275,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 +351,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 +378,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 +419,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 +466,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 +481,6 @@
 
 												<DropdownMenu.Separator class="my-1 h-px bg-border" />
 
-												<!-- Edges overlay toggle. -->
 												<DropdownMenu.Item
 													closeOnSelect={false}
 													class="{itemClass} {edgesVisible ? 'text-primary' : ''}"
@@ -540,7 +522,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 +566,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 +598,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(() => {

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 256 MB, and base64 inflates a raw file by ~4/3, so
+	// anything over ~192 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;