entangle-ui 0.9.0 → 0.11.0

package/dist/esm/components/editor/NodeGraph/NodeGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeGraph.js","sources":["src/components/editor/NodeGraph/NodeGraph.tsx"],"sourcesContent":["'use client';\n\nimport React, {\n  useCallback,\n  useImperativeHandle,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n  useTransition,\n} from 'react';\n\nimport {\n  Viewport,\n  ViewportLayer,\n  ViewportWorld,\n  ViewportOverlay,\n  screenToWorld as worldFromScreen,\n  worldToScreen as screenFromWorld,\n} from '@/components/primitives/viewport';\nimport { useControlledState, useLatest } from '@/hooks';\nimport { cx } from '@/utils/cx';\n\nimport { nodeGraphRootStyle } from './NodeGraph.css';\nimport { NodeGraphStoreContext } from './NodeGraphContext';\nimport {\n  buildDrawTheme,\n  drawBackground,\n  drawConnectionPreview,\n  drawEdges,\n  drawGroups,\n} from './nodeGraphDrawing';\nimport { EdgeLabelsLayer } from './NodeGraphEdgeLabels';\nimport { NodeGraphGroupView } from './NodeGraphGroup';\nimport {\n  computeNodesBounds,\n  findEdgeAtPoint,\n  getNodeBox,\n  isPointInNode,\n  isPointInRect,\n  rectsIntersect,\n  resolvePortRef,\n  toggleSelected,\n} from './nodeGraphMath';\nimport { NodeGraphMinimapInner } from './NodeGraphMinimap';\nimport { NodeGraphNodeView } from './NodeGraphNode';\nimport {\n  NodeGraphNodeBody,\n  NodeGraphNodeHeader,\n  NodeGraphPinList,\n  NodeGraphPinRow,\n} from './NodeGraphNodeParts';\nimport { NodeGraphNodeSection } from './NodeGraphNodeSection';\nimport { NodeGraphPin } from './NodeGraphPin';\nimport { NodeGraphPort } from './NodeGraphPort';\nimport { NodeGraphPortVisual } from './NodeGraphPortVisual';\nimport {\n  NodeGraphBackground,\n  NodeGraphMinimap,\n  NodeGraphSpawnPalette,\n  NodeGraphToolbar,\n} from './NodeGraphSlots';\nimport { NodeGraphSpawnPaletteInner } from './NodeGraphSpawnPalette';\nimport { NodeGraphStore } from './NodeGraphStore';\nimport {\n  NodeGraphToolbarInner,\n  NodeGraphFitContentButton,\n  NodeGraphFitSelectionButton,\n  NodeGraphZoomInButton,\n  NodeGraphZoomOutButton,\n  NodeGraphResetZoomButton,\n  NodeGraphToolbarSeparator,\n} from './NodeGraphToolbar';\nimport { sortSlots } from './sortSlots';\nimport { useNodeGraphConnection } from './useNodeGraphConnection';\nimport {\n  useNodeGraphEdgeInteraction,\n  EDGE_HIT_PX,\n} from './useNodeGraphEdgeInteraction';\nimport { useNodeGraphGroupDrag } from './useNodeGraphGroupDrag';\nimport { useNodeGraphKeyboard } from './useNodeGraphKeyboard';\nimport { useNodeGraphNodeDrag } from './useNodeGraphNodeDrag';\n\nimport type {\n  NodeGraphContextMenuInfo,\n  NodeGraphEdge,\n  NodeGraphGroup,\n  NodeGraphHandle,\n  NodeGraphLayerName,\n  NodeGraphNode,\n  NodeGraphPortRef,\n  NodeGraphProps,\n  NodeGraphSelection,\n  NodeGraphTarget,\n} from './NodeGraph.types';\nimport type { Point2D } from '@/components/primitives/canvas/canvas.types';\nimport type {\n  ViewportHandle,\n  ViewportSelectionEvent,\n  ViewportTransform,\n  WorldRect,\n} from '@/components/primitives/viewport';\n\nconst EMPTY_NODES: NodeGraphNode[] = [];\nconst EMPTY_EDGES: NodeGraphEdge[] = [];\nconst EMPTY_GROUPS: NodeGraphGroup[] = [];\nconst EMPTY_SELECTION: NodeGraphSelection = {\n  nodes: [],\n  edges: [],\n  groups: [],\n};\nconst DEFAULT_NODE_SIZE = { width: 180, height: 80 };\n\n// ─── Main component ───\n\n/**\n * `NodeGraph` — interactive, data-driven node editor surface built on\n * `Viewport`. Renders nodes as HTML in world space (`renderNode`) and\n * edges as Béziers on a perf-isolated canvas layer.\n *\n * The component is fully controlled-or-uncontrolled across four data\n * dimensions (nodes / edges / groups / selection) — each emits a full\n * array on change. Connection drags, marquee selection, drag-to-move,\n * snap-to-grid, and keyboard nav are all wired in.\n *\n * @example\n * ```tsx\n * <NodeGraph\n *   nodes={nodes}\n *   edges={edges}\n *   onNodesChange={setNodes}\n *   onEdgesChange={setEdges}\n *   renderNode={node => <MyNode data={node.data} />}\n *   isValidConnection={(src, tgt) => src.node !== tgt.node}\n *   responsive\n * >\n *   <NodeGraph.Background variant=\"dots\" gap={24} />\n *   <NodeGraph.Minimap placement=\"bottom-right\" />\n * </NodeGraph>\n * ```\n */\nconst NodeGraphImpl = ({\n  nodes: nodesProp,\n  defaultNodes,\n  onNodesChange,\n  edges: edgesProp,\n  defaultEdges,\n  onEdgesChange,\n  groups: groupsProp,\n  defaultGroups,\n  onGroupsChange,\n  selection: selectionProp,\n  defaultSelection,\n  onSelectionChange,\n  renderNode,\n  renderEdgeLabel,\n  edgeStyle,\n  isValidConnection,\n  snapToGrid = false,\n  onConnectStart,\n  onConnectEnd,\n  onContextMenu,\n  onDelete,\n  onActivate,\n  pan,\n  zoom,\n  minZoom = 0.1,\n  maxZoom = 4,\n  selectionRect = true,\n  responsive = false,\n  height = 480,\n  defaultNodeSize: defaultNodeSizeProp = DEFAULT_NODE_SIZE,\n  disabled = false,\n  ariaLabel = 'Node graph',\n  className,\n  style,\n  testId,\n  id,\n  children,\n  ref,\n}: NodeGraphProps): React.ReactElement => {\n  // ── Refs ──\n  const rootRef = useRef<HTMLDivElement>(null);\n  const viewportHandleRef = useRef<ViewportHandle>(null);\n  const store = useMemo(() => new NodeGraphStore(), []);\n\n  // Stabilize defaultNodeSize identity across renders when the consumer\n  // passes an inline literal — downstream effects/memos depend on its\n  // reference and would otherwise re-fire every render.\n  const defaultNodeSize = useMemo(\n    () => ({\n      width: defaultNodeSizeProp.width,\n      height: defaultNodeSizeProp.height,\n    }),\n    [defaultNodeSizeProp.width, defaultNodeSizeProp.height]\n  );\n\n  // ── Controlled / uncontrolled data ──\n  const [nodes, setNodes] = useControlledState<NodeGraphNode[]>({\n    value: nodesProp,\n    defaultValue: defaultNodes,\n    onChange: onNodesChange,\n    fallback: EMPTY_NODES,\n  });\n  const [edges, setEdges] = useControlledState<NodeGraphEdge[]>({\n    value: edgesProp,\n    defaultValue: defaultEdges,\n    onChange: onEdgesChange,\n    fallback: EMPTY_EDGES,\n  });\n  const [groups, setGroups] = useControlledState<NodeGraphGroup[]>({\n    value: groupsProp,\n    defaultValue: defaultGroups,\n    onChange: onGroupsChange,\n    fallback: EMPTY_GROUPS,\n  });\n  const [selection, setSelection] = useControlledState<NodeGraphSelection>({\n    value: selectionProp,\n    defaultValue: defaultSelection,\n    onChange: onSelectionChange,\n    fallback: EMPTY_SELECTION,\n  });\n\n  // ── Mirror React state into the store ──\n  useLayoutEffect(() => {\n    store.setData({\n      nodes,\n      edges,\n      groups,\n      defaultNodeSize,\n    });\n  }, [store, nodes, edges, groups, defaultNodeSize]);\n\n  useLayoutEffect(() => {\n    store.setSelection(selection);\n  }, [store, selection]);\n\n  // ── Transform tracking (mirror Viewport transform into a ref for math) ──\n  const transformRef = useRef<ViewportTransform>({ x: 0, y: 0, zoom: 1 });\n  const handleTransformChange = useCallback((next: ViewportTransform) => {\n    transformRef.current = next;\n  }, []);\n\n  // ── Slot sorting ──\n  const slots = useMemo(() => sortSlots(children), [children]);\n\n  // ── Helpers ──\n  const getTransform = useCallback((): ViewportTransform => {\n    return viewportHandleRef.current?.getTransform() ?? transformRef.current;\n  }, []);\n\n  const localScreenPoint = useCallback(\n    (clientX: number, clientY: number): Point2D => {\n      const el = rootRef.current;\n      if (!el) return { x: 0, y: 0 };\n      const rect = el.getBoundingClientRect();\n      return { x: clientX - rect.left, y: clientY - rect.top };\n    },\n    []\n  );\n\n  const screenToWorldLocal = useCallback(\n    (clientX: number, clientY: number): Point2D => {\n      const local = localScreenPoint(clientX, clientY);\n      return worldFromScreen(local, getTransform());\n    },\n    [localScreenPoint, getTransform]\n  );\n\n  // ── Targets / hit testing ──\n  const nodesRef = useLatest(nodes);\n  const groupsRef = useLatest(groups);\n  const selectionRef = useLatest(selection);\n  const setSelectionRef = useLatest(setSelection);\n  const setNodesRef = useLatest(setNodes);\n  const disabledRef = useLatest(disabled);\n\n  const findHitTarget = useCallback(\n    (clientX: number, clientY: number): NodeGraphTarget => {\n      const worldPoint = screenToWorldLocal(clientX, clientY);\n      const currentNodes = nodesRef.current;\n      const currentGroups = groupsRef.current;\n      // Iterate top-to-bottom so the last-rendered node \"wins\" — matches what\n      // the user sees on top.\n      for (let i = currentNodes.length - 1; i >= 0; i--) {\n        const node = currentNodes[i];\n        if (\n          node &&\n          isPointInNode(\n            worldPoint,\n            node,\n            store.getMeasuredSize(node.id),\n            defaultNodeSize\n          )\n        ) {\n          return { kind: 'node', id: node.id };\n        }\n      }\n      // Edges sit above groups / background but below nodes, so hit-test them\n      // after nodes and before groups. Drawn on a canvas → no DOM to walk.\n      const edgeThreshold = EDGE_HIT_PX / (getTransform().zoom || 1);\n      const edgeId = findEdgeAtPoint(\n        worldPoint,\n        store.getData().edges,\n        store.getNodeById,\n        store.getPortPosition,\n        edgeThreshold\n      );\n      if (edgeId) return { kind: 'edge', id: edgeId };\n      for (let i = currentGroups.length - 1; i >= 0; i--) {\n        const group = currentGroups[i];\n        if (group && isPointInRect(worldPoint, group.bounds)) {\n          return { kind: 'group', id: group.id };\n        }\n      }\n      return { kind: 'empty', worldPoint };\n    },\n    [\n      defaultNodeSize,\n      screenToWorldLocal,\n      nodesRef,\n      groupsRef,\n      store,\n      getTransform,\n    ]\n  );\n\n  // ── Connection drag (ports) ──\n  const { onPortPointerDown, onEdgeReconnectStart } = useNodeGraphConnection({\n    viewportRef: rootRef,\n    store,\n    getTransform,\n    isValidConnection,\n    onConnectStart,\n    onConnectEnd,\n    emitEdgesChange: setEdges,\n    emitSelectionChange: setSelection,\n  });\n\n  // ── Node body pointerdown — drag (single/multi) + select on release ──\n  const { onNodeBodyPointerDown, onNodeBodyPointerUp } = useNodeGraphNodeDrag({\n    store,\n    getTransform,\n    localScreenPoint,\n    snapToGrid,\n    disabled,\n    emitNodesChange: setNodes,\n    emitSelectionChange: setSelection,\n  });\n\n  // ── Group interaction (drag + resize + click-select) ──\n  const setGroupsRef = useLatest(setGroups);\n  const {\n    onGroupBodyPointerDown,\n    onGroupHandlePointerDown,\n    onGroupBodyPointerUp,\n  } = useNodeGraphGroupDrag({\n    store,\n    getTransform,\n    localScreenPoint,\n    snapToGrid,\n    disabled,\n    defaultNodeSize,\n    emitGroupsChange: setGroups,\n    emitNodesChange: setNodes,\n    emitSelectionChange: setSelection,\n  });\n\n  // ── Group label / colour edits ──\n  //\n  // The library's group overlay owns the inline label editor and the\n  // colour swatch — these handlers translate UI commits into a controlled\n  // `onGroupsChange` emission so the consumer receives the full next\n  // groups array, same as every other group mutation.\n  const handleGroupLabelChange = useCallback(\n    (group: NodeGraphGroup, nextLabel: string): void => {\n      const trimmed = nextLabel.trim();\n      const nextGroups = groupsRef.current.map(g => {\n        if (g.id !== group.id) return g;\n        if ((g.label ?? '') === trimmed) return g;\n        if (trimmed === '') {\n          // Empty label collapses back to `undefined` so the default\n          // \"Group\" placeholder shows up cleanly on next render.\n          const { label: _omit, ...rest } = g;\n          void _omit;\n          return rest;\n        }\n        return { ...g, label: trimmed };\n      });\n      setGroupsRef.current(nextGroups);\n    },\n    [groupsRef, setGroupsRef]\n  );\n\n  const handleGroupColorChange = useCallback(\n    (group: NodeGraphGroup, nextColor: string): void => {\n      if (group.color === nextColor) return;\n      const nextGroups = groupsRef.current.map(g =>\n        g.id === group.id ? { ...g, color: nextColor } : g\n      );\n      setGroupsRef.current(nextGroups);\n    },\n    [groupsRef, setGroupsRef]\n  );\n\n  // ── Marquee selection from the Viewport ──\n  const [, startMarqueeTransition] = useTransition();\n  const handleViewportSelection = useCallback(\n    (info: ViewportSelectionEvent): void => {\n      if (disabledRef.current) return;\n      if (info.inProgress) {\n        // Live preview: drive the marquee overlay via the store so canvas\n        // hit-test for hover/edge can also respond if needed.\n        store.setInteraction({\n          kind: 'marquee',\n          startWorld: { x: info.rect.x, y: info.rect.y },\n          currentWorld: {\n            x: info.rect.x + info.rect.width,\n            y: info.rect.y + info.rect.height,\n          },\n          additive: info.additive,\n        });\n        return;\n      }\n\n      // Final marquee — compute selection from rect intersection.\n      store.setInteraction({ kind: 'idle' });\n      const rect: WorldRect = info.rect;\n\n      // A near-zero-area rect is a plain click, not a drag. Use it to select\n      // an edge — edges are drawn on a canvas and never receive the pointer\n      // event directly, so this is where edge clicks are resolved. Falls\n      // through to the normal node-marquee / clear path when no edge is hit.\n      const zoom = getTransform().zoom || 1;\n      const isClick =\n        rect.width * zoom <= EDGE_HIT_PX && rect.height * zoom <= EDGE_HIT_PX;\n      if (isClick) {\n        const edgeId = findEdgeAtPoint(\n          { x: rect.x, y: rect.y },\n          store.getData().edges,\n          store.getNodeById,\n          store.getPortPosition,\n          EDGE_HIT_PX / zoom\n        );\n        if (edgeId) {\n          const current = selectionRef.current;\n          setSelectionRef.current({\n            nodes: info.additive ? current.nodes : [],\n            edges: toggleSelected(current.edges, edgeId, info.additive),\n            groups: info.additive ? current.groups : [],\n          });\n          return;\n        }\n      }\n\n      const hits: string[] = [];\n      for (const node of nodesRef.current) {\n        const box = getNodeBox(\n          node,\n          store.getMeasuredSize(node.id),\n          defaultNodeSize\n        );\n        if (\n          rectsIntersect(\n            { x: box.x, y: box.y, width: box.width, height: box.height },\n            rect\n          )\n        ) {\n          hits.push(node.id);\n        }\n      }\n      const current = selectionRef.current;\n      const nextNodes = info.additive\n        ? Array.from(new Set([...current.nodes, ...hits]))\n        : hits;\n      // Selection commits can cascade into expensive renderNode bodies for\n      // a large hit set — let React schedule it as non-urgent so the\n      // gesture release doesn't hitch.\n      startMarqueeTransition(() => {\n        setSelectionRef.current({\n          nodes: nextNodes,\n          edges: info.additive ? current.edges : [],\n          groups: info.additive ? current.groups : [],\n        });\n      });\n    },\n    [\n      store,\n      nodesRef,\n      selectionRef,\n      setSelectionRef,\n      defaultNodeSize,\n      disabledRef,\n      getTransform,\n    ]\n  );\n\n  // ── Context menu ──\n  const onContextMenuRef = useLatest(onContextMenu);\n  const handleContextMenu = useCallback(\n    (event: React.MouseEvent<HTMLDivElement>): void => {\n      if (disabledRef.current) return;\n      event.preventDefault();\n      // Walk up the DOM from the event target to find data attributes\n      // identifying a port or a node. Ports take priority because they're\n      // descendants of nodes — the loop bails on the first match.\n      const targetEl = event.target as Element | null;\n      let portRef: NodeGraphPortRef | null = null;\n      let nodeId: string | null = null;\n      let cursor: Element | null = targetEl;\n      while (cursor && cursor !== rootRef.current) {\n        const portId = cursor.getAttribute('data-port-id');\n        const dataNodeId = cursor.getAttribute('data-node-id');\n        if (portId && dataNodeId) {\n          portRef = { node: dataNodeId, port: portId };\n          break;\n        }\n        if (dataNodeId && !nodeId) {\n          nodeId = dataNodeId;\n        }\n        cursor = cursor.parentElement;\n      }\n      const screenPoint = localScreenPoint(event.clientX, event.clientY);\n      const worldPoint = worldFromScreen(screenPoint, getTransform());\n      let resolvedTarget: NodeGraphTarget;\n      if (portRef) {\n        resolvedTarget = {\n          kind: 'port',\n          node: portRef.node,\n          port: portRef.port,\n        };\n      } else if (nodeId) {\n        resolvedTarget = { kind: 'node', id: nodeId };\n      } else {\n        resolvedTarget = findHitTarget(event.clientX, event.clientY);\n      }\n      const info: NodeGraphContextMenuInfo = {\n        target: resolvedTarget,\n        screenPoint,\n        worldPoint,\n      };\n      // Consumer callback fires first — they may render their own menu,\n      // log telemetry, etc.\n      onContextMenuRef.current?.(info);\n      // SpawnPalette subscribers (if mounted) get pinged for empty /\n      // group targets: those are the \"drop a new node here\" spots.\n      if (resolvedTarget.kind === 'empty' || resolvedTarget.kind === 'group') {\n        store.requestSpawn({ worldPoint, screenPoint });\n      }\n    },\n    [\n      findHitTarget,\n      localScreenPoint,\n      getTransform,\n      onContextMenuRef,\n      disabledRef,\n      store,\n    ]\n  );\n\n  // ── Edge hover + endpoint grab (canvas edges → pointer hit-test) ──\n  const { onRootPointerMove, onRootPointerLeave, onRootPointerDownCapture } =\n    useNodeGraphEdgeInteraction({\n      store,\n      getTransform,\n      screenToWorldLocal,\n      localScreenPoint,\n      onEdgeReconnectStart,\n      disabled,\n    });\n\n  // ── Delete ──\n  //\n  // Without a consumer-supplied `onDelete`, the library cascades the\n  // selection through nodes / edges / groups automatically: nodes get\n  // removed, edges are filtered out when either endpoint is gone (or\n  // when the edge itself is selected), groups in the selection drop.\n  // Saves every consumer the same 8-line filter and avoids the classic\n  // \"I forgot to clean up orphan edges\" bug.\n  //\n  // If the consumer provides `onDelete`, they take over completely —\n  // they can still call the exported `applyCascadeDelete` helper to do\n  // the same filtering plus their own snapshot / undo / confirmation\n  // logic on top.\n  const handleDeleteInternal = useCallback(\n    (sel: NodeGraphSelection): void => {\n      if (onDelete) {\n        onDelete(sel);\n        return;\n      }\n      const currentNodes = nodesRef.current;\n      const currentEdges = store.getData().edges;\n      const currentGroups = groupsRef.current;\n      const removedNodeIds = new Set(sel.nodes);\n      const removedEdgeIds = new Set(sel.edges);\n      const removedGroupIds = new Set(sel.groups);\n      if (\n        removedNodeIds.size === 0 &&\n        removedEdgeIds.size === 0 &&\n        removedGroupIds.size === 0\n      ) {\n        return;\n      }\n      if (removedNodeIds.size > 0) {\n        setNodesRef.current(\n          currentNodes.filter(n => !removedNodeIds.has(n.id))\n        );\n      }\n      const nextEdges = currentEdges.filter(\n        e =>\n          !removedEdgeIds.has(e.id) &&\n          !removedNodeIds.has(e.source.node) &&\n          !removedNodeIds.has(e.target.node)\n      );\n      if (nextEdges.length !== currentEdges.length) {\n        setEdges(nextEdges);\n      }\n      if (removedGroupIds.size > 0) {\n        setGroupsRef.current(\n          currentGroups.filter(g => !removedGroupIds.has(g.id))\n        );\n      }\n      setSelectionRef.current({ nodes: [], edges: [], groups: [] });\n    },\n    [\n      onDelete,\n      store,\n      nodesRef,\n      groupsRef,\n      setNodesRef,\n      setGroupsRef,\n      setSelectionRef,\n      setEdges,\n    ]\n  );\n\n  // ── Keyboard ──\n  const { onKeyDown } = useNodeGraphKeyboard({\n    store,\n    emitNodesChange: setNodes,\n    emitSelectionChange: setSelection,\n    onDelete: handleDeleteInternal,\n    onActivate,\n    snapToGrid,\n    disabled,\n  });\n\n  // ── Canvas draw callbacks (stable identities via useLatest) ──\n  const backgroundProps = slots.backgroundProps;\n  const backgroundVariant = backgroundProps?.variant ?? 'dots';\n  const backgroundGap = backgroundProps?.gap ?? 24;\n  const backgroundColor = backgroundProps?.color;\n  const backgroundFill = backgroundProps?.background;\n\n  const drawBackgroundLayer = useCallback(\n    (\n      ctx: CanvasRenderingContext2D,\n      info: Parameters<React.ComponentProps<typeof ViewportLayer>['draw']>[1]\n    ): void => {\n      const theme = buildDrawTheme(info.theme);\n      drawBackground(ctx, info, theme, {\n        variant: backgroundVariant,\n        gap: backgroundGap,\n        color: backgroundColor,\n        background: backgroundFill,\n      });\n    },\n    [backgroundVariant, backgroundGap, backgroundColor, backgroundFill]\n  );\n\n  const drawGroupsLayer = useCallback(\n    (\n      ctx: CanvasRenderingContext2D,\n      info: Parameters<React.ComponentProps<typeof ViewportLayer>['draw']>[1]\n    ): void => {\n      const data = store.getData();\n      const sel = store.getSelection();\n      const interaction = store.getInteraction();\n      const theme = buildDrawTheme(info.theme);\n      drawGroups(ctx, info, data, sel, interaction, theme);\n    },\n    [store]\n  );\n\n  const edgeStyleRef = useLatest(edgeStyle);\n  const drawEdgesLayer = useCallback(\n    (\n      ctx: CanvasRenderingContext2D,\n      info: Parameters<React.ComponentProps<typeof ViewportLayer>['draw']>[1]\n    ): void => {\n      const data = store.getData();\n      const sel = store.getSelection();\n      const hover = store.getHover();\n      const interaction = store.getInteraction();\n      const theme = buildDrawTheme(info.theme);\n      drawEdges(\n        ctx,\n        info,\n        data,\n        sel,\n        hover.hoveredEdgeId,\n        interaction,\n        store.getNodeById,\n        store.getPortPosition,\n        edgeStyleRef.current,\n        theme\n      );\n    },\n    [store, edgeStyleRef]\n  );\n\n  const drawPreviewLayer = useCallback(\n    (\n      ctx: CanvasRenderingContext2D,\n      info: Parameters<React.ComponentProps<typeof ViewportLayer>['draw']>[1]\n    ): void => {\n      const interaction = store.getInteraction();\n      if (interaction.kind !== 'connect') return;\n      const theme = buildDrawTheme(info.theme);\n      drawConnectionPreview(\n        ctx,\n        info,\n        interaction,\n        portRef => {\n          const resolved = resolvePortRef(\n            portRef,\n            store.getNodeById,\n            store.getPortPosition\n          );\n          if (!resolved) return null;\n          return { position: resolved.position, side: resolved.side };\n        },\n        theme\n      );\n    },\n    [store]\n  );\n\n  // Force invalidation of canvas layers when the relevant store slices change.\n  // `invalidate` reads `viewportHandleRef.current` at call time so a viewport\n  // remount (which would re-bind the imperative handle) doesn't leave us\n  // pointing at a stale handle reference.\n  useLayoutEffect(() => {\n    const invalidate = (layer: NodeGraphLayerName): void => {\n      viewportHandleRef.current?.invalidate(layer);\n    };\n    const unsubs: Array<() => void> = [\n      store.subscribeData(() => {\n        invalidate('groups');\n        invalidate('edges');\n      }),\n      store.subscribeSelection(() => {\n        invalidate('groups');\n        invalidate('edges');\n      }),\n      store.subscribeHover(() => {\n        invalidate('edges');\n      }),\n      // Interaction drives the in-flight drag delta — every canvas layer\n      // that visualises something positional needs to redraw on each tick:\n      // edges (connectors follow dragged nodes live, not snap on release),\n      // groups (drag-groups / resize-group), and the connection preview.\n      store.subscribeInteraction(() => {\n        invalidate('edges');\n        invalidate('groups');\n        invalidate('preview');\n      }),\n      // Port positions (re)registered by `<NodeGraph.Port>` slots — edges\n      // anchor at the registered point, so any change must redraw.\n      store.subscribePortPositions(() => {\n        invalidate('edges');\n      }),\n      // Measured node sizes feed the marquee / hit-test bounds — no canvas\n      // redraw needed, but subscribe so React-side reads in renderers see\n      // the updates if they depend on it.\n      store.subscribeMeasuredSizes(() => undefined),\n    ];\n    return () => {\n      for (const unsub of unsubs) unsub();\n    };\n  }, [store]);\n\n  // ── Imperative handle ──\n  useImperativeHandle(\n    ref,\n    (): NodeGraphHandle => ({\n      fitToContent: padding => {\n        const vp = viewportHandleRef.current;\n        if (!vp) return;\n        const bounds = computeNodesBounds(\n          nodesRef.current,\n          store.getMeasuredSize,\n          defaultNodeSize\n        );\n        if (bounds.width === 0 && bounds.height === 0) return;\n        vp.fitToContent(bounds, padding ?? 32);\n      },\n      fitToSelection: padding => {\n        const vp = viewportHandleRef.current;\n        if (!vp) return;\n        const sel = selectionRef.current.nodes;\n        if (sel.length === 0) return;\n        const selectedIds = new Set(sel);\n        const selectedNodes = nodesRef.current.filter(n =>\n          selectedIds.has(n.id)\n        );\n        const bounds = computeNodesBounds(\n          selectedNodes,\n          store.getMeasuredSize,\n          defaultNodeSize\n        );\n        if (bounds.width === 0 && bounds.height === 0) return;\n        vp.fitToContent(bounds, padding ?? 64);\n      },\n      focusNode: idStr => {\n        const vp = viewportHandleRef.current;\n        if (!vp) return;\n        const node = store.getNodeById(idStr);\n        if (!node) return;\n        const box = getNodeBox(\n          node,\n          store.getMeasuredSize(node.id),\n          defaultNodeSize\n        );\n        vp.centerOn({\n          x: box.x + box.width / 2,\n          y: box.y + box.height / 2,\n        });\n      },\n      centerOn: (point, z) => {\n        viewportHandleRef.current?.centerOn(point, z);\n      },\n      zoomToRect: (rect, padding) => {\n        viewportHandleRef.current?.zoomToRect(rect, padding);\n      },\n      getTransform: () => getTransform(),\n      getSize: () =>\n        viewportHandleRef.current?.getSize() ?? { width: 0, height: 0 },\n      worldToScreen: point => screenFromWorld(point, getTransform()),\n      screenToWorld: point => worldFromScreen(point, getTransform()),\n      invalidate: layerName => viewportHandleRef.current?.invalidate(layerName),\n    }),\n    [nodesRef, selectionRef, defaultNodeSize, getTransform, store]\n  );\n\n  // Edge labels rendered as world-space children at the midpoint of each\n  // edge. Mounted as its own subscriber component so the labels follow\n  // dragged nodes live without re-rendering the whole NodeGraph.\n  const renderEdgeLabelRef = useLatest(renderEdgeLabel);\n\n  return (\n    <NodeGraphStoreContext.Provider value={store}>\n      {/*\n        The root is an event-delegation wrapper for graph-wide keyboard\n        shortcuts and pointer capture; it is not itself focusable. The\n        focusable, labelled interactive surface is the inner <Viewport>\n        (ariaLabel + ariaRoledescription=\"node graph\"), which jsx-a11y\n        cannot see through this wrapper.\n      */}\n      {/* eslint-disable-next-line jsx-a11y/no-static-element-interactions */}\n      <div\n        ref={rootRef}\n        id={id}\n        data-testid={testId}\n        onKeyDown={onKeyDown}\n        onContextMenu={handleContextMenu}\n        onPointerDownCapture={onRootPointerDownCapture}\n        onPointerMove={onRootPointerMove}\n        onPointerLeave={onRootPointerLeave}\n        className={cx(nodeGraphRootStyle, className)}\n        style={style}\n      >\n        <Viewport\n          ref={viewportHandleRef}\n          responsive={responsive}\n          height={height}\n          pan={pan}\n          zoom={zoom}\n          minZoom={minZoom}\n          maxZoom={maxZoom}\n          selectionRect={{ enabled: selectionRect, button: 'left' }}\n          onSelectionChange={handleViewportSelection}\n          onTransformChange={handleTransformChange}\n          disabled={disabled}\n          ariaLabel={ariaLabel}\n          ariaRoledescription=\"node graph\"\n        >\n          {slots.hasBackground ? (\n            <ViewportLayer name=\"background\" draw={drawBackgroundLayer} />\n          ) : null}\n          <ViewportLayer name=\"groups\" draw={drawGroupsLayer} />\n          <ViewportLayer name=\"edges\" draw={drawEdgesLayer} />\n          <ViewportWorld>\n            {groups.map(group => (\n              <NodeGraphGroupView\n                key={group.id}\n                group={group}\n                onBodyPointerDown={onGroupBodyPointerDown}\n                onBodyPointerUp={onGroupBodyPointerUp}\n                onHandlePointerDown={onGroupHandlePointerDown}\n                onBodyContextMenu={handleContextMenu}\n                onLabelChange={handleGroupLabelChange}\n                onColorChange={handleGroupColorChange}\n              />\n            ))}\n            {nodes.map(node => (\n              <NodeGraphNodeView\n                key={node.id}\n                node={node}\n                renderNode={renderNode}\n                onBodyPointerDown={onNodeBodyPointerDown}\n                onBodyPointerUp={onNodeBodyPointerUp}\n                onPortPointerDown={onPortPointerDown}\n                onBodyContextMenu={handleContextMenu}\n              />\n            ))}\n            <EdgeLabelsLayer\n              renderEdgeLabelRef={renderEdgeLabelRef}\n              hasRenderEdgeLabel={renderEdgeLabel !== undefined}\n            />\n          </ViewportWorld>\n          <ViewportLayer name=\"preview\" draw={drawPreviewLayer} />\n          {slots.hasMinimap || slots.toolbars.length > 0 ? (\n            <ViewportOverlay>\n              {slots.hasMinimap ? (\n                <NodeGraphMinimapInner {...(slots.minimapProps ?? {})} />\n              ) : null}\n              {slots.toolbars.map((toolbarProps, i) => (\n                <NodeGraphToolbarInner\n                  // Placement is part of the identity — multiple toolbars\n                  // in the same NodeGraph use different placements as\n                  // their natural key.\n                  key={toolbarProps.placement ?? `toolbar-${i}`}\n                  {...toolbarProps}\n                />\n              ))}\n            </ViewportOverlay>\n          ) : null}\n        </Viewport>\n        {/* SpawnPalette renders in a portal (via CommandPalette) so it\n            sits at the React tree root, outside the Viewport. Subscribes\n            to the store's spawn-request channel for right-click triggers. */}\n        {slots.spawnPaletteProps ? (\n          <NodeGraphSpawnPaletteInner {...slots.spawnPaletteProps} />\n        ) : null}\n      </div>\n    </NodeGraphStoreContext.Provider>\n  );\n};\n\n// ─── Compound exports ───\n\ntype NodeGraphCompound = typeof NodeGraphImpl & {\n  Minimap: typeof NodeGraphMinimap;\n  Background: typeof NodeGraphBackground;\n  Port: typeof NodeGraphPort;\n  PortVisual: typeof NodeGraphPortVisual;\n  Pin: typeof NodeGraphPin;\n  NodeBody: typeof NodeGraphNodeBody;\n  NodeHeader: typeof NodeGraphNodeHeader;\n  NodeSection: typeof NodeGraphNodeSection;\n  PinList: typeof NodeGraphPinList;\n  PinRow: typeof NodeGraphPinRow;\n  Toolbar: typeof NodeGraphToolbar;\n  ToolbarSeparator: typeof NodeGraphToolbarSeparator;\n  FitContentButton: typeof NodeGraphFitContentButton;\n  FitSelectionButton: typeof NodeGraphFitSelectionButton;\n  ZoomInButton: typeof NodeGraphZoomInButton;\n  ZoomOutButton: typeof NodeGraphZoomOutButton;\n  ResetZoomButton: typeof NodeGraphResetZoomButton;\n  SpawnPalette: typeof NodeGraphSpawnPalette;\n};\n\nNodeGraphImpl.displayName = 'NodeGraph';\n\nconst NodeGraphWithSlots = NodeGraphImpl as NodeGraphCompound;\nNodeGraphWithSlots.Minimap = NodeGraphMinimap;\nNodeGraphWithSlots.Background = NodeGraphBackground;\nNodeGraphWithSlots.Port = NodeGraphPort;\nNodeGraphWithSlots.PortVisual = NodeGraphPortVisual;\nNodeGraphWithSlots.Pin = NodeGraphPin;\nNodeGraphWithSlots.NodeBody = NodeGraphNodeBody;\nNodeGraphWithSlots.NodeHeader = NodeGraphNodeHeader;\nNodeGraphWithSlots.NodeSection = NodeGraphNodeSection;\nNodeGraphWithSlots.PinList = NodeGraphPinList;\nNodeGraphWithSlots.PinRow = NodeGraphPinRow;\nNodeGraphWithSlots.Toolbar = NodeGraphToolbar;\nNodeGraphWithSlots.ToolbarSeparator = NodeGraphToolbarSeparator;\nNodeGraphWithSlots.FitContentButton = NodeGraphFitContentButton;\nNodeGraphWithSlots.FitSelectionButton = NodeGraphFitSelectionButton;\nNodeGraphWithSlots.ZoomInButton = NodeGraphZoomInButton;\nNodeGraphWithSlots.ZoomOutButton = NodeGraphZoomOutButton;\nNodeGraphWithSlots.ResetZoomButton = NodeGraphResetZoomButton;\nNodeGraphWithSlots.SpawnPalette = NodeGraphSpawnPalette;\n\nexport const NodeGraph = NodeGraphWithSlots;\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsGA;AACA;AACA;AACA;AACE;AACA;AACA;;AAEF;AAEA;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACH;;AAyCE;AACA;AACA;;;;AAKA;;;;;AASA;AACE;AACA;AACA;AACA;AACD;AACD;AACE;AACA;AACA;AACA;AACD;AACD;AACE;AACA;AACA;AACA;AACD;AACD;AACE;AACA;AACA;AACA;AACD;;;;;;;;AASE;AACH;;AAGE;AACF;;AAGA;AACA;AACE;;;AAIF;;AAGA;;;;AAMI;AACA;;AACA;AACA;;;;AAQA;AACF;;AAKF;AACA;AACA;AACA;AACA;AACA;;;AAKI;AACA;;;AAGA;AACE;AACA;AAEE;;;;;;AAYJ;;AAQA;;AACA;AACE;;;;;AAKF;AACF;;;;;;;AAQC;;AAIH;AACE;;;;;;AAMA;AACA;AACD;;AAGD;;;;;;AAME;AACA;AACD;;AAGD;;;;;;;;AAYE;AACA;AACA;AACD;;;;;;;;AAUG;;AAEE;AAAuB;;AACU;AACjC;;;;AAKE;;;AAGJ;AACA;AACF;;AAME;;AACA;AAGA;AACF;;AAKF;AACA;;;AAGI;;;;AAII;AACA;AACA;;;AAGC;;AAEF;;;;;AAMH;;;;;;AAOA;;AAGE;;AAQE;;AAEE;AACA;AACA;AACD;;;;;AAML;AACE;AAKA;AAME;;;AAGJ;AACA;AACE;;;;;;;AAOE;AACA;AACA;AACD;AACH;AACF;;;;;;;;AASC;;AAIH;AACA;;;;;;;AAOI;;;;;;;AAOE;;;;AAIA;;;AAGA;;AAEF;;AAEA;;AAEE;AACE;;;;;;;;;;;AASJ;AACE;;;;;;AAMF;;;AAGA;;;AAGF;;;;;;;AAQC;;;;;;;;;AAYA;;;;;;;;;;;;;;AAeH;;;;;AAMI;;AAEA;;;;AAIA;;AAGE;;;AAIF;;;AAKA;;;;;;AASA;;;AAKA;AACF;;;;;;;;;AAUC;;AAIH;;AAEE;AACA;AACA;;;;AAID;;AAGD;AACA;AACA;AACA;AACA;;;AAQI;AACE;AACA;AACA;AACA;AACD;;;AAUD;AACA;AACA;;AAEA;AACF;AAIF;;AAMI;AACA;AACA;AACA;;AAEA;AAYF;;AASE;AACA;;;;AAOI;AAKA;AAAe;AACf;;AAIN;;;;;;AASA;AACE;AACF;AACA;AACE;;;AAGA;AACA;;;AAGA;AACA;;AAEA;;;;;AAKA;;;;AAIA;;;AAGA;;AAEA;;;;AAIA;;AAEF;;AAC8B;AAC9B;AACF;;AAGA;;AAIM;AACA;;AACA;;;;;;AASA;AACA;;AACA;AACA;;AACA;;AAIA;;;;;;AASA;AACA;;;AAEA;;AACA;;;;AAQC;;AAEH;;;AAGA;;;AAGA;AACA;;;AAIA;AACD;;;;AAOH;AAEA;;;;AAmFoB;AAetB;AAyBA;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AAEO;;"}

