cli-jaw 2.0.10 → 2.0.16

package/public/manager/src/notes/graph/NotesGraphCanvas.tsx

@@ -0,0 +1,195 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import * as d3 from 'd3';
+import { graphForceConfigFromSettings, labelVisibleForNode, radiusForNode } from './notes-graph-force';
+import type { NotesGraphRenderData, NotesGraphRenderEdge, NotesGraphRenderNode } from './notes-graph-filter';
+import type { NotesGraphSettings } from './notes-graph-settings';
+
+type NotesGraphCanvasProps = {
+    data: NotesGraphRenderData;
+    selectedPath: string | null;
+    settings: NotesGraphSettings;
+    fitToken: number;
+    onNavigate: (path: string) => void;
+};
+
+type SimNode = NotesGraphRenderNode & d3.SimulationNodeDatum;
+type SimEdge = Omit<NotesGraphRenderEdge, 'source' | 'target'> & {
+    source: SimNode;
+    target: SimNode;
+};
+
+function nodeClassName(node: NotesGraphRenderNode, selectedPath: string | null): string {
+    const selected = node.id === selectedPath ? ' is-selected' : '';
+    return `notes-graph-node notes-graph-node-${node.kind}${selected}`;
+}
+
+function edgeClassName(edge: Pick<NotesGraphRenderEdge, 'status' | 'virtual'>): string {
+    return `notes-graph-link notes-graph-link-${edge.status}${edge.virtual ? ' is-virtual' : ''}`;
+}
+
+export function NotesGraphCanvas(props: NotesGraphCanvasProps) {
+    const svgRef = useRef<SVGSVGElement | null>(null);
+    const hostRef = useRef<HTMLDivElement | null>(null);
+    const navigateRef = useRef(props.onNavigate);
+    const [size, setSize] = useState({ width: 900, height: 650 });
+    navigateRef.current = props.onNavigate;
+    const config = useMemo(() => graphForceConfigFromSettings(props.settings), [props.settings]);
+
+    useEffect(() => {
+        const host = hostRef.current;
+        if (!host) return undefined;
+        const updateSize = (): void => {
+            const rect = host.getBoundingClientRect();
+            setSize({
+                width: Math.max(320, Math.floor(rect.width || 900)),
+                height: Math.max(320, Math.floor(rect.height || 650)),
+            });
+        };
+        updateSize();
+        if (typeof window.ResizeObserver !== 'function') return undefined;
+        const observer = new window.ResizeObserver(updateSize);
+        observer.observe(host);
+        return () => observer.disconnect();
+    }, []);
+
+    useEffect(() => {
+        const svgElement = svgRef.current;
+        if (!svgElement) return undefined;
+        const svg = d3.select(svgElement);
+        svg.selectAll('*').remove();
+        svg.attr('viewBox', `0 0 ${size.width} ${size.height}`);
+        if (props.data.nodes.length === 0) return undefined;
+
+        const reduceMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+        const nodes: SimNode[] = props.data.nodes.map(node => ({ ...node }));
+        const nodeById = new Map(nodes.map(node => [node.id, node]));
+        const edges: SimEdge[] = props.data.edges.flatMap(edge => {
+            const source = nodeById.get(edge.source);
+            const target = nodeById.get(edge.target);
+            const edgeMeta = {
+                raw: edge.raw,
+                status: edge.status,
+                ...(edge.resolvedPath ? { resolvedPath: edge.resolvedPath } : {}),
+                ...(edge.virtual ? { virtual: edge.virtual } : {}),
+            };
+            return source && target ? [{ ...edgeMeta, source, target }] : [];
+        });
+
+        const defs = svg.append('defs');
+        defs.append('marker')
+            .attr('id', 'notes-graph-arrow')
+            .attr('viewBox', '0 -5 10 10')
+            .attr('refX', 15)
+            .attr('refY', 0)
+            .attr('markerWidth', 6)
+            .attr('markerHeight', 6)
+            .attr('orient', 'auto')
+            .append('path')
+            .attr('d', 'M0,-5L10,0L0,5')
+            .attr('fill', 'currentColor');
+
+        const viewport = svg.append('g').attr('class', 'notes-graph-viewport');
+        const link = viewport.append('g')
+            .attr('class', 'notes-graph-links')
+            .selectAll<SVGLineElement, SimEdge>('line')
+            .data(edges)
+            .join('line')
+            .attr('class', edgeClassName)
+            .attr('marker-end', config.showArrows ? 'url(#notes-graph-arrow)' : null);
+
+        const node = viewport.append('g')
+            .attr('class', 'notes-graph-nodes')
+            .selectAll<SVGGElement, SimNode>('g')
+            .data(nodes)
+            .join('g')
+            .attr('class', d => nodeClassName(d, props.selectedPath))
+            .attr('tabindex', d => d.kind === 'note' ? 0 : -1)
+            .attr('role', d => d.kind === 'note' ? 'button' : 'img')
+            .attr('aria-label', d => `${d.title}, ${d.kind}, ${d.degree} links`)
+            .on('click', (_event: MouseEvent, d: SimNode) => {
+                if (d.kind === 'note' && d.path) navigateRef.current(d.path);
+            })
+            .on('keydown', (event: KeyboardEvent, d: SimNode) => {
+                if (d.kind !== 'note' || !d.path) return;
+                if (event.key !== 'Enter' && event.key !== ' ') return;
+                event.preventDefault();
+                navigateRef.current(d.path);
+            });
+
+        node.append('circle')
+            .attr('r', d => radiusForNode(d, config))
+            .attr('fill', d => d.groupColor ?? null);
+
+        node.append('text')
+            .attr('class', 'notes-graph-label')
+            .attr('x', d => radiusForNode(d, config) + 8)
+            .attr('y', 4)
+            .text(d => d.title);
+
+        node.append('title')
+            .text(d => d.groupLabel ? `${d.title} · ${d.groupLabel}` : d.title);
+
+        const simulation = d3.forceSimulation<SimNode>(nodes)
+            .force('link', d3.forceLink<SimNode, SimEdge>(edges).id(d => d.id).distance(config.linkDistance))
+            .force('charge', d3.forceManyBody().strength(config.chargeStrength))
+            .force('center', d3.forceCenter(size.width / 2, size.height / 2))
+            .force('collision', d3.forceCollide<SimNode>().radius(d => radiusForNode(d, config) + 8));
+
+        function renderFrame(): void {
+            link
+                .attr('x1', d => d.source.x ?? 0)
+                .attr('y1', d => d.source.y ?? 0)
+                .attr('x2', d => d.target.x ?? 0)
+                .attr('y2', d => d.target.y ?? 0);
+            node.attr('transform', d => `translate(${d.x ?? size.width / 2},${d.y ?? size.height / 2})`);
+        }
+
+        const zoom = d3.zoom<SVGSVGElement, unknown>()
+            .scaleExtent([0.18, 5])
+            .on('zoom', (event) => {
+                viewport.attr('transform', event.transform);
+                node.classed('is-label-visible', d => labelVisibleForNode(d, event.transform.k, config));
+            });
+        svg.call(zoom);
+        const initialTransform = d3.zoomIdentity.translate(0, 0).scale(1);
+        svg.call(zoom.transform, initialTransform);
+
+        const drag = d3.drag<SVGGElement, SimNode>()
+            .on('start', (event, d) => {
+                if (!event.active && config.animate && !reduceMotion) simulation.alphaTarget(0.25).restart();
+                d.fx = d.x;
+                d.fy = d.y;
+            })
+            .on('drag', (event, d) => {
+                d.fx = event.x;
+                d.fy = event.y;
+            })
+            .on('end', (event, d) => {
+                if (!event.active) simulation.alphaTarget(0);
+                d.fx = null;
+                d.fy = null;
+            });
+        node.call(drag);
+
+        if (config.animate && !reduceMotion) {
+            simulation.on('tick', renderFrame);
+        } else {
+            simulation.tick(120);
+            renderFrame();
+            simulation.stop();
+        }
+        return () => {
+            simulation.stop();
+            svg.on('.zoom', null);
+        };
+    }, [props.data, props.selectedPath, size, config, props.fitToken]);
+
+    return (
+        <div ref={hostRef} className="notes-graph-canvas" data-empty={props.data.nodes.length === 0 ? 'true' : 'false'}>
+            {props.data.nodes.length === 0 ? (
+                <div className="notes-graph-empty-state">No matching graph nodes</div>
+            ) : null}
+            <svg ref={svgRef} className="notes-graph-svg" aria-label="Notes graph" />
+        </div>
+    );
+}

