@johndimm/constellations 1.0.2 → 1.0.3

package/App.tsx

@@ -669,6 +669,18 @@ const App: React.FC<AppProps> = ({
                         selectedKioskDomainId={selectedKioskDomainId}
                         onSelectKioskDomain={(id) => { setSelectedKioskDomainId(id); setPathStart(''); setPathEnd(''); }}
                         onUpdateKioskDomains={setKioskDomains}
+                        onClear={handleClear}
+                        onClearCache={cacheEnabled ? handleClearCache : undefined}
+                        onExpandAllLeafNodes={handleExpandAllLeafNodes}
+                        onSave={handleSaveGraph}
+                        onLoad={(name) => handleLoadGraph(name, applyGraphData)}
+                        onDeleteGraph={handleDeleteGraph}
+                        onImport={(data) => handleImport(data, applyGraphData)}
+                        savedGraphs={savedGraphs}
+                        helpHover={helpHover}
+                        onHelpHoverChange={setHelpHover}
+                        onToggleHelp={() => setShowHelp(!showHelp)}
+                        showHelp={showHelp}
                         isProcessing={isProcessing}
                         isCompact={isCompact}
                         onToggleCompact={() => setIsCompact(!isCompact)}

package/components/AppHeader.tsx

@@ -37,8 +37,6 @@ const AppHeader: React.FC<AppHeaderProps> = ({
 }) => {
     if (!showHeader) return null;
 
-    const showLeave = closeHref || onClose;
-
     return (
         <header
             className={`absolute left-0 right-0 z-[200] h-14 max-h-14 min-h-14 shrink-0 pointer-events-auto bg-slate-900/95 backdrop-blur flex items-center justify-between px-2 sm:px-3 py-2 gap-2 overflow-x-hidden max-w-full ${offsetTopClass}`}
@@ -57,9 +55,19 @@ const AppHeader: React.FC<AppHeaderProps> = ({
                 >
                     {panelCollapsed ? <ChevronRight size={18} /> : <ChevronLeft size={18} />}
                 </button>
-                <span className="text-base sm:text-lg font-bold text-red-500 whitespace-nowrap">
-                    Constellations
-                </span>
+                {closeHref ? (
+                    <a
+                        href={closeHref}
+                        title="Film & Music — return to hub"
+                        className="text-base sm:text-lg font-bold text-red-500 whitespace-nowrap hover:text-red-400 transition-colors"
+                    >
+                        Constellations
+                    </a>
+                ) : (
+                    <span className="text-base sm:text-lg font-bold text-red-500 whitespace-nowrap">
+                        Constellations
+                    </span>
+                )}
             </div>
             <div className="flex items-center gap-2 sm:gap-3 flex-shrink-0 mr-1">
                 {selectedNode && (
@@ -79,18 +87,7 @@ const AppHeader: React.FC<AppHeaderProps> = ({
                         {sidebarCollapsed ? <ChevronLeft size={18} /> : <ChevronRight size={18} />}
                     </button>
                 )}
-                {showLeave && closeHref && (
-                    <a
-                        href={closeHref}
-                        onClick={onClose}
-                        className="w-9 h-9 sm:w-10 sm:h-10 bg-slate-800/80 border border-slate-700 rounded-lg flex items-center justify-center text-slate-300 hover:text-white hover:border-slate-600 transition flex-shrink-0"
-                        title="Return to the main app"
-                        aria-label="Return to the main app"
-                    >
-                        <X size={20} strokeWidth={2} />
-                    </a>
-                )}
-                {showLeave && !closeHref && onClose && (
+                {!closeHref && onClose && (
                     <button
                         type="button"
                         onClick={(e) => {

package/components/ControlPanel.tsx

@@ -1,6 +1,8 @@
 "use client";
-import React, { useState, useEffect } from 'react';
-import { Search, Minimize2, Maximize2, Calendar, Network, X, Link as LinkIcon, ArrowRight, Type, ChevronLeft, ChevronRight, ChevronDown, Settings } from 'lucide-react';
+import React, { useState, useEffect, useRef } from 'react';
+import { Search, Minimize2, Maximize2, Maximize, Calendar, Network, X, Link as LinkIcon, ArrowRight, Type, ChevronLeft, ChevronRight, ChevronDown, Settings, Download, Trash2, Share2, Copy, Upload, Plus, HelpCircle, Cpu } from 'lucide-react';
+import type { LlmProviderId } from '../services/aiUtils';
+import { getBrowserLlmOverride, setBrowserLlmOverride, getEnvCacheUrl } from '../services/aiUtils';
 import { DEFAULT_KIOSK_DOMAINS, saveKioskDomains, saveSelectedKioskDomainId } from '../kioskDomains';
 import type { KioskDomain } from '../kioskDomains';
 
@@ -22,6 +24,18 @@ interface ControlPanelProps {
   selectedKioskDomainId?: string;
   onSelectKioskDomain?: (domainId: string) => void;
   onUpdateKioskDomains?: (domains: KioskDomain[]) => void;
+  onClear?: () => void;
+  onClearCache?: () => void;
+  onExpandAllLeafNodes?: () => void;
+  onSave?: (name: string) => void;
+  onLoad?: (name: string) => void;
+  onDeleteGraph?: (name: string) => void;
+  onImport?: (data: any) => void;
+  savedGraphs?: string[];
+  helpHover?: string | null;
+  onHelpHoverChange?: (value: string | null) => void;
+  onToggleHelp?: () => void;
+  showHelp?: boolean;
   isProcessing: boolean;
   isCompact: boolean;
   onToggleCompact: () => void;
@@ -66,6 +80,18 @@ const ControlPanel: React.FC<ControlPanelProps> = ({
   selectedKioskDomainId,
   onSelectKioskDomain,
   onUpdateKioskDomains,
+  onClear,
+  onClearCache,
+  onExpandAllLeafNodes,
+  onSave,
+  onLoad,
+  onDeleteGraph,
+  onImport,
+  savedGraphs = [],
+  helpHover,
+  onHelpHoverChange,
+  onToggleHelp,
+  showHelp,
   isProcessing,
   isCompact,
   onToggleCompact,
@@ -88,12 +114,42 @@ const ControlPanel: React.FC<ControlPanelProps> = ({
   const [newDomainLabel, setNewDomainLabel] = useState('');
   const [newTerm, setNewTerm] = useState('');
   const [bulkTerms, setBulkTerms] = useState('');
+  const [showSave, setShowSave] = useState(false);
+  const [showLoad, setShowLoad] = useState(false);
+  const [showShare, setShowShare] = useState(false);
+  const [saveName, setSaveName] = useState('');
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const [llmSelectValue, setLlmSelectValue] = useState<'env' | LlmProviderId>(() => getBrowserLlmOverride() ?? 'env');
 
   // Collapsible sections state - combined toggle for examples section
   const [showExamples, setShowExamples] = useState(false);
 
   const domainsImportRef = React.useRef<HTMLInputElement>(null);
 
+  const handleSaveSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (saveName.trim() && onSave) {
+      onSave(saveName.trim());
+      setShowSave(false);
+      setSaveName('');
+    }
+  };
+
+  const handleImportFile = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file || !onImport) return;
+    const reader = new FileReader();
+    reader.onload = (ev) => {
+      try {
+        const data = JSON.parse(ev.target?.result as string);
+        onImport(data);
+        setShowLoad(false);
+      } catch { alert('Invalid JSON file'); }
+      finally { e.target.value = ''; }
+    };
+    reader.readAsText(file);
+  };
+
   const handleSubmit = (e: React.FormEvent) => {
     e.preventDefault();
     if (searchMode === 'explore') {
@@ -183,8 +239,65 @@ const ControlPanel: React.FC<ControlPanelProps> = ({
               </div>
             )}
 
+            {/* Dev docs links */}
+            <div className="mb-3 flex gap-3">
+              <a href="/doc/help.html" target="_blank" rel="noreferrer"
+                 className="text-[10px] text-slate-500 hover:text-slate-300 transition-colors">
+                Help
+              </a>
+              <a href="/doc/prompt.html" target="_blank" rel="noreferrer"
+                 className="text-[10px] text-slate-500 hover:text-slate-300 transition-colors">
+                Prompt
+              </a>
+              <a href="/doc/journal.html" target="_blank" rel="noreferrer"
+                 className="text-[10px] text-slate-500 hover:text-slate-300 transition-colors">
+                Dev Journal
+              </a>
+            </div>
+
             {/* Button Groups */}
             <div className="space-y-4 mb-4">
+              {/* Group: File */}
+              {onSave && (
+                <div>
+                  <div className="text-[10px] font-bold text-slate-500 uppercase tracking-widest mb-1.5 flex items-center gap-1.5">
+                    <Download size={10} /> File
+                  </div>
+                  <div className="flex flex-wrap gap-2 text-xs">
+                    <button
+                      onClick={() => {
+                        let defaultName = searchMode === 'explore' && exploreTerm ? exploreTerm
+                          : searchMode === 'connect' && pathStart && pathEnd ? `${pathStart} to ${pathEnd}`
+                          : `Graph ${new Date().toLocaleTimeString()}`;
+                        setSaveName(defaultName);
+                        setShowSave(!showSave);
+                        setShowLoad(false);
+                        setShowShare(false);
+                        onHelpHoverChange?.(null);
+                      }}
+                      className={`px-3 py-1.5 rounded-md border border-slate-700 bg-slate-800/80 text-slate-200 hover:text-amber-300 transition-colors ${helpHover === 'save' ? 'ring-2 ring-amber-400 ring-offset-2 ring-offset-slate-900' : ''}`}
+                      title="Save Graph"
+                    >
+                      SAVE
+                    </button>
+                    <button
+                      onClick={() => { setShowLoad(!showLoad); setShowSave(false); setShowShare(false); }}
+                      className={`px-3 py-1.5 rounded-md border border-slate-700 bg-slate-800/80 text-slate-200 hover:text-amber-300 transition-colors ${helpHover === 'load' ? 'ring-2 ring-amber-400 ring-offset-2 ring-offset-slate-900' : ''}`}
+                      title="Load Graph"
+                    >
+                      LOAD
+                    </button>
+                    <button
+                      onClick={() => { setShowShare(!showShare); setShowSave(false); setShowLoad(false); onHelpHoverChange?.(null); }}
+                      className={`px-3 py-1.5 rounded-md border border-slate-700 bg-slate-800/80 text-slate-200 hover:text-amber-300 transition-colors ${helpHover === 'share' ? 'ring-2 ring-amber-400 ring-offset-2 ring-offset-slate-900' : ''}`}
+                      title="Share Graph"
+                    >
+                      SHARE
+                    </button>
+                  </div>
+                </div>
+              )}
+
               {/* Group: View */}
               <div>
                 <div className="text-[10px] font-bold text-slate-500 uppercase tracking-widest mb-1.5 flex items-center gap-1.5">
@@ -220,8 +333,199 @@ const ControlPanel: React.FC<ControlPanelProps> = ({
                   </button>
                 </div>
               </div>
+
+              {/* Group: LLM */}
+              <div>
+                <div className="text-[10px] font-bold text-slate-500 uppercase tracking-widest mb-1.5 flex items-center gap-1.5">
+                  <Cpu size={10} /> LLM
+                </div>
+                <select
+                  value={llmSelectValue}
+                  onChange={(e) => {
+                    const v = e.target.value as 'env' | LlmProviderId;
+                    setBrowserLlmOverride(v === 'env' ? null : v);
+                    setLlmSelectValue(v);
+                  }}
+                  className="w-full bg-slate-900 border border-slate-600 text-slate-100 text-xs rounded-md px-2 py-2 focus:outline-none focus:ring-1 focus:ring-indigo-500"
+                  title="Model provider for AI calls from this tab"
+                >
+                  <option value="env">Default (from .env)</option>
+                  <option value="gemini">Google Gemini</option>
+                  <option value="openai">OpenAI</option>
+                  <option value="deepseek">DeepSeek</option>
+                  <option value="anthropic">Anthropic</option>
+                </select>
+                {getEnvCacheUrl() && (
+                  <p className="text-[9px] text-slate-500 mt-1 leading-snug">
+                    Proxied — keys live on the server. Default uses{' '}
+                    <span className="text-slate-400">LLM_PROVIDER</span> env var.
+                  </p>
+                )}
+              </div>
+
+              {/* Group: Actions */}
+              {(onClear || onClearCache || onExpandAllLeafNodes || onToggleHelp) && (
+                <div>
+                  <div className="text-[10px] font-bold text-slate-500 uppercase tracking-widest mb-1.5 flex items-center gap-1.5">
+                    <Plus size={10} /> Actions
+                  </div>
+                  <div className="flex flex-wrap gap-2 text-xs">
+                    {onClear && (
+                      <button
+                        onClick={onClear}
+                        className="text-slate-300 hover:text-red-300 p-1.5 rounded-md border border-slate-700 bg-slate-800/80 transition-colors"
+                        title="Clear graph"
+                      >
+                        <Trash2 size={16} />
+                      </button>
+                    )}
+                    {onClearCache && (
+                      <button
+                        onClick={onClearCache}
+                        className="px-3 py-1.5 rounded-md border border-slate-700 bg-slate-800/80 text-slate-200 hover:text-orange-300 transition-colors"
+                        title="Clear API cache (forces fresh data from LLM)"
+                      >
+                        CLEAR CACHE
+                      </button>
+                    )}
+                    {onExpandAllLeafNodes && (
+                      <button
+                        onClick={onExpandAllLeafNodes}
+                        disabled={isProcessing}
+                        className="px-3 py-1.5 rounded-md border border-slate-700 bg-slate-800/80 text-slate-200 hover:text-emerald-300 inline-flex items-center gap-1 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
+                        title="Expand all leaf nodes"
+                      >
+                        <Maximize size={14} className="text-emerald-400" />
+                        EXPAND ALL
+                      </button>
+                    )}
+                    {onToggleHelp && (
+                      <button
+                        onClick={onToggleHelp}
+                        className={`px-3 py-1.5 rounded-md border border-slate-700 bg-slate-800/80 text-slate-200 hover:text-white flex items-center gap-1 transition-colors ${helpHover === 'help' ? 'ring-2 ring-amber-400 ring-offset-2 ring-offset-slate-900' : ''}`}
+                        title="Help & Info"
+                      >
+                        <HelpCircle size={14} /> HELP
+                      </button>
+                    )}
+                  </div>
+                </div>
+              )}
             </div>
 
+            {/* Share Dialog */}
+            {showShare && onSave && (
+              <div className="mb-4 bg-slate-800 p-3 rounded-lg border border-slate-600 animate-in fade-in slide-in-from-top-2 duration-200">
+                <div className="flex justify-between items-center mb-3">
+                  <h3 className="text-sm font-bold text-white flex items-center gap-2">
+                    <Share2 size={14} /> Share Graph
+                  </h3>
+                  <button onClick={() => setShowShare(false)}><X size={14} className="text-slate-400" /></button>
+                </div>
+                <div className="grid grid-cols-3 gap-2">
+                  <button
+                    onClick={() => onSave('__COPY_LINK__')}
+                    className="flex flex-col items-center justify-center gap-2 bg-slate-700 hover:bg-slate-600 text-white p-3 rounded-lg transition-colors border border-slate-600"
+                  >
+                    <LinkIcon size={20} className="text-orange-400" />
+                    <span className="text-[10px] font-bold uppercase tracking-wider text-center">Copy Link</span>
+                  </button>
+                  <button
+                    onClick={() => onSave('__COPY__')}
+                    className="flex flex-col items-center justify-center gap-2 bg-slate-700 hover:bg-slate-600 text-white p-3 rounded-lg transition-colors border border-slate-600"
+                  >
+                    <Copy size={20} className="text-purple-400" />
+                    <span className="text-[10px] font-bold uppercase tracking-wider text-center">Copy JSON</span>
+                  </button>
+                  <button
+                    onClick={() => onSave('__EXPORT__')}
+                    className="flex flex-col items-center justify-center gap-2 bg-slate-700 hover:bg-slate-600 text-white p-3 rounded-lg transition-colors border border-slate-600"
+                  >
+                    <Download size={20} className="text-indigo-400" />
+                    <span className="text-[10px] font-bold uppercase tracking-wider text-center">Download File</span>
+                  </button>
+                </div>
+              </div>
+            )}
+
+            {/* Save Dialog */}
+            {showSave && onSave && (
+              <div className="mb-4 bg-slate-800 p-3 rounded-lg border border-slate-600">
+                <div className="flex justify-between items-center mb-2">
+                  <h3 className="text-sm font-bold text-white">Save Graph</h3>
+                  <button onClick={() => setShowSave(false)}><X size={14} className="text-slate-400" /></button>
+                </div>
+                <form onSubmit={handleSaveSubmit} className="flex gap-2">
+                  <input
+                    type="text"
+                    value={saveName}
+                    onChange={(e) => setSaveName(e.target.value)}
+                    placeholder="Graph Name..."
+                    className="flex-1 bg-slate-900 border border-slate-700 text-white px-2 py-1 rounded text-sm focus:outline-none focus:border-indigo-500"
+                    autoFocus
+                  />
+                  <button type="submit" className="bg-green-600 hover:bg-green-500 text-white px-3 py-1 rounded text-sm font-medium">
+                    Save
+                  </button>
+                  <button
+                    type="button"
+                    onClick={() => onSave('__EXPORT__')}
+                    className="bg-indigo-600 hover:bg-indigo-500 text-white px-2 py-1 rounded text-sm font-medium flex items-center"
+                    title="Export as JSON"
+                  >
+                    <Download size={14} />
+                  </button>
+                </form>
+              </div>
+            )}
+
+            {/* Load Dialog */}
+            {showLoad && onLoad && (
+              <div className="mb-4 bg-slate-800 p-3 rounded-lg border border-slate-600 max-h-60 overflow-y-auto">
+                <div className="flex justify-between items-center mb-2">
+                  <h3 className="text-sm font-bold text-white">Load Graph</h3>
+                  <div className="flex items-center gap-2">
+                    {onImport && (
+                      <button
+                        onClick={() => fileInputRef.current?.click()}
+                        className="text-slate-400 hover:text-blue-400 flex items-center gap-1 text-xs"
+                        title="Import JSON"
+                      >
+                        <Upload size={14} /> Import
+                      </button>
+                    )}
+                    <button onClick={() => setShowLoad(false)}><X size={14} className="text-slate-400" /></button>
+                  </div>
+                </div>
+                <input type="file" ref={fileInputRef} onChange={handleImportFile} accept=".json" className="hidden" />
+                {savedGraphs.length === 0 ? (
+                  <p className="text-slate-400 text-xs italic">No saved graphs.</p>
+                ) : (
+                  <div className="space-y-1">
+                    {savedGraphs.map(name => (
+                      <div key={name} className="flex justify-between items-center bg-slate-900 p-2 rounded hover:bg-slate-700 group transition-colors">
+                        <button
+                          onClick={() => { onLoad(name); setShowLoad(false); }}
+                          className="text-white text-sm text-left flex-1"
+                        >
+                          {name}
+                        </button>
+                        {onDeleteGraph && (
+                          <button
+                            onClick={(e) => { e.stopPropagation(); onDeleteGraph(name); setShowLoad(false); }}
+                            className="text-slate-400 hover:text-red-400 transition-colors p-1.5 rounded-md hover:bg-slate-800"
+                            title="Delete Graph"
+                          >
+                            <Trash2 size={14} />
+                          </button>
+                        )}
+                      </div>
+                    ))}
+                  </div>
+                )}
+              </div>
+            )}
+
           </div>
 
           <div onMouseEnter={() => setIsHovered(true)} onMouseLeave={() => setIsHovered(false)} className="flex-1 min-h-0 flex flex-col overflow-hidden">

package/components/HelpOverlay.tsx

@@ -109,7 +109,7 @@ const HelpOverlay: React.FC<HelpOverlayProps> = ({
                         className="flex items-center gap-2 text-slate-300 hover:text-white transition-colors"
                     >
                         <LinkIcon size={14} className="text-slate-500" />
-                        <span>Regeneration Prompt</span>
+                        <span>Prompt</span>
                     </a>
                     <a
                         href="/doc/api_queries.html"

package/hooks/useExpansion.ts

@@ -182,9 +182,21 @@ export function useExpansion(options: UseExpansionOptions) {
                     // and vice versa.
                     const parentIsAtomic = !!(node.is_atomic ?? (node as any).is_person ?? (node.type || '').toLowerCase() === 'person');
                     const expectedChildIsAtomic = !parentIsAtomic;
+
+                    // Validate cache semantic consistency: if most cached children look like the
+                    // wrong bipartite type (e.g. persons cached from when this node was an Event,
+                    // but now it's a Person), skip the cache so the LLM fetches fresh data.
+                    const ATOMIC_TYPE_WORDS = new Set(['person', 'actor', 'author', 'director', 'artist', 'musician', 'character', 'scientist', 'philosopher', 'researcher', 'composer', 'photographer']);
+                    const atomicLookingCount = upgraded.filter((cn: any) => ATOMIC_TYPE_WORDS.has((cn.type || '').toLowerCase())).length;
+                    const mostlyCachedAreAtomic = upgraded.length > 0 && atomicLookingCount > upgraded.length / 2;
+                    const cacheSemanticValid = mostlyCachedAreAtomic === expectedChildIsAtomic;
+                    if (!cacheSemanticValid) {
+                        console.warn(`[useExpansion] Cache bypassed: cached nodes are mostly ${mostlyCachedAreAtomic ? 'atomic' : 'composite'} but expected ${expectedChildIsAtomic ? 'atomic' : 'composite'} for "${node.title}"`);
+                    }
+
                     validCached = upgraded.map((cn: any) => ({ ...cn, is_atomic: expectedChildIsAtomic }));
 
-                    if (validCached.length >= 5) {
+                    if (cacheSemanticValid && validCached.length >= 5) {
                         const existingNodeIdsBefore = new Set(graphDataRef.current.nodes.map(n => String(n.id)));
                         const newChildIds: (string | number)[] = validCached.filter(cn => !existingNodeIdsBefore.has(String(cn.id))).map(cn => cn.id);
                         // Include ALL connected nodes for highlighting, not just new ones
@@ -538,6 +550,13 @@ export function useExpansion(options: UseExpansionOptions) {
                 let nodesToUse = resultsWithWiki;
                 if (!exploreTerm.toLowerCase().startsWith('list of ')) nodesToUse = nodesToUse.filter((n: any) => !isBadListPage(n.title));
 
+                // Preserve LLM-assigned is_atomic before cache fetch may overwrite with stale DB values.
+                const freshAtomicByTitle = new Map<string, boolean>(
+                    resultsWithWiki
+                        .filter((cn: any) => typeof cn.is_atomic === 'boolean')
+                        .map((cn: any) => [String(cn.title || '').toLowerCase(), Boolean(cn.is_atomic)])
+                );
+
                 let finalIDMap: Record<string, number> | undefined;
                 if (cacheEnabled) {
                     let combinedNodes = [...resultsWithWiki];
@@ -609,7 +628,11 @@ export function useExpansion(options: UseExpansionOptions) {
                         const existing = nodeMap.get(String(cn.id));
                         nodeMap.set(String(cn.id), {
                             id: cn.id, title: cn.title, type: cn.type,
-                            is_atomic: (existing?.is_atomic ?? (existing as any)?.is_person ?? (typeof (cn as any).is_atomic === 'boolean' ? (cn as any).is_atomic : expectedChildIsAtomic)),
+                            // Prefer LLM-assigned is_atomic (most accurate); fall back to bipartite inference.
+                            // DB is_atomic is unreliable (can be stale from a prior wrong classification).
+                            is_atomic: freshAtomicByTitle.has(String(cn.title || '').toLowerCase())
+                                ? freshAtomicByTitle.get(String(cn.title || '').toLowerCase())!
+                                : expectedChildIsAtomic,
                             wikipedia_id: cn.wikipedia_id, description: cn.description || existing?.description || "",
                             year: cn.year ?? existing?.year, imageUrl: meta.imageUrl ?? existing?.imageUrl,
                             imageChecked: !!(meta.imageUrl ?? existing?.imageUrl) || existing?.imageChecked,

package/hooks/useSearchHandlers.ts

@@ -1,7 +1,7 @@
 "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 { classifyStartPair, fetchConnectionPath, LockedPair, classifyEntity, fetchConnections } from '../services/aiService';
 import { fetchWikipediaSummary } from '../services/wikipediaService';
 import { dedupeGraph, normalizeForDedup } from '../services/graphUtils';
 import { clampToViewport } from '../utils/graphLogicUtils';
@@ -147,8 +147,10 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
 
             const dim = dimensionsRef.current;
             const startNode: GraphNode = {
+                ...nodeData,
                 id: nodeData.id,
                 title: canonicalTitle,
+                // Fresh classification always wins over stale DB values.
                 type,
                 is_atomic: isAtomic,
                 wikipedia_id: wiki.pageid?.toString(),
@@ -161,7 +163,6 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
                 atomic_type: chosenPair.atomicType,
                 composite_type: chosenPair.compositeType,
                 imageUrl: nodeData.imageUrl || nodeData.image_url,
-                ...nodeData
             };
 
             setGraphData({ nodes: [startNode], links: [] });

package/index.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import ReactDOM from 'react-dom/client';
-import App from './App';
+import App from '@johndimm/constellations/App';
 import './index.css';
 
 const rootElement = document.getElementById('root');
@@ -9,8 +9,10 @@ if (!rootElement) {
 }
 
 const root = ReactDOM.createRoot(rootElement);
+const hubUrl: string = import.meta.env.VITE_HUB_URL || "http://127.0.0.1:8000";
+
 root.render(
   <React.StrictMode>
-    <App />
+    <App closeHref={hubUrl} />
   </React.StrictMode>
-);
+);

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@johndimm/constellations",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "type": "module",
   "main": "./index.tsx",
   "exports": {
-    ".": "./index.tsx",
+    ".": "./host.ts",
     "./App": "./App.tsx",
     "./FullPageConstellations": "./FullPageConstellations.tsx",
     "./host": "./host.ts",
@@ -52,6 +52,7 @@
   },
   "dependencies": {
     "@google/genai": "^1.33.0",
+    "@johndimm/constellations": "^1.0.2",
     "d3": "^7.9.0",
     "dotenv": "^16.4.5",
     "lucide-react": "^0.560.0"

package/services/aiService.ts

@@ -1,23 +1,27 @@
 /**
- * Provider dispatcher. Set VITE_AI_PROVIDER=deepseek (or gemini) in .env.local.
- * Defaults to gemini when unset.
+ * Provider dispatcher. gemini → geminiService; everything else →
+ * deepseekService (which re-reads getLlmProvider() inside callAltLlm
+ * to pick the right API: deepseek / openai / anthropic).
  */
-import { readBundledEnv } from "./aiUtils";
-import * as gemini from "./geminiService";
-import * as deepseek from "./deepseekService";
+import { getLlmProvider } from "./aiUtils";
+import * as geminiSvc from "./geminiService";
+import * as altSvc from "./deepseekService"; // handles deepseek, openai, anthropic
 
 export * from "./aiUtils";
 export type { LockedPair } from "./geminiService";
 
-const isDeepSeek = (readBundledEnv("VITE_AI_PROVIDER") || "gemini").toLowerCase() === "deepseek";
-const svc = isDeepSeek ? deepseek : gemini;
+function getSvc(fn: string) {
+  const p = getLlmProvider();
+  console.info(`[LLM] ${p} · ${fn}`);
+  return p === "gemini" ? geminiSvc : altSvc;
+}
 
-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);
+export const classifyStartPair         = (...args: Parameters<typeof geminiSvc.classifyStartPair>)         => getSvc("classifyStartPair").classifyStartPair(...args);
+export const classifyEntity            = (...args: Parameters<typeof geminiSvc.classifyEntity>)            => getSvc("classifyEntity").classifyEntity(...args);
+export const fetchConnections          = (...args: Parameters<typeof geminiSvc.fetchConnections>)          => getSvc("fetchConnections").fetchConnections(...args);
+export const fetchPersonWorks          = (...args: Parameters<typeof geminiSvc.fetchPersonWorks>)          => getSvc("fetchPersonWorks").fetchPersonWorks(...args);
+export const fetchConnectionPath       = (...args: Parameters<typeof geminiSvc.fetchConnectionPath>)       => getSvc("fetchConnectionPath").fetchConnectionPath(...args);
+export const findWikipediaTitle        = (...args: Parameters<typeof geminiSvc.findWikipediaTitle>)        => getSvc("findWikipediaTitle").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);
+export const fetchOrgKeyPeopleBlockViaSearch = geminiSvc.fetchOrgKeyPeopleBlockViaSearch;
+export const defaultStartPairResult    = (...args: Parameters<typeof geminiSvc.defaultStartPairResult>)    => getSvc("defaultStartPairResult").defaultStartPairResult(...args);

package/services/aiUtils.ts

@@ -337,6 +337,87 @@ export function withTimeout<T>(promise: Promise<T>, ms: number, errorMsg: string
   });
 }
 
+export function clipForLlmLog(text: string, maxChars = 16000): string {
+  const s = String(text ?? "");
+  if (s.length <= maxChars) return s;
+  return `${s.slice(0, maxChars)}\n… [truncated ${s.length - maxChars} more chars]`;
+}
+
+export function isRateLimitError(e: any): boolean {
+  if (e?.error?.code === 429 || e?.code === 429) return true;
+  const s = String(e?.error?.status || "").toLowerCase();
+  if (s === "resource_exhausted") return true;
+  const t = [e?.message, e?.error, e?.status, e?.code, typeof e === "string" ? e : ""]
+    .map(x => (typeof x === "object" ? JSON.stringify(x) : String(x ?? "")))
+    .join(" ")
+    .toLowerCase();
+  return t.includes("429") || t.includes("resource_exhausted");
+}
+
+export type LlmProviderId = "gemini" | "deepseek" | "openai" | "anthropic";
+
+const BROWSER_LLM_KEY = "constellations_llm_provider";
+
+function isValidProvider(v: string): v is LlmProviderId {
+  return v === "gemini" || v === "deepseek" || v === "openai" || v === "anthropic";
+}
+
+export function getBrowserLlmOverride(): LlmProviderId | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const v = window.localStorage.getItem(BROWSER_LLM_KEY)?.trim().toLowerCase() ?? "";
+    if (isValidProvider(v)) return v;
+  } catch {}
+  return null;
+}
+
+export function setBrowserLlmOverride(provider: LlmProviderId | null): void {
+  if (typeof window === "undefined") return;
+  try {
+    if (provider === null) {
+      window.localStorage.removeItem(BROWSER_LLM_KEY);
+    } else {
+      window.localStorage.setItem(BROWSER_LLM_KEY, provider);
+    }
+  } catch {}
+}
+
+// Server-side per-request override (Node.js module memory, set before each proxy call).
+// This is intentionally simple — dev server is single-user so concurrent-request races are fine.
+let _serverLlmOverride: LlmProviderId | null = null;
+
+export function setServerLlmOverride(provider: LlmProviderId | null): void {
+  _serverLlmOverride = provider;
+}
+
+export function getLlmProvider(): LlmProviderId {
+  if (_serverLlmOverride) return _serverLlmOverride;
+  const browser = getBrowserLlmOverride();
+  if (browser) return browser;
+  const raw = (readBundledEnv("VITE_AI_PROVIDER") || "deepseek").trim().toLowerCase();
+  return isValidProvider(raw) ? raw : "deepseek";
+}
+
+/**
+ * Returns true if `term` is likely a person name (2–4 Title-Case words, no parens or digits,
+ * no leading article). Used as a sanity-check on LLM classification results and fallbacks.
+ * False-positives (e.g. "Star Wars") can happen, but this is only consulted when the model
+ * returns or falls back to isAtomic=false, so the worst case is a wrong default that the user
+ * can easily correct by re-searching with a disambiguated term.
+ */
+export function looksLikePersonName(term: string): boolean {
+  const t = term.trim();
+  if (/[()[\]{}]/.test(t)) return false;  // parenthetical tags → work title
+  if (/\d/.test(t)) return false;          // digits → year / track number
+  const words = t.split(/\s+/);
+  if (words.length < 2 || words.length > 4) return false;
+  // Leading stopwords rule out "The Godfather", "A Star Is Born", etc.
+  if (/^(the|a|an|of|in|on|at|to|for|with|by|la|le|les|el|los|das|der|die)$/i.test(words[0])) return false;
+  // Each word: Title-Case word (≥2 chars), single initial with period, or name suffix
+  const nameWordRe = /^[A-Z][a-z'-]{1,}\.?$|^[A-Z]\.$|^(Jr|Sr|II|III|IV|VI|VII|VIII|IX)\.?$/;
+  return words.every(w => nameWordRe.test(w));
+}
+
 // Improved retry logic with exponential backoff and jitter
 export async function withRetry<T>(fn: () => Promise<T>, attempts = 3, backoffMs = 1000): Promise<T> {
   let lastError: any;

package/services/deepseekService.ts

@@ -1,20 +1,13 @@
 "use client";
 import { GeminiResponse, PersonWorksResponse, PathResponse } from "../types";
-import { parseJsonFromModelText, withTimeout, withRetry, getEnvCacheUrl, readBundledEnv } from "./aiUtils";
+import { parseJsonFromModelText, withTimeout, withRetry, getEnvCacheUrl, readBundledEnv, getLlmProvider, looksLikePersonName } from "./aiUtils";
 import type { LockedPair } from "./geminiService";
 
 export type { LockedPair };
 
-const DEEPSEEK_API_URL = "https://api.deepseek.com/chat/completions";
-const DEFAULT_MODEL = "deepseek-chat";
-
 const TIMEOUT_MS = 60000;
 const CLASSIFY_TIMEOUT_MS = 15000;
 
-function getDeepSeekApiKey(): string {
-  return readBundledEnv("VITE_DEEPSEEK_API_KEY");
-}
-
 function shouldProxy(): boolean {
   if (typeof window === "undefined") return false;
   if ((window as any).__PRERENDER_INJECTED) return false;
@@ -27,24 +20,60 @@ async function callAiProxy(endpoint: string, body: any) {
   const resp = await fetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(body),
+    body: JSON.stringify({ ...body, llmProvider: getLlmProvider() }),
   });
   if (!resp.ok) throw new Error(`AI Proxy Error (${resp.status}): ${await resp.text()}`);
   return resp.json();
 }
 
-async function callDeepSeek(system: string, user: string, timeoutMs = TIMEOUT_MS): Promise<string> {
-  const apiKey = getDeepSeekApiKey();
-  if (!apiKey) throw new Error("No VITE_DEEPSEEK_API_KEY set");
+async function callAltLlm(system: string, user: string, timeoutMs = TIMEOUT_MS): Promise<string> {
+  const provider = getLlmProvider();
+
+  if (provider === "anthropic") {
+    const key = readBundledEnv("VITE_ANTHROPIC_API_KEY");
+    if (!key) throw new Error("No VITE_ANTHROPIC_API_KEY set");
+    const model = readBundledEnv("VITE_ANTHROPIC_MODEL") || "claude-3-5-haiku-20241022";
+    const res = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "x-api-key": key,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: 8192,
+        ...(system.trim() ? { system: system.trim() } : {}),
+        messages: [{ role: "user", content: `${user}\n\nReply with a single valid JSON object only. No markdown, no commentary.` }],
+      }),
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`Anthropic API error (${res.status}): ${err}`);
+    }
+    const data = await res.json();
+    const block = data?.content?.[0];
+    return block?.type === "text" ? block.text : "";
+  }
 
-  const res = await fetch(DEEPSEEK_API_URL, {
+  // OpenAI-compatible: openai or deepseek
+  const isOpenAI = provider === "openai";
+  const baseUrl = isOpenAI
+    ? (readBundledEnv("VITE_OPENAI_BASE_URL") || "https://api.openai.com/v1")
+    : (readBundledEnv("VITE_DEEPSEEK_BASE_URL") || "https://api.deepseek.com/v1");
+  const model = isOpenAI
+    ? (readBundledEnv("VITE_OPENAI_MODEL") || "gpt-4o-mini")
+    : (readBundledEnv("VITE_DEEPSEEK_MODEL") || "deepseek-chat");
+  const key = isOpenAI
+    ? readBundledEnv("VITE_OPENAI_API_KEY")
+    : readBundledEnv("VITE_DEEPSEEK_API_KEY");
+  if (!key) throw new Error(`No API key set for ${provider}`);
+
+  const res = await fetch(`${baseUrl.replace(/\/$/, "")}/chat/completions`, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${apiKey}`,
-    },
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
     body: JSON.stringify({
-      model: DEFAULT_MODEL,
+      model,
       messages: [
         { role: "system", content: system },
         { role: "user", content: user },
@@ -52,16 +81,26 @@ async function callDeepSeek(system: string, user: string, timeoutMs = TIMEOUT_MS
       response_format: { type: "json_object" },
     }),
   });
-
   if (!res.ok) {
     const err = await res.text();
-    throw new Error(`DeepSeek API error (${res.status}): ${err}`);
+    throw new Error(`${provider} API error (${res.status}): ${err}`);
   }
-
   const data = await res.json();
   return data.choices?.[0]?.message?.content ?? "";
 }
 
+export const defaultStartPairResult = (reason: string, term?: string) => {
+  const isPerson = term ? looksLikePersonName(term) : false;
+  return {
+    type: isPerson ? "Person" : "Event",
+    description: "",
+    isAtomic: isPerson,
+    atomicType: "Person",
+    compositeType: "Event",
+    reasoning: reason,
+  };
+};
+
 const SYSTEM_INSTRUCTION = `
 You are a Bipartite Graph Generator.
 Your goal is to build a graph that alternates between an "Atomic" type and a "Composite" type.
@@ -132,19 +171,16 @@ export const classifyStartPair = async (
   compositeType: string;
   reasoning: string;
 }> => {
-  const fallback = {
-    type: "Event",
-    description: "",
-    isAtomic: false,
-    atomicType: "Person",
-    compositeType: "Event",
-    reasoning: "Default fallback.",
-  };
-
-  if (shouldProxy()) return callAiProxy("/api/ai/classify-start", { term, wikiContext });
+  const fallback = defaultStartPairResult("Default fallback.", term);
 
-  const apiKey = getDeepSeekApiKey();
-  if (!apiKey) return fallback;
+  if (shouldProxy()) {
+    const proxyResult = await callAiProxy("/api/ai/classify-start", { term, wikiContext });
+    if (!proxyResult.isAtomic && looksLikePersonName(term)) {
+      console.warn("[classifyStartPair] proxy returned isAtomic=false for apparent person name; overriding", term);
+      return { ...proxyResult, isAtomic: true, type: "Person" };
+    }
+    return proxyResult;
+  }
 
   const prompt = `Choose the most appropriate bipartite pair for: "${term}".
 
@@ -165,7 +201,7 @@ Return JSON with exactly these fields:
 
   try {
     const raw = await withTimeout(
-      withRetry(() => callDeepSeek(SYSTEM_INSTRUCTION, prompt), 3, 1000),
+      withRetry(() => callAltLlm(SYSTEM_INSTRUCTION, prompt), 3, 1000),
       CLASSIFY_TIMEOUT_MS,
       "classifyStartPair timed out"
     );
@@ -201,9 +237,6 @@ export const classifyEntity = async (
 
   if (shouldProxy()) return callAiProxy("/api/ai/classify", { term, wikiContext });
 
-  const apiKey = getDeepSeekApiKey();
-  if (!apiKey) return fallback;
-
   const wikiPrompt = wikiContext ? `\n\nUSE THIS VERIFIED INFORMATION:\n${wikiContext}\n` : "";
 
   const prompt = `Classify "${term}".${wikiPrompt}
@@ -222,7 +255,7 @@ Return JSON:
 
   try {
     const raw = await withRetry(
-      () => withTimeout(callDeepSeek(SYSTEM_INSTRUCTION, prompt), CLASSIFY_TIMEOUT_MS, "classifyEntity timed out"),
+      () => withTimeout(callAltLlm(SYSTEM_INSTRUCTION, prompt), CLASSIFY_TIMEOUT_MS, "classifyEntity timed out"),
       3,
       1000
     );
@@ -256,9 +289,6 @@ export const fetchConnections = async (
     return callAiProxy("/api/ai/connections", { nodeName, context, excludeNodes, wikiContext, wikipediaId, atomicType, compositeType, mentioningPageTitles });
   }
 
-  const apiKey = getDeepSeekApiKey();
-  if (!apiKey) return { people: [] };
-
   const atomicLabel = atomicType || "ATOMIC entity";
   const compositeLabel = compositeType || "COMPOSITE entity";
   const wikiIdStr = wikipediaId ? ` (Wikipedia ID: ${wikipediaId})` : "";
@@ -299,7 +329,7 @@ Return JSON:
 
   try {
     const raw = await withRetry(
-      () => withTimeout(callDeepSeek(SYSTEM_INSTRUCTION, prompt), TIMEOUT_MS, "fetchConnections timed out"),
+      () => withTimeout(callAltLlm(SYSTEM_INSTRUCTION, prompt), TIMEOUT_MS, "fetchConnections timed out"),
       4,
       1000
     );
@@ -328,9 +358,6 @@ export const fetchPersonWorks = async (
     return callAiProxy("/api/ai/works", { nodeName, excludeNodes, wikiContext, wikipediaId, atomicType, compositeType, mentioningPageTitles });
   }
 
-  const apiKey = getDeepSeekApiKey();
-  if (!apiKey) return { works: [] };
-
   const atomicLabel = atomicType || "ATOMIC entity";
   const compositeLabel = compositeType || "COMPOSITE entity";
   const wikiIdStr = wikipediaId ? ` (Wikipedia ID: ${wikipediaId})` : "";
@@ -365,7 +392,7 @@ Return JSON:
 
   try {
     const raw = await withRetry(
-      () => withTimeout(callDeepSeek(SYSTEM_INSTRUCTION, prompt), TIMEOUT_MS, "fetchPersonWorks timed out"),
+      () => withTimeout(callAltLlm(SYSTEM_INSTRUCTION, prompt), TIMEOUT_MS, "fetchPersonWorks timed out"),
       4,
       1000
     );
@@ -388,9 +415,6 @@ export const fetchConnectionPath = async (
 ): Promise<PathResponse> => {
   if (shouldProxy()) return callAiProxy("/api/ai/path", { start, end, context });
 
-  const apiKey = getDeepSeekApiKey();
-  if (!apiKey) return { path: [], found: false };
-
   const wikiPrompt = (context?.startWiki || context?.endWiki)
     ? `\n\nVERIFIED INFO:\n${context?.startWiki ? `[${start}]: ${context.startWiki}\n` : ""}${context?.endWiki ? `[${end}]: ${context.endWiki}\n` : ""}`
     : "";
@@ -412,7 +436,7 @@ Return JSON:
 
   try {
     const raw = await withTimeout(
-      callDeepSeek(SYSTEM_INSTRUCTION, prompt),
+      callAltLlm(SYSTEM_INSTRUCTION, prompt),
       45000,
       "fetchConnectionPath timed out"
     );
@@ -431,9 +455,6 @@ export const findWikipediaTitle = async (
 ): Promise<{ title: string; imageHint?: string } | null> => {
   if (shouldProxy()) return callAiProxy("/api/ai/title", { name, description });
 
-  const apiKey = getDeepSeekApiKey();
-  if (!apiKey) return null;
-
   const prompt = `Find the exact English Wikipedia article title for "${name}"${description ? ` described as "${description}"` : ""}.
 
 Return JSON:
@@ -444,7 +465,7 @@ Return JSON:
 
   try {
     const raw = await withTimeout(
-      callDeepSeek("You are a Wikipedia lookup assistant. Return strict JSON only.", prompt),
+      callAltLlm("You are a Wikipedia lookup assistant. Return strict JSON only.", prompt),
       10000,
       "findWikipediaTitle timed out"
     );
@@ -456,12 +477,3 @@ Return JSON:
   }
 };
 
-
-export const defaultStartPairResult = (reason: string) => ({
-  type: "Event",
-  description: "",
-  isAtomic: false,
-  atomicType: "Person",
-  compositeType: "Event",
-  reasoning: reason,
-});

package/services/geminiService.ts

@@ -1,7 +1,7 @@
 "use client";
 import { GoogleGenAI, Type } from "@google/genai";
 import { GeminiResponse, PersonWorksResponse, PathResponse } from "../types";
-import { getApiKey, getResponseText, cleanJson, parseJsonFromModelText, withTimeout, withRetry, getEnvCacheUrl, getEnvGeminiModel, getEnvGeminiModelClassify, sanitizeSearchTerm } from "./aiUtils";
+import { getApiKey, getResponseText, cleanJson, parseJsonFromModelText, withTimeout, withRetry, getEnvCacheUrl, getEnvGeminiModel, getEnvGeminiModelClassify, sanitizeSearchTerm, looksLikePersonName, getLlmProvider } from "./aiUtils";
 
 export { getApiKey, getResponseText, cleanJson, parseJsonFromModelText, withTimeout, withRetry, getEnvCacheUrl, getEnvGeminiModel, getEnvGeminiModelClassify } from "./aiUtils";
 
@@ -120,7 +120,7 @@ async function callAiProxy(endpoint: string, body: any) {
     const resp = await fetch(url, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(body)
+      body: JSON.stringify({ ...body, llmProvider: getLlmProvider() })
     });
 
     if (resp.status === 404 && endpoint === "/api/ai/classify-start") {
@@ -154,7 +154,7 @@ function shouldProxy(): boolean {
   return !!baseUrl;
 }
 
-export function defaultStartPairResult(reason: string): {
+export function defaultStartPairResult(reason: string, term?: string): {
   type: string;
   description: string;
   isAtomic: boolean;
@@ -162,10 +162,11 @@ export function defaultStartPairResult(reason: string): {
   compositeType: string;
   reasoning: string;
 } {
+  const isPerson = term ? looksLikePersonName(term) : false;
   return {
-    type: "Event",
+    type: isPerson ? "Person" : "Event",
     description: "",
-    isAtomic: false,
+    isAtomic: isPerson,
     atomicType: "Person",
     compositeType: "Event",
     reasoning: reason,
@@ -291,7 +292,13 @@ export const classifyStartPair = async (
     });
   }
   if (proxy) {
-    return callAiProxy("/api/ai/classify-start", { term: rawTerm.trim(), wikiContext });
+    const proxyResult = await callAiProxy("/api/ai/classify-start", { term: rawTerm.trim(), wikiContext });
+    // Sanity check: if proxy says non-atomic but the term strongly looks like a person name, correct it.
+    if (!proxyResult.isAtomic && looksLikePersonName(rawTerm)) {
+      console.warn("[classifyStartPair] proxy returned isAtomic=false for apparent person name; overriding", rawTerm);
+      return { ...proxyResult, isAtomic: true, type: "Person" };
+    }
+    return proxyResult;
   }
 
   const needsMusic = rawTermNeedsMusicEntityExtract(rawTerm);
@@ -330,7 +337,7 @@ export const classifyStartPair = async (
 
 
   if (!apiKey) {
-    return defaultStartPairResult("No API key available; defaulting to Person↔Event.");
+    return defaultStartPairResult("No API key available; defaulting to Person↔Event.", term);
   }
 
   const prompt = `Choose the most appropriate bipartite pair for this session based on the input: "${term}".
@@ -391,7 +398,8 @@ Rules:
   } catch (e: any) {
     console.warn("[classifyStartPair]", term, String(e?.message || e).slice(0, 200));
     return defaultStartPairResult(
-      "Classification API unavailable (quota/rate limit or error); defaulting to Person↔Event."
+      "Classification API unavailable (quota/rate limit or error); defaulting to Person↔Event.",
+      term
     );
   }
 };

package/services/wikipediaService.ts

@@ -4,6 +4,20 @@ import { jsonFromResponse } from "./aiUtils";
 
 type WikiImageCacheEntry = { url: string | null; pageId?: number; pageTitle?: string; misses?: number };
 
+// Session-level rate-limit gate: after any 429, block all Wikipedia/Wikidata calls for 90s.
+let _wikiRateLimitedUntil = 0;
+function wikiIsRateLimited() { return Date.now() < _wikiRateLimitedUntil; }
+function wikiSetRateLimited() {
+  _wikiRateLimitedUntil = Date.now() + 90_000;
+  console.warn('[Wiki] 429 received — pausing all Wikipedia/Wikidata calls for 90s');
+}
+async function wikiFetch(url: string, init?: RequestInit): Promise<Response | null> {
+  if (wikiIsRateLimited()) return null;
+  const res = await fetch(url, init);
+  if (res.status === 429) { wikiSetRateLimited(); return null; }
+  return res;
+}
+
 // DuckDuckGo image search fallback (posters/cover art when Wikimedia lacks a usable image).
 export const fetchDuckDuckGoPoster = async (q: string): Promise<string | null> => {
   // Respect network sandbox: if running in a browser without CORS, skip.
@@ -493,6 +507,7 @@ export const fetchWikipediaSummary = async (
   depth: number = 0,
   triedNoContext = false
 ): Promise<{ extract: string | null; pageid: number | null; title: string | null; year?: number | null; mentioningPageTitles?: string[] | null; searchContext?: string | null }> => {
+  if (wikiIsRateLimited()) return { extract: null, pageid: null, title: null };
   const normKey = `${query.trim().toLowerCase()}|${context || ''}`;
   if (visited.has(normKey) || depth > 2) {
     return { extract: null, pageid: null, title: null };
@@ -504,7 +519,8 @@ export const fetchWikipediaSummary = async (
     const tryDirectLookup = async (titleToFetch: string) => {
       try {
         const directUrl = `https://en.wikipedia.org/w/api.php?action=query&format=json&prop=extracts|pageprops&exintro&explaintext&titles=${encodeURIComponent(titleToFetch)}&redirects=1&origin=*`;
-        const directRes = await fetch(directUrl);
+        const directRes = await wikiFetch(directUrl);
+        if (!directRes) return null;
         const directData = (await jsonFromResponse(directRes)) as { query?: { pages?: unknown; redirects?: unknown } } | null;
         if (!directData) return null;
         const directPages = directData.query?.pages;
@@ -646,7 +662,8 @@ export const fetchWikipediaSummary = async (
 
     const avoidMedia = /\b(project|program|programme|operation|war|battle|campaign|treaty|scandal|scientist)\b/i.test(baseQuery);
     const searchUrl = `https://en.wikipedia.org/w/api.php?action=query&format=json&list=search&srsearch=${encodeURIComponent(searchQuery)}&srlimit=5&origin=*`;
-    const searchRes = await fetch(searchUrl);
+    const searchRes = await wikiFetch(searchUrl);
+    if (!searchRes) return { extract: null, pageid: null, title: null };
     const searchData = (await jsonFromResponse(searchRes)) as { query?: { search?: any[] } } | null;
 
     let bestTitle = query;
@@ -796,7 +813,8 @@ export const fetchWikipediaSummary = async (
           }
         }
         const summaryUrl = `https://en.wikipedia.org/w/api.php?action=query&format=json&prop=extracts|pageprops&exintro&explaintext&titles=${encodeURIComponent(titleToTry)}&redirects=1&origin=*`;
-        const summaryRes = await fetch(summaryUrl);
+        const summaryRes = await wikiFetch(summaryUrl);
+        if (!summaryRes) break;
         const summaryData = (await jsonFromResponse(summaryRes)) as { query?: { pages?: unknown } } | null;
         if (!summaryData) continue;
         const pages = summaryData.query?.pages;
@@ -1061,8 +1079,10 @@ const fetchWikidataLabels = async (ids: string[], signal: AbortSignal): Promise<
 
 const resolveWikidataIdBySearch = async (label: string, signal: AbortSignal): Promise<string | null> => {
   try {
+    if (wikiIsRateLimited()) return null;
     const url = `https://www.wikidata.org/w/api.php?action=wbsearchentities&format=json&language=en&limit=8&search=${encodeURIComponent(label)}&origin=*`;
     const res = await fetch(url, { signal });
+    if (res.status === 429) { wikiSetRateLimited(); return null; }
     const data = (await jsonFromResponse(res)) as { search?: any[] } | null;
     const results: any[] = data?.search || [];
     if (!results.length) return null;

package/sessionHandoff.ts

@@ -130,3 +130,29 @@ export function takeEmbedHandoffForInitialState(): ConstellationsSessionHandoffV
     embedHandoffMem = null;
     return null;
 }
+
+declare global {
+    interface Window {
+        __soundingsConstellationsGetHandoff?: () => unknown;
+    }
+}
+
+/** Serialize current embedded graph (`__soundingsConstellationsGetHandoff`) before navigating away. */
+export function persistWindowConstellationsHandoffToSession(): void {
+    if (typeof window === 'undefined') return;
+    try {
+        const fn = window.__soundingsConstellationsGetHandoff;
+        if (typeof fn !== 'function') return;
+        const payload = fn();
+        if (!payload || typeof payload !== 'object') return;
+        const p = payload as { v?: number; graph?: { nodes?: unknown[] } };
+        if (p.v !== 1 || !p.graph?.nodes?.length) return;
+        try {
+            sessionStorage.setItem(SOUNDINGS_CONSTELLATIONS_HANDOFF_KEY, JSON.stringify(payload));
+        } catch (e) {
+            console.warn('[constellations] handoff too large for sessionStorage', e);
+        }
+    } catch (e) {
+        console.warn('[constellations] handoff persist', e);
+    }
+}