package/dist/esm/components/editor/NodeGraph/NodeGraph.types.js

@@ -0,0 +1,10 @@
+// ─── Slot markers ───
+/**
+ * Symbol attached to `<NodeGraph.Minimap>` and other slot subcomponents so
+ * the parent `<NodeGraph>` can identify them without relying on
+ * `displayName` (which gets clobbered by `React.memo` / minifiers).
+ */
+const NODE_GRAPH_SLOT = Symbol.for('etui.nodegraph.slot');
+
+export { NODE_GRAPH_SLOT };
+//# sourceMappingURL=NodeGraph.types.js.map

package/dist/esm/components/editor/NodeGraph/NodeGraph.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeGraph.types.js","sources":["src/components/editor/NodeGraph/NodeGraph.types.ts"],"sourcesContent":["import type { Point2D } from '@/components/primitives/canvas/canvas.types';\nimport type {\n  ViewportPanConfig,\n  ViewportSize,\n  ViewportTransform,\n  ViewportZoomConfig,\n  WorldRect,\n} from '@/components/primitives/viewport';\nimport type { BaseComponent } from '@/types/common';\nimport type { Prettify } from '@/types/utilities';\nimport type React from 'react';\n\n// ─── Geometry primitives ───\n\n/** Side of a node a port is anchored to. */\nexport type NodeGraphPortSide = 'left' | 'right' | 'top' | 'bottom';\n\n/** Reference to a single port on a node. */\nexport interface NodeGraphPortRef {\n  /** Owning node id. */\n  node: string;\n  /** Port id within that node. */\n  port: string;\n}\n\n// ─── Data model ───\n\nexport interface NodeGraphNode {\n  /** Stable identity. */\n  id: string;\n  /** Position in world coordinates (top-left corner of the node body). */\n  position: Point2D;\n  /**\n   * Override the auto-measured width of the node body. Use this when you\n   * need fixed-size nodes. When omitted, the library measures the rendered\n   * node DOM and uses that size for hit-testing, marquee selection, and\n   * minimap geometry.\n   */\n  width?: number;\n  /** Override the auto-measured height of the node body. See {@link width}. */\n  height?: number;\n  /** Arbitrary consumer payload passed to `renderNode`. */\n  data?: unknown;\n  /**\n   * When false, the node cannot be moved by drag. Selection still works.\n   * @default true\n   */\n  draggable?: boolean;\n  /**\n   * When false, the node cannot be selected (clicks pass through to the\n   * background). Drag is also disabled.\n   * @default true\n   */\n  selectable?: boolean;\n}\n\nexport interface NodeGraphEdge {\n  /** Stable identity. */\n  id: string;\n  /** Edge source endpoint. */\n  source: NodeGraphPortRef;\n  /** Edge target endpoint. */\n  target: NodeGraphPortRef;\n  /** Arbitrary consumer payload (e.g. animation flags, weights). */\n  data?: unknown;\n  /**\n   * Optional HTML label rendered absolutely above the edge midpoint.\n   * Use `renderEdgeLabel` for full control, or pass a node here for the\n   * default centred placement.\n   */\n  label?: React.ReactNode;\n  /**\n   * Override the stroke colour of this edge in its default state.\n   * Selected / hovered edges still pick up the theme accents (so the\n   * interaction state stays visible), this colour is used only when\n   * neither state is active. Useful for type-coloured wires — assign\n   * the colour at edge-creation time based on the source pin's data\n   * type, the way UE5 paints exec / float / bool wires differently.\n   */\n  color?: string;\n}\n\n/**\n * A visual backdrop rectangle drawn under nodes. Groups in v1 are purely\n * decorative — nodes are not children of a group, they simply happen to\n * overlap with it. Selection of a group through marquee/click can be\n * wired up by the consumer via `onContextMenu` / future selection API.\n */\nexport interface NodeGraphGroup {\n  /** Stable identity. */\n  id: string;\n  /** Group rectangle in world coordinates. */\n  bounds: WorldRect;\n  /** Optional title shown above the group's top edge. */\n  label?: string;\n  /** Optional CSS colour string used for the group tint and label. */\n  color?: string;\n}\n\nexport interface NodeGraphSelection {\n  /** Selected node ids. */\n  nodes: string[];\n  /** Selected edge ids. */\n  edges: string[];\n  /** Selected group ids. */\n  groups: string[];\n}\n\n// ─── Targets / events ───\n\n/** Discriminated union describing what was hit by a pointer event. */\nexport type NodeGraphTarget =\n  | { kind: 'node'; id: string }\n  | { kind: 'edge'; id: string }\n  | { kind: 'port'; node: string; port: string }\n  | { kind: 'group'; id: string }\n  | { kind: 'empty'; worldPoint: Point2D };\n\nexport interface NodeGraphContextMenuInfo {\n  target: NodeGraphTarget;\n  /** Screen-space (CSS-pixel) position of the pointer relative to viewport. */\n  screenPoint: Point2D;\n  /** World-space position of the pointer. */\n  worldPoint: Point2D;\n}\n\nexport interface NodeGraphConnectStartInfo {\n  source: NodeGraphPortRef;\n  /** World-space position the drag started at (the source port). */\n  worldPoint: Point2D;\n}\n\nexport interface NodeGraphConnectEndInfo {\n  source: NodeGraphPortRef;\n  /** Resolved drop target, or null when the drag ended on empty space. */\n  target: NodeGraphPortRef | null;\n  /** True when the drop was rejected (target invalid or empty). */\n  cancelled: boolean;\n  /**\n   * World-space position the drag was released at. With `cancelled` + a null\n   * `target` this is an empty-space drop — the hook for a \"drag a wire onto\n   * the canvas → open a create-node menu here → connect the new node to\n   * `source`\" flow. Place the spawned node at this point.\n   */\n  worldPoint: Point2D;\n  /**\n   * Screen-space (CSS-pixel, relative to the viewport top-left) release\n   * position — position your create-node menu / popover here.\n   */\n  screenPoint: Point2D;\n}\n\nexport interface NodeGraphConnectionValidationInfo {\n  /** True when source and target reference the same node. */\n  sameNode: boolean;\n  /** Side combination shorthand, e.g. `'right->left'`. */\n  sideCombo: string;\n  /** `dataType` declared on the source `<NodeGraph.Port>`, if any. */\n  sourceDataType?: string;\n  /** `dataType` declared on the target `<NodeGraph.Port>`, if any. */\n  targetDataType?: string;\n}\n\n// ─── Rendering ───\n\n/** Context passed to `renderNode`. */\nexport interface NodeGraphRenderCtx {\n  /** True when the node is part of the current selection. */\n  selected: boolean;\n  /** True when the node is being dragged (single or multi). */\n  dragging: boolean;\n  /** True when the pointer is hovering over the node body. */\n  hovered: boolean;\n  /** Current viewport zoom — useful for LOD rendering. */\n  zoom: number;\n}\n\n/** Resolved port metadata passed to the `edgeStyle` callback. */\nexport interface NodeGraphEdgeStyleCtx {\n  /** True when the edge is in the current selection. */\n  selected: boolean;\n  /** True when the pointer is currently hovering over the edge. */\n  hovered: boolean;\n  /**\n   * The `side` and `dataType` declared on the source `<NodeGraph.Port>`,\n   * resolved from the store. `null` when the port hasn't been measured\n   * yet (e.g. first paint before `useLayoutEffect` has run).\n   */\n  sourcePort: { side: NodeGraphPortSide; dataType?: string } | null;\n  /** Same for the target endpoint. */\n  targetPort: { side: NodeGraphPortSide; dataType?: string } | null;\n}\n\n/**\n * Style overrides for a single edge, returned by `edgeStyle`. Any field\n * left undefined falls back to the default (theme + `edge.color`).\n */\nexport interface NodeGraphEdgeStyle {\n  /** Stroke colour. Overrides `edge.color`. */\n  color?: string;\n  /** Stroke width in screen pixels. */\n  width?: number;\n  /**\n   * Marching-ant dash pattern, in screen pixels.\n   * Example: `[8, 6]` draws 8 px dash + 6 px gap repeating.\n   * Pass `null` (or omit) for a solid stroke.\n   */\n  dash?: ReadonlyArray<number> | null;\n}\n\n/**\n * Per-edge style hook. Called on every frame for every edge — keep it\n * cheap (map lookup, ternary). The library memoizes nothing here; if\n * the result is expensive, hoist into a `useMemo` keyed by inputs.\n */\nexport type NodeGraphEdgeStyleFn = (\n  edge: NodeGraphEdge,\n  ctx: NodeGraphEdgeStyleCtx\n) => NodeGraphEdgeStyle | undefined;\n\n// ─── Port slot ───\n\n/**\n * Built-in port handle shapes. `circle` is the default data-pin look,\n * `triangle` is the UE-style exec/flow arrow, `diamond` / `square` cover\n * the other common node-editor conventions. Render any other visual by\n * passing `children` to `<NodeGraph.Port>`.\n */\nexport type NodeGraphPortShape = 'circle' | 'triangle' | 'diamond' | 'square';\n\n/**\n * Props for `<NodeGraph.Port>` — the compound child rendered inside\n * `renderNode` to declare a connection endpoint.\n *\n * The library tracks the slot's DOM position and registers it as the\n * anchor for any edge that references this port. Pointer events on the\n * slot start a connection drag automatically — no manual wiring from the\n * consumer.\n *\n * @example\n * ```tsx\n * <NodeGraph\n *   renderNode={(node, ctx) => (\n *     <MyNodeBody>\n *       <Row>\n *         <NodeGraph.Port id=\"exec-in\" side=\"left\" dataType=\"exec\" />\n *         Execute\n *       </Row>\n *     </MyNodeBody>\n *   )}\n * />\n * ```\n */\nexport interface NodeGraphPortSlotProps {\n  /** Stable identity within the owning node — referenced by `NodeGraphEdge`. */\n  id: string;\n  /** Which side of the node the port anchors to. Determines Bézier tangent. */\n  side: NodeGraphPortSide;\n  /**\n   * Opaque type token forwarded to `isValidConnection` and exposed on\n   * `data-port-data-type` for CSS theming. Not interpreted by the library.\n   */\n  dataType?: string;\n  /**\n   * Built-in handle shape used when no `children` are supplied.\n   * @default 'circle'\n   */\n  shape?: NodeGraphPortShape;\n  /**\n   * Handle colour for the built-in visual (any CSS colour). When omitted,\n   * the port inherits the theme focus colour; the connection-drag states\n   * (source / candidate / invalid) still override it so interaction stays\n   * visible. Ignored when `children` are supplied.\n   */\n  color?: string;\n  /**\n   * Force the built-in visual filled (`true`) or hollow (`false`). When\n   * omitted, the port fills automatically while it is connected to at\n   * least one edge and stays hollow otherwise — the standard \"wired vs\n   * unwired pin\" convention. Ignored when `children` are supplied.\n   */\n  filled?: boolean;\n  /**\n   * Replace the built-in port visual entirely. When provided, no built-in\n   * chrome is rendered — the children fill the slot wrapper. State for\n   * theming (source / candidate / hover / invalid / connected) is exposed\n   * via `data-port-*` attributes on the wrapper.\n   */\n  children?: React.ReactNode;\n  /** Accessible label. Falls back to `${side} port ${id}`. */\n  label?: string;\n  /** Extra class applied to the slot wrapper. */\n  className?: string;\n  /** Inline style override on the slot wrapper. */\n  style?: React.CSSProperties;\n}\n\n// ─── Imperative handle ───\n\nexport interface NodeGraphHandle {\n  /** Pan/zoom so all nodes fit inside the viewport with optional padding. */\n  fitToContent(padding?: number): void;\n  /** Pan/zoom so all *selected* nodes fit. No-op when selection is empty. */\n  fitToSelection(padding?: number): void;\n  /** Center the viewport on a specific node. */\n  focusNode(id: string): void;\n  /** Center on a world point, optionally setting zoom. */\n  centerOn(point: Point2D, zoom?: number): void;\n  /** Pan/zoom to fit a world rectangle. */\n  zoomToRect(rect: WorldRect, padding?: number): void;\n  /** Read the current transform. */\n  getTransform(): ViewportTransform;\n  /** Read the current viewport size in CSS pixels. */\n  getSize(): ViewportSize;\n  /** Convert a world point to a screen (CSS-pixel) point. */\n  worldToScreen(point: Point2D): Point2D;\n  /** Convert a screen (CSS-pixel) point to a world point. */\n  screenToWorld(point: Point2D): Point2D;\n  /**\n   * Force a redraw. With no `layerName`, all canvas layers redraw on the\n   * next frame; with a name (`'edges' | 'groups' | 'preview'`), only that\n   * layer redraws.\n   */\n  invalidate(layerName?: NodeGraphLayerName): void;\n}\n\nexport type NodeGraphLayerName = 'groups' | 'edges' | 'preview';\n\n// ─── Slot markers ───\n\n/**\n * Symbol attached to `<NodeGraph.Minimap>` and other slot subcomponents so\n * the parent `<NodeGraph>` can identify them without relying on\n * `displayName` (which gets clobbered by `React.memo` / minifiers).\n */\nexport const NODE_GRAPH_SLOT: unique symbol = Symbol.for('etui.nodegraph.slot');\n\nexport type NodeGraphSlotKind =\n  | 'minimap'\n  | 'background'\n  | 'toolbar'\n  | 'spawn-palette';\n\n/**\n * Template registered with `<NodeGraph.SpawnPalette>` — describes a\n * spawn-able node + how to build it at a given world point. The\n * library handles search / filtering / focus / selection of templates\n * in the popover; this is the data slice consumer cares about.\n */\nexport interface NodeGraphTemplate {\n  /** Stable identifier (used for keys + the palette's recent list). */\n  id: string;\n  /** Human-readable title shown in the palette. */\n  title: string;\n  /** Optional secondary line. */\n  subtitle?: string;\n  /** Group label used to section the palette list. */\n  group?: string;\n  /** Extra strings the fuzzy matcher considers (synonyms, tags). */\n  keywords?: ReadonlyArray<string>;\n  /** Optional leading icon. */\n  icon?: React.ReactNode;\n  /**\n   * Build the node body from a world position. The library assigns\n   * the final `id` (so consumer doesn't have to roll their own\n   * uniqueness scheme) — return everything except `id`.\n   */\n  build: (worldPoint: Point2D) => Omit<NodeGraphNode, 'id'>;\n}\n\nexport interface NodeGraphSpawnContext {\n  /** World point where the user invoked the palette. */\n  worldPoint: Point2D;\n  /** Screen-space point (CSS pixels relative to viewport top-left). */\n  screenPoint: Point2D;\n}\n\nexport interface NodeGraphSpawnPaletteSlotProps {\n  /** All spawn-able templates. Filtering happens inside the library. */\n  templates: ReadonlyArray<NodeGraphTemplate>;\n  /**\n   * Called when the user picks a template. Library has already\n   * assigned an `id`; consumer typically appends to their nodes state.\n   */\n  onSpawn: (node: NodeGraphNode, ctx: NodeGraphSpawnContext) => void;\n  /** Placeholder for the search input. */\n  placeholder?: string;\n  /** localStorage key for the palette's recent list. */\n  recentKey?: string;\n  /** Popover width. @default 400 */\n  width?: number | string;\n  /** Popover max height. @default 360 */\n  maxHeight?: number;\n}\n\nexport interface NodeGraphToolbarSlotProps {\n  /**\n   * Anchored corner inside the graph. Defaults to top-left.\n   */\n  placement?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';\n  /** Distance from the edge, CSS px. @default 12 */\n  margin?: number;\n  /** Gap between toolbar buttons / children, CSS px. @default 4 */\n  gap?: number;\n  /** Optional className applied to the toolbar wrapper. */\n  className?: string;\n  /** Inline style override. */\n  style?: React.CSSProperties;\n  /** Toolbar contents — typically `<NodeGraph.FitContentButton>` etc. */\n  children?: React.ReactNode;\n}\n\nexport interface NodeGraphSlotMarker {\n  [NODE_GRAPH_SLOT]: NodeGraphSlotKind;\n}\n\n// ─── Props ───\n\nexport interface NodeGraphBaseProps extends Omit<\n  BaseComponent,\n  'onChange' | 'onContextMenu' | 'ref'\n> {\n  // ── Nodes (controlled / uncontrolled) ──\n  nodes?: NodeGraphNode[];\n  defaultNodes?: NodeGraphNode[];\n  onNodesChange?: (nodes: NodeGraphNode[]) => void;\n\n  // ── Edges (controlled / uncontrolled) ──\n  edges?: NodeGraphEdge[];\n  defaultEdges?: NodeGraphEdge[];\n  onEdgesChange?: (edges: NodeGraphEdge[]) => void;\n\n  // ── Groups (controlled / uncontrolled) ──\n  groups?: NodeGraphGroup[];\n  defaultGroups?: NodeGraphGroup[];\n  onGroupsChange?: (groups: NodeGraphGroup[]) => void;\n\n  // ── Selection (controlled / uncontrolled) ──\n  selection?: NodeGraphSelection;\n  defaultSelection?: NodeGraphSelection;\n  onSelectionChange?: (selection: NodeGraphSelection) => void;\n\n  // ── Rendering ──\n  /**\n   * Render the body of a node. The returned content sits inside a wrapper\n   * `<div>` positioned in world space — do not set position/transform\n   * yourself. Declare connection endpoints by placing `<NodeGraph.Port>`\n   * children anywhere inside the returned tree; the library tracks their\n   * DOM positions automatically and routes edges through them.\n   */\n  renderNode?: (\n    node: NodeGraphNode,\n    ctx: NodeGraphRenderCtx\n  ) => React.ReactNode;\n  /**\n   * Render a label above the midpoint of an edge. Receives the edge data.\n   * When omitted, `edge.label` is used as-is (if defined).\n   */\n  renderEdgeLabel?: (edge: NodeGraphEdge) => React.ReactNode;\n  /**\n   * Per-edge style hook called on every draw frame. The returned shape\n   * is shallow-merged into the default edge style; any field left\n   * undefined falls back to `edge.color` / theme defaults.\n   *\n   * The second argument carries resolved port metadata from the store\n   * so consumers don't need to maintain a parallel index just to colour\n   * wires by their source pin's `dataType`.\n   *\n   * @example\n   * ```tsx\n   * <NodeGraph\n   *   edgeStyle={(edge, ctx) => ({\n   *     color: TYPE_COLOR[ctx.sourcePort?.dataType ?? 'any'],\n   *     width: ctx.selected ? 3 : 1.5,\n   *   })}\n   * />\n   * ```\n   */\n  edgeStyle?: NodeGraphEdgeStyleFn;\n\n  // ── Interaction ──\n  /**\n   * Validate a connection between two ports. Return `false` to reject the\n   * drop; the preview edge is still drawn while the user is hovering, but\n   * styled as invalid.\n   */\n  isValidConnection?: (\n    source: NodeGraphPortRef,\n    target: NodeGraphPortRef,\n    info: NodeGraphConnectionValidationInfo\n  ) => boolean;\n  /**\n   * Snap node positions to a grid of `snapToGrid` world units. Pass `false`\n   * to disable snapping. Affects drag (mouse), not programmatic position\n   * updates.\n   * @default false\n   */\n  snapToGrid?: number | false;\n  /** Fired when a connection drag starts (pointer-down on a port). */\n  onConnectStart?: (info: NodeGraphConnectStartInfo) => void;\n  /** Fired when a connection drag ends (drop on a port or cancellation). */\n  onConnectEnd?: (info: NodeGraphConnectEndInfo) => void;\n  /**\n   * Fired on a context menu (right-click) over any part of the graph.\n   * Includes a discriminated target so the consumer can render contextual\n   * menus for nodes / edges / ports / groups / empty background.\n   */\n  onContextMenu?: (info: NodeGraphContextMenuInfo) => void;\n  /** Fired when Delete/Backspace is pressed with a non-empty selection. */\n  onDelete?: (selection: NodeGraphSelection) => void;\n  /** Fired when Enter is pressed with a single focused node. */\n  onActivate?: (node: NodeGraphNode) => void;\n\n  // ── Viewport pass-through ──\n  /**\n   * Pan gesture configuration, or `false` to disable. Defaults match\n   * `<Viewport>`: middle-mouse drag + space-key + left-drag.\n   */\n  pan?: ViewportPanConfig | false;\n  /** Zoom gesture configuration, or `false` to disable. */\n  zoom?: ViewportZoomConfig | false;\n  /** @default 0.1 */\n  minZoom?: number;\n  /** @default 4 */\n  maxZoom?: number;\n  /**\n   * Enable marquee selection rectangle. When true, dragging on empty\n   * background draws a marquee that selects intersecting nodes.\n   * @default true\n   */\n  selectionRect?: boolean;\n  /**\n   * Track parent size via `ResizeObserver`. Identical to `<Viewport>`'s\n   * `responsive`. @default false\n   */\n  responsive?: boolean;\n  /** Fixed height when not responsive. @default 480 */\n  height?: number;\n  /**\n   * Fallback size used when neither `node.width`/`height` nor the measured\n   * DOM size is yet available — for the brief window between mount and\n   * first ResizeObserver tick, and for the imperative `fitToContent` /\n   * minimap reads at first paint.\n   * @default { width: 180, height: 80 }\n   */\n  defaultNodeSize?: { width: number; height: number };\n  /**\n   * Disable all interaction and dim the surface.\n   * @default false\n   */\n  disabled?: boolean;\n\n  // ── Accessibility ──\n  /** @default 'Node graph' */\n  ariaLabel?: string;\n\n  /** Slot children: `<NodeGraph.Minimap>`, `<NodeGraph.Background>`. */\n  children?: React.ReactNode;\n\n  /** Imperative handle. */\n  ref?: React.Ref<NodeGraphHandle>;\n}\n\nexport type NodeGraphProps = Prettify<NodeGraphBaseProps>;\n\n// ─── Subcomponent props ───\n\n/**\n * Per-node colouring for the minimap. Return `{ color }` for a flat tinted\n * rect, or add `headerColor` for a two-tone \"header strip + body\" mini-node\n * that echoes the real node's look at a glance.\n */\nexport interface NodeGraphMinimapNodeStyle {\n  /** Body fill colour. Falls back to the minimap's default item colour. */\n  color?: string;\n  /** When set, a header strip is drawn on top in this colour (two-tone). */\n  headerColor?: string;\n}\n\nexport interface NodeGraphMinimapSlotProps {\n  /**\n   * Anchored position inside the graph. Matches `ViewportMinimap`'s\n   * `placement` (string preset or custom anchor object).\n   * @default 'bottom-right'\n   */\n  placement?:\n    | 'top-left'\n    | 'top-right'\n    | 'bottom-left'\n    | 'bottom-right'\n    | {\n        top?: number | string;\n        right?: number | string;\n        bottom?: number | string;\n        left?: number | string;\n        width?: number | string;\n        height?: number | string;\n      };\n  /** Distance from the edge for preset placements (CSS px). @default 12 */\n  margin?: number;\n  /** Minimap width in CSS pixels. @default 200 */\n  width?: number;\n  /** Optional title (rendered as `<Minimap.Title>`). */\n  title?: React.ReactNode;\n  /** Optional className applied to the minimap wrapper. */\n  className?: string;\n  /**\n   * CSS colour used to highlight selected nodes inside the minimap. When\n   * omitted, selected nodes use the same colour as unselected ones.\n   */\n  selectedColor?: string;\n  /**\n   * Per-node colouring. Return `{ color }` to tint the rect, or\n   * `{ color, headerColor }` to draw a two-tone header/body mini-node that\n   * mirrors the real node. When omitted, every node uses the default colour\n   * (or `selectedColor` while selected).\n   */\n  nodeStyle?: (node: NodeGraphNode) => NodeGraphMinimapNodeStyle | undefined;\n}\n\nexport interface NodeGraphBackgroundSlotProps {\n  /**\n   * Background style. `'dots'` and `'grid'` are built in; pass `'none'`\n   * for an opaque background only.\n   * @default 'dots'\n   */\n  variant?: 'dots' | 'grid' | 'none';\n  /**\n   * Grid spacing in world units. The pattern repeats at this interval\n   * regardless of zoom.\n   * @default 24\n   */\n  gap?: number;\n  /** Optional dot/line colour. Defaults to theme `border.default`. */\n  color?: string;\n  /** Optional background colour. Defaults to theme `background.primary`. */\n  background?: string;\n}\n"],"names":[],"mappings":"AAwUA;AAEA;;;;AAIG;AACI,MAAM,eAAe,GAAkB,MAAM,CAAC,GAAG,CAAC,qBAAqB;;;;"}

