@pascal-app/editor 1.0.0-beta.4 → 1.0.0

package/src/lib/history.ts

@@ -1,45 +1,164 @@
-import { useLiveNodeOverrides, useLiveTransforms, useScene } from '@pascal-app/core'
+import {
+  type AnyNode,
+  type AnyNodeId,
+  emitter,
+  getHistoryDirtyNodeIds,
+  useLiveNodeOverrides,
+  useLiveTransforms,
+  useScene,
+} from '@pascal-app/core'
+import { markPerfAction } from '@pascal-app/viewer'
+import useInteractionScope from '../store/use-interaction-scope'
+import { registeredDraftingConfig } from './interaction/registered-drafting'
+
+export type HistoryCommandState = {
+  canRedo: boolean
+  canUndo: boolean
+  mode: 'collaborative' | 'standalone'
+  status: 'offline' | 'ready' | 'syncing' | 'unavailable'
+}
+
+export type HistoryCommandResult =
+  | { kind: 'applied'; persistence: 'local' | 'queued' }
+  | { kind: 'empty' }
+  | { kind: 'unavailable' }
 
 export type HistoryCommandDelegate = {
-  undo: () => void
-  redo: () => void
+  getState: () => HistoryCommandState
+  redo: () => HistoryCommandResult
+  subscribe: (listener: () => void) => () => void
+  undo: () => HistoryCommandResult
 }
 
 let historyCommandDelegate: HistoryCommandDelegate | null = null
+let historyCommandDelegateSubscription: (() => void) | null = null
+const historyCommandListeners = new Set<() => void>()
 
 export function installHistoryCommandDelegate(delegate: HistoryCommandDelegate): () => void {
+  historyCommandDelegateSubscription?.()
   historyCommandDelegate = delegate
+  historyCommandDelegateSubscription = delegate.subscribe(notifyHistoryCommandListeners)
+  notifyHistoryCommandListeners()
+  return () => {
+    if (historyCommandDelegate !== delegate) return
+    historyCommandDelegateSubscription?.()
+    historyCommandDelegateSubscription = null
+    historyCommandDelegate = null
+    notifyHistoryCommandListeners()
+  }
+}
+
+export function getHistoryCommandState(): HistoryCommandState {
+  if (historyCommandDelegate) return historyCommandDelegate.getState()
+  const temporal = useScene.temporal.getState()
+  return {
+    canRedo: temporal.futureStates.length > 0,
+    canUndo: temporal.pastStates.length > 0,
+    mode: 'standalone',
+    status: 'ready',
+  }
+}
+
+export function subscribeHistoryCommandState(listener: () => void): () => void {
+  historyCommandListeners.add(listener)
+  const unsubscribeTemporal = useScene.temporal.subscribe(listener)
   return () => {
-    if (historyCommandDelegate === delegate) historyCommandDelegate = null
+    historyCommandListeners.delete(listener)
+    unsubscribeTemporal()
   }
 }
 
