@oml/markdown 0.11.0 → 0.13.0

package/src/renderers/graph-renderer.ts

@@ -16,7 +16,9 @@ const CSS_EDGE_BG      = 'var(--vscode-editor-background, var(--oml-static-backg
 const CSS_FONT_FAMILY  = 'var(--vscode-editor-font-family, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif)';
 
 /** Extra height beneath the circle/rect shape to accommodate the below-node label. */
-const NODE_LABEL_HEIGHT = 22;
+const NODE_LABEL_HEIGHT = 18;
+const NODE_FONT_SIZE = 10;
+const EDGE_FONT_SIZE = 10;
 
 // --- Module-level library caches ---
 let x6GraphCtor: (new (options: unknown) => any) | undefined;
@@ -53,6 +55,7 @@ type NodeData = {
     degree: number;
     literal: boolean;
     group: string;
+    hidden?: boolean;
 };
 
 type EdgeData = {
@@ -61,6 +64,7 @@ type EdgeData = {
     target: string;
     value: string;
     label: string;
+    hidden?: boolean;
 };
 
 type ForceLayoutOptions = {
@@ -143,6 +147,19 @@ type CsvDataset = {
     downloadCsv: (content: string) => void;
 };
 
+type GraphExpandPayload = {
+    columns: string[];
+    rows: string[][];
+};
+
+type GraphMutableState = {
+    nodesById: Map<string, NodeData>;
+    edgeKeys: Set<string>;
+    edgeSequence: number;
+    minDegree: number;
+    maxDegree: number;
+};
+
 const RDF_TYPE_IRI = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type';
 
 // --- Renderer ---
@@ -219,6 +236,7 @@ export class GraphMarkdownBlockRenderer extends CanvasMarkdownBlockRenderer {
         const maxDegree = Math.max(...degrees);
         const layout = resolveLayoutOptions(result.options);
         const stylesheet = compileGraphStylesheet(result.options);
+        const expandOnClick = resolveExpandOnClickOption(result.options);
         const nodeDataList = [...nodeMap.values()];
         const csvDataset: CsvDataset = {
             columns: payload.columns.slice(),
@@ -235,6 +253,9 @@ export class GraphMarkdownBlockRenderer extends CanvasMarkdownBlockRenderer {
             container,
             layout,
             stylesheet,
+            result.blockSource,
+            result.blockId,
+            expandOnClick,
             csvDataset,
         );
 
@@ -253,6 +274,9 @@ function initializeGraphWhenReady(
     messageContainer: HTMLElement,
     layoutOptions: ResolvedLayout,
     stylesheet: ReadonlyArray<GraphStyleRule>,
+    blockSource: string | undefined,
+    blockId: string,
+    expandOnClick: boolean,
     csvDataset: CsvDataset,
 ): void {
     const maxAttempts = 20;
@@ -274,6 +298,9 @@ function initializeGraphWhenReady(
             maxDegree,
             layoutOptions,
             stylesheet,
+            blockSource,
+            blockId,
+            expandOnClick,
             csvDataset,
         ).catch((error) => {
             const detail = error instanceof Error ? error.message : String(error);
@@ -295,6 +322,9 @@ async function doGraphInit(
     maxDegree: number,
     layoutOptions: ResolvedLayout,
     stylesheet: ReadonlyArray<GraphStyleRule>,
+    blockSource: string | undefined,
+    blockId: string,
+    expandOnClick: boolean,
     csvDataset: CsvDataset,
 ): Promise<void> {
     const GraphCtor = await loadX6GraphCtor();
@@ -308,6 +338,7 @@ async function doGraphInit(
             minScale: 0.3,
             maxScale: 3,
             factor: 1.1,
+            modifiers: ['meta', 'ctrl'],
         },
         connecting: {
             allowBlank: false,
@@ -347,13 +378,25 @@ async function doGraphInit(
     for (const data of edgeDataList) {
         graphView.addEdge(buildEdgeDef(data));
     }
+    const mutableState: GraphMutableState = {
+        nodesById: new Map(nodeDataList.map((node) => [node.id, node])),
+        edgeKeys: new Set(edgeDataList.map((edge) => `${edge.source}|${toNodeId(edge.value)}|${edge.target}`)),
+        edgeSequence: edgeDataList.length,
+        minDegree,
+        maxDegree,
+    };
 
     // Resize the X6 canvas whenever the host element resizes.
+    const recenterAfterResizeOrMove = (): void => {
+        centerGraphContent(graphView, layoutOptions.padding);
+    };
+
     const resizeObserver = new ResizeObserver(() => {
         if (!graphRoot.isConnected) {
             return;
         }
         graphView.resize(graphRoot.clientWidth, graphRoot.clientHeight);
+        recenterAfterResizeOrMove();
     });
     resizeObserver.observe(graphRoot);
     // Also watch the result container so that when the page grows wider the
@@ -365,6 +408,7 @@ async function doGraphInit(
             const nextWidth = Math.max(0, Math.floor(resultContainer.clientWidth));
             graphRoot.style.width = `${nextWidth}px`;
             graphView.resize(graphRoot.clientWidth, graphRoot.clientHeight);
+            recenterAfterResizeOrMove();
         });
         resultResizeObserver.observe(resultContainer);
     }
@@ -384,17 +428,29 @@ async function doGraphInit(
         // Reset to CSS-variable base attrs so stale user-rule colors are cleared.
         for (const node of graphView.getNodes() as any[]) {
             const nodeData: NodeData = node.getData() as NodeData;
+            node.setData({ hidden: false }, { merge: true });
             node.setAttrs(buildNodeBaseAttrs(nodeData.literal));
         }
         for (const edge of graphView.getEdges() as any[]) {
+            edge.setData({ hidden: false }, { merge: true });
             edge.setAttrs(buildEdgeBaseAttrs());
             resetEdgeLabelColors(edge);
         }
         applyGraphStylesheet(graphView, stylesheet, theme);
+        applyGraphVisibilityState(graphView);
     };
 
     applyCurrentTheme();
 
+    installGraphNodeInteractions(
+        graphView,
+        graphRoot,
+        applyCurrentTheme,
+        blockSource,
+        blockId,
+        expandOnClick,
+    );
+
     const themeObserver = new MutationObserver(() => {
         applyCurrentTheme();
     });
@@ -422,6 +478,27 @@ async function doGraphInit(
         startContinuousForceEngine(graphView, graphRoot, layoutOptions.force, grabbedNodes);
     }
 
+    const onExpandResult = (event: Event): void => {
+        if (!(event instanceof CustomEvent)) {
+            return;
+        }
+        const detail = event.detail as { blockId?: unknown; payload?: unknown } | undefined;
+        const targetBlockId = typeof detail?.blockId === 'string' ? detail.blockId.trim() : '';
+        if (targetBlockId !== blockId) {
+            return;
+        }
+        const payload = normalizeGraphExpandPayload(detail?.payload);
+        if (!payload) {
+            return;
+        }
+        mergeExpandedGraphData(graphView, mutableState, payload);
+        applyCurrentTheme();
+        void runLayout(graphView, layoutOptions).then(() => {
+            centerGraphContent(graphView, layoutOptions.padding);
+        });
+    };
+    graphRoot.addEventListener('md-graph-expand-result', onExpandResult);
+
     installGraphToolbar(graphRoot, graphView, csvDataset);
 
     // Manual canvas resize handle.
@@ -447,11 +524,231 @@ async function doGraphInit(
     const onResizePointerEnd = (event: PointerEvent): void => {
         if (!canvasResize || event.pointerId !== canvasResize.pointerId) return;
         canvasResize = undefined;
+        recenterAfterResizeOrMove();
     };
     resizeHandle.addEventListener('pointerdown', onResizePointerDown);
     resizeHandle.addEventListener('pointermove', onResizePointerMove);
     resizeHandle.addEventListener('pointerup', onResizePointerEnd);
     resizeHandle.addEventListener('pointercancel', onResizePointerEnd);
+    graphView.on('node:mouseup', recenterAfterResizeOrMove);
+    graphRoot.addEventListener('DOMNodeRemovedFromDocument', () => {
+        graphRoot.removeEventListener('md-graph-expand-result', onExpandResult);
+    }, { once: true });
+}
+
+function installGraphNodeInteractions(
+    graphView: any,
+    graphRoot: HTMLElement,
+    reapplyBaseTheme: () => void,
+    blockSource: string | undefined,
+    blockId: string,
+    expandOnClick: boolean,
+): void {
+    const ensureSvgNativeTitle = (element: SVGElement, iri: string): void => {
+        let titleNode: SVGTitleElement | null = null;
+        for (const child of Array.from(element.children)) {
+            if (child instanceof SVGTitleElement) {
+                titleNode = child;
+                break;
+            }
+        }
+        if (!titleNode) {
+            titleNode = document.createElementNS('http://www.w3.org/2000/svg', 'title');
+            element.insertBefore(titleNode, element.firstChild);
+        }
+        titleNode.textContent = iri;
+    };
+
+    const applyNativeTooltipTitle = (container: Element | undefined, iri: string, eventTarget?: EventTarget | null): void => {
+        if (!iri) {
+            return;
+        }
+        if (container instanceof HTMLElement || container instanceof SVGElement) {
+            container.setAttribute('title', iri);
+        }
+        if (container instanceof Element) {
+            for (const element of Array.from(container.querySelectorAll<HTMLElement | SVGElement>('*'))) {
+                element.setAttribute('title', iri);
+                if (element instanceof SVGElement) {
+                    ensureSvgNativeTitle(element, iri);
+                }
+            }
+            if (container instanceof SVGElement) {
+                ensureSvgNativeTitle(container, iri);
+            }
+        }
+        if (eventTarget instanceof HTMLElement || eventTarget instanceof SVGElement) {
+            eventTarget.setAttribute('title', iri);
+            if (eventTarget instanceof SVGElement) {
+                ensureSvgNativeTitle(eventTarget, iri);
+            }
+        }
+    };
+
+    let hoveredNodeId: string | undefined;
+    const isExpandModifierPressed = (event: MouseEvent | undefined): boolean => Boolean(event?.shiftKey);
+
+    const applyHoverState = (node: any): void => {
+        const hoveredId = String(node?.id ?? '');
+        if (!hoveredId) {
+            return;
+        }
+        reapplyBaseTheme();
+        hoveredNodeId = hoveredId;
+
+        const theme = resolveThemePalette();
+        const activeNodeIds = new Set<string>([hoveredId]);
+        const activeEdgeIds = new Set<string>();
+        const connectedEdges = (graphView.getConnectedEdges(node) as any[]) ?? [];
+        for (const edge of connectedEdges) {
+            activeEdgeIds.add(String(edge.id));
+            const sourceId = String(edge.getSourceCellId?.() ?? '');
+            const targetId = String(edge.getTargetCellId?.() ?? '');
+            if (sourceId) {
+                activeNodeIds.add(sourceId);
+            }
+            if (targetId) {
+                activeNodeIds.add(targetId);
+            }
+        }
+
+        for (const candidate of graphView.getNodes() as any[]) {
+            const candidateId = String(candidate.id);
+            const active = activeNodeIds.has(candidateId);
+            if (!active) {
+                candidate.setAttrs({
+                    body: { opacity: 0.2 },
+                    label: { opacity: 0.28 },
+                });
+                continue;
+            }
+            if (candidateId === hoveredId) {
+                candidate.setAttrs({
+                    body: {
+                        fill: theme.accent,
+                        stroke: theme.selectedStroke,
+                        strokeWidth: 2,
+                        opacity: 1,
+                    },
+                    label: {
+                        fill: theme.accentForeground,
+                        opacity: 1,
+                    },
+                });
+            }
+        }
+
+        for (const edge of graphView.getEdges() as any[]) {
+            const active = activeEdgeIds.has(String(edge.id));
+            if (!active) {
+                edge.setAttrs({
+                    line: { opacity: 0.16 },
+                });
+                try {
+                    edge.prop('labels/0/attrs/label/opacity', 0.2);
+                    edge.prop('labels/0/attrs/body/opacity', 0.12);
+                } catch {
+                    // ignore
+                }
+                continue;
+            }
+            edge.setAttrs({
+                line: {
+                    opacity: 1,
+                    stroke: theme.accent,
+                    strokeWidth: Math.max(1.6, Number(edge.attr?.('line/strokeWidth')) || 1.6),
+                    targetMarker: {
+                        name: 'classic',
+                        size: 6,
+                        fill: theme.accent,
+                        stroke: theme.accent,
+                    },
+                },
+            });
+            try {
+                edge.prop('labels/0/attrs/label/fill', theme.accent);
+                edge.prop('labels/0/attrs/body/opacity', 1);
+            } catch {
+                // ignore
+            }
+        }
+    };
+
+    const clearHoverState = (): void => {
+        if (!hoveredNodeId) {
+            graphRoot.dispatchEvent(new CustomEvent('md-hide-iri-hover', { bubbles: true }));
+            return;
+        }
+        hoveredNodeId = undefined;
+        reapplyBaseTheme();
+        graphRoot.dispatchEvent(new CustomEvent('md-hide-iri-hover', { bubbles: true }));
+    };
+
+    graphView.on('node:mouseenter', ({ node, e }: { node: any; e?: MouseEvent }) => {
+        const data = node?.getData?.() as NodeData | undefined;
+        const iri = String(data?.value ?? '');
+        applyHoverState(node);
+        if (iri) {
+            const view = graphView.findViewByCell?.(node);
+            const bbox = view?.container?.getBoundingClientRect?.();
+            applyNativeTooltipTitle(view?.container as Element | undefined, iri, e?.target ?? null);
+            if (bbox) {
+                graphRoot.dispatchEvent(new CustomEvent('md-show-iri-hover', {
+                    bubbles: true,
+                    detail: {
+                        iri,
+                        previewEnabled: !!e && (/^Mac/i.test(navigator.platform) ? e.metaKey : e.ctrlKey),
+                        anchorRect: {
+                            left: bbox.left,
+                            right: bbox.right,
+                            top: bbox.top,
+                            bottom: bbox.bottom,
+                            width: bbox.width,
+                            height: bbox.height,
+                        },
+                    },
+                }));
+            }
+        }
+    });
+
+    graphView.on('node:mouseleave', () => {
+        clearHoverState();
+    });
+
+    graphView.on('blank:mousemove', () => {
+        clearHoverState();
+    });
+
+    graphView.on('node:click', ({ node, e }: { node: any; e?: MouseEvent }) => {
+        if (e && e.button !== 0) {
+            return;
+        }
+        const data = node?.getData?.() as NodeData | undefined;
+        const iri = String(data?.value ?? '');
+        if (!isIriValue(iri)) {
+            return;
+        }
+        if (expandOnClick && isExpandModifierPressed(e)) {
+            const source = (blockSource ?? '').trim();
+            if (!source) {
+                return;
+            }
+            graphRoot.dispatchEvent(new CustomEvent('md-graph-expand-request', {
+                bubbles: true,
+                detail: {
+                    blockId,
+                    blockSource: source,
+                    contextIri: iri.trim(),
+                },
+            }));
+            return;
+        }
+        graphRoot.dispatchEvent(new CustomEvent('md-navigate-iri', {
+            bubbles: true,
+            detail: { iri },
+        }));
+    });
 }
 
 // --- X6 / dagre library loaders ---
@@ -482,11 +779,11 @@ async function loadDagreLib(): Promise<any> {
 
 function computeNodeSize(degree: number, minDegree: number, maxDegree: number): number {
     if (minDegree === maxDegree) {
-        return 36;
+        return 28;
     }
-    // Mirrors Cytoscape mapData(degree, 0, 10, 18, 52).
+    // Keep default nodes compact while still preserving degree-based variation.
     const t = Math.max(0, Math.min(1, degree / 10));
-    return Math.round(18 + t * (52 - 18));
+    return Math.round(16 + t * (40 - 16));
 }
 
 /** Base attrs for a node using CSS variables so color auto-updates with VS Code theme. */
@@ -496,11 +793,13 @@ function buildNodeBaseAttrs(literal: boolean): Record<string, unknown> {
             fill: literal ? CSS_LIT_FILL : CSS_NODE_FILL,
             stroke: literal ? CSS_LIT_STROKE : CSS_NODE_STROKE,
             strokeWidth: 1,
+            opacity: 1,
         },
         label: {
             fill: CSS_NODE_TEXT,
-            fontSize: 11,
+            fontSize: NODE_FONT_SIZE,
             fontFamily: CSS_FONT_FAMILY,
+            opacity: 1,
         },
     };
 }
@@ -511,6 +810,7 @@ function buildEdgeBaseAttrs(): Record<string, unknown> {
         line: {
             stroke: CSS_EDGE_STROKE,
             strokeWidth: 1.4,
+            opacity: 1,
             targetMarker: {
                 name: 'classic',
                 size: 6,
@@ -525,7 +825,9 @@ function buildEdgeBaseAttrs(): Record<string, unknown> {
 function resetEdgeLabelColors(edge: any): void {
     try {
         edge.prop('labels/0/attrs/label/fill', CSS_EDGE_TEXT);
+        edge.prop('labels/0/attrs/label/opacity', 1);
         edge.prop('labels/0/attrs/body/fill', CSS_EDGE_BG);
+        edge.prop('labels/0/attrs/body/opacity', 1);
     } catch {
         // ignore - edge may have no labels
     }
@@ -555,12 +857,12 @@ function buildNodeDef(data: NodeData, size: number): Record<string, unknown> {
             label: {
                 text: data.label,
                 fill: CSS_NODE_TEXT,
-                fontSize: 11,
+                fontSize: NODE_FONT_SIZE,
                 fontFamily: CSS_FONT_FAMILY,
                 textAnchor: 'middle',
                 textVerticalAnchor: 'top',
                 refX: '50%',
-                refY: size + 4,             // below the visible shape
+                refY: size + 3,             // below the visible shape
             },
         },
         data: {
@@ -569,6 +871,7 @@ function buildNodeDef(data: NodeData, size: number): Record<string, unknown> {
             degree: data.degree,
             literal: data.literal,
             group: '',
+            hidden: Boolean(data.hidden),
         },
         zIndex: 1,
     };
@@ -617,7 +920,7 @@ function buildEdgeDef(data: EdgeData): Record<string, unknown> {
                     label: {
                         text: data.label,
                         fill: CSS_EDGE_TEXT,
-                        fontSize: 11,
+                        fontSize: EDGE_FONT_SIZE,
                         fontFamily: CSS_FONT_FAMILY,
                         textAnchor: 'middle',
                         textVerticalAnchor: 'middle',
@@ -628,6 +931,7 @@ function buildEdgeDef(data: EdgeData): Record<string, unknown> {
         data: {
             label: data.label,
             value: data.value,
+            hidden: Boolean(data.hidden),
         },
         zIndex: 0,
     };
@@ -759,6 +1063,18 @@ function fitGraphContent(graphView: any, padding: number): void {
     });
 }
 
+function centerGraphContent(graphView: any, padding: number): void {
+    requestAnimationFrame(() => {
+        try {
+            if (typeof graphView.centerContent === 'function') {
+                graphView.centerContent({ padding });
+            }
+        } catch {
+            // ignore
+        }
+    });
+}
+
 // --- Continuous force engine ---
 
 function startContinuousForceEngine(
@@ -941,6 +1257,29 @@ function applyGraphStylesheet(
     }
 }
 
+function applyGraphVisibilityState(graphView: any): void {
+    const visibleNodeIds = new Set<string>();
+    for (const node of graphView.getNodes() as any[]) {
+        const hidden = Boolean((node.getData?.() as { hidden?: boolean } | undefined)?.hidden);
+        if (hidden) {
+            node.hide();
+            continue;
+        }
+        node.show();
+        visibleNodeIds.add(String(node.id));
+    }
+    for (const edge of graphView.getEdges() as any[]) {
+        const hidden = Boolean((edge.getData?.() as { hidden?: boolean } | undefined)?.hidden);
+        const sourceId = String(edge.getSourceCellId?.() ?? '');
+        const targetId = String(edge.getTargetCellId?.() ?? '');
+        if (hidden || !visibleNodeIds.has(sourceId) || !visibleNodeIds.has(targetId)) {
+            edge.hide();
+            continue;
+        }
+        edge.show();
+    }
+}
+
 function buildNodeContext(node: any, graphView: any): NodeContext {
     const nodeId = String(node.id);
     const nodeContext = buildSelectorNodeContext(node, graphView);
@@ -1036,11 +1375,18 @@ function applyElementStyle(
             if (!property) {
                 continue;
             }
+            if ((property === 'display' && value.trim().toLowerCase() === 'none')
+                || (property === 'visibility' && value.trim().toLowerCase() === 'hidden')
+                || (property === 'hidden' && value.trim().toLowerCase() === 'true')) {
+                element.setData({ hidden: true }, { merge: true });
+                continue;
+            }
             const resolved = resolveColorToken(value, theme);
             if (property === 'fill') { bodyAttrs.fill = resolved; continue; }
             if (property === 'stroke') { bodyAttrs.stroke = resolved; continue; }
             if (property === 'stroke-width') { bodyAttrs.strokeWidth = value; continue; }
             if (property === 'color') { labelAttrs.fill = resolved; continue; }
+            if (property === 'font-size') { labelAttrs.fontSize = value; continue; }
             const camel = property.replace(/-([a-z])/g, (_: string, c: string) => c.toUpperCase());
             bodyAttrs[camel] = resolved;
         }
@@ -1062,6 +1408,12 @@ function applyElementStyle(
         if (!property) {
             continue;
         }
+        if ((property === 'display' && value.trim().toLowerCase() === 'none')
+            || (property === 'visibility' && value.trim().toLowerCase() === 'hidden')
+            || (property === 'hidden' && value.trim().toLowerCase() === 'true')) {
+            element.setData({ hidden: true }, { merge: true });
+            continue;
+        }
         const resolved = resolveColorToken(value, theme);
         if (property === 'stroke') {
             lineAttrs.stroke = resolved;
@@ -1070,6 +1422,14 @@ function applyElementStyle(
         }
         if (property === 'stroke-width') { lineAttrs.strokeWidth = value; continue; }
         if (property === 'color') { edgeLabelFill = resolved; continue; }
+        if (property === 'font-size') {
+            try {
+                element.prop('labels/0/attrs/label/fontSize', value);
+            } catch {
+                // ignore
+            }
+            continue;
+        }
         const camel = property.replace(/-([a-z])/g, (_: string, c: string) => c.toUpperCase());
         lineAttrs[camel] = resolved;
     }
@@ -1152,15 +1512,40 @@ function applyNeighborhoodFilter(graphView: any, rawQuery: string): void {
     const query = rawQuery.trim().toLowerCase();
     const allNodes = graphView.getNodes() as any[];
     const allEdges = graphView.getEdges() as any[];
+    const baselineHiddenNodeIds = new Set(
+        allNodes
+            .filter((node) => Boolean((node.getData?.() as { hidden?: boolean } | undefined)?.hidden))
+            .map((node) => String(node.id))
+    );
+    const baselineHiddenEdgeIds = new Set(
+        allEdges
+            .filter((edge) => Boolean((edge.getData?.() as { hidden?: boolean } | undefined)?.hidden))
+            .map((edge) => String(edge.id))
+    );
 
     if (!query) {
-        for (const node of allNodes) node.show();
-        for (const edge of allEdges) edge.show();
+        for (const node of allNodes) {
+            if (baselineHiddenNodeIds.has(String(node.id))) {
+                node.hide();
+            } else {
+                node.show();
+            }
+        }
+        for (const edge of allEdges) {
+            if (baselineHiddenEdgeIds.has(String(edge.id))) {
+                edge.hide();
+            } else {
+                edge.show();
+            }
+        }
         return;
     }
 
     const matchedIds = new Set<string>();
     for (const node of allNodes) {
+        if (baselineHiddenNodeIds.has(String(node.id))) {
+            continue;
+        }
         const nodeData = node.getData() as NodeData;
         const label = String(nodeData?.label ?? '').toLowerCase();
         const value = String(nodeData?.value ?? '').toLowerCase();
@@ -1184,7 +1569,7 @@ function applyNeighborhoodFilter(graphView: any, rawQuery: string): void {
     }
 
     for (const node of allNodes) {
-        if (keepNodeIds.has(String(node.id))) {
+        if (keepNodeIds.has(String(node.id)) && !baselineHiddenNodeIds.has(String(node.id))) {
             node.show();
         } else {
             node.hide();
@@ -1195,7 +1580,11 @@ function applyNeighborhoodFilter(graphView: any, rawQuery: string): void {
     for (const edge of allEdges) {
         const srcId = edge.getSourceCellId();
         const tgtId = edge.getTargetCellId();
-        if (keepNodeIds.has(srcId) && keepNodeIds.has(tgtId)) {
+        if (!baselineHiddenEdgeIds.has(String(edge.id))
+            && keepNodeIds.has(srcId)
+            && keepNodeIds.has(tgtId)
+            && !baselineHiddenNodeIds.has(String(srcId))
+            && !baselineHiddenNodeIds.has(String(tgtId))) {
             edge.show();
         } else {
             edge.hide();
@@ -1449,6 +1838,10 @@ function resolveCanvasMinHeight(options: Record<string, unknown> | undefined): s
     return `${numericCanvasMinHeight(options)}px`;
 }
 
+function resolveExpandOnClickOption(options: Record<string, unknown> | undefined): boolean {
+    return asBoolean(options?.expandOnClick, false);
+}
+
 function numericCanvasMinHeight(options: Record<string, unknown> | undefined): number {
     const canvas = isRecord(options?.canvas) ? options.canvas : undefined;
     const raw = canvas?.minHeight ?? options?.minHeight;
@@ -1596,6 +1989,113 @@ function resolveColorToken(value: string, theme: GraphThemePalette): string {
     return trimmed;
 }
 
+function normalizeGraphExpandPayload(value: unknown): GraphExpandPayload | undefined {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const columns = Array.isArray(value.columns)
+        ? value.columns.filter((entry): entry is string => typeof entry === 'string')
+        : [];
+    const rows = Array.isArray(value.rows)
+        ? value.rows.map((row) => Array.isArray(row)
+            ? row.map((cell) => (typeof cell === 'string' ? cell : String(cell ?? '')))
+            : [])
+        : [];
+    if (columns.length === 0 || rows.length === 0) {
+        return undefined;
+    }
+    return { columns, rows };
+}
+
+function mergeExpandedGraphData(
+    graphView: any,
+    state: GraphMutableState,
+    payload: GraphExpandPayload,
+): void {
+    const subjectIndex = payload.columns.indexOf('subject');
+    const predicateIndex = payload.columns.indexOf('predicate');
+    const objectIndex = payload.columns.indexOf('object');
+    if (subjectIndex < 0 || predicateIndex < 0 || objectIndex < 0) {
+        return;
+    }
+
+    const ensureNodeInState = (rawValue: string): NodeData => {
+        const nodeId = toNodeId(rawValue);
+        const existing = state.nodesById.get(nodeId);
+        if (existing) {
+            return existing;
+        }
+        const node: NodeData = {
+            id: nodeId,
+            label: shortLabel(rawValue),
+            value: rawValue,
+            degree: 0,
+            literal: isLiteralValue(rawValue),
+            group: '',
+        };
+        state.nodesById.set(nodeId, node);
+        graphView.addNode(buildNodeDef(node, computeNodeSize(node.degree, state.minDegree, state.maxDegree)));
+        return node;
+    };
+
+    let hasChanges = false;
+    for (const row of payload.rows) {
+        const subject = row[subjectIndex] ?? '';
+        const predicate = row[predicateIndex] ?? '';
+        const object = row[objectIndex] ?? '';
+        if (!subject || !predicate || !object) {
+            continue;
+        }
+        const sourceNode = ensureNodeInState(subject);
+        const targetNode = ensureNodeInState(object);
+        const edgeKey = `${sourceNode.id}|${toNodeId(predicate)}|${targetNode.id}`;
+        if (state.edgeKeys.has(edgeKey)) {
+            continue;
+        }
+        state.edgeKeys.add(edgeKey);
+        sourceNode.degree += 1;
+        targetNode.degree += 1;
+        state.minDegree = Math.min(state.minDegree, sourceNode.degree, targetNode.degree);
+        state.maxDegree = Math.max(state.maxDegree, sourceNode.degree, targetNode.degree);
+        graphView.addEdge(buildEdgeDef({
+            id: `${edgeKey}|${state.edgeSequence}`,
+            source: sourceNode.id,
+            target: targetNode.id,
+            value: predicate,
+            label: shortLabel(predicate),
+        }));
+        state.edgeSequence += 1;
+        hasChanges = true;
+    }
+
+    if (!hasChanges) {
+        return;
+    }
+
+    for (const node of graphView.getNodes() as any[]) {
+        const data = node.getData?.() as NodeData | undefined;
+        const degree = Number(data?.degree ?? 0);
+        const size = computeNodeSize(degree, state.minDegree, state.maxDegree);
+        node.resize(size, size + NODE_LABEL_HEIGHT);
+        if (node.shape === 'graph-node-literal') {
+            node.attr({
+                body: {
+                    width: size,
+                    height: size,
+                },
+            });
+            continue;
+        }
+        node.attr({
+            body: {
+                r: size / 2,
+                cx: size / 2,
+                cy: size / 2,
+            },
+        });
+    }
+}
+
 function ensureNode(nodes: Map<string, NodeData>, rawValue: string): void {
     const id = toNodeId(rawValue);
     if (nodes.has(id)) {