@pascal-app/editor 0.8.0 → 0.9.2

package/src/lib/contextual-help.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from 'bun:test'
+import { resolveSelectModeHelpHints } from './contextual-help'
+
+describe('resolveSelectModeHelpHints', () => {
+  test('stays hidden in idle select mode with no selection', () => {
+    expect(
+      resolveSelectModeHelpHints({
+        selectedCount: 0,
+        hasMovableSelection: false,
+        hasRotatableSelection: false,
+        commandPressed: false,
+        shiftPressed: false,
+      }),
+    ).toEqual([])
+  })
+
+  test('shows multi-select guidance when a modifier is held without selection', () => {
+    expect(
+      resolveSelectModeHelpHints({
+        selectedCount: 0,
+        hasMovableSelection: false,
+        hasRotatableSelection: false,
+        commandPressed: true,
+        shiftPressed: false,
+      }),
+    ).toEqual([
+      {
+        keys: [['Cmd/Ctrl', 'Shift'], 'Left click'],
+        label: 'Add or remove objects from the selection',
+        active: true,
+      },
+    ])
+  })
+
+  test('shows direct manipulation tips for selected movable and rotatable nodes', () => {
+    const hints = resolveSelectModeHelpHints({
+      selectedCount: 1,
+      hasMovableSelection: true,
+      hasRotatableSelection: true,
+      commandPressed: false,
+      shiftPressed: false,
+    })
+
+    expect(hints).toContainEqual({
+      keys: ['Left click'],
+      label: 'Drag selected movable object',
+    })
+    expect(hints).toContainEqual({
+      keys: ['Cmd/Ctrl', 'Right click'],
+      label: 'Drag left or right to rotate selected object',
+    })
+    // Cmd/Ctrl and Shift click both toggle selection membership (3D selection
+    // manager and 2D floorplan alike) — advertised as a single or-group row.
+    expect(hints).toContainEqual({
+      keys: [['Cmd/Ctrl', 'Shift'], 'Left click'],
+      label: 'Add or remove objects from the selection',
+      active: false,
+    })
+  })
+
+  test('multi-selection advertises the group move + rotate gestures', () => {
+    const hints = resolveSelectModeHelpHints({
+      selectedCount: 3,
+      hasMovableSelection: true,
+      hasRotatableSelection: true,
+      commandPressed: false,
+      shiftPressed: false,
+    })
+
+    expect(hints).toEqual([
+      {
+        keys: ['Left click'],
+        label: 'Click or drag the selection to move it as one',
+      },
+      { keys: ['R / T'], label: 'Rotate the selection ±45°' },
+      {
+        keys: [['Cmd/Ctrl', 'Shift'], 'Left click'],
+        label: 'Add or remove objects from the selection',
+        active: false,
+      },
+      { keys: ['Esc'], label: 'Clear the selection (or click outside)' },
+    ])
+  })
+
+  test('holding a modifier keeps the same rows and only lights the selection one', () => {
+    // Guides/snapping are governed by the snapping mode (Shift toggles it),
+    // so no modifier-specific "freely / with guides / bypass" variants exist.
+    const hints = resolveSelectModeHelpHints({
+      selectedCount: 1,
+      hasMovableSelection: true,
+      hasRotatableSelection: true,
+      commandPressed: true,
+      shiftPressed: true,
+    })
+
+    expect(hints).toEqual([
+      {
+        keys: ['Left click'],
+        label: 'Drag selected movable object',
+      },
+      {
+        keys: ['Cmd/Ctrl', 'Right click'],
+        label: 'Drag left or right to rotate selected object',
+      },
+      {
+        keys: [['Cmd/Ctrl', 'Shift'], 'Left click'],
+        label: 'Add or remove objects from the selection',
+        active: true,
+      },
+    ])
+  })
+})

package/src/lib/contextual-help.ts

