orcasvn-react-diagrams 0.2.2 → 0.2.4

package/dist/index.d.ts

@@ -22,6 +22,7 @@ type DiagramContainer = {
 type MoveConstraint = 'free' | 'inside' | 'border';
 type BorderSide$1 = 'left' | 'right' | 'top' | 'bottom';
 type HostAnchorPreset = 'vertices' | 'cardinal';
+type PortLinkAttachMode = 'external' | 'internal';
 type PortAnchor = {
     id: string;
     position: Point;
@@ -29,10 +30,32 @@ type PortAnchor = {
     normal?: Point;
     meta?: Record<string, unknown>;
 };
+type PortBorderTransformContext = {
+    side: BorderSide$1;
+    normal: Point;
+    hostRect: Rect;
+    attachMode: PortLinkAttachMode;
+    effectiveLinkAttachPoint: Point;
+    placementPoint: Point;
+    rotationPivot: Point;
+    portSize?: Size;
+};
+type PortBorderTransformResult = {
+    rotation?: number;
+    offset?: Point;
+};
 type PortAnchorConstraint = {
     preset: HostAnchorPreset;
     fallback?: 'nearest';
 };
+type PositionAxisLimit = {
+    min?: number;
+    max?: number;
+};
+type PortPositionLimits = {
+    x?: PositionAxisLimit;
+    y?: PositionAxisLimit;
+};
 type ResolvePortAnchorsOptions = {
     preset: HostAnchorPreset;
 };
@@ -143,6 +166,7 @@ type ElementShapeHoverControlActivationEvent = {
 type ElementPortMovementPolicy = {
     moveMode: MoveConstraint | 'anchors';
     anchorConstraint?: PortAnchorConstraint;
+    positionLimits?: PortPositionLimits;
 };
 type LinkRoutingMode = 'auto' | 'manual';
 type AnchorReference = 'top-left' | 'center';
@@ -153,6 +177,15 @@ type ElementLayoutMode = 'manual' | 'horizontal' | 'vertical';
 type ElementLayoutAlign = 'start' | 'center' | 'end';
 type ElementLayoutChildFitMainAxis = 'none' | 'distribute';
 type ElementLayoutChildFitCrossAxis = 'none' | 'stretch';
+type ElementLayoutLabelReservedSpaceMode = 'none' | 'fixed' | 'flexible';
+type ElementLayoutLabelReservedSpacePlacement = 'top';
+type ElementLayoutLabelReservedSpace = {
+    mode?: ElementLayoutLabelReservedSpaceMode;
+    placement?: ElementLayoutLabelReservedSpacePlacement;
+    size?: number;
+    minSize?: number;
+    maxSize?: number;
+};
 type TextLayoutBoundsMode = 'owner-width' | 'owner-box' | 'fixed';
 type TextLayoutWrapMode = 'none' | 'word' | 'char';
 type TextLayoutOverflowMode = 'clip' | 'ellipsis-end' | 'ellipsis-middle' | 'ellipsis-start';
@@ -168,6 +201,7 @@ type ElementLayout = {
     childFitCrossAxis?: ElementLayoutChildFitCrossAxis;
     childFitMinSize?: Partial<Size>;
     childFitMaxSize?: Partial<Size>;
+    labelReservedSpace?: ElementLayoutLabelReservedSpace;
 };
 type TextLayout = {
     boundsMode?: TextLayoutBoundsMode;
@@ -222,6 +256,11 @@ type PortData = {
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;
     orientToHostBorder?: boolean;
+    placementPoint?: Point;
+    linkAttachPoint?: Point;
+    externalLinkAttachPoint?: Point;
+    internalLinkAttachPoint?: Point;
+    rotationPivot?: Point;
     currentAnchorId?: string;
 };
 type ShapeDrawContext = {
@@ -441,7 +480,9 @@ type DiagramEngineHandle = {
         svgSize?: Size;
         projectToBorder?: (point: Point, rect: Rect) => Point;
         resolveBorderSide?: (point: Point, rect: Rect) => BorderSide$1;
+        resolveBorderNormal?: (point: Point, rect: Rect) => Point;
         resolvePortAnchors?: (rect: Rect, options: ResolvePortAnchorsOptions) => PortAnchor[];
+        resolvePortBorderTransform?: (context: PortBorderTransformContext) => PortBorderTransformResult | undefined;
         resolveHoverGeometry?: (rect: Rect) => ShapeHoverGeometry | undefined;
         resolveEllipseMidPoints?: (rect: Rect) => ShapeEllipseMidPointTarget[] | undefined;
     }) => void;
@@ -506,6 +547,11 @@ declare class PortModel {
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;
     orientToHostBorder: boolean;
+    placementPoint?: Point;
+    linkAttachPoint?: Point;
+    externalLinkAttachPoint?: Point;
+    internalLinkAttachPoint?: Point;
+    rotationPivot?: Point;
     currentAnchorId?: string;
     constructor(data: PortData);
     setPosition(position: Point): void;
@@ -657,7 +703,9 @@ type ShapeDefinition = {
     };
     projectToBorder?: (point: Point, rect: Rect) => Point;
     resolveBorderSide?: (point: Point, rect: Rect) => BorderSide;
+    resolveBorderNormal?: (point: Point, rect: Rect) => Point;
     resolvePortAnchors?: (rect: Rect, options: ResolvePortAnchorsOptions) => PortAnchor[];
+    resolvePortBorderTransform?: (context: PortBorderTransformContext) => PortBorderTransformResult | undefined;
     resolveHoverGeometry?: (rect: Rect) => ShapeHoverGeometry | undefined;
     resolveEllipseMidPoints?: (rect: Rect) => ShapeEllipseMidPointTarget[] | undefined;
 };
@@ -703,11 +751,29 @@ type DiagramEditorConfig = {
     onChange?: (event: EngineChangeEvent) => void;
     onSelection?: (event: EngineSelectionEvent) => void;
 };
+type DiagramImageExportOptions = {
+    mimeType?: string;
+    quality?: number;
+    pixelRatio?: number;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    fitToContent?: boolean | {
+        padding?: number;
+    };
+};
 type DiagramEditorHandle = DiagramEngineHandle & {
+    startLinkFromPort: (sourcePortId: string, pointer?: Point) => void;
+    updateLinkPreview: (pointer: Point) => void;
+    completeLinkToPort: (targetPortId: string) => void;
+    completeLinkToElement: (targetElementId: string, pointer: Point) => void;
+    cancelLink: () => void;
+    exportImage: (options?: DiagramImageExportOptions) => string;
     resize: (width: number, height: number) => void;
     setElementShapeHoverControls: (controls?: ElementShapeHoverControls) => void;
     destroy: () => void;
 };
 declare const createDiagramEditor: (config: DiagramEditorConfig) => DiagramEditorHandle;
 
-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 };
+export { type AnchorReference, type BorderSide$1 as BorderSide, type ClientRectLike, type DiagramContainer, type DiagramEditorConfig, type DiagramEditorHandle, type DiagramEngineHandle, type DiagramImageExportOptions, type DiagramPatch, type DiagramState, type EdgeHoverControl, type ElementData, type ElementDeletedEvent, type ElementDropEvent, type ElementLayout, type ElementLayoutAlign, type ElementLayoutChildFitCrossAxis, type ElementLayoutChildFitMainAxis, type ElementLayoutLabelReservedSpace, type ElementLayoutLabelReservedSpaceMode, type ElementLayoutLabelReservedSpacePlacement, 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 PortBorderTransformContext, type PortBorderTransformResult, type PortData, type PortDeletedEvent, type PortLinkAttachMode, type PortMouseEvent, type PortMovedEvent, type PortPositionLimits, type PortSelectedEvent, type PositionAxisLimit, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orcasvn-react-diagrams",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "dependencies": {
     "eventemitter3": "^5.0.1",
     "flatten-js": "^0.6.9",
@@ -63,6 +63,7 @@
     "src/displaybox/demos",
     "src/displaybox/types.ts",
     "README.md",
+    "CHANGELOG.md",
     "docs",
     "ai"
   ],

package/src/displaybox/demos/AsymmetricPortMultiAnchorDemoTab.tsx

@@ -0,0 +1,269 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { OverlayShapeHandle, PortData } from '../../api';
+import DisplayBoxControls from '../DisplayBoxControls';
+import DisplayBoxStage from '../DisplayBoxStage';
+import useDemoControls from '../useDemoControls';
+import useDemoEditor from '../useDemoEditor';
+import useOffsetSequence from '../useOffsetSequence';
+import type { DemoActionHelpers } from '../types';
+import {
+  asymmetricPortDefaultVariantId,
+  asymmetricPortMultiAnchorDemoConfig,
+  asymmetricPortShapeVariants,
+  createAsymmetricPortMultiAnchorState,
+  multiAnchorExternalPortId,
+  multiAnchorHostId,
+  resolveAsymmetricPortShapeVariant,
+} from './asymmetricPortMultiAnchorDemo';
+
+type DemoSide = 'top' | 'right' | 'bottom' | 'left';
+
+const sidePositions: Record<DemoSide, { x: number; y: number }> = {
+  top: { x: 112, y: 0 },
+  right: { x: 280, y: 68 },
+  bottom: { x: 182, y: 180 },
+  left: { x: 0, y: 130 },
+};
+
+const sideLabels: DemoSide[] = ['top', 'right', 'bottom', 'left'];
+const resolvePortSide = (port: PortData, host: { size: { width: number; height: number } }): DemoSide | null => {
+  if (Math.abs(port.position.x) <= 0.001) return 'left';
+  if (Math.abs(port.position.x - host.size.width) <= 0.001) return 'right';
+  if (Math.abs(port.position.y) <= 0.001) return 'top';
+  if (Math.abs(port.position.y - host.size.height) <= 0.001) return 'bottom';
+  return null;
+};
+
+const sideToVector = (side: DemoSide): { x: number; y: number } => {
+  if (side === 'left') return { x: -1, y: 0 };
+  if (side === 'right') return { x: 1, y: 0 };
+  if (side === 'top') return { x: 0, y: -1 };
+  return { x: 0, y: 1 };
+};
+
+const AsymmetricPortMultiAnchorDemo = () => {
+  const demo = asymmetricPortMultiAnchorDemoConfig;
+  const [showLegacyComparison, setShowLegacyComparison] = useState(true);
+  const [showExpectedAnchors, setShowExpectedAnchors] = useState(false);
+  const [selectedVariantId, setSelectedVariantId] = useState(asymmetricPortDefaultVariantId);
+  const overlayHandlesRef = useRef<OverlayShapeHandle[]>([]);
+  const selectedVariant = useMemo(
+    () => resolveAsymmetricPortShapeVariant(selectedVariantId),
+    [selectedVariantId],
+  );
+  const attachDistance = selectedVariant.externalLinkAttachPoint.x - selectedVariant.placementPoint.x;
+  const createState = useCallback(
+    () => createAsymmetricPortMultiAnchorState(showLegacyComparison, selectedVariantId),
+    [showLegacyComparison, selectedVariantId],
+  );
+
+  const { containerRef, editorRef, diagramState, selection, snapEnabled, setSnapEnabled } = useDemoEditor({
+    createState,
+    elementShapes: demo.elementShapes,
+    portShapes: demo.portShapes,
+  });
+
+  const nextOffset = useOffsetSequence();
+  const actionHelpers: DemoActionHelpers = useMemo(() => ({ nextOffset }), [nextOffset]);
+  const controls = useDemoControls({
+    demo,
+    editorRef,
+    diagramState,
+    selection,
+    snapEnabled,
+    setSnapEnabled,
+    actionHelpers,
+  });
+
+  useEffect(() => {
+    const editor = editorRef.current;
+    if (!editor) return;
+    asymmetricPortShapeVariants.forEach((variant) => {
+      editor.registerShape({
+        id: variant.shapeId,
+        baseRotation: 90,
+        svgPath: variant.svgPath,
+        svgSize: variant.svgSize,
+      });
+    });
+    editor.rerouteAllLinks();
+  }, [editorRef, showLegacyComparison, selectedVariantId]);
+
+  useEffect(() => {
+    const editor = editorRef.current;
+    const state = diagramState;
+
+    overlayHandlesRef.current.forEach((handle) => handle.destroy());
+    overlayHandlesRef.current = [];
+
+    if (!showExpectedAnchors || !editor || !state) return;
+
+    const hosts = new Map(state.elements.map((element) => [element.id, element]));
+    const debugPorts = state.ports.filter((port) => port.id.startsWith('multi-anchor-port-'));
+
+    debugPorts.forEach((port) => {
+      const host = hosts.get(port.elementId);
+      if (!host) return;
+      const side = resolvePortSide(port, host);
+      if (!side) return;
+      const vector = sideToVector(side);
+      const placementWorld = {
+        x: host.position.x + port.position.x,
+        y: host.position.y + port.position.y,
+      };
+      overlayHandlesRef.current.push(
+        editor.createOverlayShape({
+          shapeId: 'default',
+          position: placementWorld,
+          size: { width: 8, height: 8 },
+          anchorCenter: true,
+          style: {
+            fill: '#ffffff',
+            stroke: '#d97706',
+            strokeWidth: 2,
+            cornerRadius: 1,
+            opacity: 0.9,
+          },
+        }),
+      );
+
+      if (port.id === multiAnchorExternalPortId || port.id.endsWith('-port-top') || port.id.endsWith('-port-bottom')) {
+        overlayHandlesRef.current.push(
+          editor.createOverlayShape({
+            shapeId: 'port-dark',
+            position: {
+              x: placementWorld.x + vector.x * attachDistance,
+              y: placementWorld.y + vector.y * attachDistance,
+            },
+            size: { width: 8, height: 8 },
+            anchorCenter: true,
+            style: {
+              fill: '#dc2626',
+              stroke: '#dc2626',
+              opacity: 0.85,
+            },
+          }),
+        );
+      }
+    });
+
+    return () => {
+      overlayHandlesRef.current.forEach((handle) => handle.destroy());
+      overlayHandlesRef.current = [];
+    };
+  }, [diagramState, editorRef, showExpectedAnchors]);
+
+  const moveExternalPortToSide = (side: DemoSide) => {
+    const editor = editorRef.current;
+    const host = diagramState?.elements.find((element) => element.id === multiAnchorHostId);
+    if (!editor || !host) return;
+    const local = sidePositions[side];
+    editor.movePortTo(multiAnchorExternalPortId, host.position.x + local.x, host.position.y + local.y);
+    editor.setSelection([multiAnchorExternalPortId]);
+  };
+
+  return (
+    <section>
+      <div style={{ marginBottom: 12 }}>
+        <h2 style={{ marginTop: 0, marginBottom: 4 }}>{demo.title}</h2>
+        <p style={{ marginTop: 0, marginBottom: 8 }}>{demo.description}</p>
+        <p style={{ marginTop: 0, marginBottom: 0, fontSize: 13, color: '#475569' }}>
+          The custom `svgPath` glyph is intentionally non-centered. The multi-anchor row keeps the square pivot pinned to the
+          border while links use the circle for external targets and the square pivot for parent-child internal links.
+        </p>
+        <p style={{ marginTop: 8, marginBottom: 0, fontSize: 13, color: '#475569' }}>
+          Active glyph variant: <strong>{selectedVariant.label}</strong> ({selectedVariant.description})
+        </p>
+      </div>
+      <DisplayBoxControls
+        actions={demo.actions}
+        snapEnabled={controls.snapEnabled}
+        selectedLinkRouting={controls.selectedLinkRouting}
+        canToggleLinkRouting={controls.canToggleLinkRouting}
+        onReload={controls.handleReload}
+        onZoomIn={controls.handleZoomIn}
+        onZoomOut={controls.handleZoomOut}
+        onResetViewport={controls.handleResetViewport}
+        onToggleSnap={controls.handleToggleSnap}
+        onManualRender={controls.handleManualRender}
+        onToggleLinkRouting={controls.handleToggleLinkRouting}
+        onAction={controls.handleAction}
+        onExportImage={controls.handleExportImage}
+        onClearExportPreview={controls.handleClearExportPreview}
+        exportPreviewDataUrl={controls.exportPreviewDataUrl}
+        exportError={controls.exportError}
+      />
+      <div
+        style={{
+          display: 'grid',
+          gridTemplateColumns: 'minmax(0, 1fr) auto',
+          gap: 12,
+          alignItems: 'start',
+          marginBottom: 12,
+          padding: 12,
+          border: '1px solid #d9e2f0',
+          borderRadius: 8,
+          background: '#f8fbff',
+        }}
+      >
+        <div style={{ display: 'grid', gap: 8 }}>
+          <label htmlFor="legacy-comparison-toggle" style={{ display: 'flex', alignItems: 'center', gap: 8, fontWeight: 600 }}>
+            <input
+              id="legacy-comparison-toggle"
+              type="checkbox"
+              checked={showLegacyComparison}
+              onChange={(event) => setShowLegacyComparison(event.target.checked)}
+            />
+            Show legacy/default comparison
+          </label>
+          <label htmlFor="expected-anchor-toggle" style={{ display: 'flex', alignItems: 'center', gap: 8, fontWeight: 600 }}>
+            <input
+              id="expected-anchor-toggle"
+              type="checkbox"
+              checked={showExpectedAnchors}
+              onChange={(event) => setShowExpectedAnchors(event.target.checked)}
+            />
+            Show expected anchor markers
+          </label>
+          <label htmlFor="asymmetric-variant-select" style={{ display: 'flex', alignItems: 'center', gap: 8, fontWeight: 600 }}>
+            Port glyph variant
+            <select
+              id="asymmetric-variant-select"
+              value={selectedVariantId}
+              onChange={(event) => setSelectedVariantId(event.target.value)}
+            >
+              {asymmetricPortShapeVariants.map((variant) => (
+                <option key={variant.id} value={variant.id}>
+                  {variant.label}
+                </option>
+              ))}
+            </select>
+          </label>
+          <div style={{ fontSize: 13, color: '#334155' }}>
+            Drag any asymmetric port around the host border or use the side controls to verify top/right/bottom/left orientation.
+          </div>
+          <div style={{ fontSize: 13, color: '#334155' }}>
+            Quick visual check: the multi-anchor row should keep the square touching the border; the legacy row may shift because
+            it has no explicit placement or pivot anchors.
+          </div>
+          <div style={{ fontSize: 13, color: '#334155' }}>
+            Debug markers: amber square = expected border placement point, red dot = expected external attach point.
+          </div>
+        </div>
+        <div style={{ display: 'grid', gap: 8 }}>
+          <div style={{ fontSize: 12, fontWeight: 600, color: '#1e293b' }}>Move the external demo port</div>
+          <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8, justifyContent: 'flex-end' }}>
+            {sideLabels.map((side) => (
+              <button key={side} type="button" onClick={() => moveExternalPortToSide(side)} style={{ padding: '6px 10px' }}>
+                External → {side[0].toUpperCase() + side.slice(1)}
+              </button>
+            ))}
+          </div>
+        </div>
+      </div>
+      <DisplayBoxStage containerRef={containerRef} />
+    </section>
+  );
+};
+
+export default AsymmetricPortMultiAnchorDemo;

package/src/displaybox/demos/AutoLayoutDemoTab.tsx

@@ -1,5 +1,5 @@
 import React, { useEffect, useMemo, useState } from 'react';
-import type { ElementLayout, ElementLayoutMode } from '../../api';
+import type { ElementLayout, ElementLayoutLabelReservedSpaceMode, ElementLayoutMode } from '../../api';
 import { createId } from '../../utils/ids';
 import DisplayBoxControls from '../DisplayBoxControls';
 import DisplayBoxStage from '../DisplayBoxStage';
@@ -10,12 +10,15 @@ import type { DemoActionHelpers } from '../types';
 import { autoLayoutDemoConfig } from './autoLayoutDemo';
 import { gridStageStyle } from './shared';
 
-const parentOptions = [
-  { id: 'layout-row', label: 'Horizontal layout' },
-  { id: 'layout-column', label: 'Vertical layout' },
-  { id: 'layout-nested', label: 'Nested layout' },
-  { id: 'layout-manual', label: 'Manual (compare)' },
-];
+const parentOptions = [
+  { id: 'layout-row', label: 'Horizontal layout' },
+  { id: 'layout-column', label: 'Vertical layout' },
+  { id: 'layout-nested', label: 'Nested layout' },
+  { id: 'layout-manual', label: 'Manual (compare)' },
+];
+const shortLabel = 'Parent label lane demo';
+const longLabel =
+  'Parent label lane demo with longer content to increase flexible reserved space and push children downward.';
 
 const AutoLayoutDemo = () => {
   const demo = autoLayoutDemoConfig;
@@ -49,6 +52,10 @@ const AutoLayoutDemo = () => {
   const [childFitMinHeight, setChildFitMinHeight] = useState<number | ''>('');
   const [childFitMaxWidth, setChildFitMaxWidth] = useState<number | ''>('');
   const [childFitMaxHeight, setChildFitMaxHeight] = useState<number | ''>('');
+  const [labelReservedMode, setLabelReservedMode] = useState<ElementLayoutLabelReservedSpaceMode>('none');
+  const [labelReservedFixedSize, setLabelReservedFixedSize] = useState<number>(32);
+  const [labelReservedMinSize, setLabelReservedMinSize] = useState<number | ''>('');
+  const [labelReservedMaxSize, setLabelReservedMaxSize] = useState<number | ''>('');
   const [lastTrigger, setLastTrigger] = useState<string>('None yet');
 
   useEffect(() => {
@@ -133,6 +140,10 @@ const AutoLayoutDemo = () => {
     setChildFitMinHeight(layout?.childFitMinSize?.height ?? '');
     setChildFitMaxWidth(layout?.childFitMaxSize?.width ?? '');
     setChildFitMaxHeight(layout?.childFitMaxSize?.height ?? '');
+    setLabelReservedMode(layout?.labelReservedSpace?.mode ?? 'none');
+    setLabelReservedFixedSize(layout?.labelReservedSpace?.size ?? 32);
+    setLabelReservedMinSize(layout?.labelReservedSpace?.minSize ?? '');
+    setLabelReservedMaxSize(layout?.labelReservedSpace?.maxSize ?? '');
   }, [diagramState, targetId]);
 
   const childOrder = useMemo(() => {
@@ -161,7 +172,7 @@ const AutoLayoutDemo = () => {
     });
   }, [diagramState]);
 
-  const handleApplyLayout = () => {
+  const handleApplyLayout = () => {
     const editor = editorRef.current;
     if (!editor) return;
     if (!targetElement) return;
@@ -179,6 +190,16 @@ const AutoLayoutDemo = () => {
             ...(childFitMaxWidth === '' ? {} : { width: childFitMaxWidth }),
             ...(childFitMaxHeight === '' ? {} : { height: childFitMaxHeight }),
           };
+    const labelReservedSpace =
+      mode === 'manual'
+        ? undefined
+        : {
+            mode: labelReservedMode,
+            placement: 'top' as const,
+            ...(labelReservedMode === 'fixed' ? { size: labelReservedFixedSize } : {}),
+            ...(labelReservedMinSize === '' ? {} : { minSize: labelReservedMinSize }),
+            ...(labelReservedMaxSize === '' ? {} : { maxSize: labelReservedMaxSize }),
+          };
     const layout =
       mode === 'manual'
         ? { mode: 'manual' as const }
@@ -191,10 +212,20 @@ const AutoLayoutDemo = () => {
             childFitCrossAxis,
             childFitMinSize,
             childFitMaxSize,
+            labelReservedSpace,
           };
     editor.setElementLayout(targetElement.id, layout);
     setLastTrigger(`layout applied (${mode})`);
   };
+
+  const handleSetLabelContent = (content: string) => {
+    const editor = editorRef.current;
+    if (!editor || !diagramState || !targetElement) return;
+    const label = diagramState.texts.find((text) => text.ownerId === targetElement.id);
+    if (!label) return;
+    editor.updateText(label.id, content);
+    setLastTrigger('label updated');
+  };
 
   const handleAddChild = () => {
     const editor = editorRef.current;
@@ -250,6 +281,10 @@ const AutoLayoutDemo = () => {
         onManualRender={controls.handleManualRender}
         onToggleLinkRouting={controls.handleToggleLinkRouting}
         onAction={controls.handleAction}
+        onExportImage={controls.handleExportImage}
+        onClearExportPreview={controls.handleClearExportPreview}
+        exportPreviewDataUrl={controls.exportPreviewDataUrl}
+        exportError={controls.exportError}
       />
 
       <div style={{ display: 'grid', gap: 12, marginBottom: 12 }}>
@@ -400,6 +435,55 @@ const AutoLayoutDemo = () => {
             />
           </div>
 
+          <label htmlFor="label-reserved-mode-select" style={{ fontWeight: 600 }}>
+            Label lane
+          </label>
+          <select
+            id="label-reserved-mode-select"
+            value={labelReservedMode}
+            onChange={(event) => setLabelReservedMode(event.target.value as ElementLayoutLabelReservedSpaceMode)}
+            style={{ padding: '6px 10px', minWidth: 120 }}
+            disabled={mode === 'manual'}
+          >
+            <option value="none">None</option>
+            <option value="fixed">Fixed</option>
+            <option value="flexible">Flexible</option>
+          </select>
+
+          <label htmlFor="label-reserved-fixed-input" style={{ fontWeight: 600 }}>
+            Lane fixed/min/max
+          </label>
+          <div style={{ display: 'inline-flex', gap: 6 }}>
+            <input
+              id="label-reserved-fixed-input"
+              type="number"
+              value={labelReservedFixedSize}
+              onChange={(event) => setLabelReservedFixedSize(Math.max(0, Number(event.target.value) || 0))}
+              style={{ width: 70, padding: '6px 8px' }}
+              min={0}
+              placeholder="fixed"
+              disabled={mode === 'manual'}
+            />
+            <input
+              type="number"
+              value={labelReservedMinSize}
+              onChange={(event) => setLabelReservedMinSize(event.target.value === '' ? '' : Math.max(0, Number(event.target.value) || 0))}
+              style={{ width: 64, padding: '6px 8px' }}
+              min={0}
+              placeholder="min"
+              disabled={mode === 'manual'}
+            />
+            <input
+              type="number"
+              value={labelReservedMaxSize}
+              onChange={(event) => setLabelReservedMaxSize(event.target.value === '' ? '' : Math.max(0, Number(event.target.value) || 0))}
+              style={{ width: 64, padding: '6px 8px' }}
+              min={0}
+              placeholder="max"
+              disabled={mode === 'manual'}
+            />
+          </div>
+
           <button type="button" onClick={handleApplyLayout} style={{ padding: '6px 12px', fontWeight: 600 }}>
             Apply layout
           </button>
@@ -420,11 +504,27 @@ const AutoLayoutDemo = () => {
               alignItems: 'center',
             }}
           >
-            <span style={{ fontWeight: 600 }}>Target:</span> {targetElement ? targetElement.id : '—'}
+            <span style={{ fontWeight: 600 }}>Target:</span> {targetElement ? targetElement.id : '—'}
             <span style={{ width: 6, height: 6, borderRadius: '50%', background: '#1f4d99', display: 'inline-block' }} />
             Last trigger: <strong>{lastTrigger}</strong>
-          </span>
-        </div>
+          </span>
+          <button
+            type="button"
+            onClick={() => handleSetLabelContent(shortLabel)}
+            style={{ padding: '6px 10px' }}
+            disabled={!targetElement || mode === 'manual'}
+          >
+            Label short
+          </button>
+          <button
+            type="button"
+            onClick={() => handleSetLabelContent(longLabel)}
+            style={{ padding: '6px 10px' }}
+            disabled={!targetElement || mode === 'manual'}
+          >
+            Label long
+          </button>
+        </div>
 
         <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 12 }}>
           <div>
@@ -447,6 +547,7 @@ const AutoLayoutDemo = () => {
             <ul style={{ marginTop: 0, paddingLeft: 18, fontSize: 13 }}>
               <li>Horizontal: try center vs bottom alignment and larger padding.</li>
               <li>Vertical: see parent grow taller as children stack.</li>
+              <li>Label lane: compare none/fixed/flexible and observe children start below the reserved lane.</li>
               <li>Fit main-axis distribute fills inner layout space across siblings.</li>
               <li>Fit cross-axis stretch extends children across inner cross axis.</li>
               <li>Min/max fit guards cap distributed or stretched child sizes.</li>
@@ -499,3 +600,4 @@ const AutoLayoutDemo = () => {
 };
 
 export default AutoLayoutDemo;
+

package/src/displaybox/demos/DeletionEventsDemoTab.tsx

@@ -103,7 +103,11 @@ const DeletionEventsDemo = () => {
         onToggleSnap={controls.handleToggleSnap}
         onManualRender={controls.handleManualRender}
         onToggleLinkRouting={controls.handleToggleLinkRouting}
-        onAction={controls.handleAction}
+        onAction={controls.handleAction}
+        onExportImage={controls.handleExportImage}
+        onClearExportPreview={controls.handleClearExportPreview}
+        exportPreviewDataUrl={controls.exportPreviewDataUrl}
+        exportError={controls.exportError}
       />
       <div style={{ display: 'grid', gap: 12, marginBottom: 12 }}>
         <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
@@ -145,3 +149,4 @@ const DeletionEventsDemo = () => {
 };
 
 export default DeletionEventsDemo;
+

package/src/displaybox/demos/EngineEventsDemoTab.tsx

@@ -95,6 +95,10 @@ const EngineEventsDemo = () => {
         onManualRender={controls.handleManualRender}
         onToggleLinkRouting={controls.handleToggleLinkRouting}
         onAction={controls.handleAction}
+        onExportImage={controls.handleExportImage}
+        onClearExportPreview={controls.handleClearExportPreview}
+        exportPreviewDataUrl={controls.exportPreviewDataUrl}
+        exportError={controls.exportError}
       />
       <div style={{ display: 'grid', gap: 12, marginBottom: 12 }}>
         <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
@@ -149,3 +153,4 @@ const EngineEventsDemo = () => {
 };
 
 export default EngineEventsDemo;
+