@johndimm/constellations 1.0.1 → 1.0.2

package/hooks/useGraphState.ts

@@ -1,19 +1,32 @@
+"use client";
 import React, { useState, useEffect, useRef, useCallback } from 'react';
 import { GraphNode, GraphLink } from '../types';
 import { LockedPair, findWikipediaTitle } from '../services/geminiService';
-import { fetchServerImage } from '../services/imageService';
+import { fetchServerImage, getImageApiBaseUrl } from '../services/imageService';
 import { dedupeGraph } from '../services/graphUtils';
 import { GraphHandle } from '../components/Graph';
+import type { ConstellationsSessionHandoffV1 } from '../sessionHandoff';
+import { graphFromHandoff } from '../sessionHandoff';
 
 interface UseGraphStateOptions {
     cacheEnabled: boolean;
     cacheBaseUrl: string;
+    /** Restored session from player embed → full screen (no re-query). */
+    initialSession?: ConstellationsSessionHandoffV1 | null;
+    /**
+     * - `undefined` — measure the browser viewport (default standalone layout).
+     * - `null` — embedded: container not mounted yet; use a placeholder size until the ref attaches.
+     * - `HTMLElement` — embedded: size the graph to this element (ResizeObserver).
+     */
+    boundElement?: HTMLElement | null;
 }
 
 export function useGraphState(options: UseGraphStateOptions) {
-    const { cacheEnabled, cacheBaseUrl } = options;
+    const { cacheEnabled, cacheBaseUrl, boundElement, initialSession: initialSessionOpt } = options;
+    const initialSession = initialSessionOpt && initialSessionOpt.graph?.nodes?.length ? initialSessionOpt : null;
+    const initialGraph = initialSession ? graphFromHandoff(initialSession) : { nodes: [] as GraphNode[], links: [] as GraphLink[] };
 
-    const [graphData, setGraphData] = useState<{ nodes: GraphNode[], links: GraphLink[] }>({ nodes: [], links: [] });
+    const [graphData, setGraphData] = useState<{ nodes: GraphNode[], links: GraphLink[] }>(initialGraph);
     const { nodes, links } = graphData;
     const graphDataRef = useRef(graphData);
 
@@ -25,20 +38,22 @@ export function useGraphState(options: UseGraphStateOptions) {
     const [selectedNode, setSelectedNode] = useState<GraphNode | null>(null);
     const [selectedLink, setSelectedLink] = useState<GraphLink | null>(null);
 
-    const [isCompact, setIsCompact] = useState(false);
-    const [isTimelineMode, setIsTimelineMode] = useState(false);
-    const [isTextOnly, setIsTextOnly] = useState(false);
-    const [searchMode, setSearchMode] = useState<'explore' | 'connect'>('explore');
+    const [isCompact, setIsCompact] = useState(!!initialSession?.isCompact);
+    const [isTimelineMode, setIsTimelineMode] = useState(!!initialSession?.isTimelineMode);
+    const [isTextOnly, setIsTextOnly] = useState(!!initialSession?.isTextOnly);
+    const [searchMode, setSearchMode] = useState<'explore' | 'connect'>(initialSession?.searchMode ?? 'explore');
     const [error, setError] = useState<string | null>(null);
     const [isKeyReady, setIsKeyReady] = useState(false);
-    const [searchId, setSearchId] = useState(0);
-    const searchIdRef = useRef(0);
+    const [searchId, setSearchId] = useState(initialSession?.searchId ?? 0);
+    const searchIdRef = useRef(initialSession?.searchId ?? 0);
 
     useEffect(() => {
         searchIdRef.current = searchId;
     }, [searchId]);
 
-    const [lockedPair, setLockedPair] = useState<LockedPair>({ atomicType: "Person", compositeType: "Event" });
+    const [lockedPair, setLockedPair] = useState<LockedPair>(
+        initialSession?.lockedPair ?? { atomicType: "Person", compositeType: "Event" }
+    );
     const lockedPairRef = useRef<LockedPair>(lockedPair);
     useEffect(() => { lockedPairRef.current = lockedPair; }, [lockedPair]);
 
@@ -55,7 +70,7 @@ export function useGraphState(options: UseGraphStateOptions) {
     const autoExpandMoreDoneRef = useRef<Set<string | number>>(new Set());
 
     const [deletePreview, setDeletePreview] = useState<{ keepIds: (number | string)[], dropIds: (number | string)[] } | null>(null);
-    const [pathNodeIds, setPathNodeIds] = useState<(number | string)[]>([]);
+    const [pathNodeIds, setPathNodeIds] = useState<(number | string)[]>(initialSession?.pathNodeIds ?? []);
     const [newlyExpandedNodeIds, setNewlyExpandedNodeIds] = useState<(number | string)[]>([]);
     const [expandingNodeId, setExpandingNodeId] = useState<number | string | null>(null);
     const [newChildNodeIds, setNewChildNodeIds] = useState<Set<number | string>>(new Set());
@@ -77,12 +92,44 @@ export function useGraphState(options: UseGraphStateOptions) {
     const [peopleBrowserOpen, setPeopleBrowserOpen] = useState(false);
     const [savedGraphs, setSavedGraphs] = useState<string[]>([]);
 
-    const [dimensions, setDimensions] = useState({ width: window.innerWidth, height: window.innerHeight });
+    const [dimensions, setDimensions] = useState(() => {
+        if (boundElement === undefined) {
+            if (typeof window === "undefined") return { width: 800, height: 600 };
+            return { width: window.innerWidth, height: window.innerHeight };
+        }
+        if (boundElement) {
+            const r = boundElement.getBoundingClientRect();
+            return { width: Math.max(1, r.width), height: Math.max(1, r.height) };
+        }
+        return { width: 800, height: 600 };
+    });
     useEffect(() => {
-        const handleResize = () => setDimensions({ width: window.innerWidth, height: window.innerHeight });
-        window.addEventListener('resize', handleResize);
-        return () => window.removeEventListener('resize', handleResize);
-    }, []);
+        if (boundElement === undefined) {
+            const handleResize = () => setDimensions({ width: window.innerWidth, height: window.innerHeight });
+            handleResize();
+            window.addEventListener('resize', handleResize);
+            return () => window.removeEventListener('resize', handleResize);
+        }
+        if (boundElement === null) {
+            return;
+        }
+        const el = boundElement;
+        const ro = new ResizeObserver((entries) => {
+            for (const e of entries) {
+                const w = e.contentRect.width;
+                const h = e.contentRect.height;
+                if (w > 0 && h > 0) {
+                    setDimensions({ width: w, height: h });
+                }
+            }
+        });
+        ro.observe(el);
+        const r = el.getBoundingClientRect();
+        if (r.width > 0 && r.height > 0) {
+            setDimensions({ width: r.width, height: r.height });
+        }
+        return () => ro.disconnect();
+    }, [boundElement]);
 
     const graphRef = useRef<GraphHandle>(null);
 
@@ -155,27 +202,9 @@ export function useGraphState(options: UseGraphStateOptions) {
             nodes: prev.nodes.map(n => String(n.id) === String(nodeId) ? { ...n, fetchingImage: true, imageChecked: true } : n)
         }));
 