@@ -0,0 +1,144 @@
+export type ContextualShortcutHint = {
+  // A combo of keys pressed together (rendered joined by "+"). An entry may
+  // itself be an array of alternatives (rendered joined by "/"), e.g.
+  // [['Cmd/Ctrl', 'Shift'], 'Left click'] → "⌘ / ⇧ + click".
+  keys: Array<string | string[]>
+  label: string
+  // Optional secondary line under the label for a terser qualifier
+  // (e.g. "disable 15° snap"). The HUD wraps both lines rather than truncating.
+  subtitle?: string
+  active?: boolean
+}
+
+// `activeHandleDrag.label` value a rotate gizmo sets while dragging, so the
+// contextual HUD can surface the Shift = free-rotation toggle for the duration
+// (mirrors how wall drafting advertises Shift). Distinct from resize handles,
+// which route their own measurement label here.
+export const ROTATE_HANDLE_DRAG_LABEL = 'rotate-handle'
+
+// `activeHandleDrag.label` a plain resize / radial-resize arrow sets while
+// dragging (when it carries no dimension `measureLabel`). It exists only so the
+// interaction scope is non-idle during a resize, which keeps the idle
+// select-mode hints off-screen — a resize is its own action, not a selection.
+export const RESIZE_HANDLE_DRAG_LABEL = 'resize-handle'
+
+// `activeHandleDrag.label`s for the multi-selection group drags: the body
+// drag sessions (2D floorplan + 3D ground plane) and the rotate gizmo. Kept
+// here (not in the session/gizmo modules) so `snapping-mode.ts` can resolve
+// the group move to the 'item' snap context without importing component code.
+export const GROUP_MOVE_DRAG_LABEL = 'group-move-handle'
+export const GROUP_ROTATE_DRAG_LABEL = 'group-rotate-handle'
+
+// Hints shown while a rotate gizmo is mid-drag: Shift bypasses the angle step
+// (free rotation), the same toggle wall drafting exposes. `active` lights the
+// pill while Shift is held.
+export function resolveRotateHandleHelpHints(shiftPressed: boolean): ContextualShortcutHint[] {
+  return [
+    {
+      keys: [SHIFT_KEY],
+      label: shiftPressed ? 'Rotating freely (no angle step)' : 'Hold to rotate freely',
+      active: shiftPressed,
+    },
+  ]
+}
+
+export type SelectModeHelpContext = {
+  selectedCount: number
+  hasMovableSelection: boolean
+  hasRotatableSelection: boolean
+  commandPressed: boolean
+  shiftPressed: boolean
+  // When a single MEP node is selected its in-world handle rig (click a dot to
+  // reveal move arrows) is the real editing path, so the panel leads with the
+  // handle-specific hints instead of just the generic Cmd-drag tips.
+  mepSelection?: 'run' | 'fitting' | null
+}
+
+const COMMAND_KEY = 'Cmd/Ctrl'
+const LEFT_CLICK = 'Left click'
+const RIGHT_CLICK = 'Right click'
+const SHIFT_KEY = 'Shift'
+const CLICK = 'Click'
+const ALT_KEY = 'Alt'
+const ROTATE_KEYS = 'R / T'
+const ESC_KEY = 'Esc'
+
+export function resolveSelectModeHelpHints({
+  selectedCount,
+  hasMovableSelection,
+  hasRotatableSelection,
+  commandPressed,
+  shiftPressed,
+  mepSelection = null,
+}: SelectModeHelpContext): ContextualShortcutHint[] {
+  const hints: ContextualShortcutHint[] = []
+
+  if (selectedCount === 0) {
+    if (!commandPressed && !shiftPressed) return hints
+
+    hints.push({
+      keys: [[COMMAND_KEY, SHIFT_KEY], LEFT_CLICK],
+      label: 'Add or remove objects from the selection',
+      active: true,
+    })
+    return hints
+  }
+
+  // Multi-selection — advertise the group gestures: drag any member to slide
+  // the whole selection (2D floor plan body drag + the 3D move gizmo), R / T
+  // to step-rotate the group around its bounding-box center.
+  if (selectedCount > 1) {
+    hints.push({
+      keys: [LEFT_CLICK],
+      label: 'Click or drag the selection to move it as one',
+    })
+    hints.push({ keys: [ROTATE_KEYS], label: 'Rotate the selection ±45°' })
+    hints.push({
+      keys: [[COMMAND_KEY, SHIFT_KEY], LEFT_CLICK],
+      label: 'Add or remove objects from the selection',
+      active: commandPressed || shiftPressed,
+    })
+    hints.push({ keys: [ESC_KEY], label: 'Clear the selection (or click outside)' })
+    return hints
+  }
+
+  // MEP handle workflow — duct/pipe runs and fittings are edited through the
+  // in-world arrow rig that a click on the handle dot reveals, so surface those
+  // hints first. A run endpoint's side / up-down arrows swing the run and Alt
+  // detaches the joint mid-drag; a fitting's cluster adds rotate arcs, with
+  // R / T (and Alt to switch axis) for keyboard rotation.
+  if (mepSelection === 'run') {
+    hints.push({ keys: [CLICK], label: 'Click a handle dot to show move arrows' })
+    hints.push({ keys: [ALT_KEY], label: 'Detach the joint while dragging an arrow' })
+  } else if (mepSelection === 'fitting') {
+    hints.push({ keys: [CLICK], label: 'Click the handle dot to show move + rotate handles' })
+    hints.push({ keys: [ROTATE_KEYS], label: 'Rotate ±45°' })
+    hints.push({ keys: [ALT_KEY], label: 'Switch the rotation axis (Y → X → Z)' })
+  }
+
+  // The rows are the same whatever modifier is held — guides/snapping are
+  // governed by the snapping mode (Shift toggles it), not by the modifier of
+  // this gesture, so there are no modifier-specific variants to advertise.
+  // Holding Cmd/Ctrl or Shift just lights the selection row.
+  if (hasMovableSelection) {
+    hints.push({
+      keys: [LEFT_CLICK],
+      label: 'Drag selected movable object',
+    })
+  }
+
+  if (hasRotatableSelection) {
+    hints.push({
+      keys: [COMMAND_KEY, RIGHT_CLICK],
+      label: 'Drag left or right to rotate selected object',
+    })
+  }
+
+  hints.push({
+    keys: [[COMMAND_KEY, SHIFT_KEY], LEFT_CLICK],
+    label: 'Add or remove objects from the selection',
+    active: commandPressed || shiftPressed,
+  })
+
+  return hints
+}

