@ankhorage/zora 20.1.6 → 20.2.1

package/dist/features/web-component-artifact/application/use-cases/materializeWebComponentArtifactAsync.js.map

@@ -1 +1 @@
-{"version":3,"file":"materializeWebComponentArtifactAsync.js","sourceRoot":"","sources":["../../../../../src/features/web-component-artifact/application/use-cases/materializeWebComponentArtifactAsync.ts"],"names":[],"mappings":"AAgBA,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,oCAAoC,CACxD,KAA2C,EAC3C,UAA8C;IAE9C,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACrD,MAAM,eAAe,GAAG,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,UAAU,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC/F,MAAM,UAAU,CAAC,oBAAoB,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAE7D,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,GAAG,CACpC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;QACpC,MAAM,UAAU,GAAG,UAAU,CAAC,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;QAClE,MAAM,UAAU,GAAG,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;QACxE,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;QAC9D,MAAM,UAAU,CAAC,kBAAkB,CACjC,UAAU,EACV,qBAAqB,CAAC,KAAK,CAAC,cAAc,EAAE,MAAM,CAAC,CACpD,CAAC;QACF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC,CACH,CAAC;IAEF,MAAM,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,eAAe,EAAE,oBAAoB,CAAC,CAAC;IACtF,MAAM,UAAU,CAAC,kBAAkB,CACjC,YAAY,EACZ,GAAG,IAAI,CAAC,SAAS,CACf;QACE,SAAS,EAAE,IAAI;QACf,KAAK,EAAE,iBAAiB;QACxB,OAAO,EAAE,KAAK,CAAC,cAAc;QAC7B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,QAAQ,EAAE,KAAK;KAChB,EACD,IAAI,EACJ,CAAC,CACF,IAAI,CACN,CAAC;IAEF,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,YAAY,EAAE,CAAC,GAAG,YAAY,EAAE,YAAY,CAAC;QAC7C,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,QAAQ,EAAE,KAAK;KAChB,CAAC;AACJ,CAAC;AAOD,8EAA8E;AAC9E,SAAS,kBAAkB,CAAC,SAAiB;IAC3C,IAAI,SAAS,KAAK,WAAW,EAAE,CAAC;QAC9B,OAAO;YACL,SAAS,EAAE,WAAW;YACtB,KAAK,EAAE,CAAC,aAAa,EAAE,eAAe,CAAC;SACxC,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,mCAAmC,SAAS,EAAE,CAAC,CAAC;AAClE,CAAC;AAED,qFAAqF;AACrF,SAAS,qBAAqB,CAAC,cAAsB,EAAE,MAAc;IACnE,OAAO,oCAAoC,cAAc,4BAA4B,MAAM,EAAE,CAAC;AAChG,CAAC","sourcesContent":["import type { WebComponentArtifactFileSystemPort } from '../ports/outbound/WebComponentArtifactFileSystemPort';\n\nexport interface MaterializeWebComponentArtifactInput {\n  readonly component: string;\n  readonly outputDirectory: string;\n  readonly packageRoot: string;\n  readonly packageVersion: string;\n}\n\nexport interface MaterializeWebComponentArtifactResult {\n  readonly component: string;\n  readonly createdFiles: readonly string[];\n  readonly outputDirectory: string;\n  readonly platform: 'web';\n}\n\n/*** Materialize one replaceable web-only component artifact from the published ZORA build. */\nexport async function materializeWebComponentArtifactAsync(\n  input: MaterializeWebComponentArtifactInput,\n  fileSystem: WebComponentArtifactFileSystemPort,\n): Promise<MaterializeWebComponentArtifactResult> {\n  const artifact = resolveWebArtifact(input.component);\n  const sourceDirectory = fileSystem.joinPath(input.packageRoot, 'web-dist', artifact.directory);\n  await fileSystem.ensureDirectoryAsync(input.outputDirectory);\n\n  const createdFiles = await Promise.all(\n    artifact.files.map(async (fileName) => {\n      const sourcePath = fileSystem.joinPath(sourceDirectory, fileName);\n      const targetPath = fileSystem.joinPath(input.outputDirectory, fileName);\n      const source = await fileSystem.readTextFileAsync(sourcePath);\n      await fileSystem.writeTextFileAsync(\n        targetPath,\n        createGeneratedSource(input.packageVersion, source),\n      );\n      return targetPath;\n    }),\n  );\n\n  const metadataPath = fileSystem.joinPath(input.outputDirectory, 'zora-artifact.json');\n  await fileSystem.writeTextFileAsync(\n    metadataPath,\n    `${JSON.stringify(\n      {\n        generated: true,\n        owner: '@ankhorage/zora',\n        version: input.packageVersion,\n        component: input.component,\n        platform: 'web',\n      },\n      null,\n      2,\n    )}\\n`,\n  );\n\n  return {\n    component: input.component,\n    createdFiles: [...createdFiles, metadataPath],\n    outputDirectory: input.outputDirectory,\n    platform: 'web',\n  };\n}\n\ninterface WebArtifactDefinition {\n  readonly directory: string;\n  readonly files: readonly string[];\n}\n\n/*** Resolve the canonical packaged web artifact for a requested component. */\nfunction resolveWebArtifact(component: string): WebArtifactDefinition {\n  if (component === 'tree-view') {\n    return {\n      directory: 'tree-view',\n      files: ['TreeView.js', 'TreeView.d.ts'],\n    };\n  }\n\n  throw new Error(`Unsupported ZORA web component: ${component}`);\n}\n\n/*** Add a generated-file marker without changing the compiled artifact semantics. */\nfunction createGeneratedSource(packageVersion: string, source: string): string {\n  return `// Generated by @ankhorage/zora v${packageVersion}. Do not edit manually.\\n${source}`;\n}\n"]}
+{"version":3,"file":"materializeWebComponentArtifactAsync.js","sourceRoot":"","sources":["../../../../../src/features/web-component-artifact/application/use-cases/materializeWebComponentArtifactAsync.ts"],"names":[],"mappings":"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","sourcesContent":["import type { WebComponentArtifactFileSystemPort } from '../ports/outbound/WebComponentArtifactFileSystemPort';\n\nexport interface MaterializeWebComponentArtifactInput {\n  readonly component: string;\n  readonly outputDirectory: string;\n  readonly packageRoot: string;\n  readonly packageVersion: string;\n}\n\nexport interface MaterializeWebComponentArtifactResult {\n  readonly component: string;\n  readonly createdFiles: readonly string[];\n  readonly outputDirectory: string;\n  readonly platform: 'web';\n}\n\n/*** Materialize one replaceable web-only component artifact from the published ZORA build. */\nexport async function materializeWebComponentArtifactAsync(\n  input: MaterializeWebComponentArtifactInput,\n  fileSystem: WebComponentArtifactFileSystemPort,\n): Promise<MaterializeWebComponentArtifactResult> {\n  const sourceDirectory = fileSystem.joinPath(input.packageRoot, 'web-dist', input.component);\n  const artifact = await readWebArtifactDefinitionAsync(\n    sourceDirectory,\n    input.component,\n    fileSystem,\n  );\n  await fileSystem.ensureDirectoryAsync(input.outputDirectory);\n\n  const createdFiles = await Promise.all(\n    artifact.files.map(async (fileName) => {\n      const sourcePath = fileSystem.joinPath(sourceDirectory, fileName);\n      const targetPath = fileSystem.joinPath(input.outputDirectory, fileName);\n      const source = await fileSystem.readTextFileAsync(sourcePath);\n      await fileSystem.writeTextFileAsync(\n        targetPath,\n        createGeneratedSource(input.packageVersion, source),\n      );\n      return targetPath;\n    }),\n  );\n\n  const metadataPath = fileSystem.joinPath(input.outputDirectory, 'zora-artifact.json');\n  await fileSystem.writeTextFileAsync(\n    metadataPath,\n    `${JSON.stringify(\n      {\n        generated: true,\n        owner: '@ankhorage/zora',\n        version: input.packageVersion,\n        component: input.component,\n        platform: 'web',\n      },\n      null,\n      2,\n    )}\\n`,\n  );\n\n  return {\n    component: input.component,\n    createdFiles: [...createdFiles, metadataPath],\n    outputDirectory: input.outputDirectory,\n    platform: 'web',\n  };\n}\n\ninterface WebArtifactDefinition {\n  readonly component: string;\n  readonly files: readonly string[];\n}\n\n/*** Read one packaged artifact manifest so new web components require no CLI branching. */\nasync function readWebArtifactDefinitionAsync(\n  sourceDirectory: string,\n  component: string,\n  fileSystem: WebComponentArtifactFileSystemPort,\n): Promise<WebArtifactDefinition> {\n  const manifestPath = fileSystem.joinPath(sourceDirectory, 'artifact.json');\n  const manifestSource = await readWebArtifactManifestSourceAsync(\n    manifestPath,\n    component,\n    fileSystem,\n  );\n  const parsed = JSON.parse(manifestSource) as {\n    readonly component?: unknown;\n    readonly files?: unknown;\n  };\n  if (\n    parsed.component !== component ||\n    !Array.isArray(parsed.files) ||\n    parsed.files.length === 0 ||\n    !parsed.files.every((fileName) => typeof fileName === 'string' && fileName.length > 0)\n  ) {\n    throw new Error(`Invalid ZORA web artifact manifest: ${component}`);\n  }\n\n  return {\n    component,\n    files: parsed.files,\n  };\n}\n\n/*** Read an artifact manifest and translate missing packages into the CLI-facing error. */\nasync function readWebArtifactManifestSourceAsync(\n  manifestPath: string,\n  component: string,\n  fileSystem: WebComponentArtifactFileSystemPort,\n): Promise<string> {\n  try {\n    return await fileSystem.readTextFileAsync(manifestPath);\n  } catch {\n    throw new Error(`Unsupported ZORA web component: ${component}`);\n  }\n}\n\n/*** Add a generated-file marker without changing the compiled artifact semantics. */\nfunction createGeneratedSource(packageVersion: string, source: string): string {\n  return `// Generated by @ankhorage/zora v${packageVersion}. Do not edit manually.\\n${source}`;\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "20.1.6",
+  "version": "20.2.1",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {
@@ -41,8 +41,8 @@
   },
   "dependencies": {
     "@ankhorage/color-theory": "^0.3.1",
-    "@ankhorage/contracts": "^22.0.4",
-    "@ankhorage/surface": "^9.0.5",
+    "@ankhorage/contracts": "^22.1.0",
+    "@ankhorage/surface": "^9.0.7",
     "@ankhorage/utility": "^1.4.0",
     "expo-document-picker": "~57.0.1",
     "expo-image-picker": "~57.0.16"
@@ -142,7 +142,9 @@
     "react-native-svg": "15.15.4",
     "react-native-web": "~0.21.0",
     "react-native-worklets": "0.10.1",
-    "typescript": "~6.0.3"
+    "typescript": "~6.0.3",
+    "cytoscape": "^3.34.3",
+    "cytoscape-elk": "^2.3.0"
   },
   "packageManager": "bun@1.4.2",
   "ankh": {

package/src/features/graph-view/adapters/inbound/web-artifact/GraphNodeOverlay.tsx

@@ -0,0 +1,142 @@
+'use client';
+
+import React from 'react';
+
+import type {
+  GraphViewElementEventType,
+  GraphViewNode,
+  GraphViewNodeRenderContext,
+  GraphViewRenderedNode,
+  GraphViewSize,
+} from './GraphView';
+
+interface GraphNodeOverlayProps {
+  readonly nodes: readonly GraphViewNode[];
+  readonly renderedNodes: readonly GraphViewRenderedNode[];
+  readonly renderNode: (context: GraphViewNodeRenderContext) => React.ReactNode;
+  readonly onNodeEvent: (id: string, type: GraphViewElementEventType) => void;
+  readonly onNodeSize: (id: string, size: GraphViewSize) => void;
+}
+
+/*** Render optional React node content above Cytoscape at its authoritative rendered positions. */
+export function GraphNodeOverlay(props: GraphNodeOverlayProps) {
+  const nodesById = React.useMemo(
+    () => new Map(props.nodes.map((node) => [node.id, node] as const)),
+    [props.nodes],
+  );
+
+  return (
+    <div
+      aria-hidden
+      style={{
+        inset: 0,
+        overflow: 'hidden',
+        pointerEvents: 'none',
+        position: 'absolute',
+      }}
+    >
+      {props.renderedNodes.map((renderedNode) => {
+        const node = nodesById.get(renderedNode.id);
+        if (!node) return null;
+        return (
+          <MeasuredGraphNode
+            key={node.id}
+            node={node}
+            renderedNode={renderedNode}
+            renderNode={props.renderNode}
+            onNodeEvent={props.onNodeEvent}
+            onNodeSize={props.onNodeSize}
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+interface MeasuredGraphNodeProps {
+  readonly node: GraphViewNode;
+  readonly renderedNode: GraphViewRenderedNode;
+  readonly renderNode: GraphNodeOverlayProps['renderNode'];
+  readonly onNodeEvent: GraphNodeOverlayProps['onNodeEvent'];
+  readonly onNodeSize: GraphNodeOverlayProps['onNodeSize'];
+}
+
+/*** Measure one rich node at model scale and translate its DOM interactions into graph events. */
+function MeasuredGraphNode(props: MeasuredGraphNodeProps) {
+  const elementRef = React.useRef<HTMLDivElement | null>(null);
+  const { node, onNodeSize, renderedNode } = props;
+
+  React.useLayoutEffect(() => {
+    const element = elementRef.current;
+    if (element === null) return;
+    reportElementSize(element, node.id, onNodeSize);
+
+    const Observer = readResizeObserverConstructor();
+    if (Observer === null) return;
+    const observer = new Observer(() => reportElementSize(element, node.id, onNodeSize));
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [node.id, onNodeSize]);
+
+  return (
+    <div
+      ref={(element) => {
+        elementRef.current = element;
+      }}
+      style={{
+        left: renderedNode.position.x,
+        pointerEvents: 'auto',
+        position: 'absolute',
+        top: renderedNode.position.y,
+        transform: `translate(-50%, -50%) scale(${renderedNode.zoom})`,
+        transformOrigin: 'center',
+      }}
+      onClick={() => props.onNodeEvent(node.id, 'press')}
+      onDoubleClick={() => props.onNodeEvent(node.id, 'double-press')}
+      onMouseEnter={() => props.onNodeEvent(node.id, 'pointer-enter')}
+      onMouseLeave={() => props.onNodeEvent(node.id, 'pointer-leave')}
+    >
+      {props.renderNode({
+        hovered: renderedNode.hovered,
+        node,
+        selected: renderedNode.selected,
+        zoom: renderedNode.zoom,
+      })}
+    </div>
+  );
+}
+
+/*** Report unscaled DOM dimensions only when a measurable node has positive size. */
+function reportElementSize(
+  element: unknown,
+  nodeId: string,
+  onNodeSize: (id: string, size: GraphViewSize) => void,
+) {
+  const measured = element as {
+    readonly offsetHeight?: unknown;
+    readonly offsetWidth?: unknown;
+  };
+  if (typeof measured.offsetWidth !== 'number' || typeof measured.offsetHeight !== 'number') return;
+  if (measured.offsetWidth <= 0 || measured.offsetHeight <= 0) return;
+  onNodeSize(nodeId, {
+    width: measured.offsetWidth,
+    height: measured.offsetHeight,
+  });
+}
+
+/*** Read ResizeObserver without requiring the DOM lib in the package TypeScript target. */
+function readResizeObserverConstructor(): ResizeObserverConstructorLike | null {
+  const observer = (
+    globalThis as unknown as {
+      ResizeObserver?: ResizeObserverConstructorLike;
+    }
+  ).ResizeObserver;
+  return observer ?? null;
+}
+
+interface ResizeObserverLike {
+  disconnect(): void;
+  observe(target: unknown): void;
+}
+
+type ResizeObserverConstructorLike = new (callback: () => void) => ResizeObserverLike;

package/src/features/graph-view/adapters/inbound/web-artifact/GraphView.tsx

@@ -0,0 +1,293 @@
+'use client';
+
+import type { CytoscapeOptions } from 'cytoscape';
+import React from 'react';
+
+import { createGraphRuntime, type GraphRuntime } from './createGraphRuntime';
+import { GraphNodeOverlay } from './GraphNodeOverlay';
+
+export type GraphViewLayoutName = 'breadthfirst' | 'circle' | 'concentric' | 'elk' | 'grid';
+export type GraphViewElementEventType =
+  'press' | 'double-press' | 'select' | 'unselect' | 'pointer-enter' | 'pointer-leave';
+
+export interface GraphViewNode {
+  readonly id: string;
+  readonly label?: string;
+  readonly parentId?: string;
+  readonly classes?: string;
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+
+export interface GraphViewEdge {
+  readonly id?: string;
+  readonly source: string;
+  readonly target: string;
+  readonly classes?: string;
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+
+export interface GraphViewStyleRule {
+  readonly selector: string;
+  readonly style: Readonly<Record<string, unknown>>;
+}
+
+export interface GraphViewPoint {
+  readonly x: number;
+  readonly y: number;
+}
+
+export interface GraphViewSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface GraphViewNodeRenderContext {
+  readonly hovered: boolean;
+  readonly node: GraphViewNode;
+  readonly selected: boolean;
+  readonly zoom: number;
+}
+
+export interface GraphViewRenderedNode {
+  readonly hovered: boolean;
+  readonly id: string;
+  readonly position: GraphViewPoint;
+  readonly selected: boolean;
+  readonly zoom: number;
+}
+
+export interface GraphViewViewport {
+  readonly zoom: number;
+  readonly pan: GraphViewPoint;
+}
+
+export interface GraphViewFitOptions {
+  readonly nodeIds?: readonly string[];
+  readonly padding?: number;
+}
+
+export interface GraphViewElementEvent {
+  readonly id: string;
+  readonly type: GraphViewElementEventType;
+}
+
+export interface GraphViewController {
+  fit(options?: GraphViewFitOptions): void;
+  getViewport(): GraphViewViewport;
+  setPan(pan: GraphViewPoint): void;
+  setZoom(zoom: number): void;
+  zoomBy(factor: number): void;
+}
+
+export interface GraphViewProps {
+  readonly nodes: readonly GraphViewNode[];
+  readonly edges: readonly GraphViewEdge[];
+  readonly layout?: GraphViewLayoutName;
+  readonly layoutOptions?: Readonly<Record<string, unknown>>;
+  readonly spacingFactor?: number;
+  readonly styleRules?: readonly GraphViewStyleRule[];
+  readonly selectedNodeIds?: readonly string[];
+  readonly renderNode?: (context: GraphViewNodeRenderContext) => React.ReactNode;
+  readonly getNodeSize?: (node: GraphViewNode) => GraphViewSize | undefined;
+  readonly fitPadding?: number;
+  readonly minZoom?: number;
+  readonly maxZoom?: number;
+  readonly className?: string;
+  readonly style?: React.CSSProperties;
+  readonly ariaLabel?: string;
+  readonly onReady?: (controller: GraphViewController) => void;
+  readonly onLayoutComplete?: (controller: GraphViewController) => void;
+  readonly onNodeEvent?: (event: GraphViewElementEvent) => void;
+  readonly onEdgeEvent?: (event: GraphViewElementEvent) => void;
+  readonly onViewportChange?: (viewport: GraphViewViewport) => void;
+}
+
+export type GraphViewCallbacks = Pick<
+  GraphViewProps,
+  'onEdgeEvent' | 'onLayoutComplete' | 'onNodeEvent' | 'onReady' | 'onViewportChange'
+>;
+
+type GraphContainer = NonNullable<CytoscapeOptions['container']>;
+
+/*** Render a browser graph while one runtime owns Cytoscape layout, viewport, and disposal. */
+export function GraphView(props: GraphViewProps) {
+  const { containerRef, renderedNodes, runtimeRef } = useGraphViewRuntime(props);
+
+  return (
+    <div
+      aria-label={props.ariaLabel ?? 'Graph'}
+      className={props.className}
+      role="application"
+      style={{
+        height: '100%',
+        minHeight: 0,
+        minWidth: 0,
+        position: 'relative',
+        width: '100%',
+        ...props.style,
+      }}
+    >
+      <div ref={containerRef} style={{ height: '100%', width: '100%' }} />
+      {props.renderNode ? (
+        <GraphNodeOverlay
+          nodes={props.nodes}
+          renderedNodes={renderedNodes}
+          renderNode={props.renderNode}
+          onNodeEvent={(id, type) => runtimeRef.current?.handleOverlayNodeEvent(id, type)}
+          onNodeSize={(id, size) => runtimeRef.current?.setNodeSize(id, size)}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+/*** Compose React synchronization around the single imperative graph runtime. */
+function useGraphViewRuntime(props: GraphViewProps) {
+  const containerRef = React.useRef<GraphContainer | null>(null);
+  const runtimeRef = React.useRef<GraphRuntime | null>(null);
+  const callbacksRef = useGraphCallbacksRef(props);
+  const [renderedNodes, setRenderedNodes] = React.useState<readonly GraphViewRenderedNode[]>([]);
+
+  useRuntimeLifecycle(containerRef, runtimeRef, callbacksRef);
+  useRuntimeGraphUpdate(runtimeRef, props);
+  useRuntimeSelection(runtimeRef, props.selectedNodeIds);
+  useRenderedNodeSubscription(runtimeRef, props.renderNode, setRenderedNodes);
+  useKnownNodeSizes(runtimeRef, props.nodes, props.getNodeSize);
+
+  return { containerRef, renderedNodes, runtimeRef };
+}
+
+/*** Keep the callback ref current without mutating refs during render. */
+function useGraphCallbacksRef(props: GraphViewProps) {
+  const callbacksRef = React.useRef<GraphViewCallbacks>(readCallbacks(props));
+  const { onEdgeEvent, onLayoutComplete, onNodeEvent, onReady, onViewportChange } = props;
+
+  React.useEffect(() => {
+    callbacksRef.current = {
+      onEdgeEvent,
+      onLayoutComplete,
+      onNodeEvent,
+      onReady,
+      onViewportChange,
+    };
+  }, [onEdgeEvent, onLayoutComplete, onNodeEvent, onReady, onViewportChange]);
+
+  return callbacksRef;
+}
+
+/*** Create and dispose the runtime only with the underlying browser container lifetime. */
+function useRuntimeLifecycle(
+  containerRef: { current: GraphContainer | null },
+  runtimeRef: { current: GraphRuntime | null },
+  callbacksRef: { current: GraphViewCallbacks },
+) {
+  React.useEffect(() => {
+    const container = containerRef.current;
+    if (container === null) return;
+    const runtime = createGraphRuntime(container, callbacksRef);
+    runtimeRef.current = runtime;
+    return () => {
+      runtime.destroy();
+      runtimeRef.current = null;
+    };
+  }, [callbacksRef, containerRef, runtimeRef]);
+}
+
+/*** Synchronize graph data and layout policy without exposing Cytoscape to React. */
+function useRuntimeGraphUpdate(
+  runtimeRef: { current: GraphRuntime | null },
+  props: GraphViewProps,
+) {
+  const {
+    edges,
+    fitPadding,
+    layout,
+    layoutOptions,
+    maxZoom,
+    minZoom,
+    nodes,
+    renderNode,
+    spacingFactor,
+    styleRules,
+  } = props;
+
+  React.useEffect(() => {
+    runtimeRef.current?.update({
+      edges,
+      fitPadding,
+      layout,
+      layoutOptions,
+      maxZoom,
+      minZoom,
+      nodes,
+      richNodeRendering: renderNode !== undefined,
+      spacingFactor,
+      styleRules,
+    });
+  }, [
+    edges,
+    fitPadding,
+    layout,
+    layoutOptions,
+    maxZoom,
+    minZoom,
+    nodes,
+    renderNode,
+    runtimeRef,
+    spacingFactor,
+    styleRules,
+  ]);
+}
+
+/*** Synchronize optional controlled selection independently from graph layout. */
+function useRuntimeSelection(
+  runtimeRef: { current: GraphRuntime | null },
+  selectedNodeIds: readonly string[] | undefined,
+) {
+  React.useEffect(() => {
+    runtimeRef.current?.setSelectedNodeIds(selectedNodeIds);
+  }, [runtimeRef, selectedNodeIds]);
+}
+
+/*** Subscribe the optional rich-node overlay to rendered runtime positions. */
+function useRenderedNodeSubscription(
+  runtimeRef: { current: GraphRuntime | null },
+  renderNode: GraphViewProps['renderNode'],
+  setRenderedNodes: (nodes: readonly GraphViewRenderedNode[]) => void,
+) {
+  React.useEffect(() => {
+    const runtime = runtimeRef.current;
+    if (runtime === null || renderNode === undefined) {
+      setRenderedNodes([]);
+      return;
+    }
+    return runtime.subscribeRenderedNodes(setRenderedNodes);
+  }, [renderNode, runtimeRef, setRenderedNodes]);
+}
+
+/*** Seed known rich-node dimensions without requiring DOM measurement. */
+function useKnownNodeSizes(
+  runtimeRef: { current: GraphRuntime | null },
+  nodes: readonly GraphViewNode[],
+  getNodeSize: GraphViewProps['getNodeSize'],
+) {
+  React.useEffect(() => {
+    const runtime = runtimeRef.current;
+    if (runtime === null || getNodeSize === undefined) return;
+    for (const node of nodes) {
+      const size = getNodeSize(node);
+      if (size) runtime.setNodeSize(node.id, size);
+    }
+  }, [getNodeSize, nodes, runtimeRef]);
+}
+
+/*** Read callback props for the initial runtime callback-ref value. */
+function readCallbacks(props: GraphViewProps): GraphViewCallbacks {
+  return {
+    onEdgeEvent: props.onEdgeEvent,
+    onLayoutComplete: props.onLayoutComplete,
+    onNodeEvent: props.onNodeEvent,
+    onReady: props.onReady,
+    onViewportChange: props.onViewportChange,
+  };
+}

package/src/features/graph-view/adapters/inbound/web-artifact/bindGraphEvents.ts

@@ -0,0 +1,102 @@
+import type { Core, EventObject } from 'cytoscape';
+
+import type {
+  GraphViewCallbacks,
+  GraphViewController,
+  GraphViewElementEventType,
+} from './GraphView';
+
+/*** Bind stable Cytoscape events that always read the latest React callbacks. */
+export function bindGraphEvents(
+  cy: Core,
+  callbacksRef: { current: GraphViewCallbacks },
+  controller: GraphViewController,
+  onRuntimeChange: () => void,
+) {
+  const nodeHandlers = bindElementEvents(cy, 'node', callbacksRef, onRuntimeChange);
+  const edgeHandlers = bindElementEvents(cy, 'edge', callbacksRef, onRuntimeChange);
+  const viewportHandler = () => {
+    callbacksRef.current.onViewportChange?.(controller.getViewport());
+    onRuntimeChange();
+  };
+  cy.on('zoom pan', viewportHandler);
+
+  return () => {
+    unbindElementEvents(cy, 'node', nodeHandlers);
+    unbindElementEvents(cy, 'edge', edgeHandlers);
+    cy.off('zoom pan', viewportHandler);
+  };
+}
+
+type ElementSelector = 'edge' | 'node';
+
+interface BoundElementHandler {
+  readonly cytoscapeEvent: string;
+  readonly handler: (event: EventObject) => void;
+}
+
+/*** Bind one selector's translated event set without resubscribing on callback changes. */
+function bindElementEvents(
+  cy: Core,
+  selector: ElementSelector,
+  callbacksRef: { current: GraphViewCallbacks },
+  onRuntimeChange: () => void,
+): readonly BoundElementHandler[] {
+  return EVENT_TYPES.map(([cytoscapeEvent, type]) => {
+    const handler = (event: EventObject) => {
+      const target: unknown = event.target;
+      if (!isGraphEventTarget(target)) return;
+      emitElementEvent(callbacksRef.current, selector, {
+        id: target.id(),
+        type,
+      });
+      onRuntimeChange();
+    };
+    cy.on(cytoscapeEvent, selector, handler);
+    return { cytoscapeEvent, handler };
+  });
+}
+
+/*** Return whether a Cytoscape event target exposes the element identifier contract. */
+function isGraphEventTarget(value: unknown): value is GraphEventTarget {
+  return (
+    typeof value === 'object' && value !== null && 'id' in value && typeof value.id === 'function'
+  );
+}
+
+interface GraphEventTarget {
+  id(): string;
+}
+
+/*** Emit one translated element event without dynamic callback-property access. */
+function emitElementEvent(
+  callbacks: GraphViewCallbacks,
+  selector: ElementSelector,
+  event: { readonly id: string; readonly type: GraphViewElementEventType },
+) {
+  if (selector === 'node') {
+    callbacks.onNodeEvent?.(event);
+    return;
+  }
+  callbacks.onEdgeEvent?.(event);
+}
+
+/*** Remove one selector's event handlers using the exact bound callback identities. */
+function unbindElementEvents(
+  cy: Core,
+  selector: ElementSelector,
+  handlers: readonly BoundElementHandler[],
+) {
+  for (const { cytoscapeEvent, handler } of handlers) {
+    cy.off(cytoscapeEvent, selector, handler);
+  }
+}
+
+const EVENT_TYPES = [
+  ['tap', 'press'],
+  ['dbltap', 'double-press'],
+  ['select', 'select'],
+  ['unselect', 'unselect'],
+  ['mouseover', 'pointer-enter'],
+  ['mouseout', 'pointer-leave'],
+] as const satisfies readonly (readonly [string, GraphViewElementEventType])[];

package/src/features/graph-view/adapters/inbound/web-artifact/createGraphController.ts

@@ -0,0 +1,38 @@
+import type { Core } from 'cytoscape';
+
+import { fitGraphViewport } from './fitGraphViewport';
+import type { GraphViewController } from './GraphView';
+
+/*** Create the public viewport controller while keeping the Cytoscape core private. */
+export function createGraphController(
+  cy: Core,
+  fitPaddingRef: { current: number },
+): GraphViewController {
+  return {
+    fit(options) {
+      fitGraphViewport(cy, {
+        nodeIds: options?.nodeIds,
+        padding: options?.padding ?? fitPaddingRef.current,
+      });
+    },
+    getViewport() {
+      return { pan: cy.pan(), zoom: cy.zoom() };
+    },
+    setPan(pan) {
+      cy.pan(pan);
+    },
+    setZoom(zoom) {
+      cy.zoom({
+        level: zoom,
+        renderedPosition: { x: cy.width() / 2, y: cy.height() / 2 },
+      });
+    },
+    zoomBy(factor) {
+      const zoom = cy.zoom() * factor;
+      cy.zoom({
+        level: zoom,
+        renderedPosition: { x: cy.width() / 2, y: cy.height() / 2 },
+      });
+    },
+  };
+}