@selvajs/ui 0.9.0

package/dist/components/viewer/SceneManager.svelte

@@ -0,0 +1,297 @@
+<script lang="ts">
+	import * as THREE from 'three';
+	import { Eye, EyeOff, ChevronRight, Search, X } from '@lucide/svelte';
+	import { SvelteSet, SvelteMap } from 'svelte/reactivity';
+
+	interface Props {
+		scene: THREE.Scene;
+		sceneVersion?: number;
+	}
+
+	let { scene = $bindable(), sceneVersion = 0 }: Props = $props();
+
+	const getSceneObjects = () => {
+		void sceneVersion;
+		return scene.children.filter(
+			(obj) => !(obj instanceof THREE.Camera) && !(obj instanceof THREE.Light)
+		);
+	};
+
+	const getLayerGroups = () => {
+		const objects = getSceneObjects();
+		const groups = new SvelteMap<string, THREE.Object3D[]>();
+
+		for (const obj of objects) {
+			const layer: string = obj.userData?.layer || obj.userData?.category || 'Default';
+			if (!groups.has(layer)) groups.set(layer, []);
+			groups.get(layer)!.push(obj);
+		}
+
+		return groups;
+	};
+
+	let hiddenUuids = new SvelteSet<string>();
+
+	let collapsedLayers = new SvelteSet<string>();
+
+	const setObjectVisible = (object: THREE.Object3D, visible: boolean) => {
+		object.visible = visible;
+		object.traverse((child) => {
+			child.visible = visible;
+		});
+		if (visible) {
+			hiddenUuids.delete(object.uuid);
+		} else {
+			hiddenUuids.add(object.uuid);
+		}
+	};
+
+	const toggleObject = (object: THREE.Object3D) => {
+		if (selectedUuids.has(object.uuid) && selectedUuids.size > 1) {
+			const allObjects = getSceneObjects();
+			const selected = allObjects.filter((o) => selectedUuids.has(o.uuid));
+			const allHidden = selected.every((o) => hiddenUuids.has(o.uuid));
+			for (const o of selected) setObjectVisible(o, allHidden);
+		} else {
+			setObjectVisible(object, hiddenUuids.has(object.uuid));
+		}
+	};
+
+	const isLayerHidden = (objects: THREE.Object3D[]) =>
+		objects.every((obj) => hiddenUuids.has(obj.uuid));
+
+	const isLayerPartial = (objects: THREE.Object3D[]) => {
+		const hidden = objects.filter((obj) => hiddenUuids.has(obj.uuid)).length;
+		return hidden > 0 && hidden < objects.length;
+	};
+
+	const toggleLayer = (_layerName: string, objects: THREE.Object3D[]) => {
+		const allHidden = isLayerHidden(objects);
+		for (const obj of objects) {
+			setObjectVisible(obj, allHidden);
+		}
+	};
+
+	const toggleLayerCollapsed = (layerName: string) => {
+		if (collapsedLayers.has(layerName)) {
+			collapsedLayers.delete(layerName);
+		} else {
+			collapsedLayers.add(layerName);
+		}
+	};
+
+	const getObjectLabel = (object: THREE.Object3D) =>
+		object.userData?.name || object.userData?.fileName || object.name || object.type;
+
+	const getTypeLabel = (object: THREE.Object3D) =>
+		object.type.replace('Mesh', '').replace('Object3D', 'Obj') || object.type;
+
+	let searchQuery = $state('');
+
+	const getFilteredLayerGroups = () => {
+		const groups = getLayerGroups();
+		if (!searchQuery.trim()) return groups;
+		const q = searchQuery.toLowerCase();
+		const filtered = new SvelteMap<string, THREE.Object3D[]>();
+		for (const [layerName, objects] of groups) {
+			const matchingObjects = layerName.toLowerCase().includes(q)
+				? objects
+				: objects.filter((obj) => getObjectLabel(obj).toLowerCase().includes(q));
+			if (matchingObjects.length > 0) filtered.set(layerName, matchingObjects);
+		}
+		return filtered;
+	};
+
+	const getFlatVisibleUuids = (): string[] => {
+		const result: string[] = [];
+		for (const [layerName, objects] of getFilteredLayerGroups()) {
+			if (!collapsedLayers.has(layerName)) {
+				for (const obj of objects) result.push(obj.uuid);
+			}
+		}
+		return result;
+	};
+
+	let selectedUuids = new SvelteSet<string>();
+	let lastSelectedUuid = $state<string | null>(null);
+
+	const selectObject = (uuid: string, event: MouseEvent) => {
+		if (event.shiftKey && lastSelectedUuid) {
+			const flat = getFlatVisibleUuids();
+			const a = flat.indexOf(lastSelectedUuid);
+			const b = flat.indexOf(uuid);
+			if (a !== -1 && b !== -1) {
+				const [lo, hi] = a < b ? [a, b] : [b, a];
+				if (!event.ctrlKey && !event.metaKey) selectedUuids.clear();
+				for (let i = lo; i <= hi; i++) selectedUuids.add(flat[i]);
+			}
+		} else if (event.ctrlKey || event.metaKey) {
+			if (selectedUuids.has(uuid)) {
+				selectedUuids.delete(uuid);
+			} else {
+				selectedUuids.add(uuid);
+				lastSelectedUuid = uuid;
+			}
+		} else {
+			selectedUuids.clear();
+			selectedUuids.add(uuid);
+			lastSelectedUuid = uuid;
+		}
+		if (!event.shiftKey) lastSelectedUuid = uuid;
+	};
+</script>
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div
+	class="flex h-full flex-col bg-card text-card-foreground"
+	onmousedown={() => {
+		selectedUuids.clear();
+		lastSelectedUuid = null;
+	}}
+>
+	<div class="px-3 py-2 gap-2 flex items-center border-b border-border">
+		<Search class="h-3.5 w-3.5 shrink-0 text-muted-foreground/50" />
+		<input
+			class="min-w-0 text-xs flex-1 bg-transparent text-foreground outline-none placeholder:text-muted-foreground/50"
+			placeholder="Search objects..."
+			bind:value={searchQuery}
+		/>
+		{#if searchQuery}
+			<button onclick={() => (searchQuery = '')} aria-label="Clear search">
+				<X
+					class="h-3.5 w-3.5 text-muted-foreground/50 transition-colors hover:text-muted-foreground"
+				/>
+			</button>
+		{/if}
+	</div>
+
+	<div class="py-1 flex-1 overflow-y-auto">
+		{#each [...getFilteredLayerGroups()] as [layerName, objects] (layerName)}
+			{@const layerHidden = isLayerHidden(objects)}
+			{@const layerPartial = isLayerPartial(objects)}
+			{@const collapsed = collapsedLayers.has(layerName)}
+
+			<div class="gap-1 pl-1 pr-2 py-1 group flex items-center transition-colors hover:bg-muted">
+				<button
+					class="rounded p-0.5 shrink-0 text-muted-foreground transition-colors hover:text-muted-foreground"
+					onclick={() => toggleLayerCollapsed(layerName)}
+					aria-label={collapsed ? 'Expand layer' : 'Collapse layer'}
+				>
+					<ChevronRight
+						class="h-3.5 w-3.5 transition-transform duration-150 {collapsed ? '' : 'rotate-90'}"
+					/>
+				</button>
+
+				<button
+					class="rounded p-1 shrink-0 transition-colors hover:bg-muted"
+					onclick={() => toggleLayer(layerName, objects)}
+					title={layerHidden ? 'Show layer' : 'Hide layer'}
+					aria-label={layerHidden ? 'Show layer' : 'Hide layer'}
+				>
+					{#if layerHidden}
+						<EyeOff class="h-3.5 w-3.5 text-muted-foreground/40" />
+					{:else if layerPartial}
+						<Eye class="h-3.5 w-3.5 text-muted-foreground/60" />
+					{:else}
+						<Eye class="h-3.5 w-3.5 text-muted-foreground" />
+					{/if}
+				</button>
+
+				<span
+					class="min-w-0 text-xs font-medium flex-1 truncate {layerHidden
+						? 'text-muted-foreground/40 line-through'
+						: 'text-foreground'}"
+				>
+					{layerName}
+				</span>
+
+				<span class="shrink-0 text-[10px] text-muted-foreground/50 tabular-nums">
+					{objects.length}
+				</span>
+			</div>
+
+			{#if !collapsed}
+				<div role="listbox" aria-multiselectable="true" class="ml-3 border-l border-border">
+					{#each objects as object (object.uuid)}
+						{@const hidden = hiddenUuids.has(object.uuid)}
+						{@const selected = selectedUuids.has(object.uuid)}
+						<div
+							role="option"
+							aria-selected={selected}
+							tabindex="-1"
+							class="gap-1.5 pl-5 pr-2 py-0.5 flex cursor-pointer items-center transition-colors
+								{selected ? 'bg-primary/10 hover:bg-primary/15' : 'hover:bg-muted'}
+								{hidden ? 'opacity-40' : ''}"
+							onmousedown={(e) => {
+								e.stopPropagation();
+								if (e.shiftKey) e.preventDefault();
+							}}
+							onclick={(e) => selectObject(object.uuid, e)}
+							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) => {
+									e.stopPropagation();
+									toggleObject(object);
+								}}
+								title={hidden ? 'Show' : 'Hide'}
+								aria-label={hidden ? 'Show object' : 'Hide object'}
+							>
+								{#if hidden}
+									<EyeOff class="h-3 w-3 text-muted-foreground/60" />
+								{:else}
+									<Eye class="h-3 w-3 text-muted-foreground" />
+								{/if}
+							</button>
+
+							<!-- Object name -->
+							<span
+								class="min-w-0 text-xs flex-1 truncate {hidden
+									? 'text-muted-foreground line-through'
+									: 'text-foreground/80'}"
+							>
+								{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"
+							>
+								{getTypeLabel(object)}
+							</span>
+						</div>
+					{/each}
+				</div>
+			{/if}
+		{/each}
+
+		<!-- Empty state -->
+		{#if getSceneObjects().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" />
+				<p class="text-xs text-muted-foreground">No objects</p>
+			</div>
+		{:else if getFilteredLayerGroups().size === 0}
+			<div class="py-12 flex flex-col items-center justify-center text-center">
+				<Search class="mb-2 h-5 w-5 text-muted-foreground/30" />
+				<p class="text-xs text-muted-foreground">No results for "{searchQuery}"</p>
+			</div>
+		{/if}
+	</div>
+</div>
+
+<style>
+	div::-webkit-scrollbar {
+		width: 4px;
+	}
+	div::-webkit-scrollbar-track {
+		background: transparent;
+	}
+	div::-webkit-scrollbar-thumb {
+		background: hsl(var(--muted-foreground) / 0.15);
+		border-radius: 2px;
+	}
+</style>

package/dist/components/viewer/SceneManager.svelte.d.ts

@@ -0,0 +1,8 @@
+import * as THREE from 'three';
+interface Props {
+    scene: THREE.Scene;
+    sceneVersion?: number;
+}
+declare const SceneManager: import("svelte").Component<Props, {}, "scene">;
+type SceneManager = ReturnType<typeof SceneManager>;
+export default SceneManager;

package/dist/components/viewer/Viewer.svelte

@@ -0,0 +1,311 @@
+<script lang="ts">
+	import { APP_DEFAULTS } from '../../constants';
+	import { onMount, untrack } from 'svelte';
+	import {
+		initThree,
+		updateScene,
+		type ThreeInitializerOptions
+	} from '@selvajs/compute/visualization';
+	import { Maximize, Minimize, Camera, Layers } from '@lucide/svelte';
+	import type * as THREE from 'three';
+	import type { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+	import SceneManager from './SceneManager.svelte';
+	import MeshMetadataDialog from './MeshMetadataDialog.svelte';
+	import * as Resizable from '../primitives/resizable/index.js';
+
+	export interface ViewerConfig {
+		showScreenshotButton?: boolean;
+		showFullscreenButton?: boolean;
+		showSceneManager?: boolean;
+		enableMeshClick?: boolean;
+		backgroundColor?: string;
+	}
+
+	interface Props {
+		meshes: any[];
+		isFullscreen?: boolean;
+		isSolving?: boolean;
+		isBlurred?: boolean;
+		drawerOpen?: boolean;
+		viewerConfig?: ViewerConfig;
+	}
+
+	const defaultViewerConfig: Required<ViewerConfig> = {
+		showScreenshotButton: true,
+		showFullscreenButton: true,
+		showSceneManager: true,
+		enableMeshClick: true,
+		backgroundColor: '#E6E6E6'
+	};
+
+	let {
+		meshes,
+		isFullscreen = $bindable(false),
+		isSolving = false,
+		isBlurred = false,
+		drawerOpen = false,
+		viewerConfig = {}
+	}: Props = $props();
+
+	const config = $derived({ ...defaultViewerConfig, ...viewerConfig });
+
+	let canvas: HTMLCanvasElement;
+	let scene: THREE.Scene | null = $state(null);
+	let camera: THREE.PerspectiveCamera | null = null;
+	let controls: OrbitControls | null = null;
+	let viewerInitialized = false;
+	let sceneVersion = $state(0);
+	let hideButton = $state(false);
+	let sceneManagerOpen = $state(false);
+	let selectedMeshMetadata: Record<string, any> | null = $state(null);
+	let selectedMeshName: string | null = $state(null);
+
+	// Hide button instantly when expanding, show after animation when collapsing
+	$effect(() => {
+		if (drawerOpen) {
+			hideButton = true;
+		} else {
+			const timer = setTimeout(() => {
+				hideButton = false;
+			}, APP_DEFAULTS.TIMEOUTS.VIEWER_INIT_DELAY);
+			return () => clearTimeout(timer);
+		}
+	});
+
+	onMount(() => {
+		if (!canvas) return;
+
+		const opts: ThreeInitializerOptions = {
+			environment: { backgroundColor: config.backgroundColor },
+			controls: {},
+			events: {
+				onMeshMetadataClicked: config.enableMeshClick
+					? (metadata: Record<string, string>) => {
+							if (hasUsefulMetadata(metadata)) {
+								selectedMeshMetadata = metadata;
+								selectedMeshName = metadata?.name || 'Object';
+							}
+						}
+					: undefined
+			}
+		};
+
+		const init = initThree(canvas, opts);
+		scene = init.scene;
+		camera = init.camera;
+		controls = init.controls;
+
+		return () => {
+			init.dispose();
+		};
+	});
+
+	$effect(() => {
+		if (scene && camera && controls) {
+			updateScene(scene, meshes, camera, controls, viewerInitialized);
+			untrack(() => sceneVersion++);
+
+			if (!viewerInitialized && meshes.length > 0) {
+				viewerInitialized = true;
+			}
+		}
+	});
+
+	function toggleFullscreen() {
+		isFullscreen = !isFullscreen;
+	}
+
+	function hasUsefulMetadata(metadata: Record<string, any>): boolean {
+		if (!metadata) return false;
+
+		if (metadata.metadata && typeof metadata.metadata === 'object') {
+			const nestedMetadata = metadata.metadata;
+			return Object.keys(nestedMetadata).length > 0;
+		}
+
+		const EXCLUDED_KEYS = new Set([
+			'name',
+			'layer',
+			'originalIndex',
+			'sourceComponentId',
+			'vertexCount',
+			'faceCount',
+			'vertexOffset',
+			'faceOffset'
+		]);
+		const usefulEntries = Object.entries(metadata).filter(([key]) => !EXCLUDED_KEYS.has(key));
+		return usefulEntries.length > 0;
+	}
+
+	function downloadScreenshot() {
+		if (!canvas) return;
+
+		requestAnimationFrame(() => {
+			canvas.toBlob((blob) => {
+				if (!blob) return;
+				const url = URL.createObjectURL(blob);
+				const link = document.createElement('a');
+				const timestamp = new Date().toISOString().slice(0, 19).replace(/:/g, '-');
+				link.href = url;
+				link.download = `viewer-${timestamp}.png`;
+				document.body.appendChild(link);
+				link.click();
+				document.body.removeChild(link);
+				URL.revokeObjectURL(url);
+			});
+		});
+	}
+</script>
+
+<div
+	class="min-h-64 sm:min-h-96 lg:min-h-125 relative h-full flex-1 border {isFullscreen
+		? 'fullscreen-viewer'
+		: 'overflow-hidden rounded-[0.625rem]'}"
+>
+	<Resizable.PaneGroup direction="horizontal" class="h-full w-full">
+		<Resizable.Pane defaultSize={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>
+
+				<div
+					class="inset-0 blur-overlay absolute z-20 {isBlurred
+						? 'blur-overlay-active'
+						: 'blur-overlay-inactive'}"
+				></div>
+
+				{#if isSolving}
+					<div
+						class="inset-0 absolute z-10 animate-[selva-viewer-fade-in_0.2s_ease-out] backdrop-blur-[2px] transition-all duration-300"
+					></div>
+				{/if}
+
+				{#if config.showScreenshotButton || config.showFullscreenButton || config.showSceneManager}
+					<div
+						class="right-4 {isFullscreen
+							? 'bottom-4'
+							: 'bottom-16 sm:bottom-4'} gap-2 absolute z-50 flex items-center"
+						style={hideButton
+							? 'opacity: 0; pointer-events: none;'
+							: 'opacity: 1; pointer-events: auto;'}
+					>
+						<!-- Screenshot Button -->
+						{#if config.showScreenshotButton}
+							<button
+								class="h-10 w-10 shadow-lg hover:shadow-xl flex items-center justify-center rounded-lg border border-border bg-card/90 transition-all hover:bg-card active:scale-95"
+								onclick={downloadScreenshot}
+								title="Download screenshot"
+								aria-label="Download screenshot"
+							>
+								<Camera class="h-5 w-5 text-card-foreground" />
+							</button>
+						{/if}
+
+						<!-- Fullscreen Toggle -->
+						{#if config.showFullscreenButton}
+							<button
+								class="h-10 w-10 shadow-lg hover:shadow-xl flex items-center justify-center rounded-lg border border-border bg-card/90 transition-all hover:bg-card active:scale-95"
+								onclick={toggleFullscreen}
+								title={isFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'}
+								aria-label={isFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'}
+							>
+								{#if isFullscreen}
+									<Minimize class="h-5 w-5 text-card-foreground" />
+								{:else}
+									<Maximize class="h-5 w-5 text-card-foreground" />
+								{/if}
+							</button>
+						{/if}
+
+						<!-- Scene Manager Toggle -->
+						{#if config.showSceneManager}
+							<button
+								class="h-10 w-10 shadow-lg hover:shadow-xl flex items-center justify-center rounded-lg border transition-all active:scale-95 {sceneManagerOpen
+									? 'border-muted-foreground/40 bg-secondary/40 hover:bg-secondary/60'
+									: 'border-muted-foreground/50 bg-card/90 hover:bg-secondary/80'}"
+								onclick={() => (sceneManagerOpen = !sceneManagerOpen)}
+								title={sceneManagerOpen ? 'Hide scene manager' : 'Show scene manager'}
+								aria-label="Toggle scene manager"
+							>
+								<Layers
+									class="h-5 w-5 {sceneManagerOpen ? 'text-primary' : 'text-secondary-foreground'}"
+								/>
+							</button>
+						{/if}
+					</div>
+				{/if}
+			</div>
+		</Resizable.Pane>
+
+		<!-- Scene Manager Pane -->
+		{#if sceneManagerOpen && scene}
+			<Resizable.Handle withHandle />
+			<Resizable.Pane defaultSize={15} minSize={8} maxSize={30}>
+				<SceneManager {scene} {sceneVersion} />
+			</Resizable.Pane>
+		{/if}
+	</Resizable.PaneGroup>
+</div>
+
+<MeshMetadataDialog
+	open={selectedMeshMetadata !== null}
+	metadata={selectedMeshMetadata}
+	meshName={selectedMeshName}
+	{isFullscreen}
+	onOpenChange={(open: boolean) => {
+		if (!open) {
+			setTimeout(() => {
+				selectedMeshMetadata = null;
+				selectedMeshName = null;
+			}, 200);
+		}
+	}}
+/>
+
+<style>
+	.fullscreen-viewer {
+		position: fixed;
+		inset: 0;
+		z-index: 10000;
+		border-radius: 0 !important;
+	}
+
+	/* Blur overlay animation */
+	.blur-overlay {
+		pointer-events: none;
+	}
+
+	.blur-overlay-active {
+		animation: blur-in 0.35s cubic-bezier(0.32, 0.72, 0, 1) forwards;
+	}
+
+	.blur-overlay-inactive {
+		animation: blur-out 0.35s cubic-bezier(0.32, 0.72, 0, 1) forwards;
+	}
+
+	@keyframes blur-in {
+		from {
+			backdrop-filter: blur(0px);
+		}
+		to {
+			backdrop-filter: blur(5px);
+		}
+	}
+
+	@keyframes blur-out {
+		from {
+			backdrop-filter: blur(5px);
+		}
+		to {
+			backdrop-filter: blur(0px);
+		}
+	}
+
+	@keyframes selva-viewer-fade-in {
+		from {
+			opacity: 0;
+		}
+		to {
+			opacity: 1;
+		}
+	}
+</style>

package/dist/components/viewer/Viewer.svelte.d.ts

@@ -0,0 +1,18 @@
+export interface ViewerConfig {
+    showScreenshotButton?: boolean;
+    showFullscreenButton?: boolean;
+    showSceneManager?: boolean;
+    enableMeshClick?: boolean;
+    backgroundColor?: string;
+}
+interface Props {
+    meshes: any[];
+    isFullscreen?: boolean;
+    isSolving?: boolean;
+    isBlurred?: boolean;
+    drawerOpen?: boolean;
+    viewerConfig?: ViewerConfig;
+}
+declare const Viewer: import("svelte").Component<Props, {}, "isFullscreen">;
+type Viewer = ReturnType<typeof Viewer>;
+export default Viewer;

package/dist/components/viewer/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Viewer, type ViewerConfig } from './Viewer.svelte';
+export { default as MeshMetadataDialog } from './MeshMetadataDialog.svelte';
+export { default as SceneManager } from './SceneManager.svelte';

package/dist/components/viewer/index.js

@@ -0,0 +1,3 @@
+export { default as Viewer } from './Viewer.svelte';
+export { default as MeshMetadataDialog } from './MeshMetadataDialog.svelte';
+export { default as SceneManager } from './SceneManager.svelte';

package/dist/composables/useFooterItem.svelte.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Register a footer item component that reactively updates its props.
+ * The `getProps` function is called on every render, so returning reactive state
+ * (e.g. `() => ({ status: myState.status })`) will keep the footer in sync.
+ *
+ * Registration is deferred to onMount (client-side only) to avoid SSR context errors.
+ *
+ * @param id        - Unique identifier for this footer item
+ * @param component - Svelte component to render
+ * @param getProps  - Function returning current props (called reactively)
+ * @param position  - Where to display ('left' or 'right'), defaults to 'left'
+ * @param priority  - Higher values render first within their position
+ * @param onClick   - Optional click handler (e.g. open a popup/dialog)
+ */
+export declare function useFooterItem(id: string, component: any, getProps: () => Record<string, any>, position?: 'left' | 'right', priority?: number, onClick?: () => void): void;

package/dist/composables/useFooterItem.svelte.js

@@ -0,0 +1,33 @@
+import { getContext, onMount, onDestroy } from 'svelte';
+import { FOOTER_CONTEXT_KEY } from '../contexts/footerContext.svelte';
+/**
+ * Register a footer item component that reactively updates its props.
+ * The `getProps` function is called on every render, so returning reactive state
+ * (e.g. `() => ({ status: myState.status })`) will keep the footer in sync.
+ *
+ * Registration is deferred to onMount (client-side only) to avoid SSR context errors.
+ *
+ * @param id        - Unique identifier for this footer item
+ * @param component - Svelte component to render
+ * @param getProps  - Function returning current props (called reactively)
+ * @param position  - Where to display ('left' or 'right'), defaults to 'left'
+ * @param priority  - Higher values render first within their position
+ * @param onClick   - Optional click handler (e.g. open a popup/dialog)
+ */
+export function useFooterItem(id, component, getProps, position = 'left', priority = 0, onClick) {
+    onMount(() => {
+        const store = getContext(FOOTER_CONTEXT_KEY);
+        if (!store || !component)
+            return;
+        store.register(id, component, getProps, position, priority, onClick);
+    });
+    onDestroy(() => {
+        try {
+            const store = getContext(FOOTER_CONTEXT_KEY);
+            store?.unregister(id);
+        }
+        catch {
+            // Context may not exist during SSR cleanup — safe to ignore
+        }
+    });
+}