package/src/lib/continuation.ts

@@ -0,0 +1,64 @@
+export type ContinuationContext = 'wall' | 'fence' | 'point' | 'cabinet'
+export type ContinuationMode = string
+
+export const CONTINUATION_PROFILES: Record<
+  ContinuationContext,
+  {
+    options: ContinuationMode[]
+    default: ContinuationMode
+    labels: Record<string, string>
+    icons: Record<string, string>
+  }
+> = {
+  wall: {
+    options: ['room', 'single'],
+    default: 'room',
+    labels: { room: 'Room (auto-close)', single: 'Single wall' },
+    icons: { room: 'lucide:square', single: 'lucide:minus' },
+  },
+  fence: {
+    options: ['single', 'continuous', 'curved'],
+    default: 'continuous',
+    labels: {
+      continuous: 'Continuous',
+      single: 'Single fence',
+      curved: 'Curved fence',
+    },
+    icons: {
+      continuous: 'lucide:waypoints',
+      single: 'lucide:minus',
+      curved: 'lucide:spline',
+    },
+  },
+  point: {
+    options: ['once', 'repeat'],
+    default: 'once',
+    labels: { once: 'Place once', repeat: 'Place multiple' },
+    icons: { once: 'lucide:target', repeat: 'lucide:copy-plus' },
+  },
+  cabinet: {
+    options: ['single', 'continuous'],
+    default: 'single',
+    labels: { single: 'Single cabinet', continuous: 'Continuous run' },
+    icons: { single: 'lucide:minus', continuous: 'lucide:waypoints' },
+  },
+}
+
+const POINT_KINDS = new Set(['item', 'door', 'window', 'shelf', 'column'])
+
+export function nextContinuation(
+  context: ContinuationContext,
+  current: ContinuationMode,
+): ContinuationMode {
+  const profile = CONTINUATION_PROFILES[context]
+  const index = profile.options.indexOf(current)
+  if (index === -1) return profile.default
+  return profile.options[(index + 1) % profile.options.length] ?? profile.default
+}
+
+export function continuationContextOf(kind: string): ContinuationContext | null {
+  if (kind === 'wall') return 'wall'
+  if (kind === 'fence') return 'fence'
+  if (kind === 'cabinet') return 'cabinet'
+  return POINT_KINDS.has(kind) ? 'point' : null
+}

