@pauloricca/spagbol 0.0.0-stage → 0.1.0

package/src/react/context.tsx

@@ -0,0 +1,146 @@
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useSyncExternalStore,
+  type ComponentType,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+import {
+  type Diagnostic,
+  type GraphEditor,
+  type EditorSnapshot,
+  type GraphNode,
+  type NodeData,
+  type ObservationStore,
+  type Point,
+} from "../core/index.js";
+
+export interface SpagbolCanvasFeatures {
+  compact?: boolean;
+  selectable?: boolean;
+  draggable?: boolean;
+  areas?: boolean;
+  linkProperties?: boolean;
+  nestedGraphs?: boolean;
+  panels?: boolean;
+}
+export interface SpagbolNodeViewProps<D extends NodeData = NodeData> {
+  node: GraphNode<D>;
+  selected: boolean;
+  projected: boolean;
+  path: readonly string[];
+  resetOverride?(): void;
+  readOnly: boolean;
+  setValue(portId: string, value: number): void;
+  patchData(data: Partial<D>, structural?: boolean): void;
+  beginGesture(label?: string): void;
+  endGesture(cancel?: boolean): void;
+}
+export interface SpagbolNodeView {
+  body?: ComponentType<SpagbolNodeViewProps>;
+  /** Complete custom geometry; use SpagbolNodePort and the supplied command props. */
+  render?: ComponentType<SpagbolNodeViewProps>;
+  projected?: ComponentType<SpagbolNodeViewProps>;
+  minWidth?: number;
+  minHeight?: number;
+  resizable?: boolean;
+  autoWidth?: boolean;
+  compact?: boolean;
+  selectable?: boolean;
+  draggable?: boolean;
+}
+/** Keep application body props typed while the renderer registry erases payloads. */
+export function defineNodeView<D extends NodeData>(view: {
+  body?: ComponentType<SpagbolNodeViewProps<D>>;
+  render?: ComponentType<SpagbolNodeViewProps<D>>;
+  projected?: ComponentType<SpagbolNodeViewProps<D>>;
+  minWidth?: number;
+  minHeight?: number;
+  resizable?: boolean;
+  autoWidth?: boolean;
+  compact?: boolean;
+  selectable?: boolean;
+  draggable?: boolean;
+}): SpagbolNodeView {
+  const wrap = (
+    component?: ComponentType<SpagbolNodeViewProps<D>>,
+  ): ComponentType<SpagbolNodeViewProps> | undefined =>
+    component
+      ? (props) => createElement(component, props as SpagbolNodeViewProps<D>)
+      : undefined;
+  return {
+    ...view,
+    body: wrap(view.body),
+    render: wrap(view.render),
+    projected: wrap(view.projected),
+  };
+}
+export interface GraphContextValue {
+  editor: GraphEditor;
+  views: Readonly<Record<string, SpagbolNodeView>>;
+  features: SpagbolCanvasFeatures;
+  diagnostics: readonly Diagnostic[];
+  nodeKinds?: readonly string[];
+  changeNodeKind?(id: string, kind: string): void | Promise<void>;
+  zoom: number;
+  connecting: boolean;
+  linkOverlay: HTMLElement | null;
+  projection?: { groupId: string; path: readonly string[] };
+  instanceId: string;
+  areaDuplicate?(id: string, phase: "start" | "move" | "end" | "cancel", offset: Point, external?: boolean): void;
+  registerTarget(key: string, element: HTMLElement | null): void;
+}
+export const GraphContext = createContext<GraphContextValue | null>(null);
+export function useSpagbol(): GraphContextValue {
+  const context = useContext(GraphContext);
+  if (!context)
+    throw new Error("Spagbol components must be inside SpagbolCanvas.");
+  return context;
+}
+export function useGraphEditor() {
+  return useSpagbol().editor;
+}
+export function useEditorSnapshot(editor: GraphEditor) {
+  return useSyncExternalStore(
+    editor.subscribe,
+    editor.getSnapshot,
+    editor.getSnapshot,
+  );
+}
+/** Subscribe to a stable slice, so value changes do not redraw selection-only UI. */
+export function useEditorSelector<T>(editor: GraphEditor, select: (snapshot: EditorSnapshot) => T): T {
+  return useSyncExternalStore(editor.subscribe, () => select(editor.getSnapshot()), () => select(editor.getSnapshot()));
+}
+export function useObservation<T>(
+  store: ObservationStore<T>,
+  path: readonly string[],
+  nodeId: string,
+  instance = "",
+): T | undefined {
+  const key = store.key(path, nodeId, instance);
+  return useSyncExternalStore(
+    (listener) => store.subscribe(key, listener),
+    () => store.get(key),
+    () => undefined,
+  );
+}
+/** Register a scoped DOM target for app-owned GPU/canvas rendering. */
+export function useRenderTarget(nodeId: string, slot = "preview") {
+  const { editor, registerTarget, projection } = useSpagbol();
+  const path = [...editor.getSnapshot().path, ...(projection ? [projection.groupId, ...projection.path.slice(0, -1)] : [])];
+  const key = JSON.stringify([path, nodeId, slot]);
+  return useCallback(
+    (element: HTMLElement | null) => registerTarget(key, element),
+    [key, registerTarget],
+  );
+}
+export type SpagbolTheme = CSSProperties & {
+  [key: `--spagbol-${string}`]: string | number;
+};
+export interface SpagbolCanvasSlots {
+  background?: ReactNode;
+  overlay?: ReactNode;
+}

