@johndimm/constellations 1.0.0

package/sessionHandoff.ts

@@ -0,0 +1,132 @@
+"use client";
+import { GraphNode, GraphLink } from './types';
+import { LockedPair } from './services/geminiService';
+import { dedupeGraph } from './services/graphUtils';
+
+const getLinkEndpointId = (x: string | number | GraphNode) =>
+    typeof x === 'object' && x != null && 'id' in x ? (x as GraphNode).id : (x as string | number);
+
+export const SOUNDINGS_CONSTELLATIONS_HANDOFF_KEY = 'soundings-constellations-handoff-v1';
+
+export type ConstellationsSessionHandoffV1 = {
+    v: 1;
+    graph: { nodes: GraphNode[]; links: GraphLink[] };
+    exploreTerm: string;
+    pathStart: string;
+    pathEnd: string;
+    searchMode: 'explore' | 'connect';
+    isCompact: boolean;
+    isTimelineMode: boolean;
+    isTextOnly: boolean;
+    searchId: number;
+    lockedPair: LockedPair;
+    pathNodeIds: (string | number)[];
+    selectedNodeId?: string | number | null;
+};
+
+export function buildHandoffFromLiveState(params: {
+    graph: { nodes: GraphNode[]; links: GraphLink[] };
+    exploreTerm: string;
+    pathStart: string;
+    pathEnd: string;
+    searchMode: 'explore' | 'connect';
+    isCompact: boolean;
+    isTimelineMode: boolean;
+    isTextOnly: boolean;
+    searchId: number;
+    lockedPair: LockedPair;
+    pathNodeIds: (string | number)[];
+    selectedNodeId: string | number | null | undefined;
+}): ConstellationsSessionHandoffV1 {
+    if (!params.graph.nodes.length) {
+        throw new Error('Handoff requires at least one node');
+    }
+    const links: GraphLink[] = params.graph.links.map((l) => ({
+        ...l,
+        source: getLinkEndpointId(l.source as string | number | GraphNode),
+        target: getLinkEndpointId(l.target as string | number | GraphNode)
+    }));
+    const nodes: GraphNode[] = params.graph.nodes.map((n) => ({
+        ...n,
+        isLoading: false,
+        fetchingImage: false,
+        vx: n.vx ?? 0,
+        vy: n.vy ?? 0
+    }));
+    return {
+        v: 1,
+        graph: { nodes, links },
+        exploreTerm: params.exploreTerm,
+        pathStart: params.pathStart,
+        pathEnd: params.pathEnd,
+        searchMode: params.searchMode,
+        isCompact: params.isCompact,
+        isTimelineMode: params.isTimelineMode,
+        isTextOnly: params.isTextOnly,
+        searchId: params.searchId,
+        lockedPair: { ...params.lockedPair },
+        pathNodeIds: [...params.pathNodeIds],
+        selectedNodeId: params.selectedNodeId ?? null
+    };
+}
+
+/**
+ * Strips simulation cruft, dedupes, and returns graph safe to put in React state.
+ */
+export function graphFromHandoff(h: ConstellationsSessionHandoffV1) {
+    const links = h.graph.links.map((l) => ({
+        ...l,
+        source: getLinkEndpointId(l.source as string | number | GraphNode),
+        target: getLinkEndpointId(l.target as string | number | GraphNode)
+    }));
+    const nodes = h.graph.nodes.map((n) => ({
+        ...n,
+        isLoading: false,
+        fetchingImage: false,
+        vx: n.vx ?? 0,
+        vy: n.vy ?? 0,
+        fx: n.fx ?? null,
+        fy: n.fy ?? null
+    }));
+    return dedupeGraph(nodes, links);
+}
+
+const UNREAD: unique symbol = Symbol('embed-handoff');
+
+/**
+ * Staging from player embed: sessionStorage (once) + in-memory (duplicate React 18
+ * useState initializers in StrictMode must see the same object).
+ */
+let embedHandoffMem: ConstellationsSessionHandoffV1 | null | typeof UNREAD = UNREAD;
+
+/**
+ * For use in `useState(() => takeEmbedHandoffForInitialState())` — no side effects
+ * that differ between double invocations: second call must return the same value.
+ * Always prefer a fresh `sessionStorage` payload (new navigation) over the cache.
+ */
+export function takeEmbedHandoffForInitialState(): ConstellationsSessionHandoffV1 | null {
+    if (typeof window !== 'undefined') {
+        const raw = sessionStorage.getItem(SOUNDINGS_CONSTELLATIONS_HANDOFF_KEY);
+        if (raw) {
+            try {
+                const p = JSON.parse(raw) as ConstellationsSessionHandoffV1;
+                if (p?.v === 1 && p.graph?.nodes?.length) {
+                    try {
+                        sessionStorage.removeItem(SOUNDINGS_CONSTELLATIONS_HANDOFF_KEY);
+                    } catch { /* empty */ }
+                    embedHandoffMem = p;
+                    return p;
+                }
+            } catch { /* empty */ }
+        }
+    }
+    if (embedHandoffMem !== UNREAD) {
+        return embedHandoffMem;
+    }
+    if (typeof window === 'undefined') {
+        embedHandoffMem = null;
+        return null;
+    }
+    embedHandoffMem = null;
+    return null;
+}