package/src/lib/direct-manipulation.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  type AnyNode,
+  type AnyNodeDefinition,
+  DEFAULT_ANGLE_STEP,
+  nodeRegistry,
+  registerNode,
+} from '@pascal-app/core'
+import { z } from 'zod'
+import {
+  canDirectMoveNode,
+  resolveDirectManipulationNode,
+  resolveDirectRotationDragDelta,
+  snapDirectRotationDelta,
+} from './direct-manipulation'
+
+function registerTestDefinition(kind: string, overrides: Partial<AnyNodeDefinition>) {
+  if (nodeRegistry.has(kind)) return
+  registerNode({
+    kind,
+    schemaVersion: 1,
+    schema: z.object({ type: z.literal(kind) }) as never,
+    category: 'structure',
+    defaults: () => ({ type: kind }) as never,
+    capabilities: {},
+    renderer: { kind: 'parametric', module: async () => ({ default: () => null }) },
+    ...overrides,
+  } as AnyNodeDefinition)
+}
+
+describe('snapDirectRotationDelta', () => {
+  test('snaps rotation deltas to the default angle increment', () => {
+    expect(snapDirectRotationDelta(DEFAULT_ANGLE_STEP * 0.49, false)).toBe(0)
+    expect(snapDirectRotationDelta(DEFAULT_ANGLE_STEP * 0.51, false)).toBeCloseTo(
+      DEFAULT_ANGLE_STEP,
+    )
+    expect(snapDirectRotationDelta(DEFAULT_ANGLE_STEP * -1.49, false)).toBeCloseTo(
+      -DEFAULT_ANGLE_STEP,
+    )
+  })
+
+  test('keeps the raw rotation delta while free-rotating', () => {
+    const rawDelta = DEFAULT_ANGLE_STEP * 0.42
+    expect(snapDirectRotationDelta(rawDelta, true)).toBe(rawDelta)
+  })
+})
+
+describe('resolveDirectRotationDragDelta', () => {
+  test('maps horizontal pointer motion to the direct rotation delta direction', () => {
+    const radiansPerPixel = DEFAULT_ANGLE_STEP / 12
+
+    expect(resolveDirectRotationDragDelta(100, 112, radiansPerPixel, false)).toBeCloseTo(
+      -DEFAULT_ANGLE_STEP,
+    )
+    expect(resolveDirectRotationDragDelta(100, 88, radiansPerPixel, false)).toBeCloseTo(
+      DEFAULT_ANGLE_STEP,
+    )
+  })
+
+  test('keeps unsnapped drag deltas while free-rotating', () => {
+    expect(resolveDirectRotationDragDelta(100, 103, 0.1, true)).toBeCloseTo(-0.3)
+  })
+})
+
+describe('canDirectMoveNode', () => {
+  // Accepts kinds with a 3D-mountable move tool (`movable` or
+  // `affordanceTools.move`); floorplan-only movers (zone) are excluded.
+  test('rejects floorplan-only move targets (no 3D tool mounts)', () => {
+    const kind = 'direct-move-floorplan-only-test'
+    registerTestDefinition(kind, { floorplanMoveTarget: {} as never })
+
+    expect(canDirectMoveNode({ id: 'node_1', type: kind } as unknown as AnyNode)).toBe(false)
+  })
+
+  test('rejects MEP kinds that own move through bespoke selection affordances', () => {
+    for (const kind of [
+      'duct-segment',
+      'duct-fitting',
+      'pipe-segment',
+      'pipe-fitting',
+      'lineset',
+      'liquid-line',
+    ]) {
+      expect(canDirectMoveNode({ id: 'node_1', type: kind } as unknown as AnyNode)).toBe(false)
+    }
+  })
+
+  test('accepts kinds with a bespoke move tool', () => {
+    const kind = 'direct-move-bespoke-tool-test'
+    registerTestDefinition(kind, {
+      affordanceTools: {
+        move: async () => ({ default: () => null }),
+      } as never,
+    })
+
+    expect(canDirectMoveNode({ id: 'node_1', type: kind } as unknown as AnyNode)).toBe(true)
+  })
+
+  test('accepts nodes with the generic movable capability', () => {
+    const kind = 'direct-move-movable-test'
+    registerTestDefinition(kind, {
+      capabilities: {
+        movable: { axes: ['x', 'z'], gridSnap: true },
+      },
+    } as Partial<AnyNodeDefinition>)
+
+    expect(canDirectMoveNode({ id: 'node_1', type: kind } as unknown as AnyNode)).toBe(true)
+  })
+
+  test('rejects kinds with no registered move path', () => {
+    const kind = 'direct-move-none-test'
+    registerTestDefinition(kind, {})
+
+    expect(canDirectMoveNode({ id: 'node_1', type: kind } as unknown as AnyNode)).toBe(false)
+  })
+})
+
+describe('resolveDirectManipulationNode', () => {
+  test('routes proxied members to their assembly for direct transforms', () => {
+    const group = {
+      id: 'direct_manipulation_group',
+      type: 'direct-manipulation-group-test',
+    } as unknown as AnyNode
+    const member = {
+      id: 'direct_manipulation_member',
+      type: 'direct-manipulation-member-test',
+      metadata: { nodeSelectionProxyId: group.id },
+    } as unknown as AnyNode
+
+    expect(
+      resolveDirectManipulationNode(member, {
+        [group.id]: group,
+        [member.id]: member,
+      }),
+    ).toBe(group)
+  })
+
+  test('falls back to the selected node when the proxy target is missing', () => {
+    const member = {
+      id: 'direct_manipulation_orphan_member',
+      type: 'direct-manipulation-member-test',
+      metadata: { nodeSelectionProxyId: 'missing_group' },
+    } as unknown as AnyNode
+
+    expect(resolveDirectManipulationNode(member, { [member.id]: member })).toBe(member)
+  })
+
+  test('routes parent-frame children to their rotatable parent', () => {
+    const parentKind = 'direct-manipulation-parent-frame-parent-test'
+    const childKind = 'direct-manipulation-parent-frame-child-test'
+    registerTestDefinition(parentKind, {
+      capabilities: { rotatable: { axes: ['y'], snapAngles: [Math.PI / 4] } },
+    })
+    registerTestDefinition(childKind, {
+      capabilities: {
+        movable: {
+          axes: ['x', 'z'],
+          gridSnap: true,
+          parentFrame: {
+            resolveParent: (node: AnyNode, nodes: Readonly<Record<string, AnyNode>>) =>
+              (node.parentId ? nodes[node.parentId] : null) ?? null,
+            parentRotationY: () => 0,
+            localToPlan: (_parent: AnyNode, local: readonly [number, number, number]) => [
+              local[0],
+              local[1],
+              local[2],
+            ],
+            planToLocal: (_parent: AnyNode, planX: number, localY: number, planZ: number) => [
+              planX,
+              localY,
+              planZ,
+            ],
+          },
+        },
+      },
+    })
+
+    const parent = { id: 'direct_manipulation_parent', type: parentKind } as unknown as AnyNode
+    const child = {
+      id: 'direct_manipulation_child',
+      type: childKind,
+      parentId: parent.id,
+    } as unknown as AnyNode
+
+    expect(
+      resolveDirectManipulationNode(child, {
+        [parent.id]: parent,
+        [child.id]: child,
+      }),
+    ).toBe(parent)
+  })
+})

