orcasvn-react-diagrams 0.2.1 → 0.2.2

package/docs/API_CONTRACT.md

@@ -1,144 +1,200 @@
-# API Contract
-> Navigation: [Docs Index](INDEX.md) | Previous: [Architecture](ARCHITECTURE.md) | Next: [State Invariants](STATE_INVARIANTS.md)
-> Sections: [Entrypoints](#entrypoints) | [Editor Config](#editor-config-diagrameditorconfig) | [Engine Config](#engine-config-diagramengineconfig) | [Public State Types](#public-state-types) | [Handle Methods](#handle-methods) | [Events](#events-engineeventmap) | [Behavioral Notes](#behavioral-notes)
-
-## Entrypoints
-- `createDiagramEditor(config): DiagramEditorHandle`
-- `createDiagramEngine(config): DiagramEngineHandle`
-
-Primary definitions:
-- `src/api/types.ts`
-- `src/api/createDiagramEditor.ts`
-- `src/engine/DiagramEngine.ts`
-
-## Editor Config (`DiagramEditorConfig`)
-
-### Required
-- `container: HTMLDivElement | string`
-
-### Optional
-- `width?: number` (default: `900`)
-- `height?: number` (default: `560`)
-- `initialState?: DiagramState`
-- `elementShapes?: SimpleShape[]`
-- `portShapes?: SimpleShape[]`
-- `panKey?: 'Control' | 'Shift' | 'Alt' | 'Meta'` (default: `'Control'`)
-- `onChange?: (event: EngineChangeEvent) => void`
-- `onSelection?: (event: EngineSelectionEvent) => void`
-
-## Engine Config (`DiagramEngineConfig`)
-
-### Required
-- `renderer: Renderer`
-
-### Optional
-- `scheduler?: RenderScheduler`
-- `router?: RouterStrategy`
-- `snapper?: SnapStrategy`
-- `shapeRegistry?: ShapeRegistry`
-- `textMeasurer?: TextMeasurer`
-
-Defaults:
-- `scheduler`: `RenderScheduler`
-- `router`: `ObstacleRouter`
-- `snapper`: `DefaultSnapper`
-- `shapeRegistry`: `ShapeRegistry`
-- `textMeasurer`: `CanvasTextMeasurer`
-
-## Public State Types
-
-### `DiagramState`
-- `elements: ElementData[]` (required)
-- `ports: PortData[]` (required)
-- `links: LinkData[]` (required)
-- `texts: TextData[]` (required)
-
-### `ElementData`
-- Required: `id`, `position`, `size`, `shapeId`
-- Optional: `style`, `portIds`, `textIds`, `parentId`, `moveMode`, `anchorCenter`, `layout`
-- Defaults at runtime/model:
-  - `portIds`: `[]`
-  - `textIds`: `[]`
-  - `parentId`: `null`
-
-### `ElementLayout`
-- Required: `mode: 'manual' | 'horizontal' | 'vertical'`
-- Optional: `padding?: number | { x: number; y: number }`, `gap?: number`, `align?: 'start' | 'center' | 'end'`
-- Layout defaults when `mode !== 'manual'`:
-  - `padding`: `12` (or `{ x: 12, y: 12 }`)
-  - `gap`: `12`
-  - `align`: `'center'`
-
-### `PortData`
-- Required: `id`, `elementId`, `position`
-- Optional: `shapeId`, `size`, `style`, `textIds`, `moveMode`, `anchorCenter`
-- Defaults at runtime/model:
-  - `textIds`: `[]`
-  - `anchorCenter`: `true`
-
-### `LinkData`
-- Required: `id`, `sourcePortId`, `targetPortId`, `points`
-- Optional: `routing`, `style`, `textIds`
-- Defaults at runtime/model:
-  - `routing`: `'auto'`
-  - `textIds`: `[]`
-
-### `TextData`
-- Required: `id`, `content`, `position`
-- Optional: `size`, `style`, `ownerId`
-- Defaults at runtime/model:
-  - `ownerId`: `null`
-
-## Handle Methods
-
-### Shared (`DiagramEngineHandle` and `DiagramEditorHandle`)
-- State: `load`, `getState`, `getViewport`
-- Coordinates: `clientToWorld`
-- Overlay: `createOverlayShape`
-- Events: `on`
-- Element: `addElement`, `moveElementTo`, `resizeElement`, `setElementLayout`, `removeElement`
-- Port: `addPortToElement`, `movePortTo`, `removePort`
-- Link: `addLink`, `updateLinkPoints`, `setLinkRoutingMode`, `rerouteAllLinks`, `rerouteLinks`, `removeLink`
-- Text: `addText`, `updateText`, `moveTextTo`, `removeText`
-- Selection/viewport/config: `setSelection`, `setViewport`, `setRouting`, `setSnapping`
-- Rendering: `registerShape`, `render`
-
-### Editor Only (`DiagramEditorHandle`)
-- `resize(width, height)`
-- `destroy()`
-
-## Events (`EngineEventMap`)
-
-- `change: EngineChangeEvent`
-- `selection: EngineSelectionEvent`
-- `config: EngineConfigEvent`
-- `elementDrop: ElementDropEvent`
-- `element-drop: ElementDropEvent` (deprecated legacy event name)
-- `paperClick: PaperClickEvent`
-- `portMouseDown: PortMouseEvent`
-- `portMouseUp: PortMouseEvent`
-- `portMoved: PortMovedEvent`
-- `portSelected: PortSelectedEvent`
-- `elementClick: ElementPointerEvent`
-- `elementDragged: ElementDropEvent`
-- `elementMoved: ElementMovedEvent`
-- `elementResized: ElementResizedEvent`
-- `elementDeleted: ElementDeletedEvent`
-- `elementSelected: ElementSelectedEvent`
-- `elementLinkStarted: ElementLinkStartedEvent`
-- `elementLinkConnecting: ElementLinkConnectingEvent` (cancelable through `cancel()`)
-- `elementLinkEnded: ElementLinkEndedEvent`
-- `textSelected: TextSelectedEvent`
-
-## Behavioral Notes
-
-- Missing IDs in most mutators are no-op (non-throwing).
-- `setViewport` emits a `change` patch with `entity: 'viewport'` and skips immediate render scheduling.
-- `clientToWorld` uses: `world = (client - containerRect - pan) / zoom`, with zoom fallback to `1` when zoom is `0`.
-- `rerouteLinks(ids)` skips manual links unless `options.includeManual === true`.
-- `updateLinkPoints` always marks the link as manual routing.
-
-## Verification References
-- `src/api/__tests__/createDiagramEditor.test.ts`
-- `src/engine/__tests__/DiagramEngine.test.ts`
-- `src/renderer/konva/__tests__/KonvaInteraction.test.ts`
+# API Contract
+> Navigation: [Docs Index](INDEX.md) | Previous: [Architecture](ARCHITECTURE.md) | Next: [State Invariants](STATE_INVARIANTS.md)
+> Sections: [Entrypoints](#entrypoints) | [Editor Config](#editor-config-diagrameditorconfig) | [Engine Config](#engine-config-diagramengineconfig) | [Public State Types](#public-state-types) | [Handle Methods](#handle-methods) | [Events](#events-engineeventmap) | [Behavioral Notes](#behavioral-notes)
+
+## Entrypoints
+- `createDiagramEditor(config): DiagramEditorHandle`
+- `createDiagramEngine(config): DiagramEngineHandle`
+
+Primary definitions:
+- `src/api/types.ts`
+- `src/api/createDiagramEditor.ts`
+- `src/engine/DiagramEngine.ts`
+
+## Editor Config (`DiagramEditorConfig`)
+
+### Required
+- `container: HTMLDivElement | string`
+
+### Optional
+- `width?: number` (default: `900`)
+- `height?: number` (default: `560`)
+- `initialState?: DiagramState`
+- `elementShapes?: SimpleShape[]`
+- `portShapes?: SimpleShape[]`
+- `panKey?: 'Control' | 'Shift' | 'Alt' | 'Meta'` (default: `'Control'`)
+- `elementShapeHoverControls?: ElementShapeHoverControls`
+- `onElementShapeHoverControlInteraction?: (event: ElementShapeHoverControlInteractionEvent) => void`
+- `onElementShapeHoverControlActivated?: (event: ElementShapeHoverControlActivationEvent) => void` (deprecated callback contract)
+- `onChange?: (event: EngineChangeEvent) => void`
+- `onSelection?: (event: EngineSelectionEvent) => void`
+
+## Engine Config (`DiagramEngineConfig`)
+
+### Required
+- `renderer: Renderer`
+
+### Optional
+- `scheduler?: RenderScheduler`
+- `router?: RouterStrategy`
+- `snapper?: SnapStrategy`
+- `shapeRegistry?: ShapeRegistry`
+- `textMeasurer?: TextMeasurer`
+
+Defaults:
+- `scheduler`: `RenderScheduler`
+- `router`: `ObstacleRouter`
+- `snapper`: `DefaultSnapper`
+- `shapeRegistry`: `ShapeRegistry`
+- `textMeasurer`: `CanvasTextMeasurer`
+
+## Public State Types
+
+### `DiagramState`
+- `elements: ElementData[]` (required)
+- `ports: PortData[]` (required)
+- `links: LinkData[]` (required)
+- `texts: TextData[]` (required)
+
+### `ElementData`
+- Required: `id`, `position`, `size`, `shapeId`
+- Optional: `style`, `portIds`, `textIds`, `parentId`, `moveMode`, `anchorCenter`, `layout`, `portMovement`
+- Defaults at runtime/model:
+  - `portIds`: `[]`
+  - `textIds`: `[]`
+  - `parentId`: `null`
+
+### `ElementLayout`
+- Required: `mode: 'manual' | 'horizontal' | 'vertical'`
+- Optional: `padding?: number | { x: number; y: number }`, `gap?: number`, `align?: 'start' | 'center' | 'end'`
+- Optional fit controls: `childFitMainAxis?: 'none' | 'distribute'`, `childFitCrossAxis?: 'none' | 'stretch'`, `childFitMinSize?: Partial<Size>`, `childFitMaxSize?: Partial<Size>`
+- Layout defaults when `mode !== 'manual'`:
+  - `padding`: `12` (or `{ x: 12, y: 12 }`)
+  - `gap`: `12`
+  - `align`: `'center'`
+
+### `ElementPortMovementPolicy`
+- `moveMode: 'free' | 'inside' | 'border' | 'anchors'`
+- Optional `anchorConstraint?: PortAnchorConstraint`
+
+### `PortAnchorConstraint`
+- `preset: 'vertices' | 'cardinal'`
+- Optional `fallback?: 'nearest'`
+
+### `PortData`
+- Required: `id`, `elementId`, `position`
+- Optional: `shapeId`, `size`, `style`, `textIds`, `moveMode`, `anchorCenter`, `orientToHostBorder`, `currentAnchorId`
+- Defaults at runtime/model:
+  - `textIds`: `[]`
+  - `anchorCenter`: `true`
+  - `orientToHostBorder`: `true`
+
+### `LinkData`
+- Required: `id`, `sourcePortId`, `targetPortId`, `points`
+- Optional: `routing`, `style`, `textIds`
+- Defaults at runtime/model:
+  - `routing`: `'auto'`
+  - `textIds`: `[]`
+
+### `TextData`
+- Required: `id`, `content`, `position`
+- Optional: `size`, `style`, `ownerId`, `layout`, `displayContent`, `displayOffset`, `displayClipSize`
+- Defaults at runtime/model:
+  - `ownerId`: `null`
+  - `displayContent`: mirrors `content` at creation
+
+### `TextLayout`
+- Optional `boundsMode?: 'owner-width' | 'owner-box' | 'fixed'`
+- Optional `wrap?: 'none' | 'word' | 'char'`
+- Optional `overflow?: 'clip' | 'ellipsis-end' | 'ellipsis-middle' | 'ellipsis-start'`
+- Optional `padding?: number`
+- Optional `maxLines?: number`
+- Optional `fixedSize?: Size`
+
+### Hover Control Contracts
+- `ElementShapeHoverControls`:
+  - Preferred: `controls?: ShapeControlDefinition[]`
+  - Legacy deprecated: `edge`, `vertex`, `priority`
+- `ShapeControlDefinition`:
+  - Required: `id`, `targetKind`, `icon`
+  - Optional: `targetIndices`, `ellipseMidPoints`, `allowAllTargets`, `visibilityTriggers`, `lineStyle`, `tolerance`
+- `ShapeControlTargetKind`: `'vertex' | 'edge' | 'midpoint' | 'ellipse-midpoint'`
+- `ShapeControlVisibilityTrigger`: `'element-hover' | 'target-hover'`
+- `ElementShapeHoverControlInteractionEvent`:
+  - lifecycle: `eventType` is `'click' | 'drag-start' | 'drag-move' | 'drag-end'`
+  - includes `controlId`, `elementId`, `targetKind`, `targetIndex`, `pointer`, and resolved target payload (`edge`, `vertex`, or `ellipseMidPoint`) when available
+
+## Handle Methods
+
+### Shared (`DiagramEngineHandle` and `DiagramEditorHandle`)
+- State: `load`, `getState`, `getViewport`
+- Coordinates: `clientToWorld`
+- Overlay: `createOverlayShape`
+- Events: `on`
+- Element: `addElement`, `moveElementTo`, `resizeElement`, `setElementLayout`, `removeElement`
+- Port: `addPortToElement`, `movePortTo`, `removePort`
+- Link: `addLink`, `updateLinkPoints`, `setLinkRoutingMode`, `rerouteAllLinks`, `rerouteLinks`, `removeLink`
+- Text: `addText`, `updateText`, `moveTextTo`, `removeText`
+- Selection/viewport/config: `setSelection`, `setViewport`, `setRouting`, `setSnapping`
+- Rendering: `registerShape`, `render`
+
+### Editor Only (`DiagramEditorHandle`)
+- `resize(width, height)`
+- `setElementShapeHoverControls(controls?)`
+- `destroy()`
+
+### `registerShape` Definition Contract
+- Required: `id`
+- Optional behavior hooks:
+  - `baseRotation?: number`
+  - `draw?(context)`
+  - `createNode?(model)`
+  - `svgPath?: string`
+  - `svgSize?: Size`
+  - `projectToBorder?(point, rect)`
+  - `resolveBorderSide?(point, rect)`
+  - `resolvePortAnchors?(rect, options)`
+  - `resolveHoverGeometry?(rect)`
+  - `resolveEllipseMidPoints?(rect)`
+
+## Events (`EngineEventMap`)
+
+- `change: EngineChangeEvent`
+- `selection: EngineSelectionEvent`
+- `config: EngineConfigEvent`
+- `elementDrop: ElementDropEvent`
+- `element-drop: ElementDropEvent` (deprecated legacy event name)
+- `paperClick: PaperClickEvent`
+- `portMouseDown: PortMouseEvent`
+- `portMouseUp: PortMouseEvent`
+- `portMoved: PortMovedEvent`
+- `portSelected: PortSelectedEvent`
+- `elementClick: ElementPointerEvent`
+- `elementDragged: ElementDropEvent`
+- `elementMoved: ElementMovedEvent`
+- `elementResized: ElementResizedEvent`
+- `elementDeleted: ElementDeletedEvent`
+- `portDeleted: PortDeletedEvent`
+- `linkDeleted: LinkDeletedEvent`
+- `textDeleted: TextDeletedEvent`
+- `textUpdated: TextUpdatedEvent`
+- `elementSelected: ElementSelectedEvent`
+- `elementLinkStarted: ElementLinkStartedEvent`
+- `elementLinkConnecting: ElementLinkConnectingEvent` (cancelable through `cancel()`)
+- `elementLinkEnded: ElementLinkEndedEvent`
+- `textSelected: TextSelectedEvent`
+
+## Behavioral Notes
+
+- Missing IDs in most mutators are no-op (non-throwing).
+- `setViewport` emits a `change` patch with `entity: 'viewport'` and skips immediate render scheduling.
+- `clientToWorld` uses: `world = (client - containerRect - pan) / zoom`, with zoom fallback to `1` when zoom is `0`.
+- `rerouteLinks(ids)` skips manual links unless `options.includeManual === true`.
+- `updateLinkPoints` always marks the link as manual routing.
+- Text layout/overflow resolution updates `displayContent` and emits `textUpdated` when `updateText` is called.
+- Deletion mutators emit cascading `portDeleted`/`linkDeleted`/`textDeleted` for removed dependent entities.
+
+## Verification References
+- `src/api/__tests__/createDiagramEditor.test.ts`
+- `src/engine/__tests__/DiagramEngine.test.ts`
+- `src/renderer/konva/__tests__/KonvaInteraction.test.ts`

package/docs/ARCHITECTURE.md

@@ -1,31 +1,32 @@
-# Architecture
-> Navigation: [Docs Index](INDEX.md) | Previous: [Capabilities](CAPABILITIES.md) | Next: [API Contract](API_CONTRACT.md)
-> Sections: [Module Boundaries](#module-boundaries) | [Runtime Flow](#runtime-flow) | [Integration Boundary](#integration-boundary) | [Key Sources](#key-sources)
-
-## Module Boundaries
-- `src/api/`: public entry points and type contracts.
-- `src/engine/`: command execution, event bus, selection, viewport, routing/snap integration.
-- `src/models/`: in-memory state graph for elements/ports/links/texts.
-- `src/renderer/`: renderer interface and shape registry contracts.
-- `src/renderer/konva/`: Konva implementation for render + interaction overlays.
-- `src/strategies/`: pluggable router and snap strategy interfaces/defaults.
-- `src/measure/`: text measuring abstraction and canvas implementation.
-- `src/utils/`: geometry, patch helpers, guards, ids.
-
-## Runtime Flow
-1. Host calls API mutator.
-2. Engine executes command(s) against model.
-3. Engine emits patches + latest state via `change`.
-4. Scheduler requests render.
-5. Renderer syncs model to view nodes.
-
-## Integration Boundary
-- Engine core does not require Konva if you use `createDiagramEngine` with a custom `Renderer`.
-- `createDiagramEditor` wires Konva stage, hit testing, and interaction defaults.
-
-## Key Sources
-- `src/api/createDiagramEditor.ts`
-- `src/engine/DiagramEngine.ts`
-- `src/models/DiagramModel.ts`
-- `src/renderer/Renderer.ts`
-- `analysis/Development Analysis/folder-structure.md`
+# Architecture
+> Navigation: [Docs Index](INDEX.md) | Previous: [Capabilities](CAPABILITIES.md) | Next: [API Contract](API_CONTRACT.md)
+> Sections: [Module Boundaries](#module-boundaries) | [Runtime Flow](#runtime-flow) | [Integration Boundary](#integration-boundary) | [Key Sources](#key-sources)
+
+## Module Boundaries
+- `src/api/`: public entry points and type contracts.
+- `src/engine/`: command execution, event bus, selection, viewport, routing/snap integration.
+- `src/engine/`: `DiagramEngine` orchestration plus extracted services (`TextLayoutService`, `AutoLayoutService`, `LinkRoutingService`, `MutationPipeline`).
+- `src/models/`: in-memory state graph for elements/ports/links/texts.
+- `src/renderer/`: renderer interface and shape registry contracts.
+- `src/renderer/konva/`: Konva implementation for render + interaction overlays.
+- `src/strategies/`: pluggable router and snap strategy interfaces/defaults.
+- `src/measure/`: text measuring abstraction and canvas implementation.
+- `src/utils/`: geometry, patch helpers, guards, ids.
+
+## Runtime Flow
+1. Host calls API mutator.
+2. Engine executes command(s) against model.
+3. Engine emits patches + latest state via `change`.
+4. Scheduler requests render.
+5. Renderer syncs model to view nodes.
+
+## Integration Boundary
+- Engine core does not require Konva if you use `createDiagramEngine` with a custom `Renderer`.
+- `createDiagramEditor` wires Konva stage, hit testing, and interaction defaults.
+
+## Key Sources
+- `src/api/createDiagramEditor.ts`
+- `src/engine/DiagramEngine.ts`
+- `src/models/DiagramModel.ts`
+- `src/renderer/Renderer.ts`
+- `analysis/Development Analysis/folder-structure.md`

package/docs/CAPABILITIES.md

@@ -1,38 +1,40 @@
-# Capabilities
-> Navigation: [Docs Index](INDEX.md) | Next: [Architecture](ARCHITECTURE.md)
-> Sections: [Supports](#supports) | [Does Not Support](#does-not-support) | [Preconditions](#preconditions) | [Side Effects](#side-effects) | [Failure Modes](#failure-modes) | [Verification References](#verification-references)
-
-## Supports
-- CRUD for elements, ports, links, and texts.
-- Nested elements with world/local coordinate resolution.
-- Link routing modes: `auto` and `manual`.
-- Manual bend editing while preserving interior bends during endpoint moves.
-- Selection, marquee selection, and viewport pan/zoom.
-- Shape registration by canvas draw, custom node factory, or SVG path metadata.
-- Overlay shapes for external drag ghosting and previews.
-- Event-driven host integration (`change`, `selection`, pointer/link lifecycle events).
-
-## Does Not Support
-- Real-time collaborative editing.
-- Rich text editing beyond plain text entry.
-- WebGL rendering backend in this package.
-- Server-side conflict resolution or persistence workflows.
-
-## Preconditions
-- Runtime: Node `>=18.17 <19` for this repo toolchain.
-- Browser host with Konva-compatible canvas environment when using `createDiagramEditor`.
-
-## Side Effects
-- Engine mutators emit `change` events with patches and latest state.
-- Selection updates emit both `selection` and derived entity-specific selection events.
-- Rendering is scheduled after model changes, except viewport patches that set `render: false`.
-
-## Failure Modes
-- Missing IDs are ignored in most mutators (no throw, no mutation).
-- Link reroute skips links whose endpoints are unresolved.
-- Text owner references can be orphaned; text remains standalone in world coordinates.
-
-## Verification References
-- `src/engine/__tests__/DiagramEngine.test.ts`
-- `src/renderer/konva/__tests__/KonvaInteraction.test.ts`
-- `src/models/__tests__/DiagramModel.test.ts`
+# Capabilities
+> Navigation: [Docs Index](INDEX.md) | Next: [Architecture](ARCHITECTURE.md)
+> Sections: [Supports](#supports) | [Does Not Support](#does-not-support) | [Preconditions](#preconditions) | [Side Effects](#side-effects) | [Failure Modes](#failure-modes) | [Verification References](#verification-references)
+
+## Supports
+- CRUD for elements, ports, links, and texts.
+- Nested elements with world/local coordinate resolution.
+- Link routing modes: `auto` and `manual`.
+- Manual bend editing while preserving interior bends during endpoint moves.
+- Selection, marquee selection, and viewport pan/zoom.
+- Shape registration by canvas draw, custom node factory, or SVG path metadata.
+- Shape-aware host border projection and anchor-constrained port placement.
+- Element shape hover controls with edge/vertex/midpoint targets and interaction callbacks.
+- Overlay shapes for external drag ghosting and previews.
+- Event-driven host integration (`change`, `selection`, pointer/link lifecycle events).
+
+## Does Not Support
+- Real-time collaborative editing.
+- Rich text editing beyond plain text entry.
+- WebGL rendering backend in this package.
+- Server-side conflict resolution or persistence workflows.
+
+## Preconditions
+- Runtime: Node `>=20.17.0 <21.0.0` for this repo toolchain.
+- Browser host with Konva-compatible canvas environment when using `createDiagramEditor`.
+
+## Side Effects
+- Engine mutators emit `change` events with patches and latest state.
+- Selection updates emit both `selection` and derived entity-specific selection events.
+- Rendering is scheduled after model changes, except viewport patches that set `render: false`.
+
+## Failure Modes
+- Missing IDs are ignored in most mutators (no throw, no mutation).
+- Link reroute skips links whose endpoints are unresolved.
+- Text owner references can be orphaned; text remains standalone in world coordinates.
+
+## Verification References
+- `src/engine/__tests__/DiagramEngine.test.ts`
+- `src/renderer/konva/__tests__/KonvaInteraction.test.ts`
+- `src/models/__tests__/DiagramModel.test.ts`

package/docs/COMMANDS_EVENTS.md

@@ -1,60 +1,65 @@
-# Commands And Events
-> Navigation: [Docs Index](INDEX.md) | Previous: [State Invariants](STATE_INVARIANTS.md) | Next: [Integration Playbook](INTEGRATION_PLAYBOOK.md)
-> Sections: [Command Model](#command-model) | [Patch Entities](#patch-entities) | [Mutation To Events](#mutation-to-events-mapping) | [Interaction Lifecycle](#interaction-lifecycle-events) | [Failure Modes](#failure-modes)
-
-## Command Model
-- Engine mutators route through command factories in `src/engine/EngineCommands.ts`.
-- Each command applies model mutation and returns one or more patches.
-- `emitChange` publishes `{ patches, state }` on `change`.
-
-## Patch Entities
-- `element`
-- `port`
-- `link`
-- `text`
-- `selection`
-- `viewport`
-- `config`
-
-## Mutation To Events Mapping
-- `add/move/resize/remove element`
-  - Always `change`
-  - Plus `elementMoved`, `elementResized`, or `elementDeleted` when applicable
-- `add/move/remove port`
-  - Always `change`
-  - Plus `portMoved` on effective movement
-- `add/update/remove link`
-  - Always `change`
-- `add/update/move/remove text`
-  - Always `change`
-- `setSelection/toggleSelection/deleteSelection`
-  - `selection` plus derived selected entity events
-- `setViewport`
-  - `change` with viewport patch (`render: false`)
-- `setRouting/setSnapping/registerShape`
-  - `config` events
-
-## Interaction Lifecycle Events
-- Drag element:
-  - `elementDrop`
-  - legacy `element-drop`
-  - `elementDragged`
-- Click paper: `paperClick`
-- Linking:
-  - `elementLinkStarted`
-  - `elementLinkConnecting` (cancelable via `cancel()`)
-  - `elementLinkEnded`
-
-## Preconditions
-- Events are emitted only after engine state transition logic.
-- Derived events require selected IDs to resolve to known entity types.
-
-## Failure Modes
-- Unknown IDs do not emit entity-specific movement/selection events.
-- Canceled link creation emits `elementLinkEnded` with `cancelled=true` and no link creation.
-
-## Verification References
-- `src/engine/EngineCommands.ts`
-- `src/engine/DiagramEngine.ts`
-- `src/engine/__tests__/DiagramEngine.test.ts`
-- `src/renderer/konva/__tests__/KonvaInteraction.test.ts`
+# Commands And Events
+> Navigation: [Docs Index](INDEX.md) | Previous: [State Invariants](STATE_INVARIANTS.md) | Next: [Integration Playbook](INTEGRATION_PLAYBOOK.md)
+> Sections: [Command Model](#command-model) | [Patch Entities](#patch-entities) | [Mutation To Events](#mutation-to-events-mapping) | [Interaction Lifecycle](#interaction-lifecycle-events) | [Failure Modes](#failure-modes)
+
+## Command Model
+- Engine mutators route through command factories in `src/engine/EngineCommands.ts`.
+- Each command applies model mutation and returns one or more patches.
+- `emitChange` publishes `{ patches, state }` on `change`.
+
+## Patch Entities
+- `element`
+- `port`
+- `link`
+- `text`
+- `selection`
+- `viewport`
+- `config`
+
+## Mutation To Events Mapping
+- `add/move/resize/remove element`
+  - Always `change`
+  - Plus `elementMoved`, `elementResized`, or `elementDeleted` when applicable
+- `add/move/remove port`
+  - Always `change`
+  - Plus `portMoved` on effective movement
+  - Plus `portDeleted` on removal (including cascade removal)
+- `add/update/remove link`
+  - Always `change`
+  - Plus `linkDeleted` on removal (including cascade removal)
+- `add/update/move/remove text`
+  - Always `change`
+  - Plus `textUpdated` when `updateText` resolves display layout
+  - Plus `textDeleted` on removal (including cascade removal)
+- `setSelection/toggleSelection/deleteSelection`
+  - `selection` plus derived selected entity events
+- `setViewport`
+  - `change` with viewport patch (`render: false`)
+- `setRouting/setSnapping/registerShape`
+  - `config` events
+
+## Interaction Lifecycle Events
+- Drag element:
+  - `elementDrop`
+  - legacy `element-drop`
+  - `elementDragged`
+- Click paper: `paperClick`
+- Linking:
+  - `elementLinkStarted`
+  - `elementLinkConnecting` (cancelable via `cancel()`)
+  - `elementLinkEnded`
+
+## Preconditions
+- Events are emitted only after engine state transition logic.
+- Derived events require selected IDs to resolve to known entity types.
+
+## Failure Modes
+- Unknown IDs do not emit entity-specific movement/selection events.
+- Canceled link creation emits `elementLinkEnded` with `cancelled=true` and no link creation.
+- `textUpdated` emits only when target text exists; missing IDs remain no-op.
+
+## Verification References
+- `src/engine/EngineCommands.ts`
+- `src/engine/DiagramEngine.ts`
+- `src/engine/__tests__/DiagramEngine.test.ts`
+- `src/renderer/konva/__tests__/KonvaInteraction.test.ts`