@bendyline/squisq-editor-react 1.6.2 → 2.0.1

package/src/scene/adapters/DiagramAdapter.ts

@@ -10,26 +10,15 @@
  * underlying heading id when dispatching writes.
  */
 
-import type { Editor } from '@tiptap/react';
 import type { Layer } from '@bendyline/squisq/schemas';
-import type { SceneCommand, SceneEdge } from '../commands/SceneCommand';
+import type { SceneEdge } from '../commands/SceneCommand';
 import {
   nodesToCardLayers,
-  nodeIdFromCardLayerId,
   NODE_WIDTH,
   NODE_HEIGHT,
   type DiagramNodeDescriptor,
 } from '../layers/nodeCard';
-import {
-  moveNode,
-  addConnection,
-  removeConnection,
-  renameNode,
-  addNode,
-  removeNode,
-  listDiagramChildren,
-} from '../../diagram/diagramCommands';
-import type { DiagramRFNode, DiagramRFEdge } from '../../diagram/useDiagramData';
+import type { DiagramNode, DiagramEdge } from '../../diagram/types';
 
 export interface DiagramSceneData {
   layers: Layer[];
@@ -44,8 +33,8 @@ export interface DiagramSceneData {
  * shape so the existing data hook can stay unchanged during the swap.
  */
 export function buildDiagramScene(
-  nodes: readonly DiagramRFNode[],
-  edges: readonly DiagramRFEdge[],
+  nodes: readonly DiagramNode[],
+  edges: readonly DiagramEdge[],
 ): DiagramSceneData {
   const descriptors: DiagramNodeDescriptor[] = nodes.map((n) => ({
     id: n.id,
@@ -54,6 +43,7 @@ export function buildDiagramScene(
     y: n.position.y,
     ...(n.width != null ? { width: n.width } : {}),
     ...(n.height != null ? { height: n.height } : {}),
+    ...(n.kind === 'container' ? { kind: 'container' as const } : {}),
   }));
   const layers = nodesToCardLayers(descriptors);
   const sceneEdges: SceneEdge[] = edges.map((e) => ({
@@ -61,6 +51,10 @@ export function buildDiagramScene(
     source: e.source,
     target: e.target,
     ...(e.label ? { label: e.label } : {}),
+    ...(e.directed === false ? { endMarker: 'none' as const } : {}),
+    ...(e.sourceAnchor ? { sourceAnchor: e.sourceAnchor } : {}),
+    ...(e.targetAnchor ? { targetAnchor: e.targetAnchor } : {}),
+    ...(e.routing ? { routing: e.routing } : {}),
   }));
   return { layers, edges: sceneEdges, nodes: descriptors };
 }
@@ -80,89 +74,6 @@ export function nodeCenter(node: DiagramNodeDescriptor): { x: number; y: number
   return { x: node.x + NODE_WIDTH / 2, y: node.y + NODE_HEIGHT / 2 };
 }
 
-/**
- * Build a SceneCommand dispatcher that writes back to Tiptap using the
- * existing diagram commands. The returned function is stable for a
- * given (editor, parentPos) tuple.
- */
-export function makeDiagramDispatch(
-  editor: Editor,
-  parentPos: number,
-): (cmd: SceneCommand) => void {
-  return (cmd: SceneCommand) => {
-    switch (cmd.kind) {
-      case 'moveLayer': {
-        const nodeId = nodeIdFromCardLayerId(cmd.id);
-        if (!nodeId) return;
-        // Only the card layer carries the node's position; ignore label
-        // moves (they'd duplicate the same write).
-        if (!cmd.id.startsWith('node-card-')) return;
-        moveNode(editor, parentPos, nodeId, cmd.x, cmd.y);
-        return;
-      }
-      case 'addEdge':
-        addConnection(editor, parentPos, cmd.source, cmd.target, cmd.type);
-        return;
-      case 'removeEdge':
-        removeConnection(editor, parentPos, cmd.source, cmd.target, cmd.type);
-        return;
-      case 'removeLayer': {
-        const nodeId = nodeIdFromCardLayerId(cmd.id);
-        if (nodeId) removeNode(editor, parentPos, nodeId);
-        return;
-      }
-      case 'renameLayer': {
-        const nodeId = nodeIdFromCardLayerId(cmd.id);
-        if (nodeId) renameNode(editor, parentPos, nodeId, cmd.label);
-        return;
-      }
-      case 'addLayer': {
-        // Diagram mode interprets addLayer as "add a new diagram node at
-        // the layer's position". Pull (x, y) from the layer's position
-        // and synthesize a fresh id.
-        const pos = cmd.layer.position;
-        const x = typeof pos.x === 'number' ? pos.x : 0;
-        const y = typeof pos.y === 'number' ? pos.y : 0;
-        const id = nextNodeId(editor, parentPos);
-        const label = inferAddedLabel(cmd.layer) ?? `Node`;
-        addNode(editor, parentPos, id, label, x, y);
-        return;
-      }
-      case 'setLayerAttr': {
-        const nodeId = nodeIdFromCardLayerId(cmd.id);
-        if (!nodeId) return;
-        if (cmd.path === 'content.text' && typeof cmd.value === 'string') {
-          renameNode(editor, parentPos, nodeId, cmd.value);
-        }
-        return;
-      }
-      case 'resizeLayer':
-        // v1: diagram nodes are fixed-size. Ignore resize.
-        return;
-      case 'setLayerText': {
-        const nodeId = nodeIdFromCardLayerId(cmd.id);
-        if (nodeId) renameNode(editor, parentPos, nodeId, cmd.text);
-        return;
-      }
-    }
-    // Exhaustiveness check — TS will flag unhandled command kinds.
-    const _exhaustive: never = cmd;
-    void _exhaustive;
-  };
-
-  function inferAddedLabel(layer: Layer): string | null {
-    if (layer.type === 'text') return layer.content.text;
-    return null;
-  }
-}
-
-function nextNodeId(editor: Editor, parentPos: number): string {
-  const used = new Set(listDiagramChildren(editor, parentPos).map((c) => c.id));
-  let i = used.size + 1;
-  let id = `node-${i}`;
-  while (used.has(id)) {
-    i++;
-    id = `node-${i}`;
-  }
-  return id;
-}
+// (The heading-based `makeDiagramDispatch` was removed with the ASCII-fence
+// cutover — canvas commands for diagrams now flow through
+// `asciiDiagram/asciiDiagramCommands.ts` instead of heading mutations.)

package/src/scene/adapters/DrawingAdapter.ts

@@ -238,7 +238,12 @@ export function useDrawingAdapter(
       case 'resizeLayer': {
         if (!isPrimaryShapeLayer(cmd.id)) return;
         const id = shapeIdFromLayerId(cmd.id);
-        if (id) resizeShape(editor, headingPos, id, cmd.width, cmd.height);
+        if (id) {
+          if (cmd.x !== undefined && cmd.y !== undefined) {
+            moveShape(editor, headingPos, id, cmd.x, cmd.y);
+          }
+          resizeShape(editor, headingPos, id, cmd.width, cmd.height);
+        }
         return;
       }
       case 'addLayer': {

package/src/scene/adapters/LayoutAdapter.ts

@@ -130,6 +130,9 @@ export function useLayoutAdapter(
         moveLayoutLayer(editor, headingPos, cmd.id, cmd.x, cmd.y);
         return;
       case 'resizeLayer':
+        if (cmd.x !== undefined && cmd.y !== undefined) {
+          moveLayoutLayer(editor, headingPos, cmd.id, cmd.x, cmd.y);
+        }
         resizeLayoutLayer(editor, headingPos, cmd.id, cmd.width, cmd.height);
         return;
       case 'addLayer': {

package/src/scene/commands/SceneCommand.ts

@@ -11,13 +11,24 @@
  * component drive three different editing surfaces.
  */
 
-import type { Layer } from '@bendyline/squisq/schemas';
+import type { DiagramEdgeAnchor, Layer } from '@bendyline/squisq/schemas';
 
 export type SceneCommand =
   /** Commit a layer's new top-left position (in viewport units). */
   | { kind: 'moveLayer'; id: string; x: number; y: number }
-  /** Commit a layer's new size (in viewport units). */
-  | { kind: 'resizeLayer'; id: string; width: number; height: number }
+  /**
+   * Commit a layer's new size (in viewport units). `x`/`y` carry the final
+   * top-left for west/north handle drags so hosts can persist the whole
+   * resize atomically instead of reparsing between a move and a size write.
+   */
+  | {
+      kind: 'resizeLayer';
+      id: string;
+      width: number;
+      height: number;
+      x?: number;
+      y?: number;
+    }
   /** Append a new layer to the scene. */
   | { kind: 'addLayer'; layer: Layer }
   /** Remove a layer by id. */
@@ -67,4 +78,7 @@ export interface SceneEdge {
   dasharray?: string;
   /** Per-edge routing override (else the renderer's variant default). */
   routing?: import('@bendyline/squisq/doc').ConnectorRouting;
+  /** Optional authored node-side attachments (used by ASCII-derived diagrams). */
+  sourceAnchor?: DiagramEdgeAnchor;
+  targetAnchor?: DiagramEdgeAnchor;
 }

package/src/scene/index.ts

@@ -59,12 +59,7 @@ export {
 } from './layers/nodeCard';
 export { DiagramEdges } from './layers/DiagramEdges';
 
-export {
-  buildDiagramScene,
-  makeDiagramDispatch,
-  nodeCenter,
-  type DiagramSceneData,
-} from './adapters/DiagramAdapter';
+export { buildDiagramScene, nodeCenter, type DiagramSceneData } from './adapters/DiagramAdapter';
 
 export {
   useLayoutAdapter,

package/src/scene/layers/DiagramEdges.tsx

@@ -13,6 +13,7 @@
  * drag).
  */
 
+import { useId } from 'react';
 import type { MarkerStyle } from '@bendyline/squisq/schemas';
 import { connectorPath, markerPath } from '@bendyline/squisq/doc';
 import type { SceneEdge } from '../commands/SceneCommand';
@@ -33,8 +34,8 @@ interface DiagramEdgesProps {
 /** Marker styles that carry a glyph (everything except 'none'). */
 const MARKER_STYLES: MarkerStyle[] = ['arrow', 'open', 'diamond', 'circle', 'square'];
 
-function markerId(style: MarkerStyle, dir: 'start' | 'end'): string {
-  return `squisq-edge-${style}-${dir}`;
+function markerId(prefix: string, style: MarkerStyle, dir: 'start' | 'end'): string {
+  return `${prefix}-squisq-edge-${style}-${dir}`;
 }
 
 export function DiagramEdges({
@@ -45,6 +46,7 @@ export function DiagramEdges({
   onEdgeClick,
 }: DiagramEdgesProps) {
   const boxById = boxesOf(nodes);
+  const markerPrefix = useId().replace(/:/g, '');
   const defaultRouting = variant === 'straight' ? 'straight' : 'curved';
 
   return (
@@ -56,8 +58,8 @@ export function DiagramEdges({
             if (!mp) return null;
             return (
               <marker
-                key={markerId(style, dir)}
-                id={markerId(style, dir)}
+                key={markerId(markerPrefix, style, dir)}
+                id={markerId(markerPrefix, style, dir)}
                 viewBox="0 0 10 10"
                 refX={dir === 'end' ? 9 : 1}
                 refY={5}
@@ -81,7 +83,13 @@ export function DiagramEdges({
         const a = boxById.get(edge.source);
         const b = boxById.get(edge.target);
         if (!a || !b) return null;
-        const snapped = edgeEndpoints(nodes, edge.source, edge.target);
+        const snapped = edgeEndpoints(
+          nodes,
+          edge.source,
+          edge.target,
+          edge.sourceAnchor,
+          edge.targetAnchor,
+        );
         if (!snapped) return null;
         const { start, end } = snapped;
         const d = connectorPath(edge.routing ?? defaultRouting, start, end);
@@ -99,9 +107,15 @@ export function DiagramEdges({
               className="squisq-scene-edge-path"
               strokeDasharray={edge.dasharray}
               markerStart={
-                startMarker !== 'none' ? `url(#${markerId(startMarker, 'start')})` : undefined
+                startMarker !== 'none'
+                  ? `url(#${markerId(markerPrefix, startMarker, 'start')})`
+                  : undefined
+              }
+              markerEnd={
+                endMarker !== 'none'
+                  ? `url(#${markerId(markerPrefix, endMarker, 'end')})`
+                  : undefined
               }
-              markerEnd={endMarker !== 'none' ? `url(#${markerId(endMarker, 'end')})` : undefined}
             />
             {edge.label ? (
               <text

package/src/scene/layers/edgeGeometry.ts

@@ -9,8 +9,10 @@
 
 import { NODE_WIDTH, NODE_HEIGHT } from './nodeCard';
 import {
+  anchorPoint,
   nearestSnapPoint as nearestCoreSnapPoint,
   snapEndpoints as coreSnapEndpoints,
+  type ConnectorAnchor,
   type ConnectorSnapPoint,
 } from '@bendyline/squisq/doc';
 
@@ -77,12 +79,18 @@ export function edgeEndpoints(
   nodes: readonly EdgeNodeBox[],
   source: string,
   target: string,
+  sourceAnchor?: ConnectorAnchor,
+  targetAnchor?: ConnectorAnchor,
 ): { start: ConnectorSnapPoint; end: ConnectorSnapPoint } | null {
   const boxes = boxesOf(nodes);
   const a = boxes.get(source);
   const b = boxes.get(target);
   if (!a || !b) return null;
-  return coreSnapEndpoints(a, b);
+  const snapped = coreSnapEndpoints(a, b);
+  return {
+    start: sourceAnchor ? anchorPoint(a, sourceAnchor) : snapped.start,
+    end: targetAnchor ? anchorPoint(b, targetAnchor) : snapped.end,
+  };
 }
 
 export function straightPath(a: { x: number; y: number }, b: { x: number; y: number }): string {

package/src/scene/layers/nodeCard.tsx

@@ -11,6 +11,7 @@
  */
 
 import type { ShapeLayer, TextLayer, Layer } from '@bendyline/squisq/schemas';
+import { DIAGRAM_LABEL_LINE_HEIGHT, fitDiagramLabel } from '@bendyline/squisq/doc';
 
 export const NODE_WIDTH = 180;
 export const NODE_HEIGHT = 64;
@@ -34,6 +35,12 @@ export interface DiagramNodeDescriptor {
   stroke?: string;
   /** Optional shape: 'rect' (default) or 'pill' (fully rounded). */
   shape?: 'rect' | 'pill';
+  /**
+   * 'container' renders as a background grouping card: translucent fill,
+   * muted stroke, label anchored near the top edge instead of centered
+   * (children paint over the interior).
+   */
+  kind?: 'container';
 }
 
 /**
@@ -45,43 +52,55 @@ export interface DiagramNodeDescriptor {
 export function nodeCardLayers(node: DiagramNodeDescriptor): [ShapeLayer, TextLayer] {
   const width = node.width ?? NODE_WIDTH;
   const height = node.height ?? NODE_HEIGHT;
+  const isContainer = node.kind === 'container';
   const card: ShapeLayer = {
     id: `node-card-${node.id}`,
     type: 'shape',
     position: { x: node.x, y: node.y, width, height },
     content: {
       shape: 'rect',
-      fill: node.fill ?? '#ffffff',
-      stroke: node.stroke ?? '#1e293b',
+      fill: node.fill ?? (isContainer ? '#94a3b8' : '#ffffff'),
+      ...(isContainer ? { fillOpacity: 0.12 } : {}),
+      stroke: node.stroke ?? (isContainer ? '#94a3b8' : '#1e293b'),
       strokeWidth: 2,
       borderRadius: node.shape === 'pill' ? height / 2 : 10,
     },
   };
 
   // Scale the label font with the node height so resized cards stay
-  // legible without the text overflowing.
-  const fontSize = Math.max(12, Math.min(48, Math.round(height * 0.34)));
+  // legible without the text overflowing. Containers keep a fixed, small
+  // title size — their height tracks their children, not their label.
+  const labelText = isContainer ? (node.label.split('\n')[0] ?? '') : node.label;
+  const preferredFontSize = Math.max(12, Math.min(48, Math.round(height * 0.34)));
+  const fit = isContainer
+    ? { fontSize: 16, firstLineOffset: 0, textWidth: width }
+    : fitDiagramLabel(labelText, width, height, preferredFontSize);
+  const { fontSize } = fit;
 
   // Label has no explicit height — that keeps its bounding box
   // unresolvable in `layerBounds`, which in turn keeps it out of the
   // Scene's hit-test. The label rides along visually via `layerFollows`
   // but never wins a pointer-down (the card underneath does), so a
   // drag-on-text moves the card as expected.
+  //
+  // Container labels anchor near the top edge — the interior belongs to
+  // the children painting over it.
   const label: TextLayer = {
     id: `node-label-${node.id}`,
     type: 'text',
     position: {
       x: node.x + width / 2,
-      y: node.y + height / 2,
-      width,
+      y: isContainer ? node.y + fontSize + 8 : node.y + height / 2 + fit.firstLineOffset,
+      width: fit.textWidth,
       anchor: 'center',
     },
     content: {
-      text: node.label,
+      text: labelText,
       style: {
         fontSize,
+        ...(!isContainer ? { lineHeight: DIAGRAM_LABEL_LINE_HEIGHT } : {}),
         fontWeight: 'bold',
-        color: node.stroke ?? '#1e293b',
+        color: node.stroke ?? (isContainer ? '#64748b' : '#1e293b'),
         textAlign: 'center',
       },
     },

package/src/scene/scene.css

@@ -37,11 +37,14 @@
 
 .squisq-editor-shell[data-theme='dark'] .squisq-scene-layer--shape,
 .squisq-editor-shell[data-theme='dark'] .squisq-scene-layer--path,
-.squisq-editor-shell[data-theme='dark'] .squisq-scene-layer--text,
-.squisq-editor-shell[data-theme='dark'] .squisq-scene-extras {
+.squisq-editor-shell[data-theme='dark'] .squisq-scene-layer--text {
   filter: invert(1) hue-rotate(180deg) saturate(0.9);
 }
 
+/* Scene extras (diagram/drawing connectors) already use the dark-aware
+   --squisq-text tokens below. Inverting this group a second time turns the
+   intended light strokes and arrowheads nearly black against the canvas. */
+
 .squisq-scene-viewport {
   display: block;
   width: 100%;

package/src/scene/text/SceneTextOverlay.tsx

@@ -19,7 +19,6 @@ import { layerBounds } from '../hooks/useSceneHitTest';
 import type { SceneTransform } from '../hooks/useScenePanZoom';
 import type { SceneTextEditConfig } from './sceneTextConfig';
 import { buildSceneTextExtensions } from './sceneTiptap';
-import { sceneTextChannel } from './sceneTextChannel';
 
 interface SceneTextOverlayProps {
   config: SceneTextEditConfig;
@@ -90,12 +89,13 @@ export function SceneTextOverlay({
 
   // Publish to the toolbar channel while mounted; clear on unmount.
   useEffect(() => {
-    if (!editor) return;
-    sceneTextChannel.set({ editor, level: config.level });
+    if (!editor || !config.channel) return;
+    const channel = config.channel;
+    channel.set({ editor, level: config.level });
     return () => {
-      if (sceneTextChannel.get()?.editor === editor) sceneTextChannel.set(null);
+      if (channel.get()?.editor === editor) channel.set(null);
     };
-  }, [editor, config.level]);
+  }, [editor, config.level, config.channel]);
 
   // Commit when focus leaves the editor — unless it went to the toolbar
   // (the user clicking Bold) or stayed within the overlay.

package/src/scene/text/sceneTextChannel.ts

@@ -1,13 +1,13 @@
 /**
- * sceneTextChannel — a module singleton that bridges the canvas's inline
+ * sceneTextChannel — an editor-owned channel that bridges the canvas's inline
  * text editor (which renders in a **detached React root** created by the
  * Diagram/SceneBlock ProseMirror extensions, outside `<EditorProvider>`)
  * to the provider, so the top formatting toolbar can target it.
  *
  * The active textbox's `SceneTextOverlay` publishes its Tiptap editor here
  * on focus and clears it on blur/unmount; `EditorProvider` subscribes and
- * mirrors the handle into `activeSceneText`. Singleton because only one
- * canvas textbox can be focused at a time.
+ * mirrors the handle into `activeSceneText`. Each EditorProvider creates its
+ * own channel, preventing focus in one editor from mutating another editor.
  */
 
 import type { Editor as TiptapEditor } from '@tiptap/core';
@@ -20,21 +20,27 @@ export interface SceneTextHandle {
 
 type Listener = (handle: SceneTextHandle | null) => void;
 
-let current: SceneTextHandle | null = null;
-const listeners = new Set<Listener>();
+export interface SceneTextChannel {
+  set(handle: SceneTextHandle | null): void;
+  get(): SceneTextHandle | null;
+  subscribe(listener: Listener): () => void;
+}
 
-export const sceneTextChannel = {
-  /** Publish (or clear with `null`) the focused canvas textbox editor. */
-  set(handle: SceneTextHandle | null): void {
-    current = handle;
-    for (const listener of listeners) listener(handle);
-  },
-  get(): SceneTextHandle | null {
-    return current;
-  },
-  /** Subscribe to handle changes. Returns an unsubscribe function. */
-  subscribe(listener: Listener): () => void {
-    listeners.add(listener);
-    return () => listeners.delete(listener);
-  },
-};
+/** Create a channel owned by one EditorProvider; no cross-editor singleton. */
+export function createSceneTextChannel(): SceneTextChannel {
+  let current: SceneTextHandle | null = null;
+  const listeners = new Set<Listener>();
+  return {
+    set(handle) {
+      current = handle;
+      for (const listener of listeners) listener(handle);
+    },
+    get() {
+      return current;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}

package/src/scene/text/sceneTextConfig.ts

@@ -5,9 +5,13 @@
  * the host owns persistence (markdown heading vs. layout JSON blob).
  */
 
+import type { SceneTextChannel } from './sceneTextChannel';
+
 export type SceneTextLevel = 'inline' | 'block' | 'rich';
 
 export interface SceneTextEditConfig {
+  /** Per-editor bridge to the formatting toolbar. */
+  channel?: SceneTextChannel;
   /**
    * Map a hit layer id (what the pointer landed on) to the layer id whose
    * on-screen box the editor should cover, or `null` when that layer isn't

package/src/scene/tools/ConnectTool.ts

@@ -32,7 +32,13 @@ interface ConnectState {
   hoveredTargetId: string | null;
 }
 
-let state: ConnectState | null = null;
+function getState(ctx: SceneToolContext): ConnectState | null {
+  return (ctx.interaction.connect as ConnectState | undefined) ?? null;
+}
+
+function setState(ctx: SceneToolContext, state: ConnectState | null): void {
+  ctx.interaction.connect = state ?? undefined;
+}
 
 function pointerFromEvent(e: React.PointerEvent): { sx: number; sy: number } {
   const rect = (e.currentTarget as Element).getBoundingClientRect();
@@ -126,18 +132,19 @@ export const ConnectTool: SceneTool = {
     const sourceBox = nodeBoxFromCard(ctx, nodeId);
     if (!sourceBox) return;
     const preview = updatePreview(sourceBox, v, null);
-    state = {
+    setState(ctx, {
       sourceNodeId: nodeId,
       sourceBox,
       start: preview.start,
       end: preview.end,
       hoveredTargetId: null,
-    };
+    });
     (e.currentTarget as Element).setPointerCapture?.(e.pointerId);
     e.stopPropagation();
   },
 
   onPointerMove(e, ctx) {
+    const state = getState(ctx);
     if (!state) return;
     const { sx, sy } = pointerFromEvent(e);
     const v = ctx.screenToViewport(sx, sy);
@@ -152,16 +159,18 @@ export const ConnectTool: SceneTool = {
   },
 
   onPointerUp(e, ctx) {
+    const state = getState(ctx);
     if (!state) return;
     const target = state.hoveredTargetId;
     if (target) {
       ctx.dispatch({ kind: 'addEdge', source: state.sourceNodeId, target });
     }
     (e.currentTarget as Element).releasePointerCapture?.(e.pointerId);
-    state = null;
+    setState(ctx, null);
   },
 
   renderOverlay(ctx): JSX.Element | null {
+    const state = getState(ctx);
     const points = nodeBoxes(ctx).flatMap((box) =>
       connectionPoints(box).map((point, index) =>
         createElement('circle', {

package/src/scene/tools/SceneTool.ts

@@ -14,7 +14,15 @@ import type { SceneCommand, SceneEdge } from '../commands/SceneCommand';
 import type { HitTestable } from '../hooks/useSceneHitTest';
 import type { SceneTransform } from '../hooks/useScenePanZoom';
 
+/** Mutable gesture storage owned by one Scene instance. */
+export interface SceneInteractionState {
+  selectDrag?: unknown;
+  connect?: unknown;
+}
+
 export interface SceneToolContext {
+  /** Gesture state private to the owning Scene instance. */
+  interaction: SceneInteractionState;
   /** Current viewport size in viewport units. */
   viewport: { width: number; height: number };
   /** Current pan/zoom transform. */