package/dist/esm/components/editor/NodeGraph/NodeGraphContext.js

@@ -0,0 +1,54 @@
+"use client";
+import { useContext, createContext, useSyncExternalStore } from 'react';
+
+const NodeGraphStoreContext = 
+/*#__PURE__*/ createContext(null);
+function useStoreInternal() {
+    const store = useContext(NodeGraphStoreContext);
+    if (!store) {
+        throw new Error('useNodeGraph* hooks must be called inside a <NodeGraph> component');
+    }
+    return store;
+}
+/**
+ * Access the underlying `NodeGraphStore` instance — escape hatch for
+ * subscribing to custom slice combinations or for imperative reads from
+ * non-React code paths (gesture handlers, canvas draw frames).
+ */
+function useNodeGraphStore() {
+    return useStoreInternal();
+}
+/**
+ * Subscribe to the data slice — re-renders when the graph contents
+ * (`nodes`, `edges`, `groups`, default size) change.
+ */
+function useNodeGraphData() {
+    const store = useStoreInternal();
+    return useSyncExternalStore(store.subscribeData, store.getData);
+}
+/**
+ * Subscribe to the selection slice — re-renders when the selection changes.
+ */
+function useNodeGraphSelection() {
+    const store = useStoreInternal();
+    return useSyncExternalStore(store.subscribeSelection, store.getSelection);
+}
+/**
+ * Subscribe to the interaction slice — re-renders on gesture lifecycle
+ * (drag, connect, marquee) and on per-frame deltas during a drag.
+ */
+function useNodeGraphInteraction() {
+    const store = useStoreInternal();
+    return useSyncExternalStore(store.subscribeInteraction, store.getInteraction);
+}
+/**
+ * Subscribe to the hover slice — re-renders when the hovered node / edge /
+ * port changes.
+ */
+function useNodeGraphHover() {
+    const store = useStoreInternal();
+    return useSyncExternalStore(store.subscribeHover, store.getHover);
+}
+
+export { NodeGraphStoreContext, useNodeGraphData, useNodeGraphHover, useNodeGraphInteraction, useNodeGraphSelection, useNodeGraphStore };
+//# sourceMappingURL=NodeGraphContext.js.map