package/public/manager/src/notes/graph/NotesGraphControlsPanel.tsx

@@ -0,0 +1,172 @@
+import type { ReactElement } from 'react';
+import type { NotesGraphGroup, NotesGraphSection, NotesGraphSettings } from './notes-graph-settings';
+import { createNotesGraphGroup, NOTES_GRAPH_GROUP_COLORS, NOTES_GRAPH_SECTIONS } from './notes-graph-settings';
+
+type NotesGraphControlsPanelProps = {
+    settings: NotesGraphSettings;
+    selectedPath: string | null;
+    onChange: (settings: NotesGraphSettings) => void;
+    onReset: () => void;
+    onFit: () => void;
+    onClose: () => void;
+};
+
+type ToggleKey =
+    | 'existingFilesOnly'
+    | 'showOrphans'
+    | 'showTags'
+    | 'showAttachments'
+    | 'focusSelected'
+    | 'showArrows'
+    | 'animate';
+
+function sectionLabel(section: NotesGraphSection): string {
+    if (section === 'filters') return 'Filters';
+    if (section === 'display') return 'Display';
+    if (section === 'forces') return 'Forces';
+    return 'Groups';
+}
+
+function nextSettings(settings: NotesGraphSettings, patch: Partial<NotesGraphSettings>): NotesGraphSettings {
+    return {
+        ...settings,
+        ...patch,
+        collapsedSections: patch.collapsedSections ?? settings.collapsedSections,
+        groups: patch.groups ?? settings.groups,
+    };
+}
+
+function ToggleRow(props: {
+    label: string;
+    checked: boolean;
+    onChange: (value: boolean) => void;
+    disabled?: boolean;
+}): ReactElement {
+    return (
+        <label className={`notes-graph-toggle${props.disabled ? ' is-disabled' : ''}`}>
+            <span>{props.label}</span>
+            <input type="checkbox" checked={props.checked} disabled={props.disabled} onChange={event => props.onChange(event.currentTarget.checked)} />
+        </label>
+    );
+}
+
+export function NotesGraphControlsPanel(props: NotesGraphControlsPanelProps) {
+    const { settings } = props;
+
+    function patch(patchValue: Partial<NotesGraphSettings>): void {
+        props.onChange(nextSettings(settings, patchValue));
+    }
+
+    function toggle(key: ToggleKey): void {
+        patch({ [key]: !settings[key] } as Partial<Pick<NotesGraphSettings, ToggleKey>>);
+    }
+
+    function toggleSection(section: NotesGraphSection): void {
+        patch({
+            collapsedSections: {
+                ...settings.collapsedSections,
+                [section]: !settings.collapsedSections[section],
+            },
+        });
+    }
+
+    function updateGroup(id: string, patchValue: Partial<NotesGraphGroup>): void {
+        patch({ groups: settings.groups.map(group => group.id === id ? { ...group, ...patchValue } : group) });
+    }
+
+    function addGroup(): void {
+        patch({ groups: [...settings.groups, createNotesGraphGroup(settings.groups.length, settings.query)] });
+    }
+
+    function removeGroup(id: string): void {
+        patch({ groups: settings.groups.filter(group => group.id !== id) });
+    }
+
+    return (
+        <aside className="notes-graph-controls" aria-label="Graph controls">
+            <header className="notes-graph-controls-header">
+                <div>
+                    <h3>Graph</h3>
+                    <span>{props.selectedPath ? 'Focus-ready' : 'Global view'}</span>
+                </div>
+                <button type="button" className="notes-graph-icon-button" onClick={props.onClose} aria-label="Close graph controls">X</button>
+            </header>
+
+            {NOTES_GRAPH_SECTIONS.map(section => (
+                <section key={section} className="notes-graph-control-section">
+                    <button type="button" className="notes-graph-section-toggle" onClick={() => toggleSection(section)} aria-expanded={!settings.collapsedSections[section]}>
+                        <span>{sectionLabel(section)}</span>
+                        <span>{settings.collapsedSections[section] ? '+' : '-'}</span>
+                    </button>
+                    {!settings.collapsedSections[section] && section === 'filters' ? (
+                        <div className="notes-graph-control-body">
+                            <label className="notes-graph-field">
+                                <span>Search</span>
+                                <input value={settings.query} onChange={event => patch({ query: event.currentTarget.value })} placeholder="title, path:, tag:, kind:" />
+                            </label>
+                            <ToggleRow label="Existing files only" checked={settings.existingFilesOnly} onChange={() => toggle('existingFilesOnly')} />
+                            <ToggleRow label="Show orphans" checked={settings.showOrphans} onChange={() => toggle('showOrphans')} />
+                            <ToggleRow label="Show tags" checked={settings.showTags} onChange={() => toggle('showTags')} />
+                            <ToggleRow label="Show attachments" checked={settings.showAttachments} onChange={() => toggle('showAttachments')} />
+                            <ToggleRow label="Focus selected" checked={settings.focusSelected} disabled={!props.selectedPath} onChange={() => toggle('focusSelected')} />
+                            <label className="notes-graph-field">
+                                <span>Depth {settings.focusDepth}</span>
+                                <input type="range" min="1" max="4" value={settings.focusDepth} disabled={!settings.focusSelected || !props.selectedPath} onChange={event => patch({ focusDepth: Number(event.currentTarget.value) })} />
+                            </label>
+                        </div>
+                    ) : null}
+                    {!settings.collapsedSections[section] && section === 'display' ? (
+                        <div className="notes-graph-control-body">
+                            <label className="notes-graph-field">
+                                <span>Node size {settings.nodeSize.toFixed(1)}</span>
+                                <input type="range" min="0.6" max="2" step="0.1" value={settings.nodeSize} onChange={event => patch({ nodeSize: Number(event.currentTarget.value) })} />
+                            </label>
+                            <label className="notes-graph-field">
+                                <span>Labels {Math.round(settings.labelDensity * 100)}%</span>
+                                <input type="range" min="0" max="1" step="0.05" value={settings.labelDensity} onChange={event => patch({ labelDensity: Number(event.currentTarget.value) })} />
+                            </label>
+                            <ToggleRow label="Show arrows" checked={settings.showArrows} onChange={() => toggle('showArrows')} />
+                            <ToggleRow label="Animate" checked={settings.animate} onChange={() => toggle('animate')} />
+                        </div>
+                    ) : null}
+                    {!settings.collapsedSections[section] && section === 'forces' ? (
+                        <div className="notes-graph-control-body">
+                            <label className="notes-graph-field">
+                                <span>Link distance {settings.linkDistance}</span>
+                                <input type="range" min="40" max="240" value={settings.linkDistance} onChange={event => patch({ linkDistance: Number(event.currentTarget.value) })} />
+                            </label>
+                            <label className="notes-graph-field">
+                                <span>Repel {Math.abs(settings.chargeStrength)}</span>
+                                <input type="range" min="-800" max="-20" value={settings.chargeStrength} onChange={event => patch({ chargeStrength: Number(event.currentTarget.value) })} />
+                            </label>
+                            <div className="notes-graph-control-row">
+                                <button type="button" onClick={props.onFit}>Fit</button>
+                                <button type="button" onClick={props.onReset}>Reset</button>
+                            </div>
+                        </div>
+                    ) : null}
+                    {!settings.collapsedSections[section] && section === 'groups' ? (
+                        <div className="notes-graph-control-body">
+                            <ToggleRow label="Query groups" checked={settings.groupMode === 'query'} onChange={value => patch({ groupMode: value ? 'query' : 'off' })} />
+                            <div className="notes-graph-groups">
+                                {settings.groups.map((group, index) => (
+                                    <div key={group.id} className="notes-graph-group-row">
+                                        <input className="notes-graph-color" type="color" value={group.color} onChange={event => updateGroup(group.id, { color: event.currentTarget.value })} />
+                                        <input value={group.label} onChange={event => updateGroup(group.id, { label: event.currentTarget.value })} aria-label={`Group ${index + 1} label`} />
+                                        <input value={group.query} onChange={event => updateGroup(group.id, { query: event.currentTarget.value })} aria-label={`Group ${index + 1} query`} />
+                                        <button type="button" onClick={() => updateGroup(group.id, { enabled: !group.enabled })} aria-pressed={group.enabled}>{group.enabled ? 'On' : 'Off'}</button>
+                                        <button type="button" className="notes-graph-icon-button" onClick={() => removeGroup(group.id)} aria-label={`Remove ${group.label}`}>X</button>
+                                    </div>
+                                ))}
+                            </div>
+                            <div className="notes-graph-swatches" aria-label="Group color presets">
+                                {NOTES_GRAPH_GROUP_COLORS.map(color => <span key={color} style={{ background: color }} />)}
+                            </div>
+                            <button type="button" onClick={addGroup}>Add group</button>
+                        </div>
+                    ) : null}
+                </section>
+            ))}
+        </aside>
+    );
+}