-        const imageBaseUrl = cacheEnabled ? cacheBaseUrl : window.location.origin;
-        const effectiveType = context || current?.type || fallbackNode?.type || "";
-        const effectiveYear = (current?.year ?? (fallbackNode as any)?.year) as number | undefined;
-
-        // Avoid ambiguity for common screen-work titles like "The Killing" (1956 film vs 2011 TV series).
-        // Prefer a Wikipedia-style disambiguated title when we have a year and the title is not already disambiguated.
-        const looksDisambiguated = /\([^)]*\)/.test(title);
-        const typeLower = String(effectiveType).toLowerCase();
-        const isFilmLike = /\b(film|movie)\b/.test(typeLower);
-        const isTvLike = /\b(tv|television|series|miniseries|show)\b/.test(typeLower);
-        const isScreenLike = isFilmLike || isTvLike;
-        const titleForImage =
-            !looksDisambiguated && isScreenLike && effectiveYear
-                ? `${title} (${effectiveYear} ${isFilmLike ? "film" : "TV series"})`
-                : title;
-        const contextForImage =
-            effectiveYear && isScreenLike
-                ? `${effectiveType} ${effectiveYear}`.trim()
-                : effectiveType;
-
-        const imageResult = await fetchServerImage(titleForImage, contextForImage, imageBaseUrl);
+        const imageBaseUrl = getImageApiBaseUrl(cacheBaseUrl);
+        const effectiveContext = context || current?.type || fallbackNode?.type;
+        const imageResult = await fetchServerImage(title, effectiveContext, imageBaseUrl);
         if ((imageReqTokenRef.current.get(String(nodeId)) || 0) !== nextToken) return;
 
         if (imageResult.url) {
@@ -236,7 +265,7 @@ export function useGraphState(options: UseGraphStateOptions) {
                 } catch { }
 
                 if (imageHint) {
-                    const imageBaseUrl = cacheEnabled ? cacheBaseUrl : window.location.origin;
+                    const imageBaseUrl = getImageApiBaseUrl(cacheBaseUrl);
                     const imageResult = await fetchServerImage(imageHint, node.type, imageBaseUrl);
                     if (imageResult.url) {
                         setGraphData(prev => ({
@@ -273,7 +302,7 @@ export function useGraphState(options: UseGraphStateOptions) {
                 return;
             }
 
-            const imageBaseUrl = cacheEnabled ? cacheBaseUrl : window.location.origin;
+            const imageBaseUrl = getImageApiBaseUrl(cacheBaseUrl);
             const serverResult = await fetchServerImage(node.title, node.type, imageBaseUrl);
             if (serverResult.url) {
                 setGraphData(prev => ({
@@ -335,9 +364,15 @@ export function useGraphState(options: UseGraphStateOptions) {
                         // Endpoint returns array of { name, updated_at }
                         const serverGraphs = data.map((g: any) => g.name);
                         setSavedGraphs(serverGraphs.sort());
+                    } else {
+                        const body = await res.text();
+                        console.warn(
+                            `[constellations] GET /graphs failed: ${res.status}. Check cache server logs (e.g. DB connection / saved_graphs).`,
+                            body.slice(0, 500)
+                        );
                     }
                 } catch (e) {
-                    // console.warn("Failed to fetch saved graphs from server", e);
+                    console.warn("Failed to fetch saved graphs from server", e);
                 }
             }
         };

package/hooks/useKioskMode.ts

@@ -1,3 +1,4 @@
+"use client";
 import { useState, useEffect } from 'react';
 import {
     KioskDomain,

package/hooks/useNodeClickHandler.ts

@@ -1,3 +1,4 @@
+"use client";
 import { useCallback, useEffect, useRef } from 'react';
 import { GraphNode, GraphLink } from '../types';
 
@@ -62,8 +63,30 @@ export const useNodeClickHandler = ({
         onRetryImage?.(node);
         onConnectSelect?.(node);
 
+        const isSecondClick = lastSelectedIdRef.current !== null && String(lastSelectedIdRef.current) === String(node.id);
         const now = Date.now();
+        const isRepeatSameNode = lastClickRef.current !== null && String(lastClickRef.current.id) === String(node.id);
+        const lastClickAge = lastClickRef.current ? (now - lastClickRef.current.at) : null;
+        const isRapidSameNode = isRepeatSameNode && !!lastClickAge && lastClickAge < 800;
+        const isSelectedAgain = selectedNode !== null && String(selectedNode.id) === String(node.id);
         const isDoubleClick = !!event && typeof event.detail === 'number' && event.detail >= 2;
+        if (isSecondClick || isRapidSameNode || isDoubleClick || isSelectedAgain || isRepeatSameNode) {
+            const pos = getMenuPosition
+                ? getMenuPosition(node, event)
+                : {
+                    x: event?.clientX ?? window.innerWidth / 2,
+                    y: event?.clientY ?? window.innerHeight / 2
+                };
+            setContextMenu({ node, x: pos.x, y: pos.y });
+            onDebug?.(
+                `click: ${node.title} -> menu` +
+                ` (second:${isSecondClick} rapid:${isRapidSameNode} dbl:${isDoubleClick}` +
+                ` selected:${isSelectedAgain} repeat:${isRepeatSameNode}` +
+                `${lastClickAge !== null ? ` age:${lastClickAge}` : ""})`
+            );
+            lastClickRef.current = { id: node.id, at: now };
+            return;
+        }
 
         setContextMenu(null);
         onClearSecondarySelection?.();
@@ -95,24 +118,9 @@ export const useNodeClickHandler = ({
                 onDebug?.(`highlight: ${node.title} + ${connectedNodeIds.length} connected nodes`);
             }
 
-            /** Double-click on an already-expanded node opens the context menu (was unreachable next block). */
-            if (isDoubleClick && node.expanded && !node.isLoading) {
-                const pos = getMenuPosition
-                    ? getMenuPosition(node, event)
-                    : { x: event?.clientX ?? window.innerWidth / 2, y: event?.clientY ?? window.innerHeight / 2 };
-                setContextMenu({ node, x: pos.x, y: pos.y });
-                onDebug?.(`click: ${node.title} -> menu (double-click)`);
-                lastClickRef.current = { id: node.id, at: now };
-            }
-
             return;
         }
 
-        /**
-         * Unexpanded leaf: both single-click and double-click expand.
-         * A lone programmatic/synthetic click with detail>=2 used to branch to the menu-only path and skip onExpand.
-         */
-
         if (selectOnFirstClick) {
             setSelectedNode(node);
             lastSelectedIdRef.current = node.id;

package/hooks/useSearchHandlers.ts

@@ -1,10 +1,12 @@
-import React, { useState, useCallback } from 'react';
+"use client";
+import React, { useState, useCallback, useEffect, useRef } from 'react';
 import { GraphNode, GraphLink } from '../types';
 import { classifyStartPair, fetchConnectionPath, LockedPair, classifyEntity, fetchConnections } from '../services/geminiService';
 import { fetchWikipediaSummary } from '../services/wikipediaService';
 import { dedupeGraph, normalizeForDedup } from '../services/graphUtils';
 import { clampToViewport } from '../utils/graphLogicUtils';
 import { buildWikiUrl } from '../utils/wikiUtils';
+import type { ConstellationsSessionHandoffV1 } from '../sessionHandoff';
 
 interface PathResponse {
     path: any[];
@@ -32,6 +34,7 @@ interface UseSearchHandlersOptions {
     showControlPanel: boolean;
     selectedKioskDomain: any;
     graphRef: React.RefObject<any>;
+    initialSession?: ConstellationsSessionHandoffV1 | null;
 }
 
 export function useSearchHandlers(options: UseSearchHandlersOptions) {
@@ -40,15 +43,23 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
         setSearchId, searchIdRef, setLockedPair, dimensions,
         cacheEnabled, cacheBaseUrl, loadNodeImage, fetchAndExpandNode,
         setNotification, setSelectedNode, setSelectedLink, setPathNodeIds,
-        setPendingAutoExpandId, showControlPanel, selectedKioskDomain, graphRef
+        setPendingAutoExpandId, showControlPanel, selectedKioskDomain, graphRef,
+        initialSession: initialSessionOpt
     } = options;
+    const initialSession = initialSessionOpt && initialSessionOpt.graph?.nodes?.length ? initialSessionOpt : null;
 
-    const [exploreTerm, setExploreTerm] = useState('');
-    const [pathStart, setPathStart] = useState('');
-    const [pathEnd, setPathEnd] = useState('');
+    const dimensionsRef = useRef(dimensions);
+    useEffect(() => {
+        dimensionsRef.current = dimensions;
+    }, [dimensions]);
+
+    const [exploreTerm, setExploreTerm] = useState(initialSession?.exploreTerm ?? '');
+    const [pathStart, setPathStart] = useState(initialSession?.pathStart ?? '');
+    const [pathEnd, setPathEnd] = useState(initialSession?.pathEnd ?? '');
 
     const upsertNodeLocal = useCallback(async (title: string, type: string, description: string, wiki: any) => {
         let nodeData: any = null;
+        let fromCacheServer = false;
         if (cacheEnabled) {
             try {
                 const res = await fetch(new URL("/node", cacheBaseUrl).toString(), {
@@ -63,6 +74,7 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
                 });
                 if (res.ok) {
                     nodeData = await res.json();
+                    fromCacheServer = true;
                 }
             } catch (e) {
                 console.warn("Cache server unreachable", e);
@@ -78,6 +90,14 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
                 wikipedia_id: wiki.pageid?.toString()
             };
         }
+        if (process.env.NODE_ENV === "development") {
+            console.log("[Constellations]", "upsertNodeLocal", {
+                title: title.trim().slice(0, 64),
+                fromCacheServer,
+                nodeId: nodeData.id,
+                wikipediaId: wiki.pageid ?? null,
+            });
+        }
         return nodeData;
     }, [cacheEnabled, cacheBaseUrl]);
 
@@ -90,6 +110,21 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
         setPathNodeIds([]);
         setSelectedLink(null);
 
+        if (process.env.NODE_ENV === "development") {
+            let host = "";
+            try {
+                if (cacheBaseUrl) host = new URL(cacheBaseUrl).host;
+            } catch {
+                host = "(invalid cacheBaseUrl)";
+            }
+            console.log("[Constellations]", "handleStartSearch", {
+                searchId: nextSearchId,
+                term: term.trim().slice(0, 80),
+                cacheEnabled,
+                cacheHost: host || null,
+            });
+        }
+
         try {
             const startC = await classifyStartPair(term);
             const chosenPair: LockedPair = { atomicType: startC.atomicType, compositeType: startC.compositeType };
@@ -110,6 +145,7 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
 
             const nodeData = await upsertNodeLocal(canonicalTitle, type, description || '', wiki);
 
+            const dim = dimensionsRef.current;
             const startNode: GraphNode = {
                 id: nodeData.id,
                 title: canonicalTitle,
@@ -117,8 +153,8 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
                 is_atomic: isAtomic,
                 wikipedia_id: wiki.pageid?.toString(),
                 description: wiki.extract || description || '',
-                x: dimensions.width / 2,
-                y: dimensions.height / 2,
+                x: dim.width / 2,
+                y: dim.height / 2,
                 expanded: false,
                 wikiSummary: wiki.extract || undefined,
                 classification_reasoning: reasoning,
@@ -140,7 +176,7 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
         } finally {
             setIsProcessing(false);
         }
-    }, [dimensions, cacheEnabled, cacheBaseUrl, setGraphData, setIsProcessing, setError, setSearchId, searchIdRef, setLockedPair, loadNodeImage, fetchAndExpandNode, setSelectedNode, setSelectedLink, setPathNodeIds, setPendingAutoExpandId, showControlPanel, selectedKioskDomain, upsertNodeLocal]);
+    }, [cacheEnabled, cacheBaseUrl, setGraphData, setIsProcessing, setError, setSearchId, searchIdRef, setLockedPair, loadNodeImage, fetchAndExpandNode, setSelectedNode, setSelectedLink, setPathNodeIds, setPendingAutoExpandId, showControlPanel, selectedKioskDomain, upsertNodeLocal]);
 
     const handlePathSearch = useCallback(async (start: string, end: string) => {
         setIsProcessing(true);
@@ -166,10 +202,11 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
                 upsertNodeLocal(end, endC.type, endC.description || '', endWiki)
             ]);
 
+            const d = dimensionsRef.current;
             const startNode: GraphNode = {
                 id: startNodeData.id, title: start.trim(), type: startC.type, is_atomic: startC.isAtomic,
                 wikipedia_id: startWiki.pageid?.toString(), description: startWiki.extract || startC.description || '',
-                x: dimensions.width / 4, y: dimensions.height / 2, fx: dimensions.width / 4, fy: dimensions.height / 2,
+                x: d.width / 4, y: d.height / 2, fx: d.width / 4, fy: d.height / 2,
                 expanded: false, wikiSummary: startWiki.extract || undefined,
                 imageUrl: startNodeData.imageUrl || startNodeData.image_url,
                 ...startNodeData
@@ -178,7 +215,7 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
             const endNode: GraphNode = {
                 id: endNodeData.id, title: end.trim(), type: endC.type, is_atomic: endC.isAtomic,
                 wikipedia_id: endWiki.pageid?.toString(), description: endWiki.extract || endC.description || '',
-                x: (dimensions.width * 3) / 4, y: dimensions.height / 2, fx: (dimensions.width * 3) / 4, fy: dimensions.height / 2,
+                x: (d.width * 3) / 4, y: d.height / 2, fx: (d.width * 3) / 4, fy: d.height / 2,
                 expanded: false, wikiSummary: endWiki.extract || undefined,
                 imageUrl: endNodeData.imageUrl || endNodeData.image_url,
                 ...endNodeData
@@ -223,18 +260,19 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
             if (isDbPath) {
                 const dbNodes = pathData.path as any[];
                 dbNodes.forEach(n => pathNodeIdsList.push(n.id));
-                setGraphData(current => {
+                    setGraphData(current => {
+                    const dim = dimensionsRef.current;
                     const updatedNodes = [...current.nodes];
                     const updatedLinks = [...current.links];
                     dbNodes.forEach((dbNode, i) => {
                         let existingNode = updatedNodes.find(n => String(n.id) === String(dbNode.id));
                         if (!existingNode) {
-                            const nodeX = i === 0 ? (startNode.x || dimensions.width / 4) : (updatedNodes[i - 1]?.x || dimensions.width / 2) + (Math.random() - 0.5) * 150;
-                            const nodeY = i === 0 ? (startNode.y || dimensions.height / 2) : (updatedNodes[i - 1]?.y || dimensions.height / 2) + (Math.random() - 0.5) * 150;
+                            const nodeX = i === 0 ? (startNode.x || dim.width / 4) : (updatedNodes[i - 1]?.x || dim.width / 2) + (Math.random() - 0.5) * 150;
+                            const nodeY = i === 0 ? (startNode.y || dim.height / 2) : (updatedNodes[i - 1]?.y || dim.height / 2) + (Math.random() - 0.5) * 150;
                             const clamped = clampToViewport(nodeX, nodeY, 80);
-                            existingNode = { id: dbNode.id, title: dbNode.title, type: dbNode.type, x: clamped.x, y: clamped.y, fx: clamped.x, fy: clamped.y, expanded: false, ...dbNode };
-                            updatedNodes.push(existingNode);
-                            loadNodeImage(dbNode.id, existingNode.title);
+                            const created: GraphNode = { id: dbNode.id, title: dbNode.title, type: dbNode.type, x: clamped.x, y: clamped.y, fx: clamped.x, fy: clamped.y, expanded: false, ...dbNode };
+                            updatedNodes.push(created);
+                            loadNodeImage(dbNode.id, created.title);
                         }
                     });
                     for (let i = 0; i < dbNodes.length - 1; i++) {
@@ -289,7 +327,7 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
                         loadNodeImage(toId, newNode.title);
                         // CRITICAL: Dedupe immediately so that if this node merged with an existing one,
                         // we know the correct ID for the next link in the chain.
-                        return dedupeGraph(updatedNodes, updatedLinks);
+                        return dedupeGraph(updatedNodes, updatedLinks as GraphLink[]);
                     });
 
                     // Wait a moment for state to settle, then find the RESOLVED id of the node we just added.
@@ -355,7 +393,7 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
             }));
             setPathNodeIds([...finalPathIds]);
             setNotification({ message: "Path discovery complete!", type: 'success' });
-            if (finalPathIds.length) setTimeout(() => graphRef.current?.centerOnNode(finalPathIds[Math.floor(finalPathIds.length / 2)]), 200);
+            if (finalPathIds.length) setTimeout(() => graphRef.current?.fitGraphInView(), 200);
 
         } catch (e) {
             console.error("Path error:", e);
@@ -363,7 +401,7 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
         } finally {
             setIsProcessing(false);
         }
-    }, [dimensions, cacheEnabled, cacheBaseUrl, setGraphData, setIsProcessing, setError, setSearchId, searchIdRef, setNotification, loadNodeImage, fetchAndExpandNode, setSelectedNode, setPathNodeIds, graphRef, upsertNodeLocal]);
+    }, [cacheEnabled, cacheBaseUrl, setGraphData, setIsProcessing, setError, setSearchId, searchIdRef, setNotification, loadNodeImage, fetchAndExpandNode, setSelectedNode, setPathNodeIds, graphRef, upsertNodeLocal]);
 
     return { exploreTerm, setExploreTerm, pathStart, setPathStart, pathEnd, setPathEnd, handleStartSearch, handlePathSearch };
 }

package/host.ts

@@ -1,7 +1,7 @@
 "use client";
 
 /**
- * Single import surface for full-page constellations inside host apps (Soundings, Trailer Vision, …).
+ * Single import surface for full-page constellations inside Next hosts (Soundings, Trailer, …).
  * — `FullPageConstellations` (layout + App wiring)
  * — `useFullPageConstellationsHost` (URL + optional player bridge)
  * — `newChannelFromGraphNode` (sessionStorage + navigate)

package/index.css

@@ -4,9 +4,13 @@
     box-sizing: border-box;
 }
 
-html,
-body,
-#root {
+/**
+ * Full-viewport shell for the standalone Vite app only. When constellations is embedded
+ * (e.g. Soundings /player), we must NOT lock document scroll — see App.tsx toggling
+ * `constellations-standalone` on <html>.
+ */
+html.constellations-standalone,
+html.constellations-standalone body {
     position: fixed;
     inset: 0;
     width: 100%;
@@ -17,6 +21,16 @@ body,
     overflow: hidden !important;
 }
 
+html.constellations-standalone #root {
+    position: fixed;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    margin: 0;
+    padding: 0;
+    overflow: hidden !important;
+}
+
 body {
     font-family: 'Inter', sans-serif;
     background-color: #0f172a;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johndimm/constellations",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "main": "./index.tsx",
   "exports": {
@@ -60,6 +60,7 @@
     "@tailwindcss/postcss": "^4.1.18",
     "@tailwindcss/vite": "^4.1.18",
     "@types/chrome": "^0.1.36",
+    "@types/d3": "^7.4.3",
     "@types/node": "^22.14.0",
     "@vitejs/plugin-react": "^5.0.0",
     "autoprefixer": "^10.4.23",

package/services/aiService.ts

@@ -0,0 +1,23 @@
+/**
+ * Provider dispatcher. Set VITE_AI_PROVIDER=deepseek (or gemini) in .env.local.
+ * Defaults to gemini when unset.
+ */
+import { readBundledEnv } from "./aiUtils";
+import * as gemini from "./geminiService";
+import * as deepseek from "./deepseekService";
+
+export * from "./aiUtils";
+export type { LockedPair } from "./geminiService";
+
+const isDeepSeek = (readBundledEnv("VITE_AI_PROVIDER") || "gemini").toLowerCase() === "deepseek";
+const svc = isDeepSeek ? deepseek : gemini;
+
+export const classifyStartPair         = (...args: Parameters<typeof svc.classifyStartPair>)         => svc.classifyStartPair(...args);
+export const classifyEntity            = (...args: Parameters<typeof svc.classifyEntity>)            => svc.classifyEntity(...args);
+export const fetchConnections          = (...args: Parameters<typeof svc.fetchConnections>)          => svc.fetchConnections(...args);
+export const fetchPersonWorks          = (...args: Parameters<typeof svc.fetchPersonWorks>)          => svc.fetchPersonWorks(...args);
+export const fetchConnectionPath       = (...args: Parameters<typeof svc.fetchConnectionPath>)       => svc.fetchConnectionPath(...args);
+export const findWikipediaTitle        = (...args: Parameters<typeof svc.findWikipediaTitle>)        => svc.findWikipediaTitle(...args);
+// Always uses Gemini — relies on Google Search grounding which is Gemini-specific.
+export const fetchOrgKeyPeopleBlockViaSearch = gemini.fetchOrgKeyPeopleBlockViaSearch;
+export const defaultStartPairResult    = (...args: Parameters<typeof svc.defaultStartPairResult>)    => svc.defaultStartPairResult(...args);