package/src/lib/direct-manipulation.ts

@@ -0,0 +1,109 @@
+import {
+  type AnyNode,
+  type ArcResizeHandle,
+  createSceneApi,
+  DEFAULT_ANGLE_STEP,
+  type HandleDescriptor,
+  hasRegistry3DMoveTool,
+  isMovable,
+  nodeRegistry,
+  resolveSelectionProxyId,
+  type SceneApi,
+  useScene,
+} from '@pascal-app/core'
+
+function resolveHandles(node: AnyNode): HandleDescriptor<AnyNode>[] {
+  const handles = nodeRegistry.get(node.type)?.handles
+  if (!handles) return []
+  return (
+    typeof handles === 'function' ? handles(node as never) : handles
+  ) as HandleDescriptor<AnyNode>[]
+}
+
+export function getDirectRotateHandle(node: AnyNode): ArcResizeHandle<AnyNode> | null {
+  for (const handle of resolveHandles(node)) {
+    if (handle.kind === 'arc-resize' && handle.shape === 'rotate') {
+      return handle as ArcResizeHandle<AnyNode>
+    }
+  }
+  return null
+}
+
+export function canDirectRotateNode(node: AnyNode): boolean {
+  return (
+    getDirectRotateHandle(node) !== null ||
+    nodeRegistry.get(node.type)?.capabilities?.rotatable !== undefined
+  )
+}
+
+const BESPOKE_SELECTION_MOVE_KINDS = new Set([
+  'duct-segment',
+  'duct-fitting',
+  'pipe-segment',
+  'pipe-fitting',
+  'lineset',
+  'liquid-line',
+])
+
+export function canDirectMoveNode(node: AnyNode): boolean {
+  // These MEP kinds own move through bespoke selection rigs (latch cubes,
+  // directional arrows, grid-driven previews). Sending body drags/clicks
+  // through the generic direct-move handoff conflicts with that path and can
+  // leave the editor appearing frozen while their mover waits for the wrong
+  // gesture stream.
+  if (BESPOKE_SELECTION_MOVE_KINDS.has(node.type)) return false
+  // 3D direct move (Ctrl/Meta-drag, the move-cross grip) needs a move tool that
+  // mounts in 3D — distinct from `isRegistryMovable`, which also accepts
+  // floorplan-only movers (zone) for the 2D plan.
+  if (!hasRegistry3DMoveTool(node.type)) return false
+  // Bespoke movers (`affordanceTools.move`) own their constraints and often
+  // deliberately omit `capabilities.movable` — only gate registry-movable
+  // kinds on `isMovable`, so a per-node `movable.override` (e.g. a cabinet
+  // run locked behind its selection proxy) can opt out of direct move.
+  if (nodeRegistry.get(node.type)?.affordanceTools?.move) return true
+  return isMovable(node)
+}
+
+export function resolveDirectManipulationNode(
+  node: AnyNode,
+  nodes: Readonly<Record<string, AnyNode | undefined>>,
+): AnyNode {
+  const target = nodes[resolveSelectionProxyId(node, nodes)] ?? node
+  const parentFrame = nodeRegistry.get(target.type)?.capabilities?.movable?.parentFrame
+  const parent = parentFrame?.resolveParent(target, nodes as Readonly<Record<string, AnyNode>>)
+  return parent && canDirectRotateNode(parent) ? parent : target
+}
+
+export function snapDirectRotationDelta(delta: number, free: boolean): number {
+  return free ? delta : Math.round(delta / DEFAULT_ANGLE_STEP) * DEFAULT_ANGLE_STEP
+}
+
+export function resolveDirectRotationDragDelta(
+  startX: number,
+  clientX: number,
+  radiansPerPixel: number,
+  free: boolean,
+): number {
+  return snapDirectRotationDelta((startX - clientX) * radiansPerPixel, free)
+}
+
+export function resolveDirectRotationPatch(
+  node: AnyNode,
+  delta: number,
+  sceneApi: SceneApi = createSceneApi(useScene),
+): Partial<AnyNode> | null {
+  const rotateHandle = getDirectRotateHandle(node)
+  if (rotateHandle) {
+    return rotateHandle.apply(node, delta, sceneApi) as Partial<AnyNode>
+  }
+
+  const rotation = (node as { rotation?: unknown }).rotation
+  if (typeof rotation === 'number') {
+    return { rotation: rotation - delta } as Partial<AnyNode>
+  }
+  if (Array.isArray(rotation)) {
+    const [rx = 0, ry = 0, rz = 0] = rotation as [number?, number?, number?]
+    return { rotation: [rx, ry - delta, rz] } as Partial<AnyNode>
+  }
+  return null
+}