package/dist/esm/components/editor/NodeGraph/NodeGraphContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeGraphContext.js","sources":["src/components/editor/NodeGraph/NodeGraphContext.ts"],"sourcesContent":["'use client';\n\nimport { createContext, useContext, useSyncExternalStore } from 'react';\n\nimport type { NodeGraphSelection } from './NodeGraph.types';\nimport type {\n  NodeGraphDataState,\n  NodeGraphHoverState,\n  NodeGraphInteractionState,\n  NodeGraphStore,\n} from './NodeGraphStore';\n\nexport const NodeGraphStoreContext =\n  /*#__PURE__*/ createContext<NodeGraphStore | null>(null);\n\nfunction useStoreInternal(): NodeGraphStore {\n  const store = useContext(NodeGraphStoreContext);\n  if (!store) {\n    throw new Error(\n      'useNodeGraph* hooks must be called inside a <NodeGraph> component'\n    );\n  }\n  return store;\n}\n\n/**\n * Access the underlying `NodeGraphStore` instance — escape hatch for\n * subscribing to custom slice combinations or for imperative reads from\n * non-React code paths (gesture handlers, canvas draw frames).\n */\nexport function useNodeGraphStore(): NodeGraphStore {\n  return useStoreInternal();\n}\n\n/**\n * Subscribe to the data slice — re-renders when the graph contents\n * (`nodes`, `edges`, `groups`, default size) change.\n */\nexport function useNodeGraphData(): NodeGraphDataState {\n  const store = useStoreInternal();\n  return useSyncExternalStore(store.subscribeData, store.getData);\n}\n\n/**\n * Subscribe to the selection slice — re-renders when the selection changes.\n */\nexport function useNodeGraphSelection(): NodeGraphSelection {\n  const store = useStoreInternal();\n  return useSyncExternalStore(store.subscribeSelection, store.getSelection);\n}\n\n/**\n * Subscribe to the interaction slice — re-renders on gesture lifecycle\n * (drag, connect, marquee) and on per-frame deltas during a drag.\n */\nexport function useNodeGraphInteraction(): NodeGraphInteractionState {\n  const store = useStoreInternal();\n  return useSyncExternalStore(store.subscribeInteraction, store.getInteraction);\n}\n\n/**\n * Subscribe to the hover slice — re-renders when the hovered node / edge /\n * port changes.\n */\nexport function useNodeGraphHover(): NodeGraphHoverState {\n  const store = useStoreInternal();\n  return useSyncExternalStore(store.subscribeHover, store.getHover);\n}\n"],"names":[],"mappings":";;;;AAaE;AAEF;AACE;;AAEE;;AAIF;AACF;AAEA;;;;AAIG;;;AAGH;AAEA;;;AAGG;;AAED;;AAEF;AAEA;;AAEG;;AAED;;AAEF;AAEA;;;AAGG;;AAED;;AAEF;AAEA;;;AAGG;;AAED;;AAEF;;"}