package/types.ts

@@ -0,0 +1,99 @@
+import { SimulationNodeDatum, SimulationLinkDatum } from 'd3';
+
+export interface GraphNode extends SimulationNodeDatum {
+  id: number | string; // Sequential serial ID or Wikipedia/OpenAlex ID
+  title: string; // The name of the event/project/thing/person
+  type: string; // Original detailed type: 'Person', 'Movie', 'Battle', etc. (preserved)
+  is_atomic?: boolean; // True for atomic nodes, false for composite nodes
+  is_person?: boolean; // DEPRECATED: use is_atomic
+  wikipedia_id?: string;
+  description?: string;
+  meta?: Record<string, any>; // Optional source-specific metadata (e.g., OpenAlex IDs)
+  imageUrl?: string | null; // URL for the node image
+  year?: number; // Year of occurrence (for timeline view)
+  expanded?: boolean; // Whether we have already fetched connections for this node
+  isLoading?: boolean; // Visual state for fetching (connections)
+  fetchingImage?: boolean; // State for fetching image
+  imageChecked?: boolean; // Whether we have already attempted to fetch an image
+  wikiSummary?: string; // Cached Wikipedia summary for richer sidebar context
+  classification_reasoning?: string; // AI explanation of atomic/composite status
+  atomic_type?: string; // e.g. "Symptom"
+  composite_type?: string; // e.g. "Disease"
+  mentioningPageTitles?: string[]; // Titles of articles mentioning this entity (for non-article fallback)
+  // D3 Simulation properties explicitly defined to ensure access
+  x?: number;
+  y?: number;
+  fx?: number | null;
+  fy?: number | null;
+  vx?: number;
+  vy?: number;
+  index?: number;
+}
+
+export interface GraphLink extends SimulationLinkDatum<GraphNode> {
+  source: number | string | GraphNode;
+  target: number | string | GraphNode;
+  id: string | number; // Unique link ID
+  label?: string; // Role or connection description
+  evidence?: {
+    kind: 'wikipedia' | 'openalex' | 'crossref' | 'ai' | 'none';
+    // Human-readable page title where the snippet came from (usually source or target)
+    pageTitle?: string;
+    // Copyable snippet (typically 1 sentence)
+    snippet?: string;
+    // URL to open for verification
+    url?: string;
+  };
+}
+
+export interface GeminiEntity {
+  name: string;
+  type: string;
+  description: string;
+  role: string; // Role in the parent connection
+}
+
+export interface GeminiPerson {
+  name: string;
+  wikipediaTitle?: string; // Canonical Wikipedia page title (may include disambiguation parentheses)
+  role: string; // Role in the source node
+  description: string; // Brief bio
+  isAtomic?: boolean; // LLM-determined atomic vs composite classification
+  evidenceSnippet?: string; // 1 sentence from provided verified text (preferred)
+  evidencePageTitle?: string; // Which page the snippet came from (usually the source title)
+}
+
+export interface GeminiResponse {
+  sourceYear?: number;
+  people: GeminiPerson[];
+}
+
+export interface PersonWork {
+  entity: string;
+  wikipediaTitle?: string; // Canonical Wikipedia page title (may include disambiguation parentheses)
+  type: string;
+  description: string;
+  role: string;
+  year: number;
+  imageUrl?: string | null;
+  isAtomic?: boolean; // LLM-determined atomic vs composite classification
+  evidenceSnippet?: string; // 1 sentence from provided verified text (preferred)
+  evidencePageTitle?: string; // Which page the snippet came from (usually the source title)
+}
+
+export interface PersonWorksResponse {
+  works: PersonWork[];
+}
+
+export interface PathEntity {
+  id: string;
+  type: string;
+  description: string;
+  year?: number;
+  justification: string; // How it connects to the previous node
+}
+
+export interface PathResponse {
+  path: PathEntity[];
+  found: boolean;
+}

