orcasvn-react-diagrams 0.2.0 → 0.2.2

package/dist/index.d.ts

@@ -20,6 +20,130 @@ type DiagramContainer = {
     getBoundingClientRect: () => ClientRectLike;
 };
 type MoveConstraint = 'free' | 'inside' | 'border';
+type BorderSide$1 = 'left' | 'right' | 'top' | 'bottom';
+type HostAnchorPreset = 'vertices' | 'cardinal';
+type PortAnchor = {
+    id: string;
+    position: Point;
+    side?: BorderSide$1;
+    normal?: Point;
+    meta?: Record<string, unknown>;
+};
+type PortAnchorConstraint = {
+    preset: HostAnchorPreset;
+    fallback?: 'nearest';
+};
+type ResolvePortAnchorsOptions = {
+    preset: HostAnchorPreset;
+};
+type ShapeVertexTarget = {
+    id: string;
+    position: Point;
+};
+type ShapeEdgeTarget = {
+    id: string;
+    start: Point;
+    end: Point;
+    midpoint: Point;
+};
+declare enum EllipseMidPoint {
+    top = "top",
+    right = "right",
+    bottom = "bottom",
+    left = "left"
+}
+type ShapeEllipseMidPointTarget = {
+    id: EllipseMidPoint;
+    ellipseMidPoint: EllipseMidPoint;
+    position: Point;
+};
+type ShapeHoverGeometry = {
+    vertices: ShapeVertexTarget[];
+    edges: ShapeEdgeTarget[];
+};
+type HoverControlIcon = {
+    svgPath: string;
+    size?: Size;
+    style?: Record<string, unknown>;
+};
+type ShapeControlTargetKind = 'vertex' | 'edge' | 'midpoint' | 'ellipse-midpoint';
+type ShapeControlVisibilityTrigger = 'element-hover' | 'target-hover';
+type ShapeControlDefinition = {
+    id: string;
+    targetKind: ShapeControlTargetKind;
+    icon: HoverControlIcon;
+    targetIndices?: number[];
+    ellipseMidPoints?: EllipseMidPoint | EllipseMidPoint[];
+    allowAllTargets?: boolean;
+    visibilityTriggers?: ShapeControlVisibilityTrigger[];
+    lineStyle?: Record<string, unknown>;
+    tolerance?: number;
+};
+/**
+ * @deprecated Use ShapeControlDefinition with targetKind='edge'.
+ */
+type EdgeHoverControl = {
+    kind: 'edge';
+    icon: HoverControlIcon;
+    lineStyle?: Record<string, unknown>;
+    tolerance?: number;
+};
+/**
+ * @deprecated Use ShapeControlDefinition with targetKind='vertex'.
+ */
+type VertexHoverControl = {
+    kind: 'vertex';
+    icon: HoverControlIcon;
+    tolerance?: number;
+};
+type ElementShapeHoverControls = {
+    controls?: ShapeControlDefinition[];
+    /**
+     * @deprecated Legacy singleton edge control. Use controls[] instead.
+     */
+    edge?: EdgeHoverControl;
+    /**
+     * @deprecated Legacy singleton vertex control. Use controls[] instead.
+     */
+    vertex?: VertexHoverControl;
+    /**
+     * @deprecated Legacy resolution preference for singleton edge/vertex controls.
+     */
+    priority?: 'vertex-first';
+};
+type ElementShapeControlEventType = 'click' | 'drag-start' | 'drag-move' | 'drag-end';
+type ElementShapeControlDragEvent = {
+    sessionId: string;
+    startPointer: EnginePointerInfo;
+    delta: Point;
+};
+type ElementShapeHoverControlInteractionEvent = {
+    eventType: ElementShapeControlEventType;
+    controlId: string;
+    elementId: string;
+    targetKind: ShapeControlTargetKind;
+    targetIndex: number;
+    pointer: EnginePointerInfo;
+    edge?: ShapeEdgeTarget;
+    vertex?: ShapeVertexTarget;
+    ellipseMidPoint?: EllipseMidPoint;
+    drag?: ElementShapeControlDragEvent;
+};
+/**
+ * @deprecated Use ElementShapeHoverControlInteractionEvent with eventType='click'.
+ */
+type ElementShapeHoverControlActivationEvent = {
+    controlKind: 'edge' | 'vertex';
+    elementId: string;
+    targetId: string;
+    pointer: EnginePointerInfo;
+    edge?: ShapeEdgeTarget;
+    vertex?: ShapeVertexTarget;
+};
+type ElementPortMovementPolicy = {
+    moveMode: MoveConstraint | 'anchors';
+    anchorConstraint?: PortAnchorConstraint;
+};
 type LinkRoutingMode = 'auto' | 'manual';
 type AnchorReference = 'top-left' | 'center';
 type RerouteLinksOptions = {
@@ -27,6 +151,11 @@ type RerouteLinksOptions = {
 };
 type ElementLayoutMode = 'manual' | 'horizontal' | 'vertical';
 type ElementLayoutAlign = 'start' | 'center' | 'end';
+type ElementLayoutChildFitMainAxis = 'none' | 'distribute';
+type ElementLayoutChildFitCrossAxis = 'none' | 'stretch';
+type TextLayoutBoundsMode = 'owner-width' | 'owner-box' | 'fixed';
+type TextLayoutWrapMode = 'none' | 'word' | 'char';
+type TextLayoutOverflowMode = 'clip' | 'ellipsis-end' | 'ellipsis-middle' | 'ellipsis-start';
 type ElementLayout = {
     mode: ElementLayoutMode;
     padding?: number | {
@@ -35,6 +164,18 @@ type ElementLayout = {
     };
     gap?: number;
     align?: ElementLayoutAlign;
+    childFitMainAxis?: ElementLayoutChildFitMainAxis;
+    childFitCrossAxis?: ElementLayoutChildFitCrossAxis;
+    childFitMinSize?: Partial<Size>;
+    childFitMaxSize?: Partial<Size>;
+};
+type TextLayout = {
+    boundsMode?: TextLayoutBoundsMode;
+    wrap?: TextLayoutWrapMode;
+    overflow?: TextLayoutOverflowMode;
+    padding?: number;
+    maxLines?: number;
+    fixedSize?: Size;
 };
 type ElementDropEvent = {
     elementId: string;
@@ -68,6 +209,7 @@ type ElementData = {
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;
     layout?: ElementLayout;
+    portMovement?: ElementPortMovementPolicy;
 };
 type PortData = {
     id: string;
@@ -79,6 +221,8 @@ type PortData = {
     textIds?: string[];
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;
+    orientToHostBorder?: boolean;
+    currentAnchorId?: string;
 };
 type ShapeDrawContext = {
     ctx: CanvasRenderingContext2D;
@@ -100,6 +244,10 @@ type TextData = {
     size?: Size;
     style?: Record<string, unknown>;
     ownerId?: string | null;
+    layout?: TextLayout;
+    displayContent?: string;
+    displayOffset?: Point;
+    displayClipSize?: Size;
 };
 type DiagramState = {
     elements: ElementData[];
@@ -172,6 +320,26 @@ type ElementResizedEvent = {
 type ElementDeletedEvent = {
     elementId: string;
 };
+type PortDeletedEvent = {
+    portId: string;
+    elementId: string;
+};
+type LinkDeletedEvent = {
+    linkId: string;
+    sourcePortId: string;
+    targetPortId: string;
+};
+type TextDeletedEvent = {
+    textId: string;
+    ownerId?: string | null;
+};
+type TextUpdatedEvent = {
+    textId: string;
+    ownerId?: string | null;
+    content: string;
+    displayContent: string;
+    reason: 'content' | 'layout';
+};
 type ElementLinkStartedEvent = {
     sourcePortId: string;
     sourceElementId: string;
@@ -218,6 +386,10 @@ type EngineEventMap = {
     elementMoved: ElementMovedEvent;
     elementResized: ElementResizedEvent;
     elementDeleted: ElementDeletedEvent;
+    portDeleted: PortDeletedEvent;
+    linkDeleted: LinkDeletedEvent;
+    textDeleted: TextDeletedEvent;
+    textUpdated: TextUpdatedEvent;
     elementSelected: ElementSelectedEvent;
     elementLinkStarted: ElementLinkStartedEvent;
     elementLinkConnecting: ElementLinkConnectingEvent;
@@ -262,10 +434,16 @@ type DiagramEngineHandle = {
     setSnapping: (snapper: unknown) => void;
     registerShape: (shape: {
         id: string;
+        baseRotation?: number;
         draw?: (context: ShapeDrawContext) => void;
         createNode?: (model: ElementData | PortData) => unknown;
         svgPath?: string;
         svgSize?: Size;
+        projectToBorder?: (point: Point, rect: Rect) => Point;
+        resolveBorderSide?: (point: Point, rect: Rect) => BorderSide$1;
+        resolvePortAnchors?: (rect: Rect, options: ResolvePortAnchorsOptions) => PortAnchor[];
+        resolveHoverGeometry?: (rect: Rect) => ShapeHoverGeometry | undefined;
+        resolveEllipseMidPoints?: (rect: Rect) => ShapeEllipseMidPointTarget[] | undefined;
     }) => void;
     render: () => void;
 };
@@ -282,6 +460,7 @@ declare class ElementModel {
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;
     layout?: ElementData['layout'];
+    portMovement?: ElementData['portMovement'];
     constructor(data: ElementData);
     setPosition(position: Point): void;
     setSize(size: Size): void;
@@ -326,8 +505,11 @@ declare class PortModel {
     textIds: string[];
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;
+    orientToHostBorder: boolean;
+    currentAnchorId?: string;
     constructor(data: PortData);
     setPosition(position: Point): void;
+    setCurrentAnchorId(currentAnchorId?: string): void;
     addText(textId: string): void;
     removeText(textId: string): void;
     toData(): PortData;
@@ -340,9 +522,17 @@ declare class TextModel {
     size?: Size;
     style?: Record<string, unknown>;
     ownerId?: string | null;
+    layout?: TextData['layout'];
+    displayContent?: string;
+    displayOffset?: Point;
+    displayClipSize?: Size;
     constructor(data: TextData);
     setContent(content: string): void;
     setSize(size: Size): void;
+    setDisplayContent(content: string): void;
+    setDisplayOffset(offset: Point | undefined): void;
+    setDisplayClipSize(size: Size | undefined): void;
+    setLayout(layout: TextData['layout']): void;
     setPosition(position: Point): void;
     toData(): TextData;
 }
@@ -374,6 +564,7 @@ declare class DiagramModel {
     removeElement(id: string): void;
     addPort(data: PortData): PortModel;
     movePort(id: string, position: Point): void;
+    setPortCurrentAnchorId(id: string, currentAnchorId?: string): void;
     removePort(id: string): void;
     addLink(data: LinkData): LinkModel;
     updateLinkPoints(id: string, points: Point[]): void;
@@ -426,8 +617,32 @@ interface SnapStrategy {
     snap(point: Point): Point;
 }
 
+type BorderSide = 'left' | 'right' | 'top' | 'bottom';
+
+type ShapeNodeSizeUpdateContext = {
+    size: {
+        width: number;
+        height: number;
+    };
+    anchorCenter: boolean;
+    updateOffsetX: boolean;
+    updateOffsetY: boolean;
+    getNodeAttr: <T = unknown>(key: string) => T | undefined;
+};
+type ShapeNodeSizeUpdater = (context: ShapeNodeSizeUpdateContext) => Record<string, unknown>;
+type ShapeResizeHandle = 'nw' | 'ne' | 'sw' | 'se';
+type ShapeResizeNormalizeContext = {
+    element: ElementData;
+    handle: ShapeResizeHandle;
+    minSize: number;
+    proposal: {
+        width: number;
+        height: number;
+    };
+};
 type ShapeDefinition = {
     id: string;
+    baseRotation?: number;
     draw?: (context: ShapeDrawContext) => void;
     createNode?: (model: ElementData | PortData) => unknown;
     svgPath?: string;
@@ -435,6 +650,16 @@ type ShapeDefinition = {
         width: number;
         height: number;
     };
+    sizeUpdater?: ShapeNodeSizeUpdater;
+    normalizeResize?: (context: ShapeResizeNormalizeContext) => {
+        width: number;
+        height: number;
+    };
+    projectToBorder?: (point: Point, rect: Rect) => Point;
+    resolveBorderSide?: (point: Point, rect: Rect) => BorderSide;
+    resolvePortAnchors?: (rect: Rect, options: ResolvePortAnchorsOptions) => PortAnchor[];
+    resolveHoverGeometry?: (rect: Rect) => ShapeHoverGeometry | undefined;
+    resolveEllipseMidPoints?: (rect: Rect) => ShapeEllipseMidPointTarget[] | undefined;
 };
 declare class ShapeRegistry {
     private shapes;
@@ -457,9 +682,11 @@ type DiagramEngineConfig = {
 };
 declare const createDiagramEngine: (config: DiagramEngineConfig) => DiagramEngineHandle;
 
+type BuiltInShapeKind = 'rect' | 'circle' | 'ellipse' | 'diamond' | 'triangle' | 'pentagon' | 'hexagon';
+
 type SimpleShape = {
     id: string;
-    kind: 'rect' | 'circle' | 'diamond' | 'triangle';
+    kind: BuiltInShapeKind;
     style?: Record<string, unknown>;
 };
 type DiagramEditorConfig = {
@@ -470,13 +697,17 @@ type DiagramEditorConfig = {
     elementShapes?: SimpleShape[];
     portShapes?: SimpleShape[];
     panKey?: 'Control' | 'Shift' | 'Alt' | 'Meta';
+    elementShapeHoverControls?: ElementShapeHoverControls;
+    onElementShapeHoverControlInteraction?: (event: ElementShapeHoverControlInteractionEvent) => void;
+    onElementShapeHoverControlActivated?: (event: ElementShapeHoverControlActivationEvent) => void;
     onChange?: (event: EngineChangeEvent) => void;
     onSelection?: (event: EngineSelectionEvent) => void;
 };
 type DiagramEditorHandle = DiagramEngineHandle & {
     resize: (width: number, height: number) => void;
+    setElementShapeHoverControls: (controls?: ElementShapeHoverControls) => void;
     destroy: () => void;
 };
 declare const createDiagramEditor: (config: DiagramEditorConfig) => DiagramEditorHandle;
 
-export { type AnchorReference, type ClientRectLike, type DiagramContainer, type DiagramEditorConfig, type DiagramEditorHandle, type DiagramEngineHandle, type DiagramPatch, type DiagramState, type ElementData, type ElementDeletedEvent, type ElementDropEvent, type ElementLayout, type ElementLayoutAlign, type ElementLayoutMode, type ElementLinkConnectingEvent, type ElementLinkEndedEvent, type ElementLinkStartedEvent, type ElementMovedEvent, type ElementPointerEvent, type ElementResizedEvent, type ElementSelectedEvent, type EngineChangeEvent, type EngineConfigEvent, type EngineEventMap, type EnginePointerInfo, type EngineSelectionEvent, type LinkData, type LinkRoutingMode, type MoveConstraint, type OverlayShapeConfig, type OverlayShapeHandle, type PaperClickEvent, type Point, type PortData, type PortMouseEvent, type PortMovedEvent, type PortSelectedEvent, type Rect, type RerouteLinksOptions, type ShapeDrawContext, type SimpleShape, type Size, type TextData, type TextSelectedEvent, createDiagramEditor, createDiagramEngine };
+export { type AnchorReference, type BorderSide$1 as BorderSide, type ClientRectLike, type DiagramContainer, type DiagramEditorConfig, type DiagramEditorHandle, type DiagramEngineHandle, type DiagramPatch, type DiagramState, type EdgeHoverControl, type ElementData, type ElementDeletedEvent, type ElementDropEvent, type ElementLayout, type ElementLayoutAlign, type ElementLayoutChildFitCrossAxis, type ElementLayoutChildFitMainAxis, type ElementLayoutMode, type ElementLinkConnectingEvent, type ElementLinkEndedEvent, type ElementLinkStartedEvent, type ElementMovedEvent, type ElementPointerEvent, type ElementPortMovementPolicy, type ElementResizedEvent, type ElementSelectedEvent, type ElementShapeControlDragEvent, type ElementShapeControlEventType, type ElementShapeHoverControlActivationEvent, type ElementShapeHoverControlInteractionEvent, type ElementShapeHoverControls, EllipseMidPoint, type EngineChangeEvent, type EngineConfigEvent, type EngineEventMap, type EnginePointerInfo, type EngineSelectionEvent, type HostAnchorPreset, type HoverControlIcon, type LinkData, type LinkDeletedEvent, type LinkRoutingMode, type MoveConstraint, type OverlayShapeConfig, type OverlayShapeHandle, type PaperClickEvent, type Point, type PortAnchor, type PortAnchorConstraint, type PortData, type PortDeletedEvent, type PortMouseEvent, type PortMovedEvent, type PortSelectedEvent, type Rect, type RerouteLinksOptions, type ResolvePortAnchorsOptions, type ShapeControlDefinition, type ShapeControlTargetKind, type ShapeControlVisibilityTrigger, type ShapeDrawContext, type ShapeEdgeTarget, type ShapeEllipseMidPointTarget, type ShapeHoverGeometry, type ShapeVertexTarget, type SimpleShape, type Size, type TextData, type TextDeletedEvent, type TextLayout, type TextLayoutBoundsMode, type TextLayoutOverflowMode, type TextLayoutWrapMode, type TextSelectedEvent, type TextUpdatedEvent, type VertexHoverControl, createDiagramEditor, createDiagramEngine };

package/docs/API_CONTRACT.md

@@ -23,6 +23,9 @@ Primary definitions:
 - `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`
 
@@ -55,7 +58,7 @@ Defaults:
 
 ### `ElementData`
 - Required: `id`, `position`, `size`, `shapeId`
-- Optional: `style`, `portIds`, `textIds`, `parentId`, `moveMode`, `anchorCenter`, `layout`
+- Optional: `style`, `portIds`, `textIds`, `parentId`, `moveMode`, `anchorCenter`, `layout`, `portMovement`
 - Defaults at runtime/model:
   - `portIds`: `[]`
   - `textIds`: `[]`
@@ -64,17 +67,27 @@ Defaults:
 ### `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`
+- Optional: `shapeId`, `size`, `style`, `textIds`, `moveMode`, `anchorCenter`, `orientToHostBorder`, `currentAnchorId`
 - Defaults at runtime/model:
   - `textIds`: `[]`
   - `anchorCenter`: `true`
+  - `orientToHostBorder`: `true`
 
 ### `LinkData`
 - Required: `id`, `sourcePortId`, `targetPortId`, `points`
@@ -85,9 +98,31 @@ Defaults:
 
 ### `TextData`
 - Required: `id`, `content`, `position`
-- Optional: `size`, `style`, `ownerId`
+- 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
 
@@ -105,8 +140,23 @@ Defaults:
 
 ### 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`
@@ -124,6 +174,10 @@ Defaults:
 - `elementMoved: ElementMovedEvent`
 - `elementResized: ElementResizedEvent`
 - `elementDeleted: ElementDeletedEvent`
+- `portDeleted: PortDeletedEvent`
+- `linkDeleted: LinkDeletedEvent`
+- `textDeleted: TextDeletedEvent`
+- `textUpdated: TextUpdatedEvent`
 - `elementSelected: ElementSelectedEvent`
 - `elementLinkStarted: ElementLinkStartedEvent`
 - `elementLinkConnecting: ElementLinkConnectingEvent` (cancelable through `cancel()`)
@@ -137,6 +191,8 @@ Defaults:
 - `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`

package/docs/ARCHITECTURE.md

@@ -5,6 +5,7 @@
 ## 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.

package/docs/CAPABILITIES.md

@@ -9,6 +9,8 @@
 - 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).
 
@@ -19,7 +21,7 @@
 - Server-side conflict resolution or persistence workflows.
 
 ## Preconditions
-- Runtime: Node `>=18.17 <19` for this repo toolchain.
+- Runtime: Node `>=20.17.0 <21.0.0` for this repo toolchain.
 - Browser host with Konva-compatible canvas environment when using `createDiagramEditor`.
 
 ## Side Effects

package/docs/COMMANDS_EVENTS.md

@@ -23,10 +23,14 @@
 - `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`
@@ -52,6 +56,7 @@
 ## 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`

package/docs/DOCUMENTATION_WORKFLOW.md

@@ -59,9 +59,9 @@ When resuming later:
 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)
+- 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
@@ -72,15 +72,13 @@ When resuming later:
 - 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.
+- [ ] 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/INTEGRATION_PLAYBOOK.md

@@ -11,8 +11,10 @@ Embed this library into another diagram host while preserving deterministic stat
    - `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`:

package/docs/PORTING_CHECKLIST.md

@@ -33,6 +33,7 @@
   - `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.

package/docs/STATE_INVARIANTS.md

@@ -20,8 +20,11 @@
 ## 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.
@@ -37,6 +40,7 @@
 - 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orcasvn-react-diagrams",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "dependencies": {
     "eventemitter3": "^5.0.1",
     "flatten-js": "^0.6.9",
@@ -10,7 +10,7 @@
     "web-vitals": "^2.1.4"
   },
   "engines": {
-    "node": ">=18.17.0 <19.0.0"
+    "node": ">=20.17.0 <21.0.0"
   },
   "scripts": {
     "start": "react-scripts start",
@@ -47,19 +47,27 @@
       "import": "./dist/esm/index.js",
       "require": "./dist/cjs/index.js"
     },
+    "./examples": {
+      "types": "./dist/examples.d.ts",
+      "import": "./dist/esm/examples.js",
+      "require": "./dist/cjs/examples.js"
+    },
+    "./examples-source": "./src/displaybox/demos/index.tsx",
+    "./examples-source/*": "./src/displaybox/demos/*",
     "./ai-manifest": "./ai/manifest.json",
     "./package.json": "./package.json"
   },
-  "files": [
-    "dist",
-    "README.md",
-    "docs",
-    "ai"
-  ],
+  "files": [
+    "dist",
+    "src/examples",
+    "src/displaybox/demos",
+    "src/displaybox/types.ts",
+    "README.md",
+    "docs",
+    "ai"
+  ],
   "types": "dist/index.d.ts",
   "devDependencies": {
-    "@types/jest": "^27.5.2",
-    "@types/node": "^16.18.101",
     "@rollup/plugin-commonjs": "^26.0.1",
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@rollup/plugin-terser": "^0.4.4",
@@ -67,6 +75,8 @@
     "@testing-library/jest-dom": "^5.17.0",
     "@testing-library/react": "^13.4.0",
     "@testing-library/user-event": "^13.5.0",
+    "@types/jest": "^27.5.2",
+    "@types/node": "^16.18.101",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
     "@types/uuid": "^10.0.0",