package/dist/esm/components/editor/NodeGraph/NodeGraphEdgeLabels.js

@@ -0,0 +1,137 @@
+"use client";
+import { jsx, Fragment } from 'react/jsx-runtime';
+import { useSyncExternalStore, useCallback } from 'react';
+import { useNodeGraphStore } from './NodeGraphContext.js';
+import { resolvePortRef } from './nodeGraphMath.js';
+import { useStoreSlice } from './useStoreSlice.js';
+
+// Shared sentinel for "this edge isn't affected by the current gesture" —
+// one reference so the equality check below short-circuits cleanly.
+const NO_EDGE_DELTAS = { src: null, tgt: null };
+function pointEqualNullable(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    return a.x === b.x && a.y === b.y;
+}
+function edgeDeltasEqual(a, b) {
+    return pointEqualNullable(a.src, b.src) && pointEqualNullable(a.tgt, b.tgt);
+}
+/**
+ * Live drag delta for an edge's endpoints, or {@link NO_EDGE_DELTAS} when
+ * neither endpoint's node is part of the current drag. Mirrors the per-node
+ * selector in `NodeGraphNode` so a label only updates when an endpoint it
+ * actually owns is moving.
+ */
+function selectEdgeDeltas(interaction, sourceNode, targetNode) {
+    let ids = null;
+    let delta = null;
+    if (interaction.kind === 'drag-nodes') {
+        ids = interaction.nodeIds;
+        delta = interaction.delta;
+    }
+    else if (interaction.kind === 'drag-groups') {
+        ids = interaction.containedNodeIds;
+        delta = interaction.delta;
+    }
+    if (!ids || !delta)
+        return NO_EDGE_DELTAS;
+    const src = ids.has(sourceNode) ? delta : null;
+    const tgt = ids.has(targetNode) ? delta : null;
+    if (src === null && tgt === null)
+        return NO_EDGE_DELTAS;
+    return { src, tgt };
+}
+/**
+ * Mounts one `<EdgeLabel>` per edge as a world-space sibling inside
+ * `<ViewportWorld>`. Each label subscribes to the interaction slice on
+ * its own so a drag of an unrelated node doesn't re-render every label
+ * in the graph — only the labels whose endpoints actually move.
+ *
+ * One subscriber per edge: each `EdgeLabel` subscribes to the `interaction`
+ * slice through `useStoreSlice` with an endpoint-delta selector + equality,
+ * so it re-renders only when an endpoint it actually owns moves. Labels on
+ * edges untouched by the current gesture short-circuit on the equality check
+ * and skip the per-frame re-render entirely.
+ */
+function EdgeLabelsLayer({ renderEdgeLabelRef, hasRenderEdgeLabel, }) {
+    const store = useNodeGraphStore();
+    // Subscribe to data + port positions at this level so we know which
+    // edges exist. Each `EdgeLabel` below subscribes to interaction on its
+    // own for live drag tracking.
+    const data = useSyncExternalStore(store.subscribeData, store.getData);
+    useSyncExternalStore(store.subscribePortPositions, store.getPortPositionsVersion);
+    return (jsx(Fragment, { children: data.edges.map(edge => {
+            // Skip mounting an `EdgeLabel` subscriber when there's nothing it
+            // could ever render. When `renderEdgeLabel` is provided the
+            // consumer controls visibility per edge from inside their callback
+            // (and may return `null`), so we still have to mount — but if no
+            // callback exists, the only thing the label could show is
+            // `edge.label`, and a `null` value there means there's nothing to
+            // draw and no reason to pay for a per-edge store subscription.
+            if (!hasRenderEdgeLabel && edge.label == null)
+                return null;
+            return (jsx(EdgeLabel, { edge: edge, renderEdgeLabelRef: renderEdgeLabelRef }, edge.id));
+        }) }));
+}
+function EdgeLabel({ edge, renderEdgeLabelRef, }) {
+    const store = useNodeGraphStore();
+    const sourceNode = edge.source.node;
+    const targetNode = edge.target.node;
+    // Subscribe to interaction changes affecting either endpoint via the
+    // per-node channel — a drag of an unrelated node never wakes this
+    // subscriber, even before the selector runs. When source and target
+    // sit on the same node, a single subscription is enough (deduplicates
+    // the notification).
+    const subscribeEndpoints = useCallback((cb) => {
+        const unsubSource = store.subscribeNodeInteraction(sourceNode, cb);
+        if (sourceNode === targetNode)
+            return unsubSource;
+        const unsubTarget = store.subscribeNodeInteraction(targetNode, cb);
+        return () => {
+            unsubSource();
+            unsubTarget();
+        };
+    }, [store, sourceNode, targetNode]);
+    // Selector still reads the global snapshot to compute per-endpoint
+    // deltas — the subscription change above only narrows *when* this
+    // subscriber gets woken, not *what* it sees.
+    const { src: srcDelta, tgt: tgtDelta } = useStoreSlice(subscribeEndpoints, store.getInteraction, interaction => selectEdgeDeltas(interaction, sourceNode, targetNode), edgeDeltasEqual);
+    // Re-render when port positions update too (initial measure + body
+    // re-layout shift the anchor).
+    useSyncExternalStore(store.subscribePortPositions, store.getPortPositionsVersion);
+    const src = resolvePortRef(edge.source, store.getNodeById, store.getPortPosition);
+    const tgt = resolvePortRef(edge.target, store.getNodeById, store.getPortPosition);
+    if (!src || !tgt)
+        return null;
+    const sx = src.position.x + (srcDelta?.x ?? 0);
+    const sy = src.position.y + (srcDelta?.y ?? 0);
+    const tx = tgt.position.x + (tgtDelta?.x ?? 0);
+    const ty = tgt.position.y + (tgtDelta?.y ?? 0);
+    const midX = (sx + tx) / 2;
+    const midY = (sy + ty) / 2;
+    // The render callback lives in a `useLatest` ref so swapping it doesn't
+    // re-render every edge label; reading the current value here is deliberate.
+    // Labels refresh on the next data / interaction tick, which is the only
+    // moment their content is consumed anyway.
+    // eslint-disable-next-line react-hooks/refs -- intentional latest-callback read
+    const render = renderEdgeLabelRef.current;
+    const content = render ? render(edge) : (edge.label ?? null);
+    if (content == null || content === false)
+        return null;
+    return (jsx("div", { style: {
+            position: 'absolute',
+            left: 0,
+            top: 0,
+            // World-space position via `transform` so each frame's update is
+            // a GPU-friendly transform mutation (no CSS layout). The
+            // -50%/-50% piece centres the label on its midpoint.
+            transform: `translate3d(${midX}px, ${midY}px, 0) translate(-50%, -50%)`,
+            pointerEvents: 'auto',
+            willChange: 'transform',
+        }, children: content }));
+}
+
+export { EdgeLabelsLayer };
+//# sourceMappingURL=NodeGraphEdgeLabels.js.map