package/useFullPageConstellationsHost.ts

@@ -0,0 +1,116 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+export type NowPlayingSnapshot = {
+  album?: string | null;
+  track?: string | null;
+  artist?: string | null;
+};
+
+/**
+ * State sync for every full-page constellations host (Soundings, Trailer, etc.): URL `q` / `expand`,
+ * optional handoff gating, and optional live player bridge (now-playing + external search).
+ * Single implementation — host apps only supply layout-specific inputs.
+ */
+export function useFullPageConstellationsHost(input: {
+  qParam: string;
+  expandParam: string;
+  /** When a session handoff is present, do not clobber from URL/bridge. */
+  skipUrlAndPlayerBridge: boolean;
+  /**
+   * If set, merge `expand` with album/track for auto-expand and drive `nowPlayingKey` /
+   * `externalSearch` from the snapshot. Omit (Trailer) for URL `expand` only.
+   */
+  getPlayerSnapshot?: () => NowPlayingSnapshot | null | undefined;
+  /** e.g. `soundings-now-playing` — bumps a revision so `nowPlayingKey` updates with the player. */
+  nowPlayingBumperEvent?: string;
+}) {
+  const [hydrated, setHydrated] = useState(false);
+  const [npRev, setNpRev] = useState(0);
+  const [externalSearch, setExternalSearch] = useState<{
+    term: string;
+    id: string | number;
+  } | null>(null);
+  const [autoExpandTitles, setAutoExpandTitles] = useState<string[]>([]);
+  const [nowPlayingKey, setNowPlayingKey] = useState<string | null>(null);
+
+  useEffect(() => {
+    setHydrated(true);
+  }, []);
+
+  const bumper = input.nowPlayingBumperEvent;
+
+  useEffect(() => {
+    if (!bumper) return;
+    const bump = () => setNpRev((n) => n + 1);
+    window.addEventListener(bumper, bump);
+    return () => window.removeEventListener(bumper, bump);
+  }, [bumper]);
+
+  const { qParam, expandParam, skipUrlAndPlayerBridge, getPlayerSnapshot } = input;
+
+  useEffect(() => {
+    if (!hydrated) return;
+    if (skipUrlAndPlayerBridge) return;
+
+    const extra = expandParam
+      ? expandParam
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : [];
+
+    if (!getPlayerSnapshot) {
+      setExternalSearch(null);
+      setNowPlayingKey(null);
+      setAutoExpandTitles(extra);
+      return;
+    }
+
+    const snap = getPlayerSnapshot();
+    const album = snap?.album?.trim();
+    const track = snap?.track?.trim();
+    const artist = snap?.artist?.trim();
+    const mergedExpand = [
+      ...extra,
+      ...(album ? [album] : []),
+      ...(track ? [track] : []),
+      ...(artist ? [artist] : []),
+    ];
+    if (album || track) {
+      setNowPlayingKey(`${npRev}::${album || ""}::${track || ""}`);
+    } else {
+      setNowPlayingKey(null);
+    }
+    if (qParam) {
+      setExternalSearch(null);
+    } else {
+      // Prefer the track title over the artist/channel name. For YouTube classical music,
+      // the title contains the composer ("Vaughan Williams ~ The Lark Ascending") while
+      // the artist is just the uploader's channel name. The LLM in classifyStartPair
+      // (extractMusicEntity) will parse the title to extract the primary musical entity.
+      const searchTerm = track || snap?.artist?.trim() || "";
+      if (searchTerm) {
+        setExternalSearch({ term: searchTerm, id: `np:${searchTerm.toLowerCase()}` });
+      } else {
+        setExternalSearch(null);
+      }
+    }
+    setAutoExpandTitles(mergedExpand);
+  }, [
+    hydrated,
+    qParam,
+    expandParam,
+    skipUrlAndPlayerBridge,
+    getPlayerSnapshot,
+    npRev,
+  ]);
+
+  return {
+    ready: hydrated,
+    externalSearch,
+    autoExpandTitles,
+    nowPlayingKey,
+  };
+}