-function refreshSceneAfterHistoryJump() {
+function notifyHistoryCommandListeners() {
+  for (const listener of [...historyCommandListeners]) listener()
+}
+
+function capturePreviewLayout() {
+  const overrides = useLiveNodeOverrides.getState().overrides
+  if (overrides.size === 0) return null
+  const nodes = { ...useScene.getState().nodes }
+  for (const [id, values] of overrides) {
+    const node = nodes[id as AnyNodeId]
+    if (node) nodes[node.id] = { ...node, ...values } as AnyNode
+  }
+  return nodes
+}
+
+function refreshSceneAfterHistoryJump(previewLayout: Record<string, AnyNode> | null) {
+  const target = useScene.getState().nodes
+  const previewDirty = previewLayout
+    ? getHistoryDirtyNodeIds(previewLayout, target)
+    : new Set<AnyNodeId>()
+  const previewIds = new Set([
+    ...useLiveTransforms.getState().transforms.keys(),
+    ...useLiveNodeOverrides.getState().overrides.keys(),
+  ])
+  const currentPreviewLayout = capturePreviewLayout()
+  if (currentPreviewLayout) {
+    for (const id of getHistoryDirtyNodeIds(currentPreviewLayout, target)) previewDirty.add(id)
+  }
   useLiveNodeOverrides.getState().clearAll()
   useLiveTransforms.getState().clearAll()
+  // Clearing overrides can republish stair holes while a live transform still
+  // exists. Capture that final publication before clearing it too.
+  const remainingOverrides = useLiveNodeOverrides.getState().overrides
+  if (remainingOverrides.size > 0) {
+    for (const id of remainingOverrides.keys()) previewIds.add(id)
+    const remainingLayout = capturePreviewLayout()
+    if (remainingLayout) {
+      for (const id of getHistoryDirtyNodeIds(remainingLayout, target)) previewDirty.add(id)
+    }
+    useLiveNodeOverrides.getState().clearAll()
+  }
 
   const state = useScene.getState()
-  for (const node of Object.values(state.nodes)) {
+  for (const id of previewDirty) {
+    if (state.nodes[id]) state.markDirty(id)
+  }
+  for (const id of previewIds) {
+    const node = state.nodes[id as AnyNodeId]
+    if (!node) continue
     state.markDirty(node.id)
+    if (node.parentId && state.nodes[node.parentId as AnyNodeId]) {
+      state.markDirty(node.parentId as AnyNodeId)
+    }
   }
 }
 
-export function runUndo() {
+export function shouldCancelDraftOnHistoryJump(): boolean {
+  const scope = useInteractionScope.getState().scope
+  return registeredDraftingConfig(scope)?.cancelOnHistoryJump === true
+}
+
+export function runUndo(): HistoryCommandResult {
+  if (shouldCancelDraftOnHistoryJump()) emitter.emit('tool:cancel')
   if (historyCommandDelegate) {
-    historyCommandDelegate.undo()
-    return
+    const result = historyCommandDelegate.undo()
+    // Mark only real jumps: a no-op undo must not open a receipt (or
+    // interrupt one that is still settling).
+    if (result.kind !== 'empty') markPerfAction('undo')
+    return result
   }
+  if (useScene.temporal.getState().pastStates.length === 0) return { kind: 'empty' }
+  markPerfAction('undo')
+  const previewLayout = capturePreviewLayout()
   useScene.temporal.getState().undo()
-  refreshSceneAfterHistoryJump()
+  refreshSceneAfterHistoryJump(previewLayout)
+  return { kind: 'applied', persistence: 'local' }
 }
 
-export function runRedo() {
+export function runRedo(): HistoryCommandResult {
+  if (shouldCancelDraftOnHistoryJump()) emitter.emit('tool:cancel')
   if (historyCommandDelegate) {
-    historyCommandDelegate.redo()
-    return
+    const result = historyCommandDelegate.redo()
+    if (result.kind !== 'empty') markPerfAction('redo')
+    return result
   }
+  if (useScene.temporal.getState().futureStates.length === 0) return { kind: 'empty' }
+  markPerfAction('redo')
+  const previewLayout = capturePreviewLayout()
   useScene.temporal.getState().redo()
-  refreshSceneAfterHistoryJump()
+  refreshSceneAfterHistoryJump(previewLayout)
+  return { kind: 'applied', persistence: 'local' }
 }
 
 /**

package/src/lib/host-tree-children.test.ts

@@ -0,0 +1,27 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import {
+  editorHostTreeChildrenRegistry,
+  registerEditorHostTreeChildren,
+} from './host-tree-children'
+
+describe('editorHostTreeChildrenRegistry', () => {
+  afterEach(() => editorHostTreeChildrenRegistry.reset())
+
+  test('exposes host children by scene node kind and notifies mounted trees', () => {
+    let notifications = 0
+    const unsubscribe = editorHostTreeChildrenRegistry.subscribe(() => {
+      notifications += 1
+    })
+
+    registerEditorHostTreeChildren({
+      kind: 'scan',
+      component: () => null,
+      hasChildren: (node) => node.type === 'scan',
+    })
+
+    expect(editorHostTreeChildrenRegistry.childrenForKind('scan')).toBeDefined()
+    expect(editorHostTreeChildrenRegistry.childrenForKind('wall')).toBeUndefined()
+    expect(notifications).toBe(1)
+    unsubscribe()
+  })
+})

package/src/lib/host-tree-children.ts

@@ -0,0 +1,79 @@
+import type { AnyNode, AnyNodeId } from '@pascal-app/core'
+import type { ComponentType } from 'react'
+
+export type EditorHostTreeChildrenProps = {
+  nodeId: AnyNodeId
+  depth: number
+  parentVisible: boolean
+}
+
+export type EditorHostTreeChildren = {
+  kind: string
+  component: ComponentType<EditorHostTreeChildrenProps>
+  hasChildren: (node: AnyNode) => boolean
+}
+
+function isDevMode(): boolean {
+  try {
+    const meta = import.meta as { env?: { DEV?: boolean } }
+    if (typeof meta?.env?.DEV === 'boolean') return meta.env.DEV
+  } catch {
+    // import.meta unavailable in some CJS contexts — fall through.
+  }
+  if (typeof process !== 'undefined' && process.env?.NODE_ENV) {
+    return process.env.NODE_ENV !== 'production'
+  }
+  return false
+}
+
+class EditorHostTreeChildrenRegistryImpl {
+  private readonly entries = new Map<string, EditorHostTreeChildren>()
+  private readonly listeners = new Set<() => void>()
+  private revision = 0
+
+  subscribe = (onChange: () => void): (() => void) => {
+    this.listeners.add(onChange)
+    return () => {
+      this.listeners.delete(onChange)
+    }
+  }
+
+  getSnapshot = (): number => this.revision
+
+  childrenForKind = (kind: string): EditorHostTreeChildren | undefined => this.entries.get(kind)
+
+  reset(): void {
+    this.entries.clear()
+    this.emit()
+  }
+
+  register(entry: EditorHostTreeChildren): void {
+    if (typeof entry.kind !== 'string' || entry.kind.length === 0) {
+      throw new Error('[editor:host-tree-children] kind must be a non-empty string')
+    }
+    if (this.entries.has(entry.kind)) {
+      if (isDevMode()) {
+        console.warn(
+          `[editor:host-tree-children] re-registering children for "${entry.kind}" (HMR)`,
+        )
+      } else {
+        throw new Error(
+          `[editor:host-tree-children] duplicate kind: "${entry.kind}" already registered`,
+        )
+      }
+    }
+    this.entries.set(entry.kind, entry)
+    this.emit()
+  }
+
+  private emit(): void {
+    this.revision += 1
+    for (const listener of this.listeners) listener()
+  }
+}
+
+export const editorHostTreeChildrenRegistry = new EditorHostTreeChildrenRegistryImpl()
+
+export function registerEditorHostTreeChildren(entry: EditorHostTreeChildren): void {
+  editorHostTreeChildrenRegistry.register(entry)
+}

package/src/lib/inspector-card-mode.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  type InspectorCardMode,
+  resolveActiveExtension,
+  toggleCard,
+  toggleExtension,
+} from './inspector-card-mode'
+
+const collapsed: InspectorCardMode = { collapsed: true, activeExtensionId: null }
+const regular: InspectorCardMode = { collapsed: false, activeExtensionId: null }
+const engineering: InspectorCardMode = { collapsed: false, activeExtensionId: 'bones:eng' }
+
+// EITHER/OR contract (replaces #667's appended-section behavior): the
+// expanded card shows the regular controls OR one extension's content,
+// never both. These gates encode every transition of the mode machine.
+
+describe('toggleCard (chevron / header press)', () => {
+  test('folded card expands to the REGULAR controls — no extension', () => {
+    expect(toggleCard(collapsed)).toEqual(regular)
+  })
+
+  test('regular expanded card folds', () => {
+    expect(toggleCard(regular)).toEqual(collapsed)
+  })
+
+  test('extension mode returns to the regular controls, staying expanded', () => {
+    // The chevron exits extension mode first; it does NOT fold from there.
+    expect(toggleCard(engineering)).toEqual(regular)
+  })
+})
+
+describe('toggleExtension (header icon press)', () => {
+  test('folded card opens straight into extension-only mode', () => {
+    expect(toggleExtension(collapsed, 'bones:eng')).toEqual(engineering)
+  })
+
+  test('regular expanded card swaps to extension-only mode', () => {
+    expect(toggleExtension(regular, 'bones:eng')).toEqual(engineering)
+  })
+
+  test('pressing the ACTIVE extension icon again returns to regular mode', () => {
+    expect(toggleExtension(engineering, 'bones:eng')).toEqual(regular)
+  })
+
+  test('pressing another extension icon switches extension modes directly', () => {
+    expect(toggleExtension(engineering, 'other:ext')).toEqual({
+      collapsed: false,
+      activeExtensionId: 'other:ext',
+    })
+  })
+})
+
+describe('resolveActiveExtension', () => {
+  const bones = { id: 'bones:eng' }
+  const other = { id: 'other:ext' }
+  const extensions = [bones, other]
+
+  test('null id → regular mode (no extension)', () => {
+    expect(resolveActiveExtension(null, extensions)).toBeNull()
+  })
+
+  test('matching id → that extension fills the body', () => {
+    expect(resolveActiveExtension('bones:eng', extensions)).toBe(bones)
+    expect(resolveActiveExtension('other:ext', extensions)).toBe(other)
+  })
+
+  test('stale id (kind changed / plugin gated off) falls back to regular', () => {
+    expect(resolveActiveExtension('bones:eng', [])).toBeNull()
+    expect(resolveActiveExtension('gone:ext', extensions)).toBeNull()
+  })
+})
+
+describe('full user flows (QA script)', () => {
+  test('chevron → regular only; fold; icon → extension only; icon again → regular', () => {
+    let mode = collapsed
+    mode = toggleCard(mode) // chevron
+    expect(mode).toEqual(regular)
+    mode = toggleCard(mode) // fold
+    expect(mode).toEqual(collapsed)
+    mode = toggleExtension(mode, 'bones:eng') // bones icon
+    expect(mode).toEqual(engineering)
+    mode = toggleExtension(mode, 'bones:eng') // bones icon again
+    expect(mode).toEqual(regular)
+  })
+
+  test('extension mode exits via the chevron too', () => {
+    let mode = toggleExtension(collapsed, 'bones:eng')
+    expect(mode).toEqual(engineering)
+    mode = toggleCard(mode) // chevron
+    expect(mode).toEqual(regular)
+  })
+})

package/src/lib/inspector-card-mode.ts

@@ -0,0 +1,60 @@
+/**
+ * Mode machine for the floating inspector card (`PanelWrapper`).
+ *
+ * The card is in exactly one of three modes — the two expanded modes are
+ * EITHER/OR, never combined:
+ *
+ * - collapsed: header only;
+ * - regular: the node kind's own controls (`children`) — no plugin
+ *   inspector-extension sections appended;
+ * - extension: ONE plugin inspector-extension's content fills the body
+ *   (its own section chrome), the regular controls are hidden.
+ *
+ * Transitions:
+ * - chevron / header press ({@link toggleCard}): collapsed → regular,
+ *   regular → collapsed, extension → regular (exit extension mode first,
+ *   stay expanded);
+ * - extension icon press ({@link toggleExtension}): enters that
+ *   extension's mode from anywhere (expanding a folded card); pressing
+ *   the ACTIVE extension's icon again returns to regular.
+ */
+
+export interface InspectorCardMode {
+  /** Card folded to its header. */
+  collapsed: boolean
+  /** Extension whose content fills the body; null = regular controls. */
+  activeExtensionId: string | null
+}
+
+/** Chevron / header press. */
+export function toggleCard(mode: InspectorCardMode): InspectorCardMode {
+  // Folded → expand to the regular controls.
+  if (mode.collapsed) return { collapsed: false, activeExtensionId: null }
+  // Extension mode → back to the regular controls (stay expanded).
+  if (mode.activeExtensionId !== null) return { collapsed: false, activeExtensionId: null }
+  // Regular expanded → fold.
+  return { collapsed: true, activeExtensionId: null }
+}
+
+/** Header extension-icon press. */
+export function toggleExtension(mode: InspectorCardMode, extensionId: string): InspectorCardMode {
+  // The active extension's icon pressed again → back to the regular controls.
+  if (!mode.collapsed && mode.activeExtensionId === extensionId) {
+    return { collapsed: false, activeExtensionId: null }
+  }
+  // Anywhere else (folded, regular, another extension) → this extension only.
+  return { collapsed: false, activeExtensionId: extensionId }
+}
+
+/**
+ * The extension whose content should fill the card body, or null for the
+ * regular controls. A stale `activeExtensionId` (selection changed kind,
+ * plugin uninstalled, registry reset) safely falls back to regular mode.
+ */
+export function resolveActiveExtension<E extends { id: string }>(
+  activeExtensionId: string | null,
+  extensions: readonly E[],
+): E | null {
+  if (activeExtensionId === null) return null
+  return extensions.find((extension) => extension.id === activeExtensionId) ?? null
+}

package/src/lib/interaction/hot-set.test.ts

@@ -22,6 +22,13 @@ const wall: HotSetCandidate = {
   exposesTop: false,
   attachClass: 'surface',
 }
+const block: HotSetCandidate = {
+  type: 'block',
+  isFloorLike: false,
+  exposesTop: true,
+  exposesSides: true,
+  attachClass: 'surface',
+}
 const ceiling: HotSetCandidate = {
   type: 'ceiling',
   isFloorLike: false,
@@ -63,8 +70,9 @@ describe('attachClassOf', () => {
 })
 
 describe('isPickableForAttach — wall-mounted (window)', () => {
-  test('only walls are eligible; floor/ceiling/tops are not', () => {
+  test('walls and block faces are eligible; floor/ceiling/tops are not', () => {
     expect(isPickableForAttach('wall', wall)).toBe(true)
+    expect(isPickableForAttach('wall', block)).toBe(true)
     expect(isPickableForAttach('wall', floor)).toBe(false)
     expect(isPickableForAttach('wall', ceiling)).toBe(false)
     expect(isPickableForAttach('wall', table)).toBe(false)
@@ -109,6 +117,7 @@ describe('isCandidateInHotSet — by scope', () => {
       nodeType: 'item',
       view: '3d' as const,
       pressDrag: false,
+      driver: 'move-tool' as const,
     }
     expect(isCandidateInHotSet(scope, surfaceClass, floor)).toBe(true)
     expect(isCandidateInHotSet(scope, surfaceClass, ceilingFan)).toBe(false)

package/src/lib/interaction/hot-set.ts

@@ -30,6 +30,8 @@ export type HotSetCandidate = {
   // The candidate exposes a usable top surface (registry
   // `capabilities.surfaces.top`) — a table, a shelf, a slab.
   exposesTop: boolean
+  // The candidate declares wall-like side faces through registry surfaces.
+  exposesSides?: boolean
   // The candidate's own attach class. A ceiling fan is `ceiling`: it hangs from
   // the ceiling and must never act as a host top (Track E).
   attachClass: AttachClass
@@ -38,7 +40,7 @@ export type HotSetCandidate = {
 // For a node whose attach class is `placed`, is `candidate` a valid
 // host/surface to pick during placement or move?
 export function isPickableForAttach(placed: AttachClass, candidate: HotSetCandidate): boolean {
-  if (placed === 'wall') return candidate.type === 'wall'
+  if (placed === 'wall') return candidate.type === 'wall' || candidate.exposesSides === true
   if (placed === 'ceiling') return candidate.type === 'ceiling'
   // Surface-resting: the floor, or any host that exposes a top surface — but
   // never a ceiling-mounted host (a floor lamp must not land on a ceiling fan).

package/src/lib/interaction/overlay-policy.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, test } from 'bun:test'
 import type { AnyNode } from '@pascal-app/core'
-import { resolveOverlayPolicy } from './overlay-policy'
+import {
+  resolveFloatingActionMenuVisibility,
+  resolveOverlayPolicy,
+  shouldShowEditingControls,
+} from './overlay-policy'
 import type { ActiveInteractionScope } from './scope'
 
 const mockNode = (id: string, type: string): AnyNode => ({ id, type }) as unknown as AnyNode
@@ -13,6 +17,7 @@ const ACTIVE_SCOPES: ActiveInteractionScope[] = [
     nodeType: 'item',
     view: '3d',
     pressDrag: false,
+    driver: 'move-tool',
   },
   { kind: 'moving', node: mockNode('i1', 'item'), nodeId: 'i1', nodeType: 'item', view: '2d' },
   { kind: 'handle-drag', nodeId: 'w1', handle: 'height' },
@@ -50,3 +55,30 @@ describe('resolveOverlayPolicy', () => {
     }
   })
 })
+
+describe('shouldShowEditingControls', () => {
+  test('hides controls that can mutate a read-only scene', () => {
+    expect(shouldShowEditingControls(false)).toBe(true)
+    expect(shouldShowEditingControls(true)).toBe(false)
+  })
+})
+
+describe('resolveFloatingActionMenuVisibility', () => {
+  test('keeps the active measurement pill while hiding action buttons during a height drag', () => {
+    const visibility = resolveFloatingActionMenuVisibility(
+      { kind: 'handle-drag', nodeId: 'wall_1', handle: 'height' },
+      true,
+    )
+
+    expect(visibility).toEqual({ root: true, actions: false })
+  })
+
+  test('hides the whole menu during interactions without an active measurement pill', () => {
+    const visibility = resolveFloatingActionMenuVisibility(
+      { kind: 'handle-drag', nodeId: 'wall_1', handle: 'elevation' },
+      false,
+    )
+
+    expect(visibility).toEqual({ root: false, actions: false })
+  })
+})

package/src/lib/interaction/overlay-policy.ts

@@ -57,3 +57,19 @@ const ACTIVE_POLICY: OverlayPolicy = {
 export function resolveOverlayPolicy(scope: InteractionScope): OverlayPolicy {
   return isActive(scope) ? ACTIVE_POLICY : IDLE_POLICY
 }
+
+export function resolveFloatingActionMenuVisibility(
+  scope: InteractionScope,
+  hasActiveMeasurementPill: boolean,
+): { root: boolean; actions: boolean } {
+  const policy = resolveOverlayPolicy(scope)
+  const actions = policy.conflictingControls === 'shown'
+  return {
+    root: actions || (hasActiveMeasurementPill && policy.activeAffordances === 'shown'),
+    actions,
+  }
+}
+
+export function shouldShowEditingControls(readOnly: boolean): boolean {
+  return !readOnly
+}

package/src/lib/interaction/registered-drafting.ts

@@ -0,0 +1,36 @@
+import {
+  type AnyNode,
+  type AnyNodeDefinition,
+  type GridEvent,
+  nodeRegistry,
+} from '@pascal-app/core'
+import type { InteractionScope } from './scope'
+
+type RegisteredDraftingConfig = NonNullable<AnyNodeDefinition['drafting']>
+type SurfaceHit = NonNullable<GridEvent['surfaceHit']>
+
+export const DRAFTING_SURFACE_EXTENSION_KEY = 'pascal:editor/drafting-surface'
+
+export type DraftingSurfaceExtension = {
+  kind: SurfaceHit['kind']
+  raycast?: 'underside'
+  classifyFace?: (
+    node: AnyNode | undefined,
+    localNormal: readonly [number, number, number],
+  ) => Pick<SurfaceHit, 'face' | 'side'> | null
+}
+
+export function registeredDraftingConfig(scope: InteractionScope): RegisteredDraftingConfig | null {
+  if (scope.kind !== 'drafting') return null
+  return nodeRegistry.get(scope.tool)?.drafting ?? null
+}
+
+export function registeredDraftingSurface(
+  definition: AnyNodeDefinition,
+): DraftingSurfaceExtension | null {
+  return (
+    (definition.extensions?.[DRAFTING_SURFACE_EXTENSION_KEY] as
+      | DraftingSurfaceExtension
+      | undefined) ?? null
+  )
+}

package/src/lib/interaction/scope.ts

@@ -35,11 +35,31 @@ export type InteractionScope =
       nodeType: string
       view: InteractionView
       pressDrag: boolean
+      driver: 'move-tool' | 'registry-tool'
     }
   // Moving an existing node.
   | { kind: 'moving'; node: AnyNode; nodeId: string; nodeType: string; view: InteractionView }
   // Dragging a resize/translate/rotate handle of a selected node.
   | { kind: 'handle-drag'; nodeId: string; handle: string }
+  // Editing the internal topology of one block. This scope remains
+  // active for the whole edit-mode session so scene selection and whole-node
+  // movement cannot claim the same pointer stream.
+  | {
+      kind: 'mesh-editing'
+      nodeId: string
+      phase: 'selecting' | 'operating'
+      operator?:
+        | 'translate'
+        | 'rotate'
+        | 'scale'
+        | 'extrude'
+        | 'inset'
+        | 'merge'
+        | 'dissolve'
+        | 'loop-cut'
+        | 'bevel'
+        | 'delete'
+    }
   // Click-to-click drafting of a polyline/polygon kind (wall/fence/slab/…).
   | { kind: 'drafting'; tool: string }
   // Reshaping a selected node's geometry (see ReshapeKind). `holeIndex` is set
@@ -88,6 +108,7 @@ export function scopeNodeId(scope: InteractionScope): string | null {
     case 'placing':
     case 'moving':
     case 'handle-drag':
+    case 'mesh-editing':
     case 'reshaping':
       return scope.nodeId
     default:
@@ -111,6 +132,16 @@ export function selectionEnabled(scope: InteractionScope): boolean {
   return scope.kind === 'idle'
 }
 
+export function meshEditScope(
+  nodeId: string,
+  phase: 'selecting' | 'operating' = 'selecting',
+  operator?: Extract<InteractionScope, { kind: 'mesh-editing' }>['operator'],
+): ActiveInteractionScope {
+  return operator
+    ? { kind: 'mesh-editing', nodeId, phase, operator }
+    : { kind: 'mesh-editing', nodeId, phase }
+}
+
 // Derived views of the scope that mirror the legacy `useEditor` flags they
 // replaced. Each returns null unless that exact interaction is active, so a
 // stale payload is unrepresentable: the value is a pure function of the single