package/dist/esm/components/editor/NodeGraph/NodeGraphEdgeLabels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeGraphEdgeLabels.js","sources":["src/components/editor/NodeGraph/NodeGraphEdgeLabels.tsx"],"sourcesContent":["'use client';\n\nimport React, { useCallback, useSyncExternalStore } from 'react';\n\nimport { useNodeGraphStore } from './NodeGraphContext';\nimport { resolvePortRef } from './nodeGraphMath';\nimport { useStoreSlice } from './useStoreSlice';\n\nimport type { NodeGraphEdge } from './NodeGraph.types';\nimport type { NodeGraphInteractionState } from './NodeGraphStore';\nimport type { Point2D } from '@/components/primitives/canvas/canvas.types';\n\ninterface RenderEdgeLabelRef {\n  current: ((edge: NodeGraphEdge) => React.ReactNode) | undefined;\n}\n\n/** Live drag deltas for an edge's two endpoints during the current gesture. */\ninterface EdgeEndpointDeltas {\n  src: Point2D | null;\n  tgt: Point2D | null;\n}\n\n// Shared sentinel for \"this edge isn't affected by the current gesture\" —\n// one reference so the equality check below short-circuits cleanly.\nconst NO_EDGE_DELTAS: EdgeEndpointDeltas = { src: null, tgt: null };\n\nfunction pointEqualNullable(a: Point2D | null, b: Point2D | null): boolean {\n  if (a === b) return true;\n  if (a === null || b === null) return false;\n  return a.x === b.x && a.y === b.y;\n}\n\nfunction edgeDeltasEqual(\n  a: EdgeEndpointDeltas,\n  b: EdgeEndpointDeltas\n): boolean {\n  return pointEqualNullable(a.src, b.src) && pointEqualNullable(a.tgt, b.tgt);\n}\n\n/**\n * Live drag delta for an edge's endpoints, or {@link NO_EDGE_DELTAS} when\n * neither endpoint's node is part of the current drag. Mirrors the per-node\n * selector in `NodeGraphNode` so a label only updates when an endpoint it\n * actually owns is moving.\n */\nfunction selectEdgeDeltas(\n  interaction: NodeGraphInteractionState,\n  sourceNode: string,\n  targetNode: string\n): EdgeEndpointDeltas {\n  let ids: ReadonlySet<string> | null = null;\n  let delta: Point2D | null = null;\n  if (interaction.kind === 'drag-nodes') {\n    ids = interaction.nodeIds;\n    delta = interaction.delta;\n  } else if (interaction.kind === 'drag-groups') {\n    ids = interaction.containedNodeIds;\n    delta = interaction.delta;\n  }\n  if (!ids || !delta) return NO_EDGE_DELTAS;\n  const src = ids.has(sourceNode) ? delta : null;\n  const tgt = ids.has(targetNode) ? delta : null;\n  if (src === null && tgt === null) return NO_EDGE_DELTAS;\n  return { src, tgt };\n}\n\n/**\n * Mounts one `<EdgeLabel>` per edge as a world-space sibling inside\n * `<ViewportWorld>`. Each label subscribes to the interaction slice on\n * its own so a drag of an unrelated node doesn't re-render every label\n * in the graph — only the labels whose endpoints actually move.\n *\n * One subscriber per edge: each `EdgeLabel` subscribes to the `interaction`\n * slice through `useStoreSlice` with an endpoint-delta selector + equality,\n * so it re-renders only when an endpoint it actually owns moves. Labels on\n * edges untouched by the current gesture short-circuit on the equality check\n * and skip the per-frame re-render entirely.\n */\nexport function EdgeLabelsLayer({\n  renderEdgeLabelRef,\n  hasRenderEdgeLabel,\n}: {\n  renderEdgeLabelRef: RenderEdgeLabelRef;\n  /**\n   * Whether the consumer supplied a `renderEdgeLabel` callback. When `false`,\n   * edges without an explicit `edge.label` prop are skipped — no `EdgeLabel`\n   * subscriber is mounted for them. This avoids the cost of one interaction-\n   * slice subscriber per edge in graphs that don't use labels at all (the\n   * benchmark, simple recipes, etc.), which is otherwise pure waste — the\n   * subscriber fires on every drag tick and the body returns `null`.\n   */\n  hasRenderEdgeLabel: boolean;\n}): React.ReactElement | null {\n  const store = useNodeGraphStore();\n  // Subscribe to data + port positions at this level so we know which\n  // edges exist. Each `EdgeLabel` below subscribes to interaction on its\n  // own for live drag tracking.\n  const data = useSyncExternalStore(store.subscribeData, store.getData);\n  useSyncExternalStore(\n    store.subscribePortPositions,\n    store.getPortPositionsVersion\n  );\n\n  return (\n    <>\n      {data.edges.map(edge => {\n        // Skip mounting an `EdgeLabel` subscriber when there's nothing it\n        // could ever render. When `renderEdgeLabel` is provided the\n        // consumer controls visibility per edge from inside their callback\n        // (and may return `null`), so we still have to mount — but if no\n        // callback exists, the only thing the label could show is\n        // `edge.label`, and a `null` value there means there's nothing to\n        // draw and no reason to pay for a per-edge store subscription.\n        if (!hasRenderEdgeLabel && edge.label == null) return null;\n        return (\n          <EdgeLabel\n            key={edge.id}\n            edge={edge}\n            renderEdgeLabelRef={renderEdgeLabelRef}\n          />\n        );\n      })}\n    </>\n  );\n}\n\nfunction EdgeLabel({\n  edge,\n  renderEdgeLabelRef,\n}: {\n  edge: NodeGraphEdge;\n  renderEdgeLabelRef: RenderEdgeLabelRef;\n}): React.ReactElement | null {\n  const store = useNodeGraphStore();\n  const sourceNode = edge.source.node;\n  const targetNode = edge.target.node;\n  // Subscribe to interaction changes affecting either endpoint via the\n  // per-node channel — a drag of an unrelated node never wakes this\n  // subscriber, even before the selector runs. When source and target\n  // sit on the same node, a single subscription is enough (deduplicates\n  // the notification).\n  const subscribeEndpoints = useCallback(\n    (cb: () => void): (() => void) => {\n      const unsubSource = store.subscribeNodeInteraction(sourceNode, cb);\n      if (sourceNode === targetNode) return unsubSource;\n      const unsubTarget = store.subscribeNodeInteraction(targetNode, cb);\n      return () => {\n        unsubSource();\n        unsubTarget();\n      };\n    },\n    [store, sourceNode, targetNode]\n  );\n  // Selector still reads the global snapshot to compute per-endpoint\n  // deltas — the subscription change above only narrows *when* this\n  // subscriber gets woken, not *what* it sees.\n  const { src: srcDelta, tgt: tgtDelta } = useStoreSlice<\n    NodeGraphInteractionState,\n    EdgeEndpointDeltas\n  >(\n    subscribeEndpoints,\n    store.getInteraction,\n    interaction => selectEdgeDeltas(interaction, sourceNode, targetNode),\n    edgeDeltasEqual\n  );\n  // Re-render when port positions update too (initial measure + body\n  // re-layout shift the anchor).\n  useSyncExternalStore(\n    store.subscribePortPositions,\n    store.getPortPositionsVersion\n  );\n\n  const src = resolvePortRef(\n    edge.source,\n    store.getNodeById,\n    store.getPortPosition\n  );\n  const tgt = resolvePortRef(\n    edge.target,\n    store.getNodeById,\n    store.getPortPosition\n  );\n  if (!src || !tgt) return null;\n\n  const sx = src.position.x + (srcDelta?.x ?? 0);\n  const sy = src.position.y + (srcDelta?.y ?? 0);\n  const tx = tgt.position.x + (tgtDelta?.x ?? 0);\n  const ty = tgt.position.y + (tgtDelta?.y ?? 0);\n  const midX = (sx + tx) / 2;\n  const midY = (sy + ty) / 2;\n  // The render callback lives in a `useLatest` ref so swapping it doesn't\n  // re-render every edge label; reading the current value here is deliberate.\n  // Labels refresh on the next data / interaction tick, which is the only\n  // moment their content is consumed anyway.\n  // eslint-disable-next-line react-hooks/refs -- intentional latest-callback read\n  const render = renderEdgeLabelRef.current;\n  const content = render ? render(edge) : (edge.label ?? null);\n  if (content == null || content === false) return null;\n\n  return (\n    <div\n      style={{\n        position: 'absolute',\n        left: 0,\n        top: 0,\n        // World-space position via `transform` so each frame's update is\n        // a GPU-friendly transform mutation (no CSS layout). The\n        // -50%/-50% piece centres the label on its midpoint.\n        transform: `translate3d(${midX}px, ${midY}px, 0) translate(-50%, -50%)`,\n        pointerEvents: 'auto',\n        willChange: 'transform',\n      }}\n    >\n      {content}\n    </div>\n  );\n}\n"],"names":[],"mappings":";;;;;;;AAsBA;AACA;AACA;AAEA;;AACe;AACb;AAA8B;AAC9B;AACF;AAEA;;AAKA;AAEA;;;;;AAKG;AACH;;;AAOE;AACE;AACA;;AACK;AACL;AACA;;AAEF;AAAoB;AACpB;AACA;AACA;AAAkC;AAClC;AACF;AAEA;;;;;;;;;;;AAWG;;AAgBD;;;;AAIA;;;;;;;;;;AAgBM;AAA+C;AAC/C;;AAUR;AAEA;AAOE;AACA;AACA;;;;;;AAMA;;;AAGmC;;AAE/B;AACE;AACA;AACF;;;;;AAOJ;;;;AAgBA;AAKA;AAKA;AAAkB;AAElB;AACA;AACA;AACA;;;;;;;;AAQA;;AAEA;AAA0C;;AAKpC;AACA;AACA;;;;AAIA;AACA;AACA;;AAMR;;"}

