@treasuryspatial/viewer-react 0.1.44 → 0.1.48

package/dist/useComposerUiState.js

@@ -1,119 +1,157 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 const resolveString = (value, fallback) => typeof value === "string" && value.length > 0 ? value : fallback;
-const modeKey = (mode, key) => `ui${key}_${mode}`;
 const resolveBoolean = (value, fallback) => typeof value === "boolean" ? value : fallback;
 const resolvePresetId = (value) => (typeof value === "string" ? value : null);
+const resolveRightPanelTab = (value, fallback) => {
+    if (value === "stream")
+        return "feed";
+    return resolveString(value, fallback);
+};
 const resolveDefaultPrimaryTab = (mode, defaultPrimaryTabByMode) => defaultPrimaryTabByMode?.[mode] ?? (mode === "imagine" ? "render" : "controls");
-export function useComposerUiState({ mode, sessionContext, setSessionContext, defaults, promptKitModes = ["imagine"], moduleKitModes = ["design", "map"], defaultPrimaryTabByMode, }) {
+export function useComposerUiState({ mode, workspaceSession, setWorkspaceSession, defaults, promptKitModes = ["imagine"], moduleKitModes = ["design", "map"], defaultPrimaryTabByMode, }) {
     const modeDefaultTab = resolveDefaultPrimaryTab(mode, defaultPrimaryTabByMode);
-    const initialPrimaryTab = resolveString(sessionContext?.[modeKey(mode, "primaryTab")] ?? sessionContext?.uiPrimaryTab, defaults?.primaryTab ?? modeDefaultTab);
-    const initialPromptOpen = resolveBoolean(sessionContext?.[modeKey(mode, "promptKitOpen")] ?? sessionContext?.uiPromptKitOpen, defaults?.promptKitOpen ?? false);
-    const initialModuleOpen = resolveBoolean(sessionContext?.[modeKey(mode, "moduleKitOpen")] ?? sessionContext?.uiModuleKitOpen, defaults?.moduleKitOpen ?? false);
-    const initialPresetId = resolvePresetId(sessionContext?.[modeKey(mode, "activeImaginePresetId")] ??
-        sessionContext?.uiActiveImaginePresetId) ?? defaults?.activeImaginePresetId ?? null;
-    const initialControlOpen = resolveBoolean(sessionContext?.[modeKey(mode, "controlPanelOpen")] ??
-        sessionContext?.uiControlPanelOpen, defaults?.controlPanelOpen ?? true);
-    const initialRightOpen = resolveBoolean(sessionContext?.[modeKey(mode, "rightPanelOpen")] ?? sessionContext?.uiRightPanelOpen, defaults?.rightPanelOpen ?? false);
-    const initialRightTab = resolveString(sessionContext?.[modeKey(mode, "rightPanelTab")] ?? sessionContext?.uiRightPanelTab, defaults?.rightPanelTab ?? "images");
-    const [primaryTab, setPrimaryTabState] = useState(initialPrimaryTab);
-    const [promptKitOpen, setPromptKitOpenState] = useState(initialPromptOpen);
-    const [moduleKitOpen, setModuleKitOpenState] = useState(initialModuleOpen);
-    const [activeImaginePresetId, setActiveImaginePresetIdState] = useState(initialPresetId);
-    const [controlPanelOpen, setControlPanelOpenState] = useState(initialControlOpen);
-    const [rightPanelOpen, setRightPanelOpenState] = useState(initialRightOpen);
-    const [rightPanelTab, setRightPanelTabState] = useState(initialRightTab);
-    const hydratedRef = useRef(false);
+    const resolveWorkspaceValue = useCallback(() => ({
+        primaryTab: resolveString(workspaceSession?.uiState.primaryTabByMode?.[mode], defaults?.primaryTab ?? modeDefaultTab),
+        promptKitOpen: resolveBoolean(workspaceSession?.uiState.promptKitOpenByMode?.[mode], defaults?.promptKitOpen ?? false),
+        moduleKitOpen: resolveBoolean(workspaceSession?.uiState.moduleKitOpenByMode?.[mode], defaults?.moduleKitOpen ?? false),
+        activeImaginePresetId: resolvePresetId(workspaceSession?.uiState.activeImaginePresetIdByMode?.[mode]) ??
+            defaults?.activeImaginePresetId ??
+            null,
+        autoGenerateEnabled: resolveBoolean(workspaceSession?.uiState.autoGenerateEnabledByMode?.[mode], defaults?.autoGenerateEnabled ?? false),
+        controlPanelOpen: resolveBoolean(workspaceSession?.uiState.controlPanelOpenByMode?.[mode], defaults?.controlPanelOpen ?? true),
+        rightPanelOpen: resolveBoolean(workspaceSession?.uiState.rightPanelOpenByMode?.[mode], defaults?.rightPanelOpen ?? false),
+        rightPanelTab: resolveRightPanelTab(workspaceSession?.uiState.rightPanelTabByMode?.[mode], defaults?.rightPanelTab ?? "feed"),
+    }), [defaults, mode, modeDefaultTab, workspaceSession]);
+    const initialValue = resolveWorkspaceValue();
+    const [primaryTab, setPrimaryTabState] = useState(initialValue.primaryTab);
+    const [promptKitOpen, setPromptKitOpenState] = useState(initialValue.promptKitOpen);
+    const [moduleKitOpen, setModuleKitOpenState] = useState(initialValue.moduleKitOpen);
+    const [activeImaginePresetId, setActiveImaginePresetIdState] = useState(initialValue.activeImaginePresetId);
+    const [autoGenerateEnabled, setAutoGenerateEnabledState] = useState(initialValue.autoGenerateEnabled);
+    const [controlPanelOpen, setControlPanelOpenState] = useState(initialValue.controlPanelOpen);
+    const [rightPanelOpen, setRightPanelOpenState] = useState(initialValue.rightPanelOpen);
+    const [rightPanelTab, setRightPanelTabState] = useState(initialValue.rightPanelTab);
+    // Per-field delta sync: only apply a session value when the SESSION
+    // changed that field. The previous whole-snapshot stomp raced local
+    // writes — clicking a toggle (e.g. the module chooser) opened it locally
+    // while the session write was still in flight; any unrelated session
+    // churn (draft saves, hydration) then re-applied the stale session value
+    // and instantly reverted the click.
+    const lastResolvedRef = useRef(null);
     useEffect(() => {
-        if (hydratedRef.current)
+        const next = resolveWorkspaceValue();
+        const prev = lastResolvedRef.current;
+        lastResolvedRef.current = next;
+        if (!prev)
+            return; // initial useState already seeded from the session
+        if (next.primaryTab !== prev.primaryTab)
+            setPrimaryTabState(next.primaryTab);
+        if (next.promptKitOpen !== prev.promptKitOpen)
+            setPromptKitOpenState(next.promptKitOpen);
+        if (next.moduleKitOpen !== prev.moduleKitOpen)
+            setModuleKitOpenState(next.moduleKitOpen);
+        if (next.activeImaginePresetId !== prev.activeImaginePresetId)
+            setActiveImaginePresetIdState(next.activeImaginePresetId);
+        if (next.autoGenerateEnabled !== prev.autoGenerateEnabled)
+            setAutoGenerateEnabledState(next.autoGenerateEnabled);
+        if (next.controlPanelOpen !== prev.controlPanelOpen)
+            setControlPanelOpenState(next.controlPanelOpen);
+        if (next.rightPanelOpen !== prev.rightPanelOpen)
+            setRightPanelOpenState(next.rightPanelOpen);
+        if (next.rightPanelTab !== prev.rightPanelTab)
+            setRightPanelTabState(next.rightPanelTab);
+    }, [resolveWorkspaceValue]);
+    const updateWorkspaceUiState = useCallback((updater) => {
+        if (!setWorkspaceSession)
             return;
-        hydratedRef.current = true;
-        if (!sessionContext)
-            return;
-        setPrimaryTabState(resolveString(sessionContext.uiPrimaryTab, initialPrimaryTab));
-        setPromptKitOpenState(resolveBoolean(sessionContext.uiPromptKitOpen, initialPromptOpen));
-        setModuleKitOpenState(resolveBoolean(sessionContext.uiModuleKitOpen, initialModuleOpen));
-        setActiveImaginePresetIdState(resolvePresetId(sessionContext.uiActiveImaginePresetId) ?? initialPresetId);
-        setControlPanelOpenState(resolveBoolean(sessionContext.uiControlPanelOpen, initialControlOpen));
-        setRightPanelOpenState(resolveBoolean(sessionContext.uiRightPanelOpen, initialRightOpen));
-        setRightPanelTabState(resolveString(sessionContext.uiRightPanelTab, initialRightTab));
-    }, [
-        initialControlOpen,
-        initialModuleOpen,
-        initialPresetId,
-        initialPrimaryTab,
-        initialPromptOpen,
-        initialRightOpen,
-        initialRightTab,
-        sessionContext,
-    ]);
-    const setContext = useCallback((partial) => {
-        if (!setSessionContext)
-            return;
-        setSessionContext(partial);
-    }, [setSessionContext]);
+        setWorkspaceSession((session) => ({
+            ...session,
+            uiState: updater(session.uiState),
+        }));
+    }, [setWorkspaceSession]);
     const setPrimaryTab = useCallback((next) => {
         setPrimaryTabState(next);
-        setContext({ uiPrimaryTab: next, [modeKey(mode, "primaryTab")]: next });
-    }, [mode, setContext]);
+        updateWorkspaceUiState((uiState) => ({
+            ...uiState,
+            primaryTabByMode: { ...uiState.primaryTabByMode, [mode]: next },
+        }));
+    }, [mode, updateWorkspaceUiState]);
     const setPromptKitOpen = useCallback((next) => {
         setPromptKitOpenState(next);
-        setContext({ uiPromptKitOpen: next, [modeKey(mode, "promptKitOpen")]: next });
-    }, [mode, setContext]);
+        updateWorkspaceUiState((uiState) => ({
+            ...uiState,
+            promptKitOpenByMode: { ...uiState.promptKitOpenByMode, [mode]: next },
+        }));
+    }, [mode, updateWorkspaceUiState]);
     const setModuleKitOpen = useCallback((next) => {
         setModuleKitOpenState(next);
-        setContext({ uiModuleKitOpen: next, [modeKey(mode, "moduleKitOpen")]: next });
-    }, [mode, setContext]);
+        updateWorkspaceUiState((uiState) => ({
+            ...uiState,
+            moduleKitOpenByMode: { ...uiState.moduleKitOpenByMode, [mode]: next },
+        }));
+    }, [mode, updateWorkspaceUiState]);
     const setActiveImaginePresetId = useCallback((next) => {
         setActiveImaginePresetIdState(next);
-        setContext({ uiActiveImaginePresetId: next, [modeKey(mode, "activeImaginePresetId")]: next });
-    }, [mode, setContext]);
+        updateWorkspaceUiState((uiState) => ({
+            ...uiState,
+            activeImaginePresetIdByMode: { ...uiState.activeImaginePresetIdByMode, [mode]: next },
+        }));
+    }, [mode, updateWorkspaceUiState]);
+    const setAutoGenerateEnabled = useCallback((next) => {
+        setAutoGenerateEnabledState(next);
+        updateWorkspaceUiState((uiState) => ({
+            ...uiState,
+            autoGenerateEnabledByMode: { ...uiState.autoGenerateEnabledByMode, [mode]: next },
+        }));
+    }, [mode, updateWorkspaceUiState]);
     const setControlPanelOpen = useCallback((next) => {
         setControlPanelOpenState(next);
-        setContext({ uiControlPanelOpen: next, [modeKey(mode, "controlPanelOpen")]: next });
-    }, [mode, setContext]);
+        updateWorkspaceUiState((uiState) => ({
+            ...uiState,
+            controlPanelOpenByMode: { ...uiState.controlPanelOpenByMode, [mode]: next },
+        }));
+    }, [mode, updateWorkspaceUiState]);
     const setRightPanelOpen = useCallback((next) => {
         setRightPanelOpenState(next);
-        setContext({ uiRightPanelOpen: next, [modeKey(mode, "rightPanelOpen")]: next });
-    }, [mode, setContext]);
+        updateWorkspaceUiState((uiState) => ({
+            ...uiState,
+            rightPanelOpenByMode: { ...uiState.rightPanelOpenByMode, [mode]: next },
+        }));
+    }, [mode, updateWorkspaceUiState]);
     const setRightPanelTab = useCallback((next) => {
         setRightPanelTabState(next);
-        setContext({ uiRightPanelTab: next, [modeKey(mode, "rightPanelTab")]: next });
-    }, [mode, setContext]);
-    const modeRef = useRef(null);
-    useEffect(() => {
-        if (modeRef.current === mode)
-            return;
-        modeRef.current = mode;
-        if (!sessionContext)
-            return;
-        setPrimaryTabState(resolveString(sessionContext?.[modeKey(mode, "primaryTab")] ?? sessionContext?.uiPrimaryTab, resolveDefaultPrimaryTab(mode, defaultPrimaryTabByMode)));
-        setPromptKitOpenState(resolveBoolean(sessionContext?.[modeKey(mode, "promptKitOpen")] ??
-            sessionContext?.uiPromptKitOpen, false));
-        setModuleKitOpenState(resolveBoolean(sessionContext?.[modeKey(mode, "moduleKitOpen")] ??
-            sessionContext?.uiModuleKitOpen, false));
-        setActiveImaginePresetIdState(resolvePresetId(sessionContext?.[modeKey(mode, "activeImaginePresetId")] ??
-            sessionContext?.uiActiveImaginePresetId) ?? null);
-        setControlPanelOpenState(resolveBoolean(sessionContext?.[modeKey(mode, "controlPanelOpen")] ??
-            sessionContext?.uiControlPanelOpen, true));
-        setRightPanelOpenState(resolveBoolean(sessionContext?.[modeKey(mode, "rightPanelOpen")] ??
-            sessionContext?.uiRightPanelOpen, false));
-        setRightPanelTabState(resolveString(sessionContext?.[modeKey(mode, "rightPanelTab")] ??
-            sessionContext?.uiRightPanelTab, "images"));
-    }, [defaultPrimaryTabByMode, mode, sessionContext]);
+        updateWorkspaceUiState((uiState) => ({
+            ...uiState,
+            rightPanelTabByMode: { ...uiState.rightPanelTabByMode, [mode]: next },
+        }));
+    }, [mode, updateWorkspaceUiState]);
     const gatedPromptKitOpen = useMemo(() => (promptKitModes.includes(mode) ? promptKitOpen : false), [mode, promptKitOpen, promptKitModes]);
     const gatedModuleKitOpen = useMemo(() => (moduleKitModes.includes(mode) ? moduleKitOpen : false), [mode, moduleKitOpen, moduleKitModes]);