package/utils/evidenceUtils.ts

@@ -0,0 +1,107 @@
+export const normalizeForEvidence = (s: unknown) =>
+    String(s || '')
+        .toLowerCase()
+        .replace(/[“”"]/g, '"')
+        .replace(/[’‘]/g, "'")
+        .replace(/\s+/g, ' ')
+        .trim();
+
+export const splitIntoSentences = (text: string): string[] => {
+    const t = String(text || '').replace(/\s+/g, ' ').trim();
+    if (!t) return [];
+    // Improved sentence split that ignores common abbreviations
+    const commonAbbreviations = ['Bros', 'Mr', 'Mrs', 'Ms', 'Dr', 'Sr', 'Jr', 'St', 'Prof', 'Capt', 'Col', 'Gen', 'Inc', 'Ltd', 'Co'];
+    const abbrRegex = commonAbbreviations.join('|');
+    const regex = new RegExp(`(?<!\\b(?:${abbrRegex}))[.!?](?=\\s+[A-Z]|$)`, 'g');
+
+    const sentences: string[] = [];
+    let lastIndex = 0;
+    let match;
+    while ((match = regex.exec(t)) !== null) {
+        sentences.push(t.substring(lastIndex, match.index + 1).trim());
+        lastIndex = match.index + 1;
+    }
+    if (lastIndex < t.length) {
+        const remaining = t.substring(lastIndex).trim();
+        if (remaining) sentences.push(remaining);
+    }
+    return sentences.filter(Boolean);
+};
+
+export const roleLooksLikeJobTitle = (s: unknown) =>
+    /\b(president|ceo|chief|director|manager|founder|co-founder|curator|chairman|head)\b/i.test(String(s || ''));
+
+export const sanitizeTitleParen = (title: string) => title.replace(/\s*\(([^)]+)\)\s*$/, '').trim();
+
+export const isParenJobTitle = (title: unknown) => {
+    const s = String(title || '');
+    const m = s.match(/\(([^)]+)\)\s*$/);
+    return !!m && roleLooksLikeJobTitle(m[1]);
+};
+
+export const stripJobTitleParen = (title: string) => title.replace(/\s*\(([^)]+)\)\s*$/, '').trim();
+
+export const parentheticalLooksLikeJobTitle = (title: unknown) => {
+    const s = String(title || '');
+    const m = s.match(/\(([^)]+)\)\s*$/);
+    if (!m) return false;
+    return roleLooksLikeJobTitle(m[1]);
+};
+
+export const isEvidenceBacked = (snippet: unknown, verifiedNorm: string) => {
+    const sn = normalizeForEvidence(snippet);
+    if (!sn) return false;
+    if (!verifiedNorm) return false;
+    return verifiedNorm.includes(sn);
+};
+
+export const looksLikeSpecificPersonName = (title: unknown) => {
+    const s = String(title || '').trim();
+    if (!s) return false;
+    const lower = s.toLowerCase();
+    // Exclude generic terms
+    if (/\b(celebrity|celeb|celebrities|guests?|visitors?|staff|team|various|unknown)\b/.test(lower)) return false;
+
+    // Allow parenthetical disambiguation, but evaluate the base name.
+    const base = s.replace(/\s*\(.*\)\s*$/, '').trim();
+    const parts = base.split(/\s+/).filter(Boolean);
+
+    if (parts.length === 0) return false;
+
+    if (parts.length === 1) {
+        const name = parts[0];
+        // Allow proper names (starts with capital) of at least 2 characters.
+        return /^[A-Z]/.test(name) && name.length >= 2;
+    }
+
+    if (parts.some(p => p.length < 2)) return false;
+    return true;
+};
+
+export const sanitizeEvidenceAndRole = (cn: any, verifiedNorm: string) => {
+    const e = cn?.edge_meta?.evidence;
+    const hasEvidence = e && e.kind && e.kind !== 'none' && (e.snippet || e.pageTitle);
+    if (!hasEvidence) return cn;
+    // Non-Wikipedia sources (e.g., OpenAlex) are handled separately and should not be
+    // invalidated by Wikipedia-only snippet matching.
+    if (String(e.kind) === 'openalex') return cn;
+
+    const pageTitle = String(e.pageTitle || '');
+    const snippet = String(e.snippet || '');
+    const pageLooksNonWiki = pageTitle.includes(' - ') || /^https?:\/\//i.test(pageTitle);
+    const backed = isEvidenceBacked(snippet, verifiedNorm);
+
+    if (!backed || pageLooksNonWiki) {
+        const next = { ...cn };
+        // Drop unverified evidence.
+        next.edge_meta = { ...(next.edge_meta || {}), evidence: { kind: 'none' } };
+        // Drop role label if it looks like a job-title claim.
+        if (roleLooksLikeJobTitle(next.edge_label)) next.edge_label = null;
+        // If the node title itself is just a job-title parenthetical (unverified), strip it.
+        if (typeof next.title === 'string' && parentheticalLooksLikeJobTitle(next.title)) {
+            next.title = stripJobTitleParen(next.title);
+        }
+        return next;
+    }
+    return cn;
+};