package/dist/esm/components/editor/NodeGraph/NodeGraphGroup.js

@@ -0,0 +1,211 @@
+"use client";
+import { jsxs, jsx } from 'react/jsx-runtime';
+import React, { useState, useRef, useEffect, useCallback } from 'react';
+import { ColorPicker } from '../../controls/ColorPicker/ColorPicker.js';
+import { Popover } from '../../primitives/Popover/Popover.js';
+import { PopoverContent } from '../../primitives/Popover/PopoverContent.js';
+import { PopoverTrigger } from '../../primitives/Popover/PopoverTrigger.js';
+import { cx } from '../../../utils/cx.js';
+import { groupLabelBarStyle, groupLabelInputStyle, groupLabelStyle, groupColorSwatchStyle, groupResizeHandleStyle, groupOverlayRecipe } from './NodeGraph.css.js';
+import { useNodeGraphStore } from './NodeGraphContext.js';
+import { applyGroupResize } from './nodeGraphMath.js';
+import { useStoreSlice } from './useStoreSlice.js';
+
+const RESIZE_CURSORS = {
+    nw: 'nwse-resize',
+    n: 'ns-resize',
+    ne: 'nesw-resize',
+    e: 'ew-resize',
+    se: 'nwse-resize',
+    s: 'ns-resize',
+    sw: 'nesw-resize',
+    w: 'ew-resize',
+};
+const HANDLE_POSITIONS = {
+    nw: { left: '-5px', top: '-5px' },
+    n: { left: 'calc(50% - 5px)', top: '-5px' },
+    ne: { right: '-5px', top: '-5px' },
+    e: { right: '-5px', top: 'calc(50% - 5px)' },
+    se: { right: '-5px', bottom: '-5px' },
+    s: { left: 'calc(50% - 5px)', bottom: '-5px' },
+    sw: { left: '-5px', bottom: '-5px' },
+    w: { left: '-5px', top: 'calc(50% - 5px)' },
+};
+const ALL_HANDLES = [
+    'nw',
+    'n',
+    'ne',
+    'e',
+    'se',
+    's',
+    'sw',
+    'w',
+];
+const DEFAULT_PICKER_COLOR = '#5d8dff';
+function gestureStateEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (a.kind !== b.kind)
+        return false;
+    if (a.blocked !== b.blocked)
+        return false;
+    if (a.kind === 'drag' && b.kind === 'drag') {
+        return a.delta.x === b.delta.x && a.delta.y === b.delta.y;
+    }
+    if (a.kind === 'resize' && b.kind === 'resize') {
+        return (a.handle === b.handle &&
+            a.delta.x === b.delta.x &&
+            a.delta.y === b.delta.y &&
+            a.startBounds.x === b.startBounds.x &&
+            a.startBounds.y === b.startBounds.y &&
+            a.startBounds.width === b.startBounds.width &&
+            a.startBounds.height === b.startBounds.height);
+    }
+    return false;
+}
+function selectGroupGesture(interaction, groupId) {
+    if (interaction.kind === 'drag-groups' && interaction.groupIds.has(groupId)) {
+        return {
+            kind: 'drag',
+            delta: interaction.delta,
+            blocked: interaction.blocked,
+        };
+    }
+    if (interaction.kind === 'resize-group' && interaction.groupId === groupId) {
+        return {
+            kind: 'resize',
+            handle: interaction.handle,
+            startBounds: interaction.startBounds,
+            delta: interaction.delta,
+            blocked: interaction.blocked,
+        };
+    }
+    return null;
+}
+function computeLiveBounds(group, gesture) {
+    if (gesture === null)
+        return group.bounds;
+    if (gesture.kind === 'drag') {
+        return {
+            x: group.bounds.x + gesture.delta.x,
+            y: group.bounds.y + gesture.delta.y,
+            width: group.bounds.width,
+            height: group.bounds.height,
+        };
+    }
+    return applyGroupResize(gesture.startBounds, gesture.handle, gesture.delta);
+}
+/**
+ * Render a single interactive group overlay positioned in world space.
+ * The canvas layer draws the visual fill underneath — this HTML element
+ * handles selection, drag-to-move, corner/edge resize, label editing,
+ * and the colour swatch.
+ *
+ * Uses per-id selectors so a group only re-renders when *its* selection
+ * or gesture state changes — drag deltas of other groups never reach the
+ * subscriber.
+ *
+ * Wrapped in `React.memo` for the same reason as
+ * {@link NodeGraphNodeView}: a parent render caused by an unrelated
+ * controlled-state update would otherwise iterate every group. Handlers
+ * passed from `NodeGraphImpl` are all `useCallback`-stable.
+ */
+function NodeGraphGroupViewImpl({ group, onBodyPointerDown, onBodyPointerUp, onHandlePointerDown, onBodyContextMenu, onLabelChange, onColorChange, }) {
+    const store = useNodeGraphStore();
+    const groupId = group.id;
+    const selected = useStoreSlice(store.subscribeSelection, store.getSelection, sel => sel.groups.includes(groupId));
+    const gesture = useStoreSlice(store.subscribeInteraction, store.getInteraction, interaction => selectGroupGesture(interaction, groupId), gestureStateEqual);
+    const dragging = gesture?.kind === 'drag';
+    const blocked = gesture?.blocked ?? false;
+    const bounds = computeLiveBounds(group, gesture);
+    // ── Inline label edit ──
+    // `draft` is initialised from `group.label` on mount and re-synced by
+    // `cancelLabel` / `commitLabel` / `handleLabelDoubleClick` on every
+    // transition out of / into edit mode. Mirroring `group.label` into
+    // state via a side effect would be the classic anti-pattern.
+    const [editing, setEditing] = useState(false);
+    const [draft, setDraft] = useState(group.label ?? '');
+    const inputRef = useRef(null);
+    useEffect(() => {
+        if (editing) {
+            // Defer focus until the input has been mounted.
+            inputRef.current?.focus();
+            inputRef.current?.select();
+        }
+    }, [editing]);
+    const commitLabel = useCallback(() => {
+        const trimmed = draft.trim();
+        setEditing(false);
+        if (trimmed === (group.label ?? ''))
+            return;
+        onLabelChange(group, trimmed);
+    }, [draft, group, onLabelChange]);
+    const cancelLabel = useCallback(() => {
+        setEditing(false);
+        setDraft(group.label ?? '');
+    }, [group.label]);
+    const handleLabelDoubleClick = useCallback((event) => {
+        event.stopPropagation();
+        // Re-sync from the prop on open — covers the case where `group.label`
+        // changed externally while we weren't editing, so the input opens
+        // with the current value rather than a stale draft.
+        setDraft(group.label ?? '');
+        setEditing(true);
+    }, [group.label]);
+    const handleInputKeyDown = useCallback((event) => {
+        if (event.key === 'Enter') {
+            event.preventDefault();
+            commitLabel();
+        }
+        else if (event.key === 'Escape') {
+            event.preventDefault();
+            cancelLabel();
+        }
+        // Stop arrow keys from triggering the graph's nudge handler.
+        event.stopPropagation();
+    }, [commitLabel, cancelLabel]);
+    // ── Colour picker ──
+    //
+    // The swatch is a `<button>` that triggers the entangle-ui `<ColorPicker>`
+    // popover. The picker has `showAlpha` enabled so it returns proper
+    // `rgba(...)` strings when the user lowers opacity — the canvas
+    // `drawGroups` fill plumbs that straight through with no transform.
+    const handleColorChange = useCallback((next) => {
+        onColorChange(group, next);
+    }, [group, onColorChange]);
+    // Picker value falls back to a sensible default when the group hasn't
+    // been coloured yet (the library doesn't impose a default).
+    const pickerValue = group.color ?? DEFAULT_PICKER_COLOR;
+    return (jsxs("div", { className: cx(groupOverlayRecipe({ selected, dragging, blocked })), style: {
+            left: bounds.x,
+            top: bounds.y,
+            width: bounds.width,
+            height: bounds.height,
+        }, "data-group-id": group.id, "data-blocked": blocked || undefined, onPointerDown: e => {
+            onBodyPointerDown(e, group);
+        }, onPointerUp: e => {
+            onBodyPointerUp(e, group);
+        }, onContextMenu: onBodyContextMenu, children: [jsxs("div", { className: groupLabelBarStyle, 
+                // Don't let pointerdown on the label bar (label text, color swatch,
+                // input) fall through to the body drag handler — the label bar is
+                // an interactive control row, not a draggable handle.
+                onPointerDown: e => {
+                    e.stopPropagation();
+                }, children: [editing ? (jsx("input", { ref: inputRef, className: groupLabelInputStyle, value: draft, placeholder: "Group name", spellCheck: false, onChange: e => {
+                            setDraft(e.target.value);
+                        }, onBlur: commitLabel, onKeyDown: handleInputKeyDown })) : (jsx("span", { className: groupLabelStyle, onDoubleClick: handleLabelDoubleClick, title: "Double-click to rename", children: group.label?.trim() ? group.label : 'Group' })), jsxs(Popover, { placement: "bottom-end", children: [jsx(PopoverTrigger, { children: jsx("button", { type: "button", "aria-label": "Change group colour", title: "Change group colour", className: groupColorSwatchStyle, style: { background: group.color ?? DEFAULT_PICKER_COLOR } }) }), jsx(PopoverContent, { padding: "md", children: jsx(ColorPicker, { inline: true, showAlpha: true, defaultValue: pickerValue, format: "rgba", palette: "material", onChangeComplete: handleColorChange }) })] })] }), selected
+                ? ALL_HANDLES.map(handle => (jsx("div", { className: groupResizeHandleStyle, style: {
+                        ...HANDLE_POSITIONS[handle],
+                        cursor: RESIZE_CURSORS[handle],
+                    }, "data-group-id": group.id, "data-group-handle": handle, onPointerDown: e => {
+                        onHandlePointerDown(e, group, handle);
+                    } }, handle)))
+                : null] }));
+}
+const NodeGraphGroupView = React.memo(NodeGraphGroupViewImpl);
+NodeGraphGroupView.displayName = 'NodeGraphGroupView';
+
+export { NodeGraphGroupView };
+//# sourceMappingURL=NodeGraphGroup.js.map