+    const chooserOpen = gatedPromptKitOpen || gatedModuleKitOpen;
+    const setChooserOpen = useCallback((next) => {
+        if (promptKitModes.includes(mode)) {
+            setPromptKitOpen(next);
+        }
+        if (moduleKitModes.includes(mode)) {
+            setModuleKitOpen(next);
+        }
+    }, [mode, moduleKitModes, promptKitModes, setModuleKitOpen, setPromptKitOpen]);
     return {
         primaryTab,
         promptKitOpen: gatedPromptKitOpen,
         moduleKitOpen: gatedModuleKitOpen,
+        chooserOpen,
         activeImaginePresetId,
+        autoGenerateEnabled,
         controlPanelOpen,
         rightPanelOpen,
         rightPanelTab,
         setPrimaryTab,
         setPromptKitOpen,
         setModuleKitOpen,
+        setChooserOpen,
         setActiveImaginePresetId,
+        setAutoGenerateEnabled,
         setControlPanelOpen,
         setRightPanelOpen,
         setRightPanelTab,

package/dist/useComposerWorkspaceSession.d.ts

@@ -0,0 +1,21 @@
+import { type ComposerWorkspaceSession, type ComposerWorkspaceSessionUpdater } from './workspaceSession';
+export type WorkspaceSessionRemoteStatus = 'idle' | 'loading' | 'ready' | 'error';
+export type UseComposerWorkspaceSessionOptions<TDraft> = {
+    activeMode: string;
+    modeIds?: string[];
+    enabled?: boolean;
+    remoteEndpoint?: string;
+    storageKey?: string;
+    createDraft: () => TDraft;
+    restoreDraft: (raw: unknown) => TDraft;
+};
+export declare function useComposerWorkspaceSession<TDraft>({ activeMode, modeIds, enabled, remoteEndpoint, storageKey, createDraft, restoreDraft, }: UseComposerWorkspaceSessionOptions<TDraft>): {
+    workspaceSession: ComposerWorkspaceSession<TDraft>;
+    workspaceSessionHydrated: boolean;
+    remoteHydrated: boolean;
+    remoteStatus: WorkspaceSessionRemoteStatus;
+    remoteError: string | null;
+    setWorkspaceSession: (updater: ComposerWorkspaceSessionUpdater<TDraft>) => void;
+    clearWorkspaceSession: () => void;
+};
+//# sourceMappingURL=useComposerWorkspaceSession.d.ts.map

package/dist/useComposerWorkspaceSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useComposerWorkspaceSession.d.ts","sourceRoot":"","sources":["../src/useComposerWorkspaceSession.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,+BAA+B,EACrC,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,4BAA4B,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAElF,MAAM,MAAM,kCAAkC,CAAC,MAAM,IAAI;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B,YAAY,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;CACxC,CAAC;AA0CF,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,EAClD,UAAU,EACV,OAAY,EACZ,OAAe,EACf,cAAyC,EACzC,UAAgC,EAChC,WAAW,EACX,YAAY,GACb,EAAE,kCAAkC,CAAC,MAAM,CAAC,GAAG;IAC9C,gBAAgB,EAAE,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACnD,wBAAwB,EAAE,OAAO,CAAC;IAClC,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,4BAA4B,CAAC;IAC3C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,mBAAmB,EAAE,CAAC,OAAO,EAAE,+BAA+B,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAChF,qBAAqB,EAAE,MAAM,IAAI,CAAC;CACnC,CA2QA"}

package/dist/useComposerWorkspaceSession.js

@@ -0,0 +1,291 @@
+'use client';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { createEmptyComposerWorkspaceSession, restoreComposerWorkspaceSession, } from './workspaceSession';
+const DEFAULT_STORAGE_KEY = 'treasury:composer-workspace-session:v1';
+const REMOTE_SAVE_DEBOUNCE_MS = 800;
+const isAbortError = (error) => error instanceof Error && error.name === 'AbortError';
+const readUpdatedAtMs = (session) => {
+    const parsed = Date.parse(session.updatedAt ?? '');
+    return Number.isFinite(parsed) ? parsed : null;
+};
+const shouldPreferLocalSession = (localSession, remoteSession) => {
+    const localUpdatedAtMs = readUpdatedAtMs(localSession);
+    const remoteUpdatedAtMs = readUpdatedAtMs(remoteSession);
+    if (localUpdatedAtMs !== null && remoteUpdatedAtMs !== null) {
+        return localUpdatedAtMs > remoteUpdatedAtMs;
+    }
+    if (localUpdatedAtMs !== null && remoteUpdatedAtMs === null) {
+        return true;
+    }
+    return false;
+};
+const resolveRemoteError = (payload, status, fallback) => {
+    if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+        const record = payload;
+        const error = record.error;
+        if (typeof error === 'string' && error.trim())
+            return error.trim();
+        if (error && typeof error === 'object' && !Array.isArray(error)) {
+            const message = error.message;
+            if (typeof message === 'string' && message.trim())
+                return message.trim();
+        }
+        if (typeof record.message === 'string' && record.message.trim())
+            return record.message.trim();
+    }
+    return `${fallback} (${status || 0})`;
+};
+export function useComposerWorkspaceSession({ activeMode, modeIds = [], enabled = false, remoteEndpoint = '/api/workspace/session', storageKey = DEFAULT_STORAGE_KEY, createDraft, restoreDraft, }) {
+    const restoreOptions = useMemo(() => ({
+        createDraft,
+        restoreDraft,
+        activeMode,
+        modeIds,
+    }), [activeMode, createDraft, modeIds, restoreDraft]);
+    const normalizeSession = useCallback((value) => restoreComposerWorkspaceSession(value, restoreOptions), [restoreOptions]);
+    const createEmptySession = useCallback(() => createEmptyComposerWorkspaceSession(createDraft, { activeMode, modeIds }), [activeMode, createDraft, modeIds]);
+    const [workspaceSession, setWorkspaceSessionState] = useState(() => createEmptyComposerWorkspaceSession(createDraft, { activeMode, modeIds }));
+    const [workspaceSessionHydrated, setWorkspaceSessionHydrated] = useState(false);
+    const [remoteHydrated, setRemoteHydrated] = useState(!enabled);
+    const [remoteStatus, setRemoteStatus] = useState(enabled ? 'loading' : 'idle');
+    const [remoteError, setRemoteError] = useState(null);
+    const lastSyncedSignatureRef = useRef('');
+    const remoteSaveTimerRef = useRef(null);
+    const setWorkspaceSession = useCallback((updater) => {
+        setWorkspaceSessionState((prev) => {
+            const normalizedPrev = normalizeSession(prev);
+            const nextCandidate = updater(normalizedPrev);
+            const normalizedNext = normalizeSession({
+                ...nextCandidate,
+                activeMode: nextCandidate.activeMode || activeMode,
+            });
+            const previousSignature = JSON.stringify(normalizedPrev);
+            const nextSignature = JSON.stringify(normalizedNext);
+            if (previousSignature === nextSignature) {
+                return prev;
+            }
+            return {
+                ...normalizedNext,
+                updatedAt: new Date().toISOString(),
+            };
+        });
+    }, [activeMode, normalizeSession]);
+    const clearWorkspaceSession = useCallback(() => {
+        const next = createEmptySession();
+        const nextSignature = JSON.stringify(normalizeSession(next));
+        if (typeof window !== 'undefined') {
+            window.sessionStorage.removeItem(storageKey);
+        }
+        setWorkspaceSessionState(next);
+        setRemoteError(null);
+        lastSyncedSignatureRef.current = '';
+        if (!enabled) {
+            setRemoteStatus('idle');
+            setRemoteHydrated(true);
+            lastSyncedSignatureRef.current = nextSignature;
+            return;
+        }
+        setRemoteStatus('loading');
+        setRemoteHydrated(false);
+        void (async () => {
+            try {
+                const response = await fetch(remoteEndpoint, {
+                    method: 'DELETE',
+                    cache: 'no-store',
+                    credentials: 'same-origin',
+                });
+                const payload = await response.json().catch(() => null);
+                if (!response.ok || !payload?.success) {
+                    throw new Error(resolveRemoteError(payload, response.status, 'Workspace session delete failed'));
+                }
+                lastSyncedSignatureRef.current = nextSignature;
+                setRemoteStatus('ready');
+                setRemoteError(null);
+            }
+            catch (error) {
+                setRemoteStatus('error');
+                setRemoteError(error instanceof Error ? error.message : 'Workspace session delete failed');
+            }
+            finally {
+                setRemoteHydrated(true);
+            }
+        })();
+    }, [createEmptySession, enabled, normalizeSession, remoteEndpoint, storageKey]);
+    useEffect(() => {
+        if (typeof window === 'undefined') {
+            setWorkspaceSessionHydrated(true);
+            return;
+        }
+        try {
+            const raw = window.sessionStorage.getItem(storageKey);
+            if (!raw) {
+                setWorkspaceSessionState(createEmptySession());
+            }
+            else {
+                const parsed = JSON.parse(raw);
+                setWorkspaceSessionState(normalizeSession(parsed));
+            }
+        }
+        catch {
+            setWorkspaceSessionState(createEmptySession());
+        }
+        finally {
+            setWorkspaceSessionHydrated(true);
+        }
+    }, [createEmptySession, normalizeSession, storageKey]);
+    useEffect(() => {
+        if (!workspaceSessionHydrated)
+            return;
+        setWorkspaceSession((session) => {
+            if (session.activeMode === activeMode)
+                return session;
+            return { ...session, activeMode };
+        });
+    }, [activeMode, setWorkspaceSession, workspaceSessionHydrated]);
+    useEffect(() => {
+        if (!workspaceSessionHydrated || typeof window === 'undefined')
+            return;
+        try {
+            window.sessionStorage.setItem(storageKey, JSON.stringify(workspaceSession));
+        }
+        catch {
+            // Ignore crash-cache persistence failures.
+        }
+    }, [storageKey, workspaceSession, workspaceSessionHydrated]);
+    useEffect(() => {
+        if (!workspaceSessionHydrated)
+            return;
+        if (!enabled) {
+            setRemoteHydrated(true);
+            setRemoteStatus('idle');
+            setRemoteError(null);
+            return;
+        }
+        let cancelled = false;
+        const controller = new AbortController();
+        setRemoteHydrated(false);
+        setRemoteStatus('loading');
+        setRemoteError(null);
+        const loadRemoteWorkspaceSession = async () => {
+            try {
+                const response = await fetch(remoteEndpoint, {
+                    method: 'GET',
+                    cache: 'no-store',
+                    credentials: 'same-origin',
+                    signal: controller.signal,
+                });
+                const payload = await response.json().catch(() => null);
+                if (!response.ok || !payload?.success) {
+                    throw new Error(resolveRemoteError(payload, response.status, 'Workspace session load failed'));
+                }
+                if (cancelled)
+                    return;
+                const remoteSessionRaw = payload?.session ?? null;
+                setWorkspaceSessionState((prev) => {
+                    const localSession = normalizeSession(prev);
+                    if (!remoteSessionRaw) {
+                        return localSession;
+                    }
+                    const remoteSession = normalizeSession(remoteSessionRaw);
+                    if (shouldPreferLocalSession(localSession, remoteSession)) {
+                        return localSession;
+                    }
+                    lastSyncedSignatureRef.current = JSON.stringify(remoteSession);
+                    const localSignature = JSON.stringify(localSession);
+                    const remoteSignature = lastSyncedSignatureRef.current;
+                    return localSignature === remoteSignature ? prev : remoteSession;
+                });
+                setRemoteStatus('ready');
+                setRemoteError(null);
+            }
+            catch (error) {
+                if (cancelled || isAbortError(error))
+                    return;
+                setRemoteStatus('error');
+                setRemoteError(error instanceof Error ? error.message : 'Workspace session load failed');
+            }
+            finally {
+                if (!cancelled) {
+                    setRemoteHydrated(true);
+                }
+            }
+        };
+        void loadRemoteWorkspaceSession();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [enabled, normalizeSession, remoteEndpoint, workspaceSessionHydrated]);
+    useEffect(() => {
+        if (!workspaceSessionHydrated)
+            return;
+        if (!enabled || !remoteHydrated)
+            return;
+        const normalizedSession = normalizeSession(workspaceSession);
+        const nextSignature = JSON.stringify(normalizedSession);
+        if (nextSignature === lastSyncedSignatureRef.current) {
+            return;
+        }
+        if (remoteSaveTimerRef.current) {
+            clearTimeout(remoteSaveTimerRef.current);
+            remoteSaveTimerRef.current = null;
+        }
+        remoteSaveTimerRef.current = setTimeout(() => {
+            const controller = new AbortController();
+            const persistRemoteWorkspaceSession = async () => {
+                try {
+                    const response = await fetch(remoteEndpoint, {
+                        method: 'PUT',
+                        cache: 'no-store',
+                        credentials: 'same-origin',
+                        headers: {
+                            'Content-Type': 'application/json',
+                        },
+                        body: JSON.stringify({ session: normalizedSession }),
+                        signal: controller.signal,
+                    });
+                    const payload = await response.json().catch(() => null);
+                    if (!response.ok || !payload?.success) {
+                        throw new Error(resolveRemoteError(payload, response.status, 'Workspace session save failed'));
+                    }
+                    const savedSession = normalizeSession(payload?.session ?? normalizedSession);
+                    const savedSignature = JSON.stringify(savedSession);
+                    lastSyncedSignatureRef.current = savedSignature;
+                    setRemoteStatus('ready');
+                    setRemoteError(null);
+                    setWorkspaceSessionState((prev) => {
+                        const localSession = normalizeSession(prev);
+                        const localSignature = JSON.stringify(localSession);
+                        if (localSignature === savedSignature || shouldPreferLocalSession(localSession, savedSession)) {
+                            return prev;
+                        }
+                        return savedSession;
+                    });
+                }
+                catch (error) {
+                    if (isAbortError(error))
+                        return;
+                    setRemoteStatus('error');
+                    setRemoteError(error instanceof Error ? error.message : 'Workspace session save failed');
+                }
+            };
+            void persistRemoteWorkspaceSession();
+            return () => controller.abort();
+        }, REMOTE_SAVE_DEBOUNCE_MS);
+        return () => {
+            if (remoteSaveTimerRef.current) {
+                clearTimeout(remoteSaveTimerRef.current);
+                remoteSaveTimerRef.current = null;
+            }
+        };
+    }, [enabled, normalizeSession, remoteEndpoint, remoteHydrated, workspaceSession, workspaceSessionHydrated]);
+    return {
+        workspaceSession,
+        workspaceSessionHydrated,
+        remoteHydrated,
+        remoteStatus,
+        remoteError,
+        setWorkspaceSession,
+        clearWorkspaceSession,
+    };
+}

package/dist/useGrasshopperSession.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useGrasshopperSession.d.ts","sourceRoot":"","sources":["../src/useGrasshopperSession.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,6BAA6B,CAAC;AAC3E,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,EACb,MAAM,6BAA6B,CAAC;AAQrC,KAAK,iBAAiB,GAAG,gBAAgB,GAAG;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAiGF,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;QACnB,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;QAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IACnD,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,iBAAiB,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAClD,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACrD,KAAK,EAAE,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;IAC5F,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,EACpC,QAA0B,EAC1B,OAAO,EACP,kBAAkB,EAClB,UAAU,EACV,OAAO,GACR,GAAE,yBAA8B,GAAG,uBAAuB,CAgI1D"}
+{"version":3,"file":"useGrasshopperSession.d.ts","sourceRoot":"","sources":["../src/useGrasshopperSession.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,6BAA6B,CAAC;AAC3E,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,EACb,MAAM,6BAA6B,CAAC;AAQrC,KAAK,iBAAiB,GAAG,gBAAgB,GAAG;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAuGF,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;QACnB,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;QAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IACnD,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,iBAAiB,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAClD,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACrD,KAAK,EAAE,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;IAC5F,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,EACpC,QAA0B,EAC1B,OAAO,EACP,kBAAkB,EAClB,UAAU,EACV,OAAO,GACR,GAAE,yBAA8B,GAAG,uBAAuB,CAgI1D"}

package/dist/useGrasshopperSession.js

@@ -2,6 +2,8 @@ import { useCallback, useMemo, useRef, useState } from "react";
 import { buildGrasshopperDefaults, buildGrasshopperValues, solveGrasshopperFile, warmGrasshopperSolver, } from "@treasuryspatial/viewer-kit";
 const sanitizeGhKey = (value) => value.replace(/[^a-zA-Z0-9_-]/g, "_");
 const resolveGhParamName = (input, index) => {
+    if (input.paramName)
+        return input.paramName;
     if (input.name)
         return input.name;
     if (input.nickname)
@@ -56,10 +58,14 @@ const buildGhPanelField = (input, index) => {
     const label = resolveGhLabel(input, index);
     const type = (input.type ?? "").toLowerCase();
     const options = Array.isArray(input.options)
-        ? input.options.map((option, optionIndex) => ({
-            value: option?.value ?? optionIndex,
-            label: option?.label ?? String(option?.value ?? optionIndex),
-        }))
+        ? input.options.map((option, optionIndex) => {
+            const optionRecord = typeof option === "object" && option !== null ? option : null;
+            const value = optionRecord?.value ?? optionIndex;
+            return {
+                value: typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : optionIndex,
+                label: typeof optionRecord?.label === "string" ? optionRecord.label : String(value),
+            };
+        })
         : undefined;
     if (options && options.length > 0) {
         return { key, label, control: "select", options };

package/dist/useModeShellState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useModeShellState.d.ts","sourceRoot":"","sources":["../src/useModeShellState.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAWF,wBAAgB,iBAAiB,CAAC,EAChC,IAAI,EACJ,MAAM,EACN,gBAAuB,EACvB,kBAA0B,EAC1B,oBAA4B,EAC5B,OAAc,GACf,EAAE,wBAAwB;;;;;;;;;;EA0E1B"}
+{"version":3,"file":"useModeShellState.d.ts","sourceRoot":"","sources":["../src/useModeShellState.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAKtE,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAWF,wBAAgB,iBAAiB,CAAC,EAChC,IAAI,EACJ,MAAM,EACN,gBAAuB,EACvB,kBAA0B,EAC1B,oBAA4B,EAC5B,OAAc,GACf,EAAE,wBAAwB;;;;;;;;;;EAyH1B"}