orcasvn-react-diagrams 0.2.1 → 0.2.2

package/docs/DOCUMENTATION_WORKFLOW.md

@@ -1,6 +1,6 @@
-# Documentation Workflow Playbook
-> Navigation: [Docs Index](INDEX.md) | Previous: [Porting Checklist](PORTING_CHECKLIST.md)
-> Sections: [Workflow Steps](#3-step-by-step-workflow) | [Definition Of Done](#4-definition-of-done) | [Current Status](#6-current-status) | [Decisions Log](#7-decisions-log) | [Open Items](#8-open-items)
+# Documentation Workflow Playbook
+> Navigation: [Docs Index](INDEX.md) | Previous: [Porting Checklist](PORTING_CHECKLIST.md)
+> Sections: [Workflow Steps](#3-step-by-step-workflow) | [Definition Of Done](#4-definition-of-done) | [Current Status](#6-current-status) | [Decisions Log](#7-decisions-log) | [Open Items](#8-open-items)
 
 ## 1. Purpose
 Create and maintain publish-ready docs (human + AI-consumable) for this library, with a repeatable process for future rework.
@@ -58,29 +58,27 @@ When resuming later:
 4. Update “Decisions Log” and “Open Items”.
 5. Re-run packaging verification.
 
-## 6. Current Status
-- Last updated: 2026-02-26
-- Last completed step: 4
-- Next step: 5 (model/invariant docs deep pass)
-- Owner: Codex (with repository maintainers)
-
-## 7. Decisions Log
-- 2026-02-26: Freeze first iteration scope to steps 1-4 so entry docs and API contract become publish-ready before deeper integration refactors.
-- 2026-02-26: Keep `docs/` as the shared source for both human and AI handoff docs, with `ai/*.json` mirroring key contract/invariant data.
-- 2026-02-26: Preserve legacy event name `element-drop` in docs and machine contract while documenting `elementDrop` as preferred.
-- 2026-02-26: Set `docs/INDEX.md` as the main docs entrypoint.
-- 2026-02-26: Flatten docs structure by moving `docs/ai/*` into `docs/*` and moving fixtures to `docs/fixtures/*`.
-
-## 8. Open Items
-- [ ] Complete step 5: extend `STATE_INVARIANTS.md` with explicit ownership/cascade examples and coordinate edge cases.
-- [ ] Complete step 6: tighten host adapter mapping details for non-Konva renderer integrations.
-- [ ] Complete step 7: add at least one additional fixture covering manual link reroute + nested parent movement.
-- [ ] Complete step 9: run `npm pack --dry-run` after final doc pass and confirm package artifact list.
-- [ ] Complete step 10: run full terminology/link/version QA sweep across all docs.
-- [ ] Complete step 11: record final completion notes in changelog/task log.
-
-## 9. Change Log
-- 2026-02-26: Completed workflow steps 1-4 for this iteration (audit, scope freeze, entry docs update, API contract expansion).
-- 2026-02-26: Updated `README.md`, `docs/INDEX.md`, `docs/API_CONTRACT.md`, and `ai/api-contract.json`.
-- 2026-02-26: Reorganized docs so core pages are under `docs/*` and fixtures are under `docs/fixtures/*`.
-- 2026-02-26: Added cross-page navigation and section-level links across core docs for human and AI readability.
+## 6. Current Status
+- Last updated: 2026-04-25
+- Last completed step: 10
+- Next step: 7 (optional additional fixture coverage for deeper nested/manual-route scenarios)
+- Owner: Codex (with repository maintainers)
+
+## 7. Decisions Log
+- 2026-02-26: Freeze first iteration scope to steps 1-4 so entry docs and API contract become publish-ready before deeper integration refactors.
+- 2026-02-26: Keep `docs/` as the shared source for both human and AI handoff docs, with `ai/*.json` mirroring key contract/invariant data.
+- 2026-02-26: Preserve legacy event name `element-drop` in docs and machine contract while documenting `elementDrop` as preferred.
+- 2026-02-26: Set `docs/INDEX.md` as the main docs entrypoint.
+- 2026-02-26: Flatten docs structure by moving `docs/ai/*` into `docs/*` and moving fixtures to `docs/fixtures/*`.
+
+## 8. Open Items
+- [ ] Complete step 7: add at least one additional fixture covering manual link reroute + nested parent movement.
+- [ ] Complete step 11: record final completion notes in the external release changelog/task log used by maintainers.
+
+## 9. Change Log
+- 2026-02-26: Completed workflow steps 1-4 for this iteration (audit, scope freeze, entry docs update, API contract expansion).
+- 2026-02-26: Updated `README.md`, `docs/INDEX.md`, `docs/API_CONTRACT.md`, and `ai/api-contract.json`.
+- 2026-02-26: Reorganized docs so core pages are under `docs/*` and fixtures are under `docs/fixtures/*`.
+- 2026-02-26: Added cross-page navigation and section-level links across core docs for human and AI readability.
+- 2026-04-25: Completed release-doc pass for `v0.2.2` including `v0.2.1` scope consolidation; refreshed API/event contracts in `docs/*` and `ai/*`.
+- 2026-04-25: Ran release validations: `npm run typecheck`, `npm test -- --watchAll=false`, `npm run build`, `npm run rollup-build-lib`, and `npm pack --dry-run`.

package/docs/INDEX.md

@@ -1,41 +1,41 @@
-# Library Documentation Index
-
-## Purpose
-Primary documentation entrypoint for `orcasvn-react-diagrams`, designed to be readable by both humans and AI agents.
-
-## Read Order
-1. [Capabilities](CAPABILITIES.md)
-2. [Architecture](ARCHITECTURE.md)
-3. [API Contract](API_CONTRACT.md)
-4. [State Invariants](STATE_INVARIANTS.md)
-5. [Commands And Events](COMMANDS_EVENTS.md)
-6. [Integration Playbook](INTEGRATION_PLAYBOOK.md)
-7. [Porting Checklist](PORTING_CHECKLIST.md)
-8. [Documentation Workflow](DOCUMENTATION_WORKFLOW.md)
-
-## Section Map
-- [Supports](CAPABILITIES.md#supports), [Failure Modes](CAPABILITIES.md#failure-modes)
-- [Module Boundaries](ARCHITECTURE.md#module-boundaries), [Runtime Flow](ARCHITECTURE.md#runtime-flow)
-- [Entrypoints](API_CONTRACT.md#entrypoints), [Handle Methods](API_CONTRACT.md#handle-methods), [Events](API_CONTRACT.md#events-engineeventmap)
-- [Global Invariants](STATE_INVARIANTS.md#global), [Entity Rules](STATE_INVARIANTS.md#element)
-- [Command Model](COMMANDS_EVENTS.md#command-model), [Mutation To Event Mapping](COMMANDS_EVENTS.md#mutation-to-events-mapping)
-- [Path A (Editor)](INTEGRATION_PLAYBOOK.md#path-a-full-editor-konva-included), [Path B (Engine)](INTEGRATION_PLAYBOOK.md#path-b-engine-only-adapter)
-- [Porting Steps](PORTING_CHECKLIST.md#1-define-data-mapping), [Publish Checks](PORTING_CHECKLIST.md#8-npm-publish-accessibility-checks)
-- [Workflow Steps](DOCUMENTATION_WORKFLOW.md#3-step-by-step-workflow), [Current Status](DOCUMENTATION_WORKFLOW.md#6-current-status)
-
-## Fixtures
-- [Empty State](fixtures/empty-state.json)
-- [Basic Linked Elements](fixtures/basic-linked-elements.json)
-- [Nested Layout](fixtures/nested-layout.json)
-
-## Machine Discovery
-- Manifest: `../ai/manifest.json`
-- API JSON: `../ai/api-contract.json`
-- Invariants JSON: `../ai/invariants.json`
-- Fixtures: `fixtures/*.json`
-
-## Source Of Truth Links
-- White paper: `../analysis/White paper/`
-- Development analysis: `../analysis/Development Analysis/`
-- Public API: `../src/api/`
-- Engine implementation: `../src/engine/DiagramEngine.ts`
+# Library Documentation Index
+
+## Purpose
+Primary documentation entrypoint for `orcasvn-react-diagrams`, designed to be readable by both humans and AI agents.
+
+## Read Order
+1. [Capabilities](CAPABILITIES.md)
+2. [Architecture](ARCHITECTURE.md)
+3. [API Contract](API_CONTRACT.md)
+4. [State Invariants](STATE_INVARIANTS.md)
+5. [Commands And Events](COMMANDS_EVENTS.md)
+6. [Integration Playbook](INTEGRATION_PLAYBOOK.md)
+7. [Porting Checklist](PORTING_CHECKLIST.md)
+8. [Documentation Workflow](DOCUMENTATION_WORKFLOW.md)
+
+## Section Map
+- [Supports](CAPABILITIES.md#supports), [Failure Modes](CAPABILITIES.md#failure-modes)
+- [Module Boundaries](ARCHITECTURE.md#module-boundaries), [Runtime Flow](ARCHITECTURE.md#runtime-flow)
+- [Entrypoints](API_CONTRACT.md#entrypoints), [Handle Methods](API_CONTRACT.md#handle-methods), [Events](API_CONTRACT.md#events-engineeventmap)
+- [Global Invariants](STATE_INVARIANTS.md#global), [Entity Rules](STATE_INVARIANTS.md#element)
+- [Command Model](COMMANDS_EVENTS.md#command-model), [Mutation To Event Mapping](COMMANDS_EVENTS.md#mutation-to-events-mapping)
+- [Path A (Editor)](INTEGRATION_PLAYBOOK.md#path-a-full-editor-konva-included), [Path B (Engine)](INTEGRATION_PLAYBOOK.md#path-b-engine-only-adapter)
+- [Porting Steps](PORTING_CHECKLIST.md#1-define-data-mapping), [Publish Checks](PORTING_CHECKLIST.md#8-npm-publish-accessibility-checks)
+- [Workflow Steps](DOCUMENTATION_WORKFLOW.md#3-step-by-step-workflow), [Current Status](DOCUMENTATION_WORKFLOW.md#6-current-status)
+
+## Fixtures
+- [Empty State](fixtures/empty-state.json)
+- [Basic Linked Elements](fixtures/basic-linked-elements.json)
+- [Nested Layout](fixtures/nested-layout.json)
+
+## Machine Discovery
+- Manifest: `../ai/manifest.json`
+- API JSON: `../ai/api-contract.json`
+- Invariants JSON: `../ai/invariants.json`
+- Fixtures: `fixtures/*.json`
+
+## Source Of Truth Links
+- White paper: `../analysis/White paper/`
+- Development analysis: `../analysis/Development Analysis/`
+- Public API: `../src/api/`
+- Engine implementation: `../src/engine/DiagramEngine.ts`

package/docs/INTEGRATION_PLAYBOOK.md

@@ -1,54 +1,56 @@
-# Integration Playbook
-> Navigation: [Docs Index](INDEX.md) | Previous: [Commands And Events](COMMANDS_EVENTS.md) | Next: [Porting Checklist](PORTING_CHECKLIST.md)
-> Sections: [Objective](#objective) | [Path A](#path-a-full-editor-konva-included) | [Path B](#path-b-engine-only-adapter) | [Required Host Mappings](#required-host-mappings) | [Verification](#verification)
-
-## Objective
-Embed this library into another diagram host while preserving deterministic state, events, and routing behavior.
-
-## Path A: Full Editor (Konva Included)
-1. Call `createDiagramEditor({ container, width, height, initialState })`.
-2. Subscribe to:
-   - `change` for persistence/sync
-   - `selection` for host inspector panels
-   - link/pointer events for UI workflows
-3. Convert external pointer drops with `clientToWorld`.
-4. Use `createOverlayShape` during host drag previews.
-
-## Path B: Engine-Only Adapter
-1. Implement `Renderer`:
-   - `render(model)`
-   - `renderSelection(ids)`
-   - `createOverlayShape(config)`
-2. Instantiate `createDiagramEngine({ renderer, router?, snapper?, textMeasurer? })`.
-3. Bridge host pointer interactions into engine API methods/events.
-4. Keep world/local coordinate mapping consistent with engine contracts.
-
-## Required Host Mappings
-- Entity mapping:
-  - host node -> `ElementData`
-  - host port/anchor -> `PortData`
-  - host edge -> `LinkData`
-  - host label -> `TextData`
-- Event mapping:
-  - host click -> `setSelection` / `emitElementClick`-equivalent behavior
-  - host drag end -> `emitElementDrop`-equivalent payload
-  - host link gesture -> `elementLinkStarted/Connecting/Ended` lifecycle
-
-## Behavioral Checklist Per Integration Step
-- Preconditions
-  - Entity IDs stable across re-renders.
-  - Parent/child relationships available before routing/link creation.
-- Inputs
-  - Pass world coordinates to engine mutators.
-- Outputs
-  - Consume `change` event state as single source of truth.
-- Side effects
-  - Expect reroutes after port/element movements.
-- Failure modes
-  - If unresolved port refs exist, reroute/update is skipped.
-
-## Verification
-- Replay fixtures in `fixtures/*.json`.
-- Compare emitted patches/events against expected flow in:
-  - `src/engine/__tests__/DiagramEngine.test.ts`
-  - `src/renderer/konva/__tests__/KonvaInteraction.test.ts`
+# Integration Playbook
+> Navigation: [Docs Index](INDEX.md) | Previous: [Commands And Events](COMMANDS_EVENTS.md) | Next: [Porting Checklist](PORTING_CHECKLIST.md)
+> Sections: [Objective](#objective) | [Path A](#path-a-full-editor-konva-included) | [Path B](#path-b-engine-only-adapter) | [Required Host Mappings](#required-host-mappings) | [Verification](#verification)
+
+## Objective
+Embed this library into another diagram host while preserving deterministic state, events, and routing behavior.
+
+## Path A: Full Editor (Konva Included)
+1. Call `createDiagramEditor({ container, width, height, initialState })`.
+2. Subscribe to:
+   - `change` for persistence/sync
+   - `selection` for host inspector panels
+   - link/pointer events for UI workflows
+   - deletion/text lifecycle events when host needs side-effects (`portDeleted`, `linkDeleted`, `textDeleted`, `textUpdated`)
+3. Convert external pointer drops with `clientToWorld`.
+4. Use `createOverlayShape` during host drag previews.
+5. For shape controls, pass `elementShapeHoverControls` and handle `onElementShapeHoverControlInteraction`.
+
+## Path B: Engine-Only Adapter
+1. Implement `Renderer`:
+   - `render(model)`
+   - `renderSelection(ids)`
+   - `createOverlayShape(config)`
+2. Instantiate `createDiagramEngine({ renderer, router?, snapper?, textMeasurer? })`.
+3. Bridge host pointer interactions into engine API methods/events.
+4. Keep world/local coordinate mapping consistent with engine contracts.
+
+## Required Host Mappings
+- Entity mapping:
+  - host node -> `ElementData`
+  - host port/anchor -> `PortData`
+  - host edge -> `LinkData`
+  - host label -> `TextData`
+- Event mapping:
+  - host click -> `setSelection` / `emitElementClick`-equivalent behavior
+  - host drag end -> `emitElementDrop`-equivalent payload
+  - host link gesture -> `elementLinkStarted/Connecting/Ended` lifecycle
+
+## Behavioral Checklist Per Integration Step
+- Preconditions
+  - Entity IDs stable across re-renders.
+  - Parent/child relationships available before routing/link creation.
+- Inputs
+  - Pass world coordinates to engine mutators.
+- Outputs
+  - Consume `change` event state as single source of truth.
+- Side effects
+  - Expect reroutes after port/element movements.
+- Failure modes
+  - If unresolved port refs exist, reroute/update is skipped.
+
+## Verification
+- Replay fixtures in `fixtures/*.json`.
+- Compare emitted patches/events against expected flow in:
+  - `src/engine/__tests__/DiagramEngine.test.ts`
+  - `src/renderer/konva/__tests__/KonvaInteraction.test.ts`

package/docs/PORTING_CHECKLIST.md

@@ -1,58 +1,59 @@
-# Porting Checklist
-> Navigation: [Docs Index](INDEX.md) | Previous: [Integration Playbook](INTEGRATION_PLAYBOOK.md) | Next: [Documentation Workflow](DOCUMENTATION_WORKFLOW.md)
-> Sections: [Data Mapping](#1-define-data-mapping) | [Coordinate Semantics](#2-match-coordinate-semantics) | [Renderer Boundary](#3-implement-renderer-boundary-if-non-konva) | [Event Lifecycle](#5-event-lifecycle-compatibility) | [Fixture Validation](#7-run-fixture-based-validation) | [Publish Accessibility](#8-npm-publish-accessibility-checks)
-
-## 1. Define Data Mapping
-- Map host model fields into:
-  - `ElementData`
-  - `PortData`
-  - `LinkData`
-  - `TextData`
-- Confirm owner-relative semantics for ports/texts.
-
-## 2. Match Coordinate Semantics
-- Confirm world-to-local conversion for:
-  - child elements
-  - ports
-  - owner-bound text
-- Validate `anchorCenter` behavior for element/port rendering.
-
-## 3. Implement Renderer Boundary (if non-Konva)
-- Implement `Renderer` contract in `src/renderer/Renderer.ts`.
-- Support selection highlighting and overlay shape lifecycle.
-- Ensure incremental sync supports add/update/remove entity operations.
-
-## 4. Route/Snap Strategy Compatibility
-- Port router to `RouterStrategy.route(source, target, context?)`.
-- Port snapper to `SnapStrategy.snap(point)`.
-- Validate manual-route endpoint updates preserve interior points.
-
-## 5. Event Lifecycle Compatibility
-- Ensure host can emulate:
-  - `elementDrop` + legacy `element-drop`
-  - `paperClick`
-  - `elementLinkStarted/Connecting/Ended`
-  - `portMouseDown/portMouseUp`
-
-## 6. Verify Cascading Deletes
-- Deleting element should remove descendant ports, connected links, owned texts.
-- Deleting port should remove connected links and owned texts.
-- Deleting link should remove owned texts.
-
-## 7. Run Fixture-Based Validation
-- Load fixtures from `fixtures/*.json`.
-- Validate state snapshots before/after operations.
-- Validate emitted patch entities and event payload shape.
-
-## 8. npm Publish Accessibility Checks
-- Ensure package includes:
-  - `docs/*`
-  - `ai/manifest.json`
-  - machine JSON (`ai/api-contract.json`, `ai/invariants.json`)
-- Validate with `npm pack --dry-run`.
-
-## Verification References
-- `src/renderer/Renderer.ts`
-- `src/engine/DiagramEngine.ts`
-- `src/models/DiagramModel.ts`
-- `src/engine/__tests__/DiagramEngine.test.ts`
+# Porting Checklist
+> Navigation: [Docs Index](INDEX.md) | Previous: [Integration Playbook](INTEGRATION_PLAYBOOK.md) | Next: [Documentation Workflow](DOCUMENTATION_WORKFLOW.md)
+> Sections: [Data Mapping](#1-define-data-mapping) | [Coordinate Semantics](#2-match-coordinate-semantics) | [Renderer Boundary](#3-implement-renderer-boundary-if-non-konva) | [Event Lifecycle](#5-event-lifecycle-compatibility) | [Fixture Validation](#7-run-fixture-based-validation) | [Publish Accessibility](#8-npm-publish-accessibility-checks)
+
+## 1. Define Data Mapping
+- Map host model fields into:
+  - `ElementData`
+  - `PortData`
+  - `LinkData`
+  - `TextData`
+- Confirm owner-relative semantics for ports/texts.
+
+## 2. Match Coordinate Semantics
+- Confirm world-to-local conversion for:
+  - child elements
+  - ports
+  - owner-bound text
+- Validate `anchorCenter` behavior for element/port rendering.
+
+## 3. Implement Renderer Boundary (if non-Konva)
+- Implement `Renderer` contract in `src/renderer/Renderer.ts`.
+- Support selection highlighting and overlay shape lifecycle.
+- Ensure incremental sync supports add/update/remove entity operations.
+
+## 4. Route/Snap Strategy Compatibility
+- Port router to `RouterStrategy.route(source, target, context?)`.
+- Port snapper to `SnapStrategy.snap(point)`.
+- Validate manual-route endpoint updates preserve interior points.
+
+## 5. Event Lifecycle Compatibility
+- Ensure host can emulate:
+  - `elementDrop` + legacy `element-drop`
+  - `paperClick`
+  - `elementLinkStarted/Connecting/Ended`
+  - `portMouseDown/portMouseUp`
+  - deletion and text lifecycle events (`portDeleted`, `linkDeleted`, `textDeleted`, `textUpdated`)
+
+## 6. Verify Cascading Deletes
+- Deleting element should remove descendant ports, connected links, owned texts.
+- Deleting port should remove connected links and owned texts.
+- Deleting link should remove owned texts.
+
+## 7. Run Fixture-Based Validation
+- Load fixtures from `fixtures/*.json`.
+- Validate state snapshots before/after operations.
+- Validate emitted patch entities and event payload shape.
+
+## 8. npm Publish Accessibility Checks
+- Ensure package includes:
+  - `docs/*`
+  - `ai/manifest.json`
+  - machine JSON (`ai/api-contract.json`, `ai/invariants.json`)
+- Validate with `npm pack --dry-run`.
+
+## Verification References
+- `src/renderer/Renderer.ts`
+- `src/engine/DiagramEngine.ts`
+- `src/models/DiagramModel.ts`
+- `src/engine/__tests__/DiagramEngine.test.ts`

package/docs/STATE_INVARIANTS.md

@@ -1,56 +1,60 @@
-# State Invariants
-> Navigation: [Docs Index](INDEX.md) | Previous: [API Contract](API_CONTRACT.md) | Next: [Commands And Events](COMMANDS_EVENTS.md)
-> Sections: [Global](#global) | [Element](#element) | [Port](#port) | [Link](#link) | [Text](#text) | [Selection And View](#selection-and-view) | [Failure Modes](#failure-modes)
-
-## Global
-- State shape always serializes as:
-  - `elements[]`, `ports[]`, `links[]`, `texts[]`
-- IDs are expected unique by entity type.
-- Missing references are tolerated at runtime (non-throwing), but produce degraded behavior.
-
-## Element
-- Position is local to parent if `parentId` exists; otherwise world.
-- World position resolves by summing ancestor positions.
-- If `anchorCenter=true`, world top-left is shifted by half size.
-- Deleting an element cascades to:
-  - child ports
-  - links connected through removed ports
-  - owned texts
-
-## Port
-- Port position is local to owner element.
-- Default `anchorCenter=true` in model constructor.
-- Moving ports can be constrained by:
-  - `moveMode: inside|border`
-  - `style.moveAxis`
-  - `style.moveBounds`
-- Port removal cascades to connected links and owned texts.
-
-## Link
-- `routing` defaults to `auto`.
-- Auto routing recomputes from router strategy and normalized endpoints.
-- Manual routing preserves interior bends on endpoint movement.
-- Links with unresolved source/target world positions are skipped by reroute/update paths.
-
-## Text
-- `ownerId` can reference element, port, or link.
-- Owned text position is stored owner-relative.
-- Text with missing owner behaves as standalone world-position text.
-- Size is measured on add/update when using engine text measurer.
-
-## Selection And View
-- `setSelection` emits:
-  - `selection`
-  - plus derived `elementSelected`/`portSelected`/`textSelected`
-- `setViewport` emits `change` with `entity=viewport` and does not force render directly.
-
-## Failure Modes
-- Non-existent target IDs: operation is no-op.
-- Orphan ownership references: text persists, ownership index may not bind to entity.
-- Invalid or missing routing endpoints: route update is skipped.
-
-## Verification References
-- `src/models/DiagramModel.ts`
-- `src/models/__tests__/DiagramModel.test.ts`
-- `src/engine/DiagramEngine.ts`
-- `src/engine/__tests__/DiagramEngine.test.ts`
+# State Invariants
+> Navigation: [Docs Index](INDEX.md) | Previous: [API Contract](API_CONTRACT.md) | Next: [Commands And Events](COMMANDS_EVENTS.md)
+> Sections: [Global](#global) | [Element](#element) | [Port](#port) | [Link](#link) | [Text](#text) | [Selection And View](#selection-and-view) | [Failure Modes](#failure-modes)
+
+## Global
+- State shape always serializes as:
+  - `elements[]`, `ports[]`, `links[]`, `texts[]`
+- IDs are expected unique by entity type.
+- Missing references are tolerated at runtime (non-throwing), but produce degraded behavior.
+
+## Element
+- Position is local to parent if `parentId` exists; otherwise world.
+- World position resolves by summing ancestor positions.
+- If `anchorCenter=true`, world top-left is shifted by half size.
+- Deleting an element cascades to:
+  - child ports
+  - links connected through removed ports
+  - owned texts
+
+## Port
+- Port position is local to owner element.
+- Default `anchorCenter=true` in model constructor.
+- Default `orientToHostBorder=true` in model constructor.
+- Moving ports can be constrained by:
+  - `moveMode: inside|border`
+  - element-level `portMovement.moveMode: free|inside|border|anchors`
+  - anchor presets via `portMovement.anchorConstraint`
+  - `style.moveAxis`
+  - `style.moveBounds`
+- Port removal cascades to connected links and owned texts.
+
+## Link
+- `routing` defaults to `auto`.
+- Auto routing recomputes from router strategy and normalized endpoints.
+- Manual routing preserves interior bends on endpoint movement.
+- Links with unresolved source/target world positions are skipped by reroute/update paths.
+
+## Text
+- `ownerId` can reference element, port, or link.
+- Owned text position is stored owner-relative.
+- Text with missing owner behaves as standalone world-position text.
+- Size is measured on add/update when using engine text measurer.
+- Text layout can compute derived `displayContent`, `displayOffset`, and `displayClipSize`.
+
+## Selection And View
+- `setSelection` emits:
+  - `selection`
+  - plus derived `elementSelected`/`portSelected`/`textSelected`
+- `setViewport` emits `change` with `entity=viewport` and does not force render directly.
+
+## Failure Modes
+- Non-existent target IDs: operation is no-op.
+- Orphan ownership references: text persists, ownership index may not bind to entity.
+- Invalid or missing routing endpoints: route update is skipped.
+
+## Verification References
+- `src/models/DiagramModel.ts`
+- `src/models/__tests__/DiagramModel.test.ts`
+- `src/engine/DiagramEngine.ts`
+- `src/engine/__tests__/DiagramEngine.test.ts`

package/docs/fixtures/basic-linked-elements.json

@@ -1,52 +1,52 @@
-{
-  "name": "basic-linked-elements",
-  "description": "Two elements with one port each and one auto-routed link.",
-  "state": {
-    "elements": [
-      {
-        "id": "e1",
-        "position": { "x": 40, "y": 80 },
-        "size": { "width": 120, "height": 80 },
-        "shapeId": "default"
-      },
-      {
-        "id": "e2",
-        "position": { "x": 320, "y": 80 },
-        "size": { "width": 120, "height": 80 },
-        "shapeId": "default"
-      }
-    ],
-    "ports": [
-      {
-        "id": "p1",
-        "elementId": "e1",
-        "position": { "x": 120, "y": 40 },
-        "shapeId": "port"
-      },
-      {
-        "id": "p2",
-        "elementId": "e2",
-        "position": { "x": 0, "y": 40 },
-        "shapeId": "port"
-      }
-    ],
-    "links": [
-      {
-        "id": "l1",
-        "sourcePortId": "p1",
-        "targetPortId": "p2",
-        "points": [],
-        "routing": "auto"
-      }
-    ],
-    "texts": [
-      {
-        "id": "t1",
-        "content": "Link Label",
-        "position": { "x": 0, "y": -12 },
-        "ownerId": "l1"
-      }
-    ]
-  }
-}
-
+{
+  "name": "basic-linked-elements",
+  "description": "Two elements with one port each and one auto-routed link.",
+  "state": {
+    "elements": [
+      {
+        "id": "e1",
+        "position": { "x": 40, "y": 80 },
+        "size": { "width": 120, "height": 80 },
+        "shapeId": "default"
+      },
+      {
+        "id": "e2",
+        "position": { "x": 320, "y": 80 },
+        "size": { "width": 120, "height": 80 },
+        "shapeId": "default"
+      }
+    ],
+    "ports": [
+      {
+        "id": "p1",
+        "elementId": "e1",
+        "position": { "x": 120, "y": 40 },
+        "shapeId": "port"
+      },
+      {
+        "id": "p2",
+        "elementId": "e2",
+        "position": { "x": 0, "y": 40 },
+        "shapeId": "port"
+      }
+    ],
+    "links": [
+      {
+        "id": "l1",
+        "sourcePortId": "p1",
+        "targetPortId": "p2",
+        "points": [],
+        "routing": "auto"
+      }
+    ],
+    "texts": [
+      {
+        "id": "t1",
+        "content": "Link Label",
+        "position": { "x": 0, "y": -12 },
+        "ownerId": "l1"
+      }
+    ]
+  }
+}
+

package/docs/fixtures/empty-state.json

@@ -1,11 +1,11 @@
-{
-  "name": "empty-state",
-  "description": "Baseline state with no entities.",
-  "state": {
-    "elements": [],
-    "ports": [],
-    "links": [],
-    "texts": []
-  }
-}
-
+{
+  "name": "empty-state",
+  "description": "Baseline state with no entities.",
+  "state": {
+    "elements": [],
+    "ports": [],
+    "links": [],
+    "texts": []
+  }
+}
+