package/dist/esm/components/editor/NodeGraph/NodeGraphGroup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeGraphGroup.js","sources":["src/components/editor/NodeGraph/NodeGraphGroup.tsx"],"sourcesContent":["'use client';\n\nimport React, { useCallback, useEffect, useRef, useState } from 'react';\n\nimport { ColorPicker } from '@/components/controls/ColorPicker/ColorPicker';\nimport { Popover } from '@/components/primitives/Popover/Popover';\nimport { PopoverContent } from '@/components/primitives/Popover/PopoverContent';\nimport { PopoverTrigger } from '@/components/primitives/Popover/PopoverTrigger';\nimport { cx } from '@/utils/cx';\n\nimport {\n  groupColorSwatchStyle,\n  groupLabelBarStyle,\n  groupLabelInputStyle,\n  groupLabelStyle,\n  groupOverlayRecipe,\n  groupResizeHandleStyle,\n} from './NodeGraph.css';\nimport { useNodeGraphStore } from './NodeGraphContext';\nimport { applyGroupResize } from './nodeGraphMath';\nimport { useStoreSlice } from './useStoreSlice';\n\nimport type { NodeGraphGroup } from './NodeGraph.types';\nimport type {\n  NodeGraphGroupResizeHandle,\n  NodeGraphInteractionState,\n} from './NodeGraphStore';\nimport type { WorldRect } from '@/components/primitives/viewport';\n\ninterface NodeGraphGroupViewProps {\n  group: NodeGraphGroup;\n  /** Pointer-down on the group body — used for drag / click selection. */\n  onBodyPointerDown: (\n    event: React.PointerEvent<HTMLDivElement>,\n    group: NodeGraphGroup\n  ) => void;\n  /** Pointer-up on the group body — completes click-to-select if no drag. */\n  onBodyPointerUp: (\n    event: React.PointerEvent<HTMLDivElement>,\n    group: NodeGraphGroup\n  ) => void;\n  /** Pointer-down on a resize handle. */\n  onHandlePointerDown: (\n    event: React.PointerEvent<HTMLDivElement>,\n    group: NodeGraphGroup,\n    handle: NodeGraphGroupResizeHandle\n  ) => void;\n  onBodyContextMenu: (event: React.MouseEvent<HTMLDivElement>) => void;\n  /**\n   * Commit a label or colour edit. The library calls this when the user\n   * finishes editing the label (Enter / blur) or picks a new colour from\n   * the swatch. Parent forwards to `setGroups` / `onGroupsChange`.\n   */\n  onLabelChange: (group: NodeGraphGroup, nextLabel: string) => void;\n  onColorChange: (group: NodeGraphGroup, nextColor: string) => void;\n}\n\nconst RESIZE_CURSORS: Record<NodeGraphGroupResizeHandle, string> = {\n  nw: 'nwse-resize',\n  n: 'ns-resize',\n  ne: 'nesw-resize',\n  e: 'ew-resize',\n  se: 'nwse-resize',\n  s: 'ns-resize',\n  sw: 'nesw-resize',\n  w: 'ew-resize',\n};\n\nconst HANDLE_POSITIONS: Record<\n  NodeGraphGroupResizeHandle,\n  { left?: string; right?: string; top?: string; bottom?: string }\n> = {\n  nw: { left: '-5px', top: '-5px' },\n  n: { left: 'calc(50% - 5px)', top: '-5px' },\n  ne: { right: '-5px', top: '-5px' },\n  e: { right: '-5px', top: 'calc(50% - 5px)' },\n  se: { right: '-5px', bottom: '-5px' },\n  s: { left: 'calc(50% - 5px)', bottom: '-5px' },\n  sw: { left: '-5px', bottom: '-5px' },\n  w: { left: '-5px', top: 'calc(50% - 5px)' },\n};\n\nconst ALL_HANDLES: NodeGraphGroupResizeHandle[] = [\n  'nw',\n  'n',\n  'ne',\n  'e',\n  'se',\n  's',\n  'sw',\n  'w',\n];\n\nconst DEFAULT_PICKER_COLOR = '#5d8dff';\n\n/**\n * Per-group slice of the interaction state — `null` for groups that\n * aren't currently being dragged or resized. Two distinct `null`\n * references would defeat the equality short-circuit, so we share the\n * module-level constant below.\n */\ntype GroupGestureState =\n  | {\n      kind: 'drag';\n      delta: { x: number; y: number };\n      blocked: boolean;\n    }\n  | {\n      kind: 'resize';\n      handle: NodeGraphGroupResizeHandle;\n      startBounds: WorldRect;\n      delta: { x: number; y: number };\n      blocked: boolean;\n    }\n  | null;\n\nfunction gestureStateEqual(\n  a: GroupGestureState,\n  b: GroupGestureState\n): boolean {\n  if (a === b) return true;\n  if (a === null || b === null) return false;\n  if (a.kind !== b.kind) return false;\n  if (a.blocked !== b.blocked) return false;\n  if (a.kind === 'drag' && b.kind === 'drag') {\n    return a.delta.x === b.delta.x && a.delta.y === b.delta.y;\n  }\n  if (a.kind === 'resize' && b.kind === 'resize') {\n    return (\n      a.handle === b.handle &&\n      a.delta.x === b.delta.x &&\n      a.delta.y === b.delta.y &&\n      a.startBounds.x === b.startBounds.x &&\n      a.startBounds.y === b.startBounds.y &&\n      a.startBounds.width === b.startBounds.width &&\n      a.startBounds.height === b.startBounds.height\n    );\n  }\n  return false;\n}\n\nfunction selectGroupGesture(\n  interaction: NodeGraphInteractionState,\n  groupId: string\n): GroupGestureState {\n  if (interaction.kind === 'drag-groups' && interaction.groupIds.has(groupId)) {\n    return {\n      kind: 'drag',\n      delta: interaction.delta,\n      blocked: interaction.blocked,\n    };\n  }\n  if (interaction.kind === 'resize-group' && interaction.groupId === groupId) {\n    return {\n      kind: 'resize',\n      handle: interaction.handle,\n      startBounds: interaction.startBounds,\n      delta: interaction.delta,\n      blocked: interaction.blocked,\n    };\n  }\n  return null;\n}\n\nfunction computeLiveBounds(\n  group: NodeGraphGroup,\n  gesture: GroupGestureState\n): WorldRect {\n  if (gesture === null) return group.bounds;\n  if (gesture.kind === 'drag') {\n    return {\n      x: group.bounds.x + gesture.delta.x,\n      y: group.bounds.y + gesture.delta.y,\n      width: group.bounds.width,\n      height: group.bounds.height,\n    };\n  }\n  return applyGroupResize(gesture.startBounds, gesture.handle, gesture.delta);\n}\n\n/**\n * Render a single interactive group overlay positioned in world space.\n * The canvas layer draws the visual fill underneath — this HTML element\n * handles selection, drag-to-move, corner/edge resize, label editing,\n * and the colour swatch.\n *\n * Uses per-id selectors so a group only re-renders when *its* selection\n * or gesture state changes — drag deltas of other groups never reach the\n * subscriber.\n *\n * Wrapped in `React.memo` for the same reason as\n * {@link NodeGraphNodeView}: a parent render caused by an unrelated\n * controlled-state update would otherwise iterate every group. Handlers\n * passed from `NodeGraphImpl` are all `useCallback`-stable.\n */\nfunction NodeGraphGroupViewImpl({\n  group,\n  onBodyPointerDown,\n  onBodyPointerUp,\n  onHandlePointerDown,\n  onBodyContextMenu,\n  onLabelChange,\n  onColorChange,\n}: NodeGraphGroupViewProps): React.ReactElement {\n  const store = useNodeGraphStore();\n  const groupId = group.id;\n\n  const selected = useStoreSlice(\n    store.subscribeSelection,\n    store.getSelection,\n    sel => sel.groups.includes(groupId)\n  );\n\n  const gesture = useStoreSlice<NodeGraphInteractionState, GroupGestureState>(\n    store.subscribeInteraction,\n    store.getInteraction,\n    interaction => selectGroupGesture(interaction, groupId),\n    gestureStateEqual\n  );\n\n  const dragging = gesture?.kind === 'drag';\n  const blocked = gesture?.blocked ?? false;\n  const bounds = computeLiveBounds(group, gesture);\n\n  // ── Inline label edit ──\n  // `draft` is initialised from `group.label` on mount and re-synced by\n  // `cancelLabel` / `commitLabel` / `handleLabelDoubleClick` on every\n  // transition out of / into edit mode. Mirroring `group.label` into\n  // state via a side effect would be the classic anti-pattern.\n  const [editing, setEditing] = useState(false);\n  const [draft, setDraft] = useState(group.label ?? '');\n  const inputRef = useRef<HTMLInputElement>(null);\n\n  useEffect(() => {\n    if (editing) {\n      // Defer focus until the input has been mounted.\n      inputRef.current?.focus();\n      inputRef.current?.select();\n    }\n  }, [editing]);\n\n  const commitLabel = useCallback((): void => {\n    const trimmed = draft.trim();\n    setEditing(false);\n    if (trimmed === (group.label ?? '')) return;\n    onLabelChange(group, trimmed);\n  }, [draft, group, onLabelChange]);\n\n  const cancelLabel = useCallback((): void => {\n    setEditing(false);\n    setDraft(group.label ?? '');\n  }, [group.label]);\n\n  const handleLabelDoubleClick = useCallback(\n    (event: React.MouseEvent<HTMLSpanElement>): void => {\n      event.stopPropagation();\n      // Re-sync from the prop on open — covers the case where `group.label`\n      // changed externally while we weren't editing, so the input opens\n      // with the current value rather than a stale draft.\n      setDraft(group.label ?? '');\n      setEditing(true);\n    },\n    [group.label]\n  );\n\n  const handleInputKeyDown = useCallback(\n    (event: React.KeyboardEvent<HTMLInputElement>): void => {\n      if (event.key === 'Enter') {\n        event.preventDefault();\n        commitLabel();\n      } else if (event.key === 'Escape') {\n        event.preventDefault();\n        cancelLabel();\n      }\n      // Stop arrow keys from triggering the graph's nudge handler.\n      event.stopPropagation();\n    },\n    [commitLabel, cancelLabel]\n  );\n\n  // ── Colour picker ──\n  //\n  // The swatch is a `<button>` that triggers the entangle-ui `<ColorPicker>`\n  // popover. The picker has `showAlpha` enabled so it returns proper\n  // `rgba(...)` strings when the user lowers opacity — the canvas\n  // `drawGroups` fill plumbs that straight through with no transform.\n  const handleColorChange = useCallback(\n    (next: string): void => {\n      onColorChange(group, next);\n    },\n    [group, onColorChange]\n  );\n\n  // Picker value falls back to a sensible default when the group hasn't\n  // been coloured yet (the library doesn't impose a default).\n  const pickerValue = group.color ?? DEFAULT_PICKER_COLOR;\n\n  return (\n    <div\n      className={cx(groupOverlayRecipe({ selected, dragging, blocked }))}\n      style={{\n        left: bounds.x,\n        top: bounds.y,\n        width: bounds.width,\n        height: bounds.height,\n      }}\n      data-group-id={group.id}\n      data-blocked={blocked || undefined}\n      onPointerDown={e => {\n        onBodyPointerDown(e, group);\n      }}\n      onPointerUp={e => {\n        onBodyPointerUp(e, group);\n      }}\n      onContextMenu={onBodyContextMenu}\n    >\n      <div\n        className={groupLabelBarStyle}\n        // Don't let pointerdown on the label bar (label text, color swatch,\n        // input) fall through to the body drag handler — the label bar is\n        // an interactive control row, not a draggable handle.\n        onPointerDown={e => {\n          e.stopPropagation();\n        }}\n      >\n        {editing ? (\n          <input\n            ref={inputRef}\n            className={groupLabelInputStyle}\n            value={draft}\n            placeholder=\"Group name\"\n            spellCheck={false}\n            onChange={e => {\n              setDraft(e.target.value);\n            }}\n            onBlur={commitLabel}\n            onKeyDown={handleInputKeyDown}\n          />\n        ) : (\n          <span\n            className={groupLabelStyle}\n            onDoubleClick={handleLabelDoubleClick}\n            title=\"Double-click to rename\"\n          >\n            {group.label?.trim() ? group.label : 'Group'}\n          </span>\n        )}\n        <Popover placement=\"bottom-end\">\n          <PopoverTrigger>\n            <button\n              type=\"button\"\n              aria-label=\"Change group colour\"\n              title=\"Change group colour\"\n              className={groupColorSwatchStyle}\n              style={{ background: group.color ?? DEFAULT_PICKER_COLOR }}\n            />\n          </PopoverTrigger>\n          <PopoverContent padding=\"md\">\n            {/* Uncontrolled picker — `useColor` only mutates its internal\n                state when `value` is undefined, so passing `defaultValue`\n                lets the user actually drag the sliders / click the\n                palette. PopoverContent unmounts on close, so each open\n                gets a fresh mount that picks up the current\n                `group.color` via `defaultValue`. `showAlpha` lets the\n                picker emit translucent fills directly — we ask for\n                `format=\"rgba\"` so the alpha channel is actually included\n                in the output string (`\"rgb\"` strips it). Survives\n                round-trip through the canvas group fill with no\n                consumer-side transform. */}\n            <ColorPicker\n              inline\n              showAlpha\n              defaultValue={pickerValue}\n              format=\"rgba\"\n              palette=\"material\"\n              onChangeComplete={handleColorChange}\n            />\n          </PopoverContent>\n        </Popover>\n      </div>\n      {selected\n        ? ALL_HANDLES.map(handle => (\n            <div\n              key={handle}\n              className={groupResizeHandleStyle}\n              style={{\n                ...HANDLE_POSITIONS[handle],\n                cursor: RESIZE_CURSORS[handle],\n              }}\n              data-group-id={group.id}\n              data-group-handle={handle}\n              onPointerDown={e => {\n                onHandlePointerDown(e, group, handle);\n              }}\n            />\n          ))\n        : null}\n    </div>\n  );\n}\n\nexport const NodeGraphGroupView = React.memo(NodeGraphGroupViewImpl);\nNodeGraphGroupView.displayName = 'NodeGraphGroupView';\n"],"names":[],"mappings":";;;;;;;;;;;;;AAyDA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGF;;;;;;;;;;AAcA;;;;;;;;;;AAWA;AAuBA;;AAIe;AACb;AAA8B;AAC9B;AAAuB;AACvB;AAA6B;AAC7B;;;AAGA;AACE;;;;;;;;AAUF;AACF;AAEA;AAIE;;AAEI;;;;;AAKJ;;AAEI;;;;;;;AAOJ;AACF;AAEA;;;AAKE;;;;AAII;AACA;;;AAGJ;AACF;AAEA;;;;;;;;;;;;;;AAcG;AACH;AASE;AACA;;;AAeA;AACA;;;;;;;;AASA;AACA;;;;AAKI;AACA;;AAEJ;AAEA;AACE;;;;AAGA;;AAGF;;AAEE;AACF;AAEA;;;;;AAMI;;AAEF;AAIF;AAEI;;AAEE;;AACK;;AAEL;;;;AAIJ;;;;;;;AAUF;AAEI;AACF;;;AAMF;AAEA;;;;;AAQK;AAIC;AACF;AAEE;;;;;;;AAWA;AAUM;;AAgDN;;AAMQ;;AAKA;AACF;AAGN;AAGR;AAEO;AACP;;"}