package/public/manager/src/notes/graph/NotesGraphWorkspace.tsx

@@ -0,0 +1,116 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { NotesGraphCanvas } from './NotesGraphCanvas';
+import { NotesGraphControlsPanel } from './NotesGraphControlsPanel';
+import { deriveNotesGraphData } from './notes-graph-filter';
+import {
+    cloneNotesGraphSettings,
+    DEFAULT_NOTES_GRAPH_SETTINGS,
+    normalizeNotesGraphSettings,
+    type NotesGraphSettings,
+} from './notes-graph-settings';
+import type { NotesVaultIndexSnapshot } from '../notes-types';
+
+export type NotesGraphRuntimeBoundary = {
+    dataPlane: 'dashboard-notes-api';
+    shellPanels: 'render-only';
+};
+
+export const NOTES_GRAPH_RUNTIME_BOUNDARY: NotesGraphRuntimeBoundary = {
+    dataPlane: 'dashboard-notes-api',
+    shellPanels: 'render-only',
+};
+
+type NotesGraphWorkspaceProps = {
+    vaultIndex: NotesVaultIndexSnapshot | null;
+    selectedPath: string | null;
+    settings?: NotesGraphSettings | undefined;
+    onSettingsChange?: (settings: NotesGraphSettings) => void;
+    onNavigate: (path: string) => void;
+};
+
+function defaultSettings(): NotesGraphSettings {
+    return cloneNotesGraphSettings(DEFAULT_NOTES_GRAPH_SETTINGS);
+}
+
+export function NotesGraphWorkspace(props: NotesGraphWorkspaceProps) {
+    // Graph is intentionally web-capable: data comes from the dashboard notes API.
+    // Electron side panels may render Jawsidian content, but must not become the
+    // source of graph connectivity or persistence.
+    const [draft, setDraft] = useState<NotesGraphSettings>(() => normalizeNotesGraphSettings(props.settings ?? defaultSettings()));
+    const [fitToken, setFitToken] = useState(0);
+    const persistTimerRef = useRef<number | null>(null);
+
+    useEffect(() => {
+        setDraft(normalizeNotesGraphSettings(props.settings ?? defaultSettings()));
+    }, [props.settings]);
+
+    useEffect(() => () => {
+        if (persistTimerRef.current != null) window.clearTimeout(persistTimerRef.current);
+    }, []);
+
+    function persist(next: NotesGraphSettings, immediate = false): void {
+        setDraft(next);
+        if (!props.onSettingsChange) return;
+        if (persistTimerRef.current != null) window.clearTimeout(persistTimerRef.current);
+        if (immediate) {
+            props.onSettingsChange(next);
+            return;
+        }
+        persistTimerRef.current = window.setTimeout(() => props.onSettingsChange?.(next), 140);
+    }
+
+    function resetSettings(): void {
+        persist(defaultSettings(), true);
+        setFitToken(token => token + 1);
+    }
+
+    function closePanel(): void {
+        persist({ ...draft, panelOpen: false }, true);
+    }
+
+    function openPanel(): void {
+        persist({ ...draft, panelOpen: true }, true);
+    }
+
+    const graphData = useMemo(
+        () => deriveNotesGraphData(props.vaultIndex, draft, props.selectedPath),
+        [props.vaultIndex, draft, props.selectedPath],
+    );
+
+    return (
+        <div className={`notes-graph-workspace${draft.panelOpen ? ' has-controls' : ''}`}>
+            <header className="notes-graph-toolbar">
+                <div className="notes-graph-counts" aria-live="polite">
+                    <strong>{graphData.noteCount}</strong> notes
+                    <span>{graphData.linkCount} links</span>
+                    <span>{graphData.missingCount} unresolved</span>
+                    {graphData.tagCount > 0 ? <span>{graphData.tagCount} tags</span> : null}
+                </div>
+                <div className="notes-graph-actions">
+                    <button type="button" onClick={() => setFitToken(token => token + 1)}>Fit</button>
+                    <button type="button" onClick={resetSettings}>Reset</button>
+                    {!draft.panelOpen ? <button type="button" onClick={openPanel}>Controls</button> : null}
+                </div>
+            </header>
+            <div className="notes-graph-body">
+                <NotesGraphCanvas
+                    data={graphData}
+                    selectedPath={props.selectedPath}
+                    settings={draft}
+                    fitToken={fitToken}
+                    onNavigate={props.onNavigate}
+                />
+                {draft.panelOpen ? (
+                    <NotesGraphControlsPanel
+                        settings={draft}
+                        selectedPath={props.selectedPath}
+                        onChange={next => persist(next)}
+                        onReset={resetSettings}
+                        onFit={() => setFitToken(token => token + 1)}
+                        onClose={closePanel}
+                    />
+                ) : null}
+            </div>
+        </div>
+    );
+}