package/utils/graphLogicUtils.ts

@@ -0,0 +1,32 @@
+export const getLinkKey = (a: number | string, b: number | string) => {
+    const s = String(a);
+    const t = String(b);
+    return s < t ? `${s}-${t}` : `${t}-${s}`;
+};
+
+export const looksLikeScreenWork = (title: string, desc?: string) => {
+    const s = String(title || '').toLowerCase();
+    const d = String(desc || '').toLowerCase();
+    return (
+        s.includes('(film)') || s.includes('(movie)') || s.includes('(tv series)') ||
+        d.includes('film') || d.includes('movie') || d.includes('television series') || d.includes('tv series')
+    );
+};
+
+export const isBadListPage = (t?: string) => {
+    const s = String(t || '').toLowerCase();
+    if (!s) return false;
+    if (s.startsWith('list of ')) return true;
+    if (s.includes('acquired by google') || s.includes('companies acquired by google') || s.includes('acquisitions by google')) return true;
+    return false;
+};
+
+export const clampToViewport = (x: number, y: number, margin = 50) => {
+    if (typeof window === 'undefined') return { x, y };
+    const w = window.innerWidth;
+    const h = window.innerHeight;
+    return {
+        x: Math.max(margin, Math.min(x, w - margin)),
+        y: Math.max(margin, Math.min(y, h - margin))
+    };
+};

package/utils/graphNodeToChannelNotes.ts