package/src/react/controls.css

@@ -0,0 +1,122 @@
+/* Teia's original controls. Existing Teia tokens take precedence; Spagbol
+   tokens/defaults allow the same controls in other consumers and outside a canvas. */
+.spagbol-control-slider,
+.spagbol-control-button {
+  grid-column: 1 / -1;
+  width: 100%;
+  min-width: 156px;
+}
+
+.spagbol-control-slider {
+  position: relative;
+  height: var(--node-display-height, 48px);
+  background: transparent;
+  overflow: hidden;
+  touch-action: none;
+}
+
+.spagbol-control-button {
+  height: var(--node-display-height, 48px);
+  min-width: 0;
+  border: 0;
+  background: transparent;
+  cursor: pointer;
+  touch-action: none;
+}
+
+.spagbol-control-button:hover,
+.spagbol-control-button:focus-visible {
+  background: var(--color-foreground-08, rgba(255, 255, 255, 0.08));
+  color: var(--color-foreground, var(--spagbol-foreground, #fff));
+  outline: 0;
+}
+
+.spagbol-control-button-active {
+  background: var(--color-accent, var(--spagbol-accent, #2fd061));
+  color: var(--color-background, var(--spagbol-bg, #000));
+}
+
+.spagbol-control-button-active:hover,
+.spagbol-control-button-active:focus-visible {
+  background: var(--color-accent, var(--spagbol-accent, #2fd061));
+  color: var(--color-background, var(--spagbol-bg, #000));
+}
+
+.spagbol-control-slider-fill {
+  position: absolute;
+  inset: auto auto 0 0;
+  width: 0;
+  height: 100%;
+  background: var(--color-accent, var(--spagbol-accent, #2fd061));
+  pointer-events: none;
+}
+
+.spagbol-control-slider-vertical .spagbol-control-slider-fill {
+  width: 100%;
+  height: 0;
+}
+
+.spagbol-control-slider input[type="range"] {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  opacity: 0;
+  cursor: pointer;
+}
+
+.spagbol-control-slider-vertical input[type="range"] {
+  writing-mode: vertical-lr;
+  direction: rtl;
+}
+
+/* Match Teia's control focus styling inside the canvas's generic button rules. */
+.spagbol-canvas button.spagbol-control-button:focus-visible {
+  outline: 0;
+}
+
+
+.spagbol-control-number {
+  width: 68px;
+  min-width: 0;
+  max-width: 68px;
+  height: 22px;
+  padding: 0 4px;
+  border: 1px solid var(--spagbol-foreground, #fff);
+  background: transparent;
+  color: var(--spagbol-foreground, #fff);
+  cursor: ns-resize;
+  line-height: 20px;
+  overflow: hidden;
+  text-align: left;
+  text-overflow: clip;
+  white-space: nowrap;
+  user-select: none;
+}
+
+.spagbol-control-number:focus {
+  outline: 1px solid var(--spagbol-foreground, #fff);
+  outline-offset: 1px;
+}
+
+.spagbol-control-number-editing {
+  display: block;
+  appearance: textfield;
+  cursor: text;
+  font: inherit;
+  user-select: text;
+  -webkit-appearance: none;
+  -moz-appearance: textfield;
+}
+
+.spagbol-control-number-replaced {
+  border-color: color-mix(in srgb, var(--spagbol-foreground, #fff) 42%, transparent);
+  color: color-mix(in srgb, var(--spagbol-foreground, #fff) 48%, var(--spagbol-bg, #000));
+}
+
+.spagbol-control-number-editing::selection {
+  background: var(--spagbol-foreground, #fff);
+  color: var(--spagbol-bg, #000);
+}
+

package/src/react/duplicateDrag.ts

@@ -0,0 +1,97 @@
+import type {
+  GraphDocument,
+  GraphFragment,
+  GraphNode,
+  GraphArea,
+  Point,
+} from "../core/index.js";
+
+export interface DuplicateDrag {
+  namespace: string;
+  fragment: GraphFragment;
+  origin: Point;
+  nodeId: string;
+  positions: Map<string, Point>;
+  external: boolean;
+  areaPositions?: Map<string, Point>;
+}
+
+/** Rendering only: originals and moving copies coexist without editing the document. */
+export function duplicateDragPresentation(
+  graph: GraphDocument,
+  drag: DuplicateDrag,
+) {
+  const aliases = new Map(
+    drag.fragment.nodes.map((node) => [
+      node.id,
+      `${drag.namespace}:origin:${node.id}`,
+    ]),
+  );
+  const areaAliases = new Map(drag.fragment.areas.map(area => [area.id, `${drag.namespace}:origin:${area.id}`]));
+  const originalAreas = new Map<string, GraphArea>();
+  const originalNodes = new Map<string, GraphNode>();
+  const previewNodeIds = new Set(drag.fragment.nodes.map((node) => node.id));
+  const candidates = [
+    ...drag.fragment.links,
+    ...(drag.external ? drag.fragment.boundaryLinks : []),
+  ];
+  const previewLinks = new Map(
+    candidates.map((link) => [`${drag.namespace}:link:${link.id}`, link.id]),
+  );
+  const linkIds = new Map(
+    candidates.map((link) => [link.id, `${drag.namespace}:link:${link.id}`]),
+  );
+  const stationary = graph.nodes.map((node) => {
+    const alias = aliases.get(node.id);
+    if (!alias) return node;
+    originalNodes.set(alias, node);
+    return { ...node, id: alias };
+  });
+  const moving = drag.fragment.nodes.map((node) => ({
+    ...node,
+    position: drag.positions.get(node.id) ?? node.position,
+  }));
+  const originalLinks = graph.links.map((link) => ({
+    ...link,
+    source: {
+      ...link.source,
+      nodeId: aliases.get(link.source.nodeId) ?? link.source.nodeId,
+    },
+    target:
+      link.target.type === "port"
+        ? {
+            ...link.target,
+            nodeId: aliases.get(link.target.nodeId) ?? link.target.nodeId,
+          }
+        : link.target,
+  }));
+  const movingLinks = candidates.map((link) => ({
+    ...link,
+    id: linkIds.get(link.id)!,
+    target:
+      link.target.type === "link"
+        ? {
+            ...link.target,
+            linkId: linkIds.get(link.target.linkId) ?? link.target.linkId,
+          }
+        : link.target,
+  }));
+  const presentation: GraphDocument = {
+    ...graph,
+    nodes: [...stationary, ...moving],
+    links: [...originalLinks, ...movingLinks],
+    areas: [
+      ...graph.areas.map(area => {
+        const alias = areaAliases.get(area.id);
+        if (alias) originalAreas.set(alias, area);
+        return { ...area, id: alias ?? area.id,
+          ...(area.ownerNodeId ? { ownerNodeId: aliases.get(area.ownerNodeId) ?? area.ownerNodeId } : {}),
+          ...(area.nodeIds ? { nodeIds: area.nodeIds.map(id => aliases.get(id) ?? id) } : {}),
+          ...(area.areaIds ? { areaIds: area.areaIds.map(id => areaAliases.get(id) ?? id) } : {}),
+        };
+      }),
+      ...drag.fragment.areas.map(area => ({ ...area, position: drag.areaPositions?.get(area.id) ?? area.position })),
+    ],
+  };
+  return { graph: presentation, originalAreas, originalNodes, previewNodeIds, previewLinks };
+}

package/src/react/flowPresentation.ts

@@ -0,0 +1,56 @@
+import type { Edge, Node, NodeChange } from "@xyflow/react";
+import type { Size } from "../core/index.js";
+
+/** Apply measurement notifications without turning them into graph/history edits. */
+export function rememberMeasurements<N extends Node>(
+  cache: Map<string, Size>,
+  changes: readonly NodeChange<N>[],
+): boolean {
+  let changed = false;
+  for (const change of changes)
+    if (change.type === "dimensions" && change.dimensions) {
+      const previous = cache.get(change.id);
+      if (
+        previous?.width !== change.dimensions.width ||
+        previous?.height !== change.dimensions.height
+      ) {
+        cache.set(change.id, { ...change.dimensions });
+        changed = true;
+      }
+    }
+  return changed;
+}
+
+/** React Flow hides the reconnecting edge; a separate identity keeps the source visible. */
+export function stationaryReconnectEdge<E extends Edge>(edge: E): E {
+  return {
+    ...edge,
+    id: `reconnect-preview:${edge.id}`,
+    selected: false,
+    reconnectable: false,
+    selectable: false,
+    focusable: false,
+    deletable: false,
+    data: { ...edge.data, emphasized: false, dimmed: false },
+  };
+}
+
+function shallowRecordEqual(left: unknown, right: unknown): boolean {
+  if (left === right) return true;
+  if (!left || !right || typeof left !== 'object' || typeof right !== 'object') return false;
+  const a = left as Record<string, unknown>, b = right as Record<string, unknown>;
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every(key => a[key] === b[key]);
+}
+/** Keep native flow records stable when immutable model and geometry are unchanged. */
+export function reuseFlowPresentations<T extends { id: string }>(previous: T[], next: T[]): T[] {
+  const byId = new Map(previous.map(item => [item.id, item]));
+  const result = next.map(item => {
+    const old = byId.get(item.id);
+    if (!old) return item;
+    const a = old as unknown as Record<string, unknown>, b = item as unknown as Record<string, unknown>;
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every(key => a[key] === b[key] || (['data', 'style', 'position', 'measured'].includes(key) && shallowRecordEqual(a[key], b[key]))) ? old : item;
+  });
+  return result.length === previous.length && result.every((item, index) => item === previous[index]) ? previous : result;
+}

package/src/react/geometry.ts

@@ -0,0 +1,53 @@
+import { getBezierPath, Position } from "@xyflow/react";
+import type { Point } from "../core/index.js";
+
+/** Adapted from Teia's feedback/self-loop treatment; no audio semantics here. */
+export function linkPath(
+  source: Point,
+  target: Point,
+  feedback = false,
+  sameNode = false,
+): [string, number, number] {
+  if (!feedback && !sameNode) {
+    const [path, x, y] = getBezierPath({
+      sourceX: source.x,
+      sourceY: source.y,
+      targetX: target.x,
+      targetY: target.y,
+      sourcePosition: Position.Right,
+      targetPosition: Position.Left,
+    });
+    return [path, x, y];
+  }
+  const dx = Math.abs(source.x - target.x),
+    dy = Math.abs(source.y - target.y);
+  if (sameNode) {
+    const offset = Math.max(220 * 0.36, dx * 0.34 + dy * 0.12);
+    const controlY =
+      Math.min(source.y, target.y) - Math.min(32, Math.max(16, dy * 0.2 + 16));
+    return [
+      `M ${source.x},${source.y} C ${source.x + offset},${controlY} ${target.x - offset},${controlY} ${target.x},${target.y}`,
+      (source.x + target.x) / 2,
+      0.125 * source.y + 0.75 * controlY + 0.125 * target.y,
+    ];
+  }
+  const offset = Math.max(142, dx * 0.8 + dy * 0.2);
+  return [
+    `M ${source.x},${source.y} C ${source.x + offset},${source.y} ${target.x - offset},${target.y} ${target.x},${target.y}`,
+    (source.x + target.x) / 2,
+    (source.y + target.y) / 2,
+  ];
+}
+export const nodeFlowId = (id: string) => `node:${id}`;
+export const areaFlowId = (id: string) => `area:${id}`;
+export const anchorFlowId = (id: string) => `anchor:${id}`;
+export const sourceHandle = (id: string) => `out:${id}`;
+export const targetHandle = (id: string) => `in:${id}`;
+export function parseHandle(
+  handle: string | null | undefined,
+): { direction: "input" | "output"; id: string } | undefined {
+  if (handle?.startsWith("out:"))
+    return { direction: "output", id: handle.slice(4) };
+  if (handle?.startsWith("in:"))
+    return { direction: "input", id: handle.slice(3) };
+}

package/src/react/index.ts

@@ -0,0 +1,61 @@
+export {
+  SpagbolCanvas,
+  type SpagbolCanvasProps,
+  type SpagbolLinkPresentation,
+} from "./SpagbolCanvas.js";
+export {
+  SpagbolNodeFrame,
+  SpagbolNodePort,
+  SpagbolNodePanel,
+  type SpagbolNodeFrameProps,
+  type SpagbolNodePortProps,
+} from "./SpagbolNodeFrame.js";
+export {
+  SpagbolControlNumber,
+  formatNumber,
+  type SpagbolControlNumberProps,
+} from "./SpagbolControlNumber.js";
+export {
+  defineNodeView,
+  useEditorSnapshot,
+  useGraphEditor,
+  useObservation,
+  useRenderTarget,
+  useSpagbol,
+  type SpagbolNodeView,
+  type SpagbolNodeViewProps,
+  type SpagbolCanvasFeatures,
+  type SpagbolTheme,
+  type SpagbolCanvasSlots,
+} from "./context.js";
+export { linkPath } from "./geometry.js";
+export {
+  SpagbolCanvasFlow,
+  type SpagbolCanvasFlowProps,
+} from "./SpagbolCanvasFlow.js";
+export {
+  SpagbolControlZoom,
+  type SpagbolControlZoomProps,
+} from "./SpagbolControlZoom.js";
+export {
+  SpagbolCanvasMenu,
+  type SpagbolCanvasMenuProps,
+} from "./SpagbolCanvasMenu.js";
+export {
+  translateExtentForVisibleContent,
+  clampViewportToTranslateExtent,
+  visibleContentBounds,
+  infiniteCanvasExtent,
+  type CanvasBoundsItem,
+  type CanvasViewport,
+  type CanvasExtent,
+} from "./viewport.js";
+export {
+  SpagbolCanvasControls,
+  SpagbolCanvasActions,
+  SpagbolCanvasControlsZoom,
+  type SpagbolCanvasControlsOptions,
+  type SpagbolCanvasAction,
+  type SpagbolCanvasMenuItem,
+  type SpagbolCanvasMenuSeparator,
+} from "./SpagbolCanvasControls.js";

package/src/react/link-controls.css

@@ -0,0 +1,123 @@
+.spagbol-canvas .spagbol-canvas-link-controls {
+  position: fixed;
+  z-index: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 4px;
+  border: 1px solid var(--color-foreground, var(--spagbol-foreground, #fff));
+  background:
+    linear-gradient(var(--color-foreground, var(--spagbol-foreground, #fff)), var(--color-foreground, var(--spagbol-foreground, #fff))) left top / 100% 4px no-repeat,
+    linear-gradient(var(--color-foreground, var(--spagbol-foreground, #fff)), var(--color-foreground, var(--spagbol-foreground, #fff))) left bottom / 100% 4px no-repeat,
+    linear-gradient(var(--color-foreground, var(--spagbol-foreground, #fff)), var(--color-foreground, var(--spagbol-foreground, #fff))) left top / 4px 100% no-repeat,
+    linear-gradient(var(--color-foreground, var(--spagbol-foreground, #fff)), var(--color-foreground, var(--spagbol-foreground, #fff))) right top / 4px 100% no-repeat,
+    linear-gradient(var(--color-foreground, var(--spagbol-foreground, #fff)), var(--color-foreground, var(--spagbol-foreground, #fff))) left 26px / 100% 4px no-repeat;
+  color: var(--color-background, var(--spagbol-bg, #000));
+  font-size: 13px;
+  font-weight: 400;
+  pointer-events: all;
+  box-shadow: 6px 6px 0 var(--color-background-42, #0000006b);
+  transform-origin: center;
+  --edge-control-width: 96px;
+  --edge-weight-control-width: 74px;
+}
+
+.spagbol-canvas .spagbol-canvas-link-controls-value-row {
+  display: flex;
+  gap: 0;
+}
+
+.spagbol-canvas .spagbol-control-number-link {
+  width: var(--edge-weight-control-width);
+  height: 22px;
+  padding: 0 4px;
+  border: 0;
+  background: var(--color-surface, var(--spagbol-surface, #000));
+  color: var(--color-foreground, var(--spagbol-foreground, #fff));
+  cursor: ns-resize;
+  font-size: 13px;
+  font-weight: 400;
+  line-height: 20px;
+  overflow: hidden;
+  text-align: left;
+  text-overflow: clip;
+  white-space: nowrap;
+  user-select: none;
+}
+
+.spagbol-canvas .spagbol-control-number-link:focus {
+  outline: 1px solid var(--color-foreground, var(--spagbol-foreground, #fff));
+  outline-offset: 1px;
+}
+
+.spagbol-canvas .spagbol-control-number-link-editing {
+  display: block;
+  background: var(--color-surface, var(--spagbol-surface, #000));
+  color: var(--color-foreground, var(--spagbol-foreground, #fff));
+  cursor: text;
+  font-size: 13px;
+  font-weight: 400;
+  user-select: text;
+  -moz-appearance: textfield;
+}
+
+.spagbol-canvas .spagbol-control-number-link-editing::selection {
+  background: var(--color-foreground, var(--spagbol-foreground, #fff));
+  color: var(--color-background, var(--spagbol-bg, #000));
+}
+
+.spagbol-canvas .spagbol-canvas-link-controls-enabled {
+  display: grid;
+  width: 22px;
+  height: 22px;
+  flex: 0 0 22px;
+  place-items: center;
+  padding: 0;
+  border: 0;
+  border-radius: 0;
+  background: var(--color-surface, var(--spagbol-surface, #000));
+  cursor: pointer;
+}
+
+.spagbol-canvas .spagbol-canvas-link-controls-enabled::after {
+  display: block;
+  width: 9px;
+  height: 9px;
+  border: 1px solid var(--color-foreground, var(--spagbol-foreground, #fff));
+  border-radius: 50%;
+  content: '';
+}
+
+.spagbol-canvas .spagbol-canvas-link-controls-enabled-active::after {
+  background: var(--color-foreground, var(--spagbol-foreground, #fff));
+}
+
+.spagbol-canvas .spagbol-canvas-link-controls-enabled:hover {
+  background: var(--color-surface, var(--spagbol-surface, #000));
+  color: var(--color-foreground, var(--spagbol-foreground, #fff));
+}
+
+.spagbol-canvas .spagbol-canvas-link-controls-enabled:focus-visible {
+  outline: 1px solid var(--color-foreground, var(--spagbol-foreground, #fff));
+  outline-offset: 2px;
+}
+
+.spagbol-canvas .spagbol-canvas-link-controls-mode {
+  width: var(--edge-control-width);
+  height: 22px;
+  padding: 0 4px;
+  border: 0;
+  border-radius: 0;
+  background: var(--color-surface, var(--spagbol-surface, #000));
+  color: var(--color-foreground, var(--spagbol-foreground, #fff));
+  cursor: pointer;
+  font-size: 13px;
+  font-weight: 400;
+  line-height: 20px;
+}
+
+.spagbol-canvas .spagbol-canvas-link-controls-mode:focus {
+  outline: 1px solid var(--color-foreground, var(--spagbol-foreground, #fff));
+  outline-offset: 1px;
+}
+

package/src/react/portState.ts

@@ -0,0 +1,24 @@
+import type { GraphDocument } from "../core/index.js";
+export type PortState = { inputs: Set<string>; outputs: Set<string>; replaced: Set<string> };
+const documentCache = new WeakMap<GraphDocument, Map<string, PortState>>();
+const connectionCache = new WeakMap<GraphDocument['links'], { enabled: string; state: Map<string, PortState> }>();
+export const emptyPortState: PortState = { inputs: new Set(), outputs: new Set(), replaced: new Set() };
+/** Value edits share connection state; rewiring/mode/enabled edits invalidate it. */
+export function graphPortStates(graph: GraphDocument) {
+  const cached = documentCache.get(graph); if (cached) return cached;
+  const enabledKey = JSON.stringify(graph.nodes.map(node => [node.id, node.enabled !== false]));
+  const connections = Object.isFrozen(graph) ? connectionCache.get(graph.links) : undefined;
+  if (connections?.enabled === enabledKey) { documentCache.set(graph, connections.state); return connections.state; }
+  const result = new Map<string, PortState>();
+  const enabled = new Set(graph.nodes.filter(node => node.enabled !== false).map(node => node.id));
+  const state = (id: string) => { let value = result.get(id); if (!value) { value = { inputs: new Set(), outputs: new Set(), replaced: new Set() }; result.set(id, value); } return value; };
+  for (const link of graph.links) {
+    state(link.source.nodeId).outputs.add(link.source.portId);
+    if (link.target.type === 'port') {
+      state(link.target.nodeId).inputs.add(link.target.portId);
+      if (link.enabled !== false && link.mode === 'set' && enabled.has(link.source.nodeId)) state(link.target.nodeId).replaced.add(link.target.portId);
+    }
+  }
+  if (Object.isFrozen(graph)) { documentCache.set(graph, result); connectionCache.set(graph.links, { enabled: enabledKey, state: result }); }
+  return result;
+}