@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/material/MaterialGraphCanvas.tsx

@@ -0,0 +1,861 @@
+// The node canvas: React Flow's props and handlers, and nothing else.
+//
+// Everything this file used to also be now lives beside it — the graph-to-flow
+// conversion in `flowModel.ts`, the socket vocabulary in `socketGlyph.ts`, the
+// pan memory in `viewportMemory.ts`, the thumbnails in `previewScheduler.ts`,
+// the four renderers in their own files. What is left is the wiring, which is
+// the part that has to read as one page.
+//
+// ── THE THREE RULES THIS FILE IS HELD TO ────────────────────────────────
+//
+//   NO EDIT HAPPENS HERE. Every handler ends at a store verb, so a gesture is
+//   one transaction, one undo entry and one refusal route. v1 built the next
+//   graph inline and handed it to `onUpdate`, which is how "connect" ended up
+//   with its own duplicate-edge rule that the validator did not share.
+//
+//   NO VALIDATOR PER POINTER FRAME. `isValidConnection` fires on every hover
+//   while a wire is in hand; v1 ran `validateMaterialGraph` over the WHOLE
+//   graph inside it, which is O(nodes + edges) per mouse move and was
+//   measurably the slowest thing in the lane. It asks the memoised type index
+//   one question now. The problem LIST still runs the full validator, once per
+//   graph, in a `useMemo`.
+//
+//   THE KEYMAP OWNS THE KEYS. This canvas has no `onKeyDown` of its own. It is
+//   focusable and it carries the `.material-graph-canvas` class, which is the
+//   whole of its contract with `state/keymap.ts` — that class under the event
+//   target is what puts the resolver in the graph lane. A local handler here
+//   was a second binding site for Delete, and the two disagreed about whether
+//   an edge counted as a selection.
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import {
+  Background,
+  MiniMap,
+  ReactFlow,
+  ReactFlowProvider,
+  SelectionMode,
+  useNodesInitialized,
+  useReactFlow,
+  useStore as useFlowStore,
+} from "@xyflow/react";
+import { IconMinus, IconPlus, LockedControls } from "@dailies-studio/ui";
+import type {
+  Connection,
+  Edge,
+  EdgeChange,
+  EdgeMouseHandler,
+  FinalConnectionState,
+  NodeChange,
+  NodeMouseHandler,
+  OnNodeDrag,
+  Viewport,
+} from "@xyflow/react";
+import {
+  indexMaterialGraphTypes,
+  materialGraphPixelSignature,
+  materialGraphSemanticSignature,
+  validateMaterialGraph,
+} from "@dailies-studio/shot/doc";
+import type { MaterialGraph3D } from "@dailies-studio/shot/doc";
+import { useShotEditor, useStore } from "../../state/context.js";
+import { MATERIAL_GRAPH_GRID } from "../../state/store.js";
+import {
+  buildMaterialFlow,
+  graphPositionOf,
+  groupUnderPoint,
+  nodesInScope,
+  segmentIntersectsRect,
+} from "./flowModel.js";
+import type { MaterialFlowNode } from "./flowModel.js";
+import { MaterialConnectProvider, MaterialNodeCard } from "./MaterialNode.js";
+import { MaterialGroupNode } from "./MaterialGroupNode.js";
+import { MaterialCommentNode } from "./MaterialCommentNode.js";
+import { MaterialRerouteNode } from "./MaterialRerouteNode.js";
+import { MaterialNodePalette } from "./MaterialNodePalette.js";
+import { useMaterialGraphMenu } from "./MaterialGraphMenu.js";
+import { MaterialPreviewProvider, NODE_PREVIEW_PX } from "./NodePreview.js";
+import { createPreviewScheduler, visiblePreviewNodes } from "./previewScheduler.js";
+import type { PreviewEntry } from "./previewScheduler.js";
+import { materialViewportKey, recallMaterialViewport, rememberMaterialViewport } from "./viewportMemory.js";
+// React Flow's own sheet, in this chunk with the canvas that needs it.
+import "./reactFlow.css";
+
+const NODE_TYPES = {
+  material: MaterialNodeCard,
+  materialGroup: MaterialGroupNode,
+  materialComment: MaterialCommentNode,
+  materialReroute: MaterialRerouteNode,
+} as const;
+
+const FIT_VIEW = { padding: 0.2, maxZoom: 1 } as const;
+const NO_PREVIEWS: ReadonlyMap<string, PreviewEntry> = new Map();
+
+/** Fallback card size for the two drag hit tests, used only until React Flow
+ *  has measured a card. Same nominal box `MATERIAL_NODE_CARD` names in the
+ *  store, and for the same reason: a hit test may not depend on the zoom. */
+const MATERIAL_CARD_W = 180;
+const MATERIAL_CARD_H = 96;
+
+export interface MaterialGraphCanvasProps {
+  /** The graph the workspace resolved THROUGH THE SLOT. Passed rather than
+   *  looked up, so the canvas cannot disagree with the header about which
+   *  surface is on screen. */
+  graph: MaterialGraph3D;
+  materialId: string;
+  layerId: string;
+  slot: number | null;
+  /** Where the graph's zoom goes: a place in the canvas bar the workspace
+   *  keeps for it (MaterialWorkspace.tsx). Absent or null, no zoom is shown. */
+  zoomSlot?: HTMLElement | null;
+}
+
+export function MaterialGraphCanvas(props: MaterialGraphCanvasProps) {
+  // A viewer's cards show every field in its own locked state. The zoom is a
+  // view control, so it stays outside.
+  const readOnly = useShotEditor((state) => state.readOnly);
+  return (
+    <ReactFlowProvider>
+      <LockedControls value={readOnly}>
+        <MaterialGraphCanvasInner {...props} />
+      </LockedControls>
+      {/* INSIDE THE PROVIDER, and portalled out to the canvas bar. The zoom
+          drives this flow's own viewport, which only a component under the
+          provider can reach; the portal keeps it in this subtree while its
+          buttons sit in the bar with the rest of the mode's verbs. */}
+      {props.zoomSlot == null ? null : createPortal(<GraphZoom />, props.zoomSlot)}
+    </ReactFlowProvider>
+  );
+}
+
+/**
+ * The graph's zoom, in the canvas bar: out, the percentage, in, Fit.
+ *
+ * It replaces React Flow's own `<Controls>` island, which floated over the
+ * graph's corner in a second look. The readout subscribes to the ZOOM alone,
+ * not the viewport, so a pan does not re-render it.
+ */
+function GraphZoom() {
+  const flow = useReactFlow();
+  const zoom = useFlowStore((flowState) => flowState.transform[2]);
+  return (
+    <div className="zoom-controls" role="group" aria-label="Graph zoom" data-testid="material-zoom">
+      <button
+        type="button"
+        className="btn is-icon"
+        aria-label="Zoom the graph out"
+        title="Zoom the graph out"
+        onClick={() => void flow.zoomOut()}
+      >
+        <IconMinus />
+      </button>
+      <span className="zoom-readout" data-testid="material-zoom-level">
+        {Math.round(zoom * 100)}%
+      </span>
+      <button
+        type="button"
+        className="btn is-icon"
+        aria-label="Zoom the graph in"
+        title="Zoom the graph in"
+        onClick={() => void flow.zoomIn()}
+      >
+        <IconPlus />
+      </button>
+      {/* Named for its subject: the dock head under the graph has a "Fit" of
+          its own, for the timeline. */}
+      <button
+        type="button"
+        className="btn"
+        aria-label="Fit the graph"
+        title="Fit the whole graph (Home or F over the graph)"
+        onClick={() => void flow.fitView(FIT_VIEW)}
+      >
+        Fit
+      </button>
+    </div>
+  );
+}
+
+function MaterialGraphCanvasInner({ graph, materialId, layerId, slot }: MaterialGraphCanvasProps) {
+  const store = useStore();
+  const flow = useReactFlow<MaterialFlowNode, Edge>();
+  const initialised = useNodesInitialized();
+  const menu = useMaterialGraphMenu();
+  const openMenu = menu.open;
+  const surface = useRef<HTMLElement | null>(null);
+
+  const assets = useShotEditor((state) => state.doc?.assets);
+  const path = useShotEditor((state) => state.materialGraphPath);
+  const selection = useShotEditor((state) => state.materialGraphSelection);
+  const palette = useShotEditor((state) => state.materialPalette);
+  const snapToGrid = useShotEditor((state) => state.materialSnapToGrid);
+  // A VIEWER reads the graph: no node moves and no wire is drawn.
+  const readOnly = useShotEditor((state) => state.readOnly);
+  const frameRequest = useShotEditor((state) => state.materialFrameRequest);
+
+  /** Positions while a drag is live. React Flow needs the cards to follow the
+   *  pointer, and the DOCUMENT must not: sixty writes per drag is sixty undo
+   *  entries. Committed once at drag stop, through `moveMaterialNodes`. */
+  const [draft, setDraft] = useState<Readonly<Record<string, { x: number; y: number }>> | null>(null);
+  const [previews, setPreviews] = useState<ReadonlyMap<string, PreviewEntry>>(NO_PREVIEWS);
+  /** What the live drag would do on release: the wire it would be spliced into,
+   *  and the group box it would join. Both are ANSWERS on screen, never edits —
+   *  the document learns about either only at `onNodeDragStop`. */
+  const [spliceEdge, setSpliceEdge] = useState<string | null>(null);
+  const [dropGroup, setDropGroup] = useState<string | null>(null);
+  /** Box sizes while a resize is live, for the reason `draft` exists: the flow
+   *  is controlled, so nothing follows the handle unless this does. */
+  const [draftSize, setDraftSize] = useState<Readonly<
+    Record<string, { width: number; height: number }>
+  > | null>(null);
+
+  const types = useMemo(() => indexMaterialGraphTypes(graph), [graph]);
+  const problems = useMemo(() => validateMaterialGraph(graph, assets ?? {}), [graph, assets]);
+  const built = useMemo(
+    () =>
+      buildMaterialFlow({
+        graph,
+        materialId,
+        path,
+        assets: assets ?? {},
+        selection,
+        problems,
+        types,
+      }),
+    [graph, materialId, path, assets, selection, problems, types],
+  );
+  // The draft is spliced in AFTER the memo, so a drag re-renders the cards it
+  // moves and leaves every other card's object identity alone. The drop
+  // highlight rides the same splice, for the same reason.
+  const nodes = useMemo(
+    () =>
+      draft === null && dropGroup === null && draftSize === null
+        ? built.nodes
+        : built.nodes.map((node) => {
+            const at = draft?.[node.id];
+            const box = draftSize?.[node.id];
+            const marked = node.id === dropGroup;
+            if (at === undefined && box === undefined && !marked) return node;
+            return {
+              ...node,
+              ...(at === undefined ? {} : { position: at }),
+              ...(box === undefined ? {} : { style: { ...node.style, ...box } }),
+              ...(marked ? { className: [node.className, "is-drop-target"].filter(Boolean).join(" ") } : {}),
+            };
+          }),
+    [built.nodes, draft, dropGroup, draftSize],
+  );
+  // Only the one wire changes identity, so a pointer frame during a drag
+  // re-renders one edge rather than all of them.
+  const edges = useMemo(
+    () =>
+      spliceEdge === null
+        ? built.edges
+        : built.edges.map((edge) =>
+            edge.id === spliceEdge
+              ? { ...edge, className: `${edge.className ?? ""} is-splice-target`.trim() }
+              : edge,
+          ),
+    [built.edges, spliceEdge],
+  );
+
+  const canConnect = useCallback(
+    (source: { nodeId: string; socket: string }, target: { nodeId: string; socket: string }): boolean =>
+      types.canConnect(source, target).ok,
+    [types],
+  );
+
+  // ── viewport memory ──────────────────────────────────────────────────────
+  const viewportKey = materialViewportKey(materialId, path);
+  const restored = useRef<string | null>(null);
+  useEffect(() => {
+    // React Flow renders nothing until it has measured its container, and it
+    // reports a zero-size viewport until then — restoring into that lands the
+    // graph off screen with no way back but the frame key.
+    if (!initialised || restored.current === viewportKey) return;
+    restored.current = viewportKey;
+    const remembered = recallMaterialViewport(viewportKey);
+    if (remembered === null) void flow.fitView(FIT_VIEW);
+    else void flow.setViewport(remembered);
+  }, [initialised, viewportKey, flow]);
+
+  // The FRAME mailbox: a fresh identity per ask, like `appMenu`, because only
+  // this component knows its own viewport.
+  const framed = useRef(frameRequest);
+  useEffect(() => {
+    if (frameRequest === null || framed.current === frameRequest) {
+      framed.current = frameRequest;
+      return;
+    }
+    framed.current = frameRequest;
+    void flow.fitView(FIT_VIEW);
+  }, [frameRequest, flow]);
+
+  const rememberNow = useCallback(
+    (viewport: Viewport) => rememberMaterialViewport(materialViewportKey(materialId, path), viewport),
+    [materialId, path],
+  );
+
+  // ── node previews ────────────────────────────────────────────────────────
+  const scheduler = useMemo(
+    () =>
+      createPreviewScheduler({
+        request: async (request) => (await store.stage()?.requestNodePreviews(request)) ?? null,
+        onChange: (entries) => setPreviews(entries),
+      }),
+    [store],
+  );
+  useEffect(() => () => scheduler.dispose(), [scheduler]);
+
+  const askForPreviews = useCallback(() => {
+    const box = surface.current?.getBoundingClientRect();
+    // INSIDE A FUNCTION, NOTHING IS PREVIEWED. A function body compiles with
+    // its call site's arguments bound, so a thumbnail of a node in there would
+    // be a picture of one call among several — v2 is main-scope only, and a
+    // wrong picture is worse than none.
+    if (box === undefined || path.length > 0) {
+      scheduler.ask(null);
+      return;
+    }
+    const wanted = visiblePreviewNodes(nodesInScope(graph, path), flow.getViewport(), box);
+    if (wanted.length === 0) {
+      scheduler.ask(null);
+      return;
+    }
+    scheduler.ask({
+      materialId,
+      layerId,
+      slot,
+      nodeIds: wanted,
+      size: Math.round(NODE_PREVIEW_PX * (window.devicePixelRatio || 1)),
+      pixelSignature: materialGraphPixelSignature(graph),
+      semanticSignature: materialGraphSemanticSignature(graph),
+    });
+  }, [graph, path, materialId, layerId, slot, flow, scheduler]);
+
+  useEffect(() => {
+    askForPreviews();
+  }, [askForPreviews, initialised]);
+
+  // ── handlers ─────────────────────────────────────────────────────────────
+  /**
+   * The store's selection, written from one place.
+   *
+   * ── WHY THIS IS THE CHANGE STREAM AND NOT `onSelectionChange` ─────────
+   *
+   * In a CONTROLLED flow — one where `nodes` is a prop, which is the only kind
+   * this canvas can be — React Flow does not apply a selection itself. Look at
+   * `triggerNodeChanges`: it applies changes only when it owns the nodes, and
+   * otherwise emits them and waits for the owner to write them back. So
+   * `onSelectionChange` fires from React Flow's LOOKUP, which is filled from
+   * our `nodes` prop, which is filled from the store — it can only ever echo
+   * what we already wrote. Wiring the store to it makes clicking a card do
+   * precisely nothing, which is what it did.
+   *
+   * So the change stream is the writer, and it is still exactly one: both
+   * halves land in `setMaterialGraphSelection`, which is identity-stable when
+   * the answer has not moved.
+   */
+  const writeSelection = useCallback(
+    (next: { nodeIds?: readonly string[]; edgeIds?: readonly string[] }) => {
+      // The half that did not change is re-read LIVE rather than closed over:
+      // one gesture emits node changes and edge changes separately, and a
+      // stale read would make the second undo the first.
+      const current = store.getState().materialGraphSelection;
+      store.setMaterialGraphSelection({
+        nodeIds: next.nodeIds ?? current.nodeIds,
+        edgeIds: next.edgeIds ?? current.edgeIds,
+      });
+    },
+    [store],
+  );
+
+  const onNodesChange = useCallback(
+    (changes: NodeChange<MaterialFlowNode>[]) => {
+      // POSITION, SELECT and a LIVE RESIZE. Removal is impossible because
+      // `deleteKeyCode` is null — the keymap owns Delete.
+      let moved: Record<string, { x: number; y: number }> | null = null;
+      let picked: Set<string> | null = null;
+      let sized: Record<string, { width: number; height: number }> | null = null;
+      let settled = false;
+      for (const change of changes) {
+        if (change.type === "position" && change.dragging === true && change.position !== undefined) {
+          moved ??= {};
+          moved[change.id] = change.position;
+        } else if (change.type === "select") {
+          picked ??= new Set(store.getState().materialGraphSelection.nodeIds);
+          if (change.selected) picked.add(change.id);
+          else picked.delete(change.id);
+        } else if (change.type === "dimensions" && change.dimensions !== undefined) {
+          // THE SAME BARGAIN THE POSITION DRAFT MAKES. The flow is controlled,
+          // so React Flow cannot resize a box on its own; without this the
+          // corner handle would drag against a card that never moved. Held
+          // locally until `onResizeEnd` commits, so a resize is one entry and
+          // not one per frame.
+          if (change.resizing === true) {
+            sized ??= {};
+            sized[change.id] = change.dimensions;
+          } else if (change.resizing === false) settled = true;
+        }
+      }
+      if (picked !== null) writeSelection({ nodeIds: [...picked] });
+      // The commit has landed in the document, so the local override must go or
+      // it would outrank it.
+      if (settled) setDraftSize(null);
+      if (sized !== null) {
+        const next = sized;
+        setDraftSize((current) => ({ ...(current ?? {}), ...next }));
+      }
+      if (moved === null) return;
+      const next = moved;
+      setDraft((current) => ({ ...(current ?? {}), ...next }));
+    },
+    [store, writeSelection],
+  );
+
+  const onEdgesChange = useCallback(
+    (changes: EdgeChange<Edge>[]) => {
+      let picked: Set<string> | null = null;
+      for (const change of changes) {
+        if (change.type !== "select") continue;
+        picked ??= new Set(store.getState().materialGraphSelection.edgeIds);
+        if (change.selected) picked.add(change.id);
+        else picked.delete(change.id);
+      }
+      if (picked !== null) writeSelection({ edgeIds: [...picked] });
+    },
+    [store, writeSelection],
+  );
+
+  /**
+   * WHAT THE DRAG WOULD DO IF IT ENDED NOW — the wire it would splice into and
+   * the box it would join. Live state, so the answer is on screen before the
+   * author commits to it; both are recomputed from final positions at drop.
+   */
+  const onNodeDrag = useCallback<OnNodeDrag<MaterialFlowNode>>(
+    (_event, dragged) => {
+      // SPLICE NEEDS ONE CARD WITH TWO ENDS. Dragging a selection says nothing
+      // about which card goes in the wire, and a node with no inputs or no
+      // outputs cannot sit in the middle of one.
+      const alone = draft === null || Object.keys(draft).length === 1;
+      const data = dragged.data;
+      const spliceable =
+        alone &&
+        (dragged.type === "material" || dragged.type === "materialReroute") &&
+        data.inputs.length > 0 &&
+        data.outputs.length > 0;
+
+      let hit: string | null = null;
+      if (spliceable) {
+        // Which of this card's inputs are already wired. Built once per pointer
+        // Which of this card's inputs are already wired, so the highlight
+        // promises only splices `dropMaterialNodes` will actually make. Built
+        // once per pointer frame rather than once per candidate wire.
+        const filled = new Set(
+          graph.edges
+            .filter((candidate) => candidate.target.nodeId === dragged.id)
+            .map((candidate) => `${candidate.target.nodeId}\u0000${candidate.target.socket}`),
+        );
+        const self = flow.getInternalNode(dragged.id);
+        const box = self?.measured;
+        if (self !== undefined && box?.width != null && box.height != null) {
+          const rect = {
+            x: self.internals.positionAbsolute.x,
+            y: self.internals.positionAbsolute.y,
+            width: box.width,
+            height: box.height,
+          };
+          for (const edge of built.edges) {
+            if (edge.source === dragged.id || edge.target === dragged.id) continue;
+            const from = flow.getInternalNode(edge.source);
+            const to = flow.getInternalNode(edge.target);
+            if (from === undefined || to === undefined) continue;
+            // ponytail: the wire is approximated as a straight segment between
+            // the two cards' facing edges. Edges are drawn smoothstep, so a
+            // sharply bent one can be reported a few pixels off. Upgrade by
+            // sampling `getSmoothStepPath` if it ever reads wrong.
+            const a = {
+              x: from.internals.positionAbsolute.x + (from.measured?.width ?? 0),
+              y: from.internals.positionAbsolute.y + (from.measured?.height ?? 0) / 2,
+            };
+            const b = {
+              x: to.internals.positionAbsolute.x,
+              y: to.internals.positionAbsolute.y + (to.measured?.height ?? 0) / 2,
+            };
+            if (!segmentIntersectsRect(a, b, rect)) continue;
+            // CROSSING IS NOT ENOUGH — it has to be a splice the graph would
+            // accept. Two type questions against the memoised index, which is
+            // the same budget `isValidConnection` spends per hover.
+            const source = { nodeId: edge.source, socket: edge.sourceHandle ?? "value" };
+            const target = { nodeId: edge.target, socket: edge.targetHandle ?? "value" };
+            // A FREE input, matching `dropMaterialNodes` exactly — the
+            // highlight must promise the edit the drop will actually make, and
+            // an already-wired input is one this gesture will not take.
+            const takes = data.inputs.some(
+              (socket) =>
+                !filled.has(`${dragged.id}\u0000${socket.id}`) &&
+                types.canConnect(source, { nodeId: dragged.id, socket: socket.id }).ok,
+            );
+            const gives = data.outputs.some(
+              (socket) => types.canConnect({ nodeId: dragged.id, socket: socket.id }, target).ok,
+            );
+            if (takes && gives) {
+              hit = edge.id;
+              break;
+            }
+          }
+        }
+      }
+      setSpliceEdge(hit);
+
+      // THE BOX, for any dragged card. A group cannot go inside a group, and a
+      // card's CENTRE decides — using a corner would join a box the author only
+      // brushed the edge of.
+      const centre = graphPositionOf(
+        { position: dragged.position, parentId: dragged.parentId },
+        graph,
+      );
+      const size = dragged.measured;
+      setDropGroup(
+        dragged.type === "materialGroup"
+          ? null
+          : groupUnderPoint(graph, path, [
+              centre[0] + (size?.width ?? MATERIAL_CARD_W) / 2,
+              centre[1] + (size?.height ?? MATERIAL_CARD_H) / 2,
+            ]),
+      );
+    },
+    [draft, flow, built.edges, types, graph, path],
+  );
+
+  const onNodeDragStop = useCallback(() => {
+    const held = draft;
+    const splicing = spliceEdge;
+    setDraft(null);
+    setSpliceEdge(null);
+    setDropGroup(null);
+    if (held === null) return;
+    const positions: Record<string, [number, number]> = {};
+    const membership: Record<string, string | null> = {};
+    let single: string | null = null;
+    for (const [id, at] of Object.entries(held)) {
+      const node = built.nodes.find((candidate) => candidate.id === id);
+      if (node === undefined) continue;
+      const landed = graphPositionOf({ position: at, parentId: node.parentId }, graph);
+      positions[id] = landed;
+      single = single === null ? id : "";
+      if (node.type === "materialGroup") continue;
+      // RECOMPUTED, not read off the hover state: the last `onNodeDrag` fired
+      // wherever the pointer last MOVED, and a drop can land somewhere else.
+      // The document should agree with where the card actually is.
+      const size = node.measured;
+      const box = groupUnderPoint(graph, path, [
+        landed[0] + (size?.width ?? MATERIAL_CARD_W) / 2,
+        landed[1] + (size?.height ?? MATERIAL_CARD_H) / 2,
+      ]);
+      const before = graph.nodesById[id]?.groupId ?? null;
+      if (box !== before) membership[id] = box;
+    }
+    // ONE CALL for the whole drag: twelve cards moved, whatever they joined,
+    // and the wire they were dropped across are one gesture and one undo entry.
+    store.dropMaterialNodes(materialId, path, positions, {
+      ...(Object.keys(membership).length === 0 ? {} : { membership }),
+      ...(splicing !== null && single !== null && single !== ""
+        ? { splice: { nodeId: single, edgeId: splicing } }
+        : {}),
+    });
+  }, [draft, spliceEdge, built.nodes, graph, store, materialId, path]);
+
+  const onConnect = useCallback(
+    (connection: Connection) => {
+      if (connection.sourceHandle === null || connection.targetHandle === null) return;
+      store.connectMaterialSockets(
+        materialId,
+        path,
+        { nodeId: connection.source, socket: connection.sourceHandle },
+        { nodeId: connection.target, socket: connection.targetHandle },
+      );
+    },
+    [store, materialId, path],
+  );
+
+  /** Set by `onReconnect`, read by `onReconnectEnd`: React Flow's own way of
+   *  telling "moved somewhere" from "let go over nothing", which is the
+   *  gesture that means DISCONNECT. */
+  const reconnected = useRef(false);
+
+  const onConnectEnd = useCallback(
+    (event: MouseEvent | TouchEvent, connection: FinalConnectionState) => {
+      if (connection.isValid === true || connection.fromHandle?.id == null) return;
+      const point = "changedTouches" in event ? event.changedTouches[0] : event;
+      if (point === undefined) return;
+      const at = flow.screenToFlowPosition({ x: point.clientX, y: point.clientY });
+      // A WIRE DROPPED IN EMPTY SPACE IS A QUESTION, not a mistake: "what could
+      // take this?". The palette answers it filtered, and `addMaterialNode`
+      // draws the wire for whatever is picked.
+      store.openMaterialPalette(at, {
+        nodeId: connection.fromHandle.nodeId,
+        socket: connection.fromHandle.id,
+        side: connection.fromHandle.type === "source" ? "source" : "target",
+        type: socketTypeOf(connection.fromHandle.nodeId, connection.fromHandle.id, connection.fromHandle.type, built.nodes),
+      });
+    },
+    [flow, store, built.nodes],
+  );
+
+  const onNodeDoubleClick: NodeMouseHandler<MaterialFlowNode> = useCallback(
+    (_event, node) => {
+      if (node.data.node.kind !== "subgraph") return;
+      store.enterMaterialSubgraph(node.id);
+    },
+    [store],
+  );
+
+  const targetsAt = useCallback(
+    (event: { clientX: number; clientY: number }, over: { nodeIds?: string[]; edgeIds?: string[] }) => {
+      const at = flow.screenToFlowPosition({ x: event.clientX, y: event.clientY });
+      return {
+        materialId,
+        path,
+        nodeIds: over.nodeIds ?? [],
+        edgeIds: over.edgeIds ?? [],
+        at: { x: at.x, y: at.y },
+      };
+    },
+    [flow, materialId, path],
+  );
+
+  const onNodeContextMenu: NodeMouseHandler<MaterialFlowNode> = useCallback(
+    (event, node) => {
+      event.preventDefault();
+      // The press SELECTS what it landed on unless that was already part of the
+      // selection, which is the rule every other menu in this chrome follows:
+      // right-clicking outside a selection is a new subject, inside it is the
+      // whole of it.
+      const nodeIds = selection.nodeIds.includes(node.id) ? [...selection.nodeIds] : [node.id];
+      if (!selection.nodeIds.includes(node.id)) {
+        store.setMaterialGraphSelection({ nodeIds, edgeIds: [] });
+      }
+      openMenu({ x: event.clientX, y: event.clientY }, targetsAt(event, { nodeIds }));
+    },
+    [openMenu, selection.nodeIds, store, targetsAt],
+  );
+
+  const onEdgeContextMenu: EdgeMouseHandler<Edge> = useCallback(
+    (event, edge) => {
+      event.preventDefault();
+      const edgeIds = selection.edgeIds.includes(edge.id) ? [...selection.edgeIds] : [edge.id];
+      if (!selection.edgeIds.includes(edge.id)) {
+        store.setMaterialGraphSelection({ nodeIds: [], edgeIds });
+      }
+      openMenu({ x: event.clientX, y: event.clientY }, targetsAt(event, { edgeIds }));
+    },
+    [openMenu, selection.edgeIds, store, targetsAt],
+  );
+
+  const isValidConnection = useCallback(
+    (connection: Connection | Edge): boolean => {
+      const sourceHandle = connection.sourceHandle ?? null;
+      const targetHandle = connection.targetHandle ?? null;
+      if (sourceHandle === null || targetHandle === null) return false;
+      return types.canConnect(
+        { nodeId: connection.source, socket: sourceHandle },
+        { nodeId: connection.target, socket: targetHandle },
+      ).ok;
+    },
+    [types],
+  );
+
+  // Where the palette sits, and where what it adds lands. The request carries a
+  // GRAPH point (or null for the keyboard route, which has no pointer to ask),
+  // and only this component can turn one into a screen point.
+  const paletteAt = useMemo(() => {
+    if (palette === null) return null;
+    const box = surface.current?.getBoundingClientRect();
+    if (palette.at !== null) {
+      const screen = flow.flowToScreenPosition(palette.at);
+      return {
+        screenAt: { x: screen.x - (box?.left ?? 0), y: screen.y - (box?.top ?? 0) },
+        graphAt: [palette.at.x, palette.at.y] as const,
+      };
+    }
+    const centre = flow.screenToFlowPosition({
+      x: (box?.left ?? 0) + (box?.width ?? 0) / 2,
+      y: (box?.top ?? 0) + (box?.height ?? 0) / 2,
+    });
+    return {
+      screenAt: { x: (box?.width ?? 0) / 2, y: (box?.height ?? 0) / 2 },
+      graphAt: [centre.x, centre.y] as const,
+    };
+  }, [palette, flow]);
+
+  return (
+    <section
+      className="material-graph-canvas"
+      aria-label="Material node graph"
+      tabIndex={0}
+      ref={surface}
+      // FOCUS FOLLOWS THE PRESS, because `state/keymap.ts` decides it is in the
+      // graph lane by asking the event TARGET for `.material-graph-canvas`. A
+      // canvas nobody has focused sends its keys to `<body>` and the whole lane
+      // silently does not exist. Fields and buttons keep their own presses.
+      onPointerDownCapture={(event) => {
+        const target = event.target;
+        if (
+          target instanceof Element &&
+          target.closest("button, input, textarea, select, [contenteditable='true']") !== null
+        ) {
+          return;
+        }
+        event.currentTarget.focus({ preventScroll: true });
+      }}
+    >
+      <MaterialPreviewProvider entries={previews}>
+        <MaterialConnectProvider canConnect={canConnect}>
+          <ReactFlow<MaterialFlowNode, Edge>
+            nodes={nodes}
+            edges={edges}
+            nodeTypes={NODE_TYPES}
+            nodesDraggable={!readOnly}
+            nodesConnectable={!readOnly}
+            edgesReconnectable={!readOnly}
+            onNodesChange={onNodesChange}
+            onEdgesChange={onEdgesChange}
+            onNodeDrag={onNodeDrag}
+            onNodeDragStop={onNodeDragStop}
+            onConnect={onConnect}
+            onConnectEnd={onConnectEnd}
+            isValidConnection={isValidConnection}
+            onReconnectStart={() => {
+              reconnected.current = false;
+            }}
+            onReconnect={(oldEdge, connection) => {
+              if (connection.sourceHandle === null || connection.targetHandle === null) return;
+              reconnected.current = true;
+              store.reconnectMaterialEdge(materialId, path, oldEdge.id, {
+                source: { nodeId: connection.source, socket: connection.sourceHandle },
+                target: { nodeId: connection.target, socket: connection.targetHandle },
+              });
+            }}
+            onReconnectEnd={(_event, edge) => {
+              // LET GO OVER NOTHING IS A DISCONNECT. It is the gesture every
+              // node editor binds, and without it the only way to remove one
+              // wire is to select it and press Delete.
+              if (reconnected.current) return;
+              store.disconnectMaterialEdges(materialId, path, [edge.id]);
+            }}
+            onNodeDoubleClick={onNodeDoubleClick}
+            onNodeContextMenu={onNodeContextMenu}
+            onEdgeContextMenu={onEdgeContextMenu}
+            onPaneContextMenu={(event) => {
+              event.preventDefault();
+              openMenu({ x: event.clientX, y: event.clientY }, targetsAt(event, {}));
+            }}
+            onDoubleClick={(event) => {
+              // The PANE only. A double-click on a card is how a subgraph is
+              // entered, and on a field it is how a word is selected.
+              if (!(event.target instanceof Element)) return;
+              if (event.target.classList.contains("react-flow__pane") !== true) return;
+              const at = flow.screenToFlowPosition({ x: event.clientX, y: event.clientY });
+              store.openMaterialPalette({ x: at.x, y: at.y });
+            }}
+            onMoveEnd={(_event, viewport) => {
+              rememberNow(viewport);
+              askForPreviews();
+            }}
+            snapToGrid={snapToGrid}
+            snapGrid={[MATERIAL_GRAPH_GRID, MATERIAL_GRAPH_GRID]}
+            deleteKeyCode={null}
+            // SAME ROOT CAUSE AS THE BOARD'S, and here the skipped rung is
+            // worse. React Flow's a11y handler clears node selection on Escape
+            // synchronously, so `materialEscape` then read an empty selection
+            // and took its next rung, which closes the whole workspace. The
+            // ladder is meant to drop the selection first.
+            disableKeyboardA11y
+            // OFF, because a double-click on the pane opens the palette and
+            // d3-zoom's own dblclick handler calls `stopImmediatePropagation`
+            // — with it on, the native event never reaches React's delegated
+            // root and the palette silently never opened.
+            zoomOnDoubleClick={false}
+            // ── THE POINTER, AS EVERY OTHER CANVAS TOOL SPELLS IT ──────────
+            //
+            // Left-drag on empty space SELECTS; the middle and right buttons
+            // pan. React Flow's default is the other way round, which makes
+            // the commonest thing in a node graph — "take those four and move
+            // them" — the one gesture behind a modifier, while panning, which
+            // an author does with the wheel anyway, gets the whole left button.
+            // Figma, Blender's node editor and Unreal all read it this way, and
+            // an author arrives here with those in their fingers.
+            //
+            // Shift-drag still marquees, so the old habit is not punished.
+            selectionOnDrag
+            // TOUCHING counts, not enclosing. A long wire chain never fits in
+            // a rubber band drawn inside the viewport, so "fully contained"
+            // would mean zooming out before every multi-select.
+            selectionMode={SelectionMode.Partial}
+            // MIDDLE BUTTON ONLY, and deliberately not the right one. React
+            // Flow's `Pane.onContextMenu` opens with
+            //   if (Array.isArray(panOnDrag) && panOnDrag.includes(2)) return;
+            // — an UNCONDITIONAL bail, not a "did this right press actually
+            // pan" test. Listing button 2 here would trade every right-click
+            // menu on this canvas (add node here, paste here, snap while
+            // dragging) for a second way to do what the middle button and
+            // Space already do. The menu is worth more.
+            panOnDrag={[1]}
+            // Hold-to-pan, and the contract with `state/keymap.ts`: the graph
+            // lane returns `null` for Space so nothing calls `preventDefault`
+            // and React Flow's own window listener sees the key.
+            panActivationKeyCode="Space"
+            // A HAND TREMOR IS NOT AN EDIT. The default is 1px, so brushing a
+            // card while clicking it committed a `moveMaterialNodes` — a real
+            // undo entry that restores a position nobody meant to change and
+            // buries the edit before it.
+            nodeDragThreshold={4}
+            // One socket-row pitch (rows are 24px), up from the 20px default:
+            // the closest handle inside the radius wins, so a wire dropped a
+            // little short still lands rather than opening the palette.
+            connectionRadius={24}
+            // …and the same idea at the other end: a click ON a socket is a
+            // click, not a one-pixel wire dropped back where it started.
+            connectionDragThreshold={3}
+            selectionKeyCode="Shift"
+            multiSelectionKeyCode={["Meta", "Control"]}
+            minZoom={0.15}
+            maxZoom={2.5}
+            proOptions={{ hideAttribution: true }}
+          >
+            <Background gap={MATERIAL_GRAPH_GRID} size={1} color="var(--material-grid-dot)" />
+            <MiniMap pannable zoomable position="bottom-right" ariaLabel="Material graph overview" />
+          </ReactFlow>
+        </MaterialConnectProvider>
+      </MaterialPreviewProvider>
+      {palette === null || paletteAt === null ? null : (
+        <MaterialNodePalette
+          materialId={materialId}
+          path={path}
+          request={palette}
+          screenAt={paletteAt.screenAt}
+          graphAt={paletteAt.graphAt}
+        />
+      )}
+      {menu.menu}
+    </section>
+  );
+}
+
+/**
+ * The declared type of the socket a drag started from.
+ *
+ * Read off the flow nodes rather than the graph, because those already carry
+ * the PER-NODE sockets — a subgraph call's are its function's signature, and
+ * the static spec would say it has none.
+ */
+function socketTypeOf(
+  nodeId: string,
+  socket: string,
+  side: "source" | "target",
+  nodes: readonly MaterialFlowNode[],
+) {
+  const node = nodes.find((candidate) => candidate.id === nodeId);
+  const list = side === "source" ? node?.data.outputs : node?.data.inputs;
+  return list?.find((candidate) => candidate.id === socket)?.type ?? "numeric";
+}