@@ -0,0 +1,71 @@
+"use client";
+import type { GraphNode } from '../types';
+import { buildWikiUrl } from './wikiUtils';
+
+const DEFAULT_NAME_MAX = 40;
+
+/**
+ * Short tab label for a channel (distinct from the long notes / DJ prompt).
+ * Safe for Wikipedia-style titles; truncates with an ellipsis when needed.
+ */
+export function graphNodeToChannelName(node: GraphNode, maxLen = DEFAULT_NAME_MAX): string {
+    const year = node.year;
+    const raw = (node.title || 'Channel').replace(/\s+/g, ' ').trim() || 'Channel';
+    const withYear = year != null ? `${raw} (${year})` : raw;
+    const primary = withYear.length <= maxLen ? withYear : raw;
+    if (primary.length <= maxLen) return primary;
+    if (maxLen < 2) return '…';
+    return primary.slice(0, maxLen - 1) + '…';
+}
+
+/**
+ * Free-text notes for a new Soundings channel, seeded from a graph node
+ * (used with createChannelWithNotes in the player).
+ */
+export function graphNodeToChannelNotes(node: GraphNode): string {
+    const type = (node.type || 'entity').trim();
+    const year = node.year != null ? ` (${node.year})` : '';
+    const titleLine = `From Constellations: ${node.title}${year}`;
+    const typeLine = `Type: ${type}`;
+
+    const parts: string[] = [titleLine, typeLine];
+
+    if (node.wikipedia_id) {
+        parts.push(`Wikipedia: ${buildWikiUrl(node.title, node.wikipedia_id)}`);
+    }
+
+    const blurb = (node.wikiSummary || node.description || '').trim();
+    if (blurb) {
+        parts.push('', blurb.slice(0, 2000));
+    }
+
+    return parts.join('\n');
+}
+
+/** Use this when both the short name and the long prompt are needed (e.g. Soundings channel tabs + notes). */
+export function graphNodeToChannelSeeds(node: GraphNode): { name: string; notes: string } {
+    return {
+        name: graphNodeToChannelName(node),
+        notes: graphNodeToChannelNotes(node),
+    };
+}
+
+/**
+ * Host apps (Soundings, Trailer) queue the same sessionStorage payload then navigate; keeps route files minimal.
+ */
+export function newChannelFromGraphNode(
+    node: GraphNode,
+    options: { sessionStorageKey: string; navigate: (path: string) => void; path: string; logLabel?: string }
+) {
+    const { name, notes } = graphNodeToChannelSeeds(node);
+    const label = options.logLabel ?? "constellations";
+    try {
+        sessionStorage.setItem(
+            options.sessionStorageKey,
+            JSON.stringify({ v: 1, name, notes })
+        );
+    } catch (e) {
+        console.warn(`[${label}] could not queue new channel for host`, e);
+    }
+    options.navigate(options.path);
+}

package/utils/wikiUtils.ts

@@ -0,0 +1,34 @@
+import { fetchWikipediaExtract } from '../services/wikipediaService';
+
+export const buildWikiUrl = (title: string, wikipediaId?: string | number) => {
+    if (wikipediaId) {
+        // If we have an ID, we likely have the exact title too.
+        return `https://en.wikipedia.org/wiki/${encodeURIComponent(title.replace(/\s+/g, '_'))}`;
+    }
+    // Fallback to search if no ID is present, to avoid 404s.
+    return `https://en.wikipedia.org/wiki/Special:Search?search=${encodeURIComponent(title)}`;
+};
+
+export const buildWikiSearchUrl = (title: string) => `https://en.wikipedia.org/wiki/Special:Search?search=${encodeURIComponent(title)}`;
+
+export const looksLikeWikipediaTitle = (t: unknown) => {
+    const s = String(t || '').trim();
+    if (!s) return false;
+    if (/^https?:\/\//i.test(s)) return false;
+    // Web page titles frequently include " - " separators; Wikipedia titles rarely do.
+    if (s.includes(' - ')) return false;
+    if (s.length > 90) return false;
+    return true;
+};
+
+const extractCache: Map<string, string | null> =
+    ((window as any).__wikiExtractCache ||= new Map<string, string | null>());
+
+export const getExtractCached = async (title: string) => {
+    const key = String(title || '').trim();
+    if (!key) return null;
+    if (extractCache.has(key)) return extractCache.get(key) || null;
+    const ex = (await fetchWikipediaExtract(key, 6000)).extract || null;
+    extractCache.set(key, ex);
+    return ex;
+};