package/public/manager/src/notes/graph/notes-graph-filter.ts

@@ -0,0 +1,192 @@
+import type { NoteGraphEdge, NoteGraphNode, NoteMetadata } from '../../types';
+import type { NotesVaultIndexSnapshot } from '../notes-types';
+import type { NotesGraphGroup, NotesGraphSettings } from './notes-graph-settings';
+
+export type NotesGraphRenderNode = NoteGraphNode & {
+    degree: number;
+    groupColor?: string;
+    groupLabel?: string;
+    searchMatch: boolean;
+};
+
+export type NotesGraphRenderEdge = NoteGraphEdge & {
+    virtual?: boolean;
+};
+
+export type NotesGraphRenderData = {
+    nodes: NotesGraphRenderNode[];
+    edges: NotesGraphRenderEdge[];
+    noteCount: number;
+    linkCount: number;
+    missingCount: number;
+    tagCount: number;
+    hiddenCount: number;
+};
+
+type GraphShape = { nodes: NoteGraphNode[]; edges: NoteGraphEdge[] };
+
+const NODE_KIND_ORDER: Record<NoteGraphNode['kind'], number> = {
+    note: 0,
+    tag: 1,
+    missing: 2,
+    ambiguous: 3,
+    attachment: 4,
+};
+
+function normalizeTag(tag: string): string {
+    return tag.trim().replace(/^#/, '').toLowerCase();
+}
+
+function tagNodeId(tag: string): string {
+    return `tag:${normalizeTag(tag)}`;
+}
+
+function nodeSearchFields(node: NoteGraphNode, metadata: NoteMetadata | undefined): string[] {
+    const fields = [node.id, node.title, node.path ?? ''];
+    if (metadata) fields.push(metadata.title, metadata.path, ...metadata.aliases, ...metadata.tags);
+    return fields.filter(Boolean).map(field => field.toLowerCase());
+}
+
+function tokenMatchesNode(token: string, node: NoteGraphNode, metadata: NoteMetadata | undefined): boolean {
+    const lower = token.toLowerCase();
+    if (lower.startsWith('kind:')) return node.kind === lower.slice(5);
+    if (lower.startsWith('path:')) return (node.path ?? node.id).toLowerCase().includes(lower.slice(5));
+    if (lower.startsWith('tag:')) {
+        const tag = normalizeTag(lower.slice(4));
+        if (!tag) return true;
+        if (node.kind === 'tag') return normalizeTag(node.title).includes(tag) || node.id.includes(tag);
+        return Boolean(metadata?.tags.some(noteTag => normalizeTag(noteTag).includes(tag)));
+    }
+    return nodeSearchFields(node, metadata).some(field => field.includes(lower));
+}
+
+function matchesQuery(query: string, node: NoteGraphNode, metadata: NoteMetadata | undefined): boolean {
+    const tokens = query.trim().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0) return true;
+    return tokens.every(token => tokenMatchesNode(token, node, metadata));
+}
+
+function matchingGroup(
+    node: NoteGraphNode,
+    metadata: NoteMetadata | undefined,
+    settings: NotesGraphSettings,
+): NotesGraphGroup | undefined {
+    if (settings.groupMode === 'off') return undefined;
+    return settings.groups.find(group => group.enabled && matchesQuery(group.query, node, metadata));
+}
+
+function buildWorkingGraph(snapshot: NotesVaultIndexSnapshot, settings: NotesGraphSettings): GraphShape {
+    const nodes = new Map<string, NoteGraphNode>();
+    for (const node of snapshot.graph.nodes) nodes.set(node.id, { ...node });
+    for (const note of snapshot.notes) {
+        if (!nodes.has(note.path)) nodes.set(note.path, { id: note.path, title: note.title, kind: 'note', path: note.path });
+    }
+    const edges: NoteGraphEdge[] = snapshot.graph.edges.map(edge => ({ ...edge }));
+    // The server-owned vault index is the authority for wikilink connectivity,
+    // including missing/ambiguous nodes. The client only adds virtual tag edges.
+    if (settings.showTags) {
+        for (const note of snapshot.notes) {
+            for (const rawTag of note.tags) {
+                const tag = normalizeTag(rawTag);
+                if (!tag) continue;
+                const id = tagNodeId(tag);
+                if (!nodes.has(id)) nodes.set(id, { id, title: `#${tag}`, kind: 'tag' });
+                edges.push({ source: note.path, target: id, raw: `#${tag}`, status: 'resolved', resolvedPath: note.path });
+            }
+        }
+    }
+    return { nodes: [...nodes.values()], edges };
+}
+
+function degreeByNode(edges: NoteGraphEdge[]): Map<string, number> {
+    const degree = new Map<string, number>();
+    for (const edge of edges) {
+        degree.set(edge.source, (degree.get(edge.source) ?? 0) + 1);
+        degree.set(edge.target, (degree.get(edge.target) ?? 0) + 1);
+    }
+    return degree;
+}
+
+function focusedNodeIds(edges: NoteGraphEdge[], selectedPath: string, maxDepth: number): Set<string> {
+    const adjacency = new Map<string, Set<string>>();
+    for (const edge of edges) {
+        if (!adjacency.has(edge.source)) adjacency.set(edge.source, new Set());
+        if (!adjacency.has(edge.target)) adjacency.set(edge.target, new Set());
+        adjacency.get(edge.source)?.add(edge.target);
+        adjacency.get(edge.target)?.add(edge.source);
+    }
+    const visible = new Set<string>([selectedPath]);
+    let frontier = new Set<string>([selectedPath]);
+    for (let depth = 0; depth < maxDepth; depth += 1) {
+        const next = new Set<string>();
+        for (const nodeId of frontier) {
+            for (const neighbor of adjacency.get(nodeId) ?? []) {
+                if (visible.has(neighbor)) continue;
+                visible.add(neighbor);
+                next.add(neighbor);
+            }
+        }
+        frontier = next;
+        if (frontier.size === 0) break;
+    }
+    return visible;
+}
+
+function compareNodes(a: NotesGraphRenderNode, b: NotesGraphRenderNode): number {
+    return NODE_KIND_ORDER[a.kind] - NODE_KIND_ORDER[b.kind] || a.title.localeCompare(b.title) || a.id.localeCompare(b.id);
+}
+
+export function deriveNotesGraphData(
+    snapshot: NotesVaultIndexSnapshot | null,
+    settings: NotesGraphSettings,
+    selectedPath: string | null,
+): NotesGraphRenderData {
+    if (!snapshot) return { nodes: [], edges: [], noteCount: 0, linkCount: 0, missingCount: 0, tagCount: 0, hiddenCount: 0 };
+    const metadataByPath = new Map(snapshot.notes.map(note => [note.path, note]));
+    const graph = buildWorkingGraph(snapshot, settings);
+    let candidateNodes = graph.nodes.filter(node => {
+        if (settings.existingFilesOnly && (node.kind === 'missing' || node.kind === 'ambiguous')) return false;
+        if (!settings.showTags && node.kind === 'tag') return false;
+        if (!settings.showAttachments && node.kind === 'attachment') return false;
+        return matchesQuery(settings.query, node, metadataByPath.get(node.path ?? node.id));
+    });
+    let candidateIds = new Set(candidateNodes.map(node => node.id));
+    let candidateEdges = graph.edges.filter(edge => candidateIds.has(edge.source) && candidateIds.has(edge.target));
+    if (!settings.showOrphans) {
+        const degree = degreeByNode(candidateEdges);
+        candidateNodes = candidateNodes.filter(node => node.id === selectedPath || (degree.get(node.id) ?? 0) > 0 || node.kind !== 'note');
+        candidateIds = new Set(candidateNodes.map(node => node.id));
+        candidateEdges = candidateEdges.filter(edge => candidateIds.has(edge.source) && candidateIds.has(edge.target));
+    }
+    if (settings.focusSelected && selectedPath && candidateIds.has(selectedPath)) {
+        const focusedIds = focusedNodeIds(candidateEdges, selectedPath, settings.focusDepth);
+        candidateNodes = candidateNodes.filter(node => focusedIds.has(node.id));
+        candidateIds = new Set(candidateNodes.map(node => node.id));
+        candidateEdges = candidateEdges.filter(edge => candidateIds.has(edge.source) && candidateIds.has(edge.target));
+    }
+    const degree = degreeByNode(candidateEdges);
+    const renderNodes: NotesGraphRenderNode[] = candidateNodes.map(node => {
+        const metadata = metadataByPath.get(node.path ?? node.id);
+        const group = matchingGroup(node, metadata, settings);
+        return {
+            ...node,
+            degree: degree.get(node.id) ?? 0,
+            ...(group ? { groupColor: group.color, groupLabel: group.label } : {}),
+            searchMatch: matchesQuery(settings.query, node, metadata),
+        };
+    }).sort(compareNodes);
+    const visibleIds = new Set(renderNodes.map(node => node.id));
+    const edges = candidateEdges
+        .filter(edge => visibleIds.has(edge.source) && visibleIds.has(edge.target))
+        .map(edge => ({ ...edge, virtual: edge.target.startsWith('tag:') || edge.source.startsWith('tag:') }))
+        .sort((a, b) => a.source.localeCompare(b.source) || a.target.localeCompare(b.target) || a.raw.localeCompare(b.raw));
+    return {
+        nodes: renderNodes,
+        edges,
+        noteCount: renderNodes.filter(node => node.kind === 'note').length,
+        linkCount: edges.filter(edge => !edge.virtual).length,
+        missingCount: renderNodes.filter(node => node.kind === 'missing' || node.kind === 'ambiguous').length,
+        tagCount: renderNodes.filter(node => node.kind === 'tag').length,
+        hiddenCount: graph.nodes.length - renderNodes.length,
+    };
+}