package/src/lib/editor-api.ts

@@ -0,0 +1,50 @@
+import type { AnyNode, EditorApi } from '@pascal-app/core'
+import useEditor from '../store/use-editor'
+import useInteractionScope from '../store/use-interaction-scope'
+import {
+  controlPointReshapeScope,
+  endpointReshapeScope,
+  tangentReshapeScope,
+} from './interaction/scope'
+
+/**
+ * Concrete {@link EditorApi} backed by `useEditor` + the interaction scope.
+ * Descriptors call into editor state through this interface; the editor owns
+ * the actual store wiring so core stays decoupled.
+ *
+ * `engageMove` no longer clears any in-progress endpoint drag or curve gesture:
+ * `setMovingNode` begins the `moving` scope, and the scope is single-owner, so
+ * it atomically replaces any prior reshape — there is no separate flag to reset.
+ */
+export function createEditorApi(): EditorApi {
+  return {
+    engageMove(node: AnyNode) {
+      const editor = useEditor.getState()
+      editor.setPlacementDragMode(false)
+      // `setMovingNode` is typed against a narrower union than `AnyNode`
+      // (every concrete kind enumerated). Descriptors pass any node; the
+      // cast lets registry-driven move kinds through without forcing a
+      // schema-level type widening.
+      editor.setMovingNode(node as Parameters<typeof editor.setMovingNode>[0])
+    },
+    engageMoveDrag(node: AnyNode) {
+      const editor = useEditor.getState()
+      // Flag drag mode BEFORE mounting the move tool so the coordinator reads
+      // it at setup and wires its commit-on-release listener.
+      editor.setPlacementDragMode(true)
+      editor.setMovingNode(node as Parameters<typeof editor.setMovingNode>[0])
+    },
+    engageEndpointMove(node: AnyNode, endpoint: 'start' | 'end') {
+      // Endpoint reshape is kind-agnostic: the scope carries the node id + which
+      // endpoint, and consumers recover the node from the scene. Adding a new
+      // endpoint-draggable kind needs no entry here.
+      useInteractionScope.getState().begin(endpointReshapeScope(node.id, endpoint))
+    },
+    engageControlPointMove(node: AnyNode, index: number) {
+      useInteractionScope.getState().begin(controlPointReshapeScope(node.id, index))
+    },
+    engageTangentMove(node: AnyNode, index: number, side: 'in' | 'out') {
+      useInteractionScope.getState().begin(tangentReshapeScope(node.id, index, side))
+    },
+  }
+}