orcasvn-react-diagrams 0.2.7 → 0.2.9

package/dist/esm/types/api/types.d.ts

@@ -269,6 +269,8 @@ export type ElementData = {
     style?: Record<string, unknown>;
     portIds?: string[];
     textIds?: string[];
+    visible?: boolean;
+    selectable?: boolean;
     parentId?: string | null;
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;

package/dist/esm/types/displaybox/demos/elementVisibilitySelectionDemo.d.ts

@@ -0,0 +1,4 @@
+import type { DiagramState } from '../../api';
+import type { DemoConfig } from '../types';
+export declare const createElementVisibilitySelectionState: () => DiagramState;
+export declare const elementVisibilitySelectionDemoConfig: DemoConfig;

package/dist/esm/types/engine/DiagramEngine.d.ts

@@ -76,6 +76,11 @@ export default class DiagramEngine {
     setSelection(ids: string[]): void;
     toggleSelection(id: string): void;
     getSelection(): string[];
+    isElementVisible(id: string): boolean;
+    isElementSelectable(id: string): boolean;
+    isPortVisible(id: string): boolean;
+    isLinkVisible(id: string): boolean;
+    isTextVisible(id: string): boolean;
     getElementWorldPosition(id: string): Point | null;
     getElementRotation(id: string): number;
     normalizeElementResize(id: string, proposal: {
@@ -146,6 +151,9 @@ export default class DiagramEngine {
     private resolveTextPresentation;
     private resolveAllTextPresentationPatches;
     private emitSelection;
+    private normalizeSelectionIds;
+    private isSelectableId;
+    private syncSelectionToPolicies;
     private applyLayoutForParent;
     private applyLayoutCascade;
     private applyAllLayouts;

package/dist/esm/types/models/DiagramModel.d.ts

@@ -13,14 +13,19 @@ export default class DiagramModel {
     load(state: DiagramState): void;
     toState(): DiagramState;
     getElement(id: string): ElementModel | undefined;
+    isElementVisible(id: string): boolean;
+    isElementSelectable(id: string): boolean;
     setElementLayout(id: string, layout: ElementData['layout']): void;
     getChildren(parentId: string): ElementModel[];
     getElementWorldPosition(id: string): Point | null;
     getPort(id: string): PortModel | undefined;
+    isPortVisible(id: string): boolean;
     getPortWorldPosition(id: string): Point | null;
     getLink(id: string): LinkModel | undefined;
+    isLinkVisible(id: string): boolean;
     getLinkMidpoint(id: string): Point | null;
     getText(id: string): TextModel | undefined;
+    isTextVisible(id: string): boolean;
     getTextWorldPosition(id: string): Point | null;
     addElement(data: ElementData): ElementModel;
     moveElement(id: string, position: Point): void;

package/dist/esm/types/models/ElementModel.d.ts

@@ -7,6 +7,8 @@ export default class ElementModel {
     style?: Record<string, unknown>;
     portIds: string[];
     textIds: string[];
+    visible?: boolean;
+    selectable?: boolean;
     parentId: string | null;
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;

package/dist/examples.d.ts

@@ -242,6 +242,8 @@ type ElementData = {
     style?: Record<string, unknown>;
     portIds?: string[];
     textIds?: string[];
+    visible?: boolean;
+    selectable?: boolean;
     parentId?: string | null;
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;

package/dist/index.d.ts

@@ -269,6 +269,8 @@ type ElementData = {
     style?: Record<string, unknown>;
     portIds?: string[];
     textIds?: string[];
+    visible?: boolean;
+    selectable?: boolean;
     parentId?: string | null;
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;
@@ -543,6 +545,8 @@ declare class ElementModel {
     style?: Record<string, unknown>;
     portIds: string[];
     textIds: string[];
+    visible?: boolean;
+    selectable?: boolean;
     parentId: string | null;
     moveMode?: MoveConstraint;
     anchorCenter?: boolean;
@@ -640,14 +644,19 @@ declare class DiagramModel {
     load(state: DiagramState): void;
     toState(): DiagramState;
     getElement(id: string): ElementModel | undefined;
+    isElementVisible(id: string): boolean;
+    isElementSelectable(id: string): boolean;
     setElementLayout(id: string, layout: ElementData['layout']): void;
     getChildren(parentId: string): ElementModel[];
     getElementWorldPosition(id: string): Point | null;
     getPort(id: string): PortModel | undefined;
+    isPortVisible(id: string): boolean;
     getPortWorldPosition(id: string): Point | null;
     getLink(id: string): LinkModel | undefined;
+    isLinkVisible(id: string): boolean;
     getLinkMidpoint(id: string): Point | null;
     getText(id: string): TextModel | undefined;
+    isTextVisible(id: string): boolean;
     getTextWorldPosition(id: string): Point | null;
     addElement(data: ElementData): ElementModel;
     moveElement(id: string, position: Point): void;

package/docs/API_CONTRACT.md

@@ -62,12 +62,22 @@ Defaults:
 
 ### `ElementData`
 - Required: `id`, `position`, `size`, `shapeId`
-- Optional: `style`, `portIds`, `textIds`, `parentId`, `moveMode`, `anchorCenter`, `layout`, `childElementInteraction`, `portMovement`
+- Optional: `style`, `portIds`, `textIds`, `visible`, `selectable`, `parentId`, `moveMode`, `anchorCenter`, `layout`, `childElementInteraction`, `portMovement`
 - Defaults at runtime/model:
   - `portIds`: `[]`
   - `textIds`: `[]`
   - `parentId`: `null`
 
+### `ElementData.visible` and `ElementData.selectable`
+- Optional `visible?: boolean` (default behavior: `true`)
+- Optional `selectable?: boolean` (default behavior: `true`)
+- Semantics:
+  - `visible: false` removes the element body from built-in render, hit testing, marquee selection, persisted selection, `zoomToFitElements`, and `exportImage({ fitToContent })`
+  - hidden-scene propagation also hides owned ports, owned texts, and links whose source/target ports belong to hidden elements
+  - `selectable: false` prevents built-in element-body click selection, marquee selection, and programmatic `setSelection(...)` / `toggleSelection(...)` from retaining that element id
+  - `selectable: false` does not hide the element
+  - visible ports on a visible-but-unselectable element remain interactable/selectable unless separately constrained
+
 ### `ElementLayout`
 - Required: `mode: 'manual' | 'horizontal' | 'vertical' | 'grid'`
 - Optional: `padding?: number | { x: number; y: number }`, `gap?: number`, `align?: 'start' | 'center' | 'end'`
@@ -261,7 +271,9 @@ Defaults:
 - Missing IDs in most mutators are no-op (non-throwing).
 - `setViewport` emits a `change` patch with `entity: 'viewport'` and skips immediate render scheduling.
 - `zoomToFitElements` computes bounds from `elements[]` only, ignores ports/links/texts for fit expansion, and no-ops when no elements exist.
+- `zoomToFitElements` ignores hidden elements when computing fit bounds.
 - `zoomToFitElements` applies its result through `setViewport`, so hosts observe the standard viewport patch/change path.
+- `exportImage({ fitToContent })` derives crop bounds from visible scene entities only.
 - Built-in empty-paper panning now starts from plain primary-button drag and no longer requires `panKey`; marquee selection uses `Shift + primary drag`.
 - `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`.
@@ -269,6 +281,9 @@ Defaults:
 - `updateLinkPoints` always marks the link as manual routing.
 - `linkColorPoolPolicy` is opt-in and applies only to newly created links; explicitly provided non-empty `style.stroke` values are preserved.
 - `gridLayoutChanged` is additive and does not replace standard `change` / `elementResized` flows.
+- `ElementData.visible = false` hides the element plus owned ports/texts and endpoint-dependent links from built-in renderer sync, hit testing, marquee selection, persisted selection, and fit/export helpers.
+- `ElementData.selectable = false` blocks built-in element-body selection while still allowing visible owned ports to participate in their normal interaction flows.
+- `setSelection(...)` and `toggleSelection(...)` normalize away unknown IDs, hidden scene members, and unselectable elements before emitting `selection`.
 - `ElementData.childElementInteraction.movable = false` suppresses built-in drag only for direct child elements; programmatic `moveElementTo(...)` and layout/ancestor-driven repositioning remain allowed.
 - `TextData.interaction.movable = false` blocks built-in drag only; selection still works and programmatic movement remains allowed.
 - `TextData.interaction.editable = false` blocks built-in textarea editing only; selection still works and programmatic text updates remain allowed.

package/docs/CAPABILITIES.md

@@ -17,6 +17,7 @@
 - Auto-layout parent resize policy (`grow` / `grow-shrink`) and child size constraints.
 - Optional grid-child width topology editing with `gridLayoutChanged` host events.
 - Parent-owned direct-child drag suppression through `ElementData.childElementInteraction`.
+- Element-level visibility/selectability policy through `ElementData.visible` and `ElementData.selectable`, including hidden-scene propagation to owned ports/texts and endpoint-dependent links.
 - Element shape hover controls with edge/vertex/midpoint targets and interaction callbacks.
 - Optional random link color assignment from configurable pools during link creation.
 - Per-text interaction policy for suppressing built-in text drag and/or built-in text editing.

package/docs/COMMANDS_EVENTS.md

@@ -38,10 +38,11 @@
   - Plus `textDeleted` on removal (including cascade removal)
 - `setSelection/toggleSelection/deleteSelection`
   - `selection` plus derived selected entity events
+  - hidden scene members and `selectable:false` element IDs are filtered out before selection persists/emits
 - `setViewport`
   - `change` with viewport patch (`render: false`)
 - `zoomToFitElements`
-  - delegates to `setViewport` when at least one element exists
+  - delegates to `setViewport` when at least one visible element exists
   - emits the same viewport `change` patch path
 - `setRouting/setSnapping/registerShape`
   - `config` events
@@ -64,6 +65,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.
+- Built-in element-body selection emits no persisted element selection when the target element is hidden or sets `selectable = false`.
 - Built-in drag on a direct child element emits no move/drop mutation when its parent sets `childElementInteraction.movable = false`.
 - `textUpdated` emits only when target text exists; missing IDs remain no-op.
 

package/docs/DOCUMENTATION_WORKFLOW.md

@@ -59,7 +59,7 @@ When resuming later:
 5. Re-run packaging verification.
 
 ## 6. Current Status
-- Last updated: 2026-05-18
+- Last updated: 2026-05-27
 - Last completed step: 10
 - Next step: 7 (optional additional fixture coverage for deeper nested/manual-route scenarios)
 - Owner: Codex (with repository maintainers)
@@ -86,3 +86,5 @@ When resuming later:
 - 2026-05-10: Ran release validations: `npm run typecheck`, `npm test -- --watchAll=false`, `npm run build`, `npm run rollup-build-lib`, and `npm pack --dry-run`.
 - 2026-05-14: Completed release-doc pass for `v0.2.6`; refreshed release highlights, API contract updates (`zoomToFitElements`, `ViewportFitOptions`, `gridChildWidthResizeEnabled`, `gridLayoutChanged`, `TextInteractionPolicy`), and machine-readable contract metadata.
 - 2026-05-18: Completed release-doc pass for `v0.2.7`; refreshed release highlights, API contract updates (`ElementChildInteractionPolicy`, `childElementInteraction`, and built-in pan gesture behavior), and machine-readable contract metadata.
+- 2026-05-24: Completed release-doc pass for `v0.2.8`; refreshed release highlights and publish-facing workflow metadata for the nested grid slot-preservation fix.
+- 2026-05-27: Completed release-doc pass for `v0.2.9`; refreshed release highlights, visibility/selectability API docs, state/event integration notes, and machine-readable contract metadata.

package/docs/INTEGRATION_PLAYBOOK.md

@@ -19,6 +19,7 @@ Embed this library into another diagram host while preserving deterministic stat
 6. Use `zoomToFitElements(options?)` when the host needs library-owned fit-to-elements navigation instead of recomputing viewport math externally.
 7. Set `TextData.interaction` when some labels must remain read-only or fixed in place while still using library selection behavior.
 8. Set `ElementData.childElementInteraction` on parent elements when direct child nodes should stay selectable but not be draggable through built-in interaction.
+9. Set `ElementData.visible` and `ElementData.selectable` when hosts need hidden-but-retained nodes or visible-but-nonselectable element bodies; hidden elements also suppress owned ports/texts and endpoint-dependent links from built-in view helpers.
 
 ## Path B: Engine-Only Adapter
 1. Implement `Renderer`:

package/docs/PORTING_CHECKLIST.md

@@ -8,6 +8,7 @@
   - `PortData`
   - `LinkData`
   - `TextData`
+- Confirm host mapping for `ElementData.visible` / `ElementData.selectable` if hidden or non-selectable nodes must retain state.
 - Confirm owner-relative semantics for ports/texts.
 
 ## 2. Match Coordinate Semantics

package/docs/STATE_INVARIANTS.md

@@ -12,6 +12,9 @@
 - 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.
+- `visible` and `selectable` behave as enabled when omitted.
+- `visible=false` excludes the element from the visible scene, and ancestor hidden state propagates to descendant elements.
+- `selectable=false` prevents the element ID from persisting in engine selection state.
 - Deleting an element cascades to:
   - child ports
   - links connected through removed ports
@@ -21,6 +24,7 @@
 - Port position is local to owner element.
 - Default `anchorCenter=true` in model constructor.
 - Default `orientToHostBorder=true` in model constructor.
+- Port visible-state is derived from owning element visibility.
 - Moving ports can be constrained by:
   - `moveMode: inside|border`
   - element-level `portMovement.moveMode: free|inside|border|anchors`
@@ -34,11 +38,13 @@
 - 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.
+- Link visible-state requires both endpoint ports to remain visible.
 
 ## 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.
+- Owned text visible-state follows its owner visibility when the owner resolves to an element, port, or link.
 - Text interaction policy is persisted separately from style/layout metadata.
 - `interaction.movable = false` suppresses built-in drag without blocking selection or programmatic movement.
 - `interaction.editable = false` suppresses built-in editing without blocking selection or programmatic content updates.
@@ -49,8 +55,10 @@
 - `setSelection` emits:
   - `selection`
   - plus derived `elementSelected`/`portSelected`/`textSelected`
+- `setSelection` and `toggleSelection` normalize IDs against current visibility/selectability rules before persisting or emitting selection.
 - `setViewport` emits `change` with `entity=viewport` and does not force render directly.
-- `zoomToFitElements` derives viewport fit from `elements[]` bounds only and applies the result through `setViewport`.
+- `zoomToFitElements` derives viewport fit from visible `elements[]` bounds only and applies the result through `setViewport`.
+- `exportImage({ fitToContent })` derives crop bounds from visible scene entities only.
 
 ## Failure Modes
 - Non-existent target IDs: operation is no-op.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orcasvn-react-diagrams",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "dependencies": {
     "eventemitter3": "^5.0.1",
     "flatten-js": "^0.6.9",

package/src/displaybox/demos/AutoLayoutDemoTab.tsx

@@ -22,6 +22,9 @@ const parentOptions = [
   { id: 'layout-grid', label: 'Grid layout' },
   { id: 'layout-nested', label: 'Nested layout' },
   { id: 'layout-grid-deep', label: 'Nested grid' },
+  { id: 'layout-grid-empty-compare', label: 'Grid empty vs filled' },
+  { id: 'layout-grid-mixed-modes', label: 'Grid mixed child modes' },
+  { id: 'layout-column-grid-tree', label: 'Non-grid with grid descendants' },
   { id: 'layout-lock-compare', label: 'Child lock compare' },
   { id: 'layout-manual', label: 'Manual (compare)' },
 ];
@@ -391,11 +394,11 @@ const AutoLayoutDemo = () => {
           stable while height changes.
         </p>
         <p style={{ marginTop: 0, marginBottom: 0, fontSize: 13, color: '#333' }}>
-          The <code>layout-grid-deep</code> scenario now keeps the outer container focused on grid behavior with three direct
-          grid children, including one nested grid parent that also follows the enabled 12-unit resize path. The child drag
-          lock comparison lives beside it in <code> layout-lock-compare</code>; toggle the lock, try dragging
-          <code> deep-lock-child-a</code> versus <code> deep-free-child-a</code>, then use the API move shortcut to confirm
-          the policy suppresses built-in drag without freezing geometry.
+          The seeded scenarios now cover empty nested grids, mixed child layout modes under one grid owner, and grid
+          descendants inside a non-grid tree. Use <code>layout-grid-deep</code> for enabled 12-unit nested-child resize,
+          <code>layout-grid-empty-compare</code> for empty-versus-filled nested grid comparison, <code>layout-grid-mixed-modes</code>
+          for direct-child layout mixing, and <code>layout-column-grid-tree</code> for a non-grid owner that still contains
+          grid-layout descendants. The child drag lock comparison lives beside them in <code>layout-lock-compare</code>.
         </p>
       </div>
       <DisplayBoxControls
@@ -747,6 +750,9 @@ const AutoLayoutDemo = () => {
             <ul style={{ marginTop: 0, paddingLeft: 18, fontSize: 13 }}>
               <li>Nested grid: target layout-grid-deep to inspect an outer grid where all three direct children, including the nested grid parent, use enabled 12-unit resize.</li>
               <li>Select deep-grid-nested-parent and drag a horizontal resize handle; it should snap in grid units and then reflow inner children inside the resized container.</li>
+              <li>Empty nested grid: target layout-grid-empty-compare and compare empty-grid-slot against filled-grid-slot. The empty nested grid should still occupy its assigned outer slot.</li>
+              <li>Mixed grid children: target layout-grid-mixed-modes to inspect one grid owner whose direct children use grid, vertical, and horizontal auto-layout modes side by side.</li>
+              <li>Non-grid with grid descendants: target layout-column-grid-tree to inspect a vertical parent that still contains grid-layout containers deeper in the subtree.</li>
               <li>Lock comparison: target layout-lock-compare, toggle Lock comparison child drag, then compare deep-lock-child-a and deep-free-child-a.</li>
               <li>Use Move lock target via API after locking; the child should still reposition because the policy only suppresses built-in drag.</li>
               <li>Resize lock: with grid child width resize off, select grid-b and drag diagonally; width should stay fixed.</li>

package/src/displaybox/demos/autoLayoutDemo.ts

@@ -139,6 +139,195 @@ export const createAutoLayoutState = (lockComparisonChildren = true): DiagramSta
     { id: 'deep-grid-c', position: { x: 0, y: 0 }, size: { width: 52, height: 24 }, shapeId: 'default', parentId: 'deep-grid-nested-parent' },
     { id: 'deep-grid-d', position: { x: 0, y: 0 }, size: { width: 28, height: 30 }, shapeId: 'default', parentId: 'deep-grid-nested-parent' },
 
+    {
+      id: 'layout-grid-empty-compare',
+      position: { x: 930, y: 70 },
+      size: { width: 280, height: 190 },
+      shapeId: 'panel',
+      layout: {
+        mode: 'grid',
+        padding: { x: 12, y: 12 },
+        gap: 12,
+        align: 'center',
+        autoResize: 'grow-shrink',
+        gridTemplate: [4, 4, 4],
+        gridChildWidthResizeEnabled: true,
+        childMinWidth: 44,
+        childMinHeight: 52,
+      },
+    },
+    {
+      id: 'empty-grid-slot',
+      position: { x: 0, y: 0 },
+      size: { width: 28, height: 18 },
+      shapeId: 'default',
+      parentId: 'layout-grid-empty-compare',
+      layout: {
+        mode: 'grid',
+        padding: { x: 8, y: 8 },
+        gap: 8,
+        align: 'center',
+        autoResize: 'grow-shrink',
+        gridTemplate: [6, 6],
+        gridChildWidthResizeEnabled: true,
+      },
+    },
+    {
+      id: 'filled-grid-slot',
+      position: { x: 0, y: 0 },
+      size: { width: 92, height: 88 },
+      shapeId: 'default',
+      parentId: 'layout-grid-empty-compare',
+      layout: {
+        mode: 'grid',
+        padding: { x: 8, y: 8 },
+        gap: 8,
+        align: 'center',
+        autoResize: 'grow-shrink',
+        gridTemplate: [6, 6],
+        gridChildWidthResizeEnabled: true,
+        childMinWidth: 18,
+        childMinHeight: 18,
+      },
+    },
+    {
+      id: 'empty-grid-compare-leaf',
+      position: { x: 0, y: 0 },
+      size: { width: 60, height: 70 },
+      shapeId: 'default',
+      parentId: 'layout-grid-empty-compare',
+    },
+    { id: 'filled-grid-slot-a', position: { x: 0, y: 0 }, size: { width: 34, height: 22 }, shapeId: 'default', parentId: 'filled-grid-slot' },
+    { id: 'filled-grid-slot-b', position: { x: 0, y: 0 }, size: { width: 40, height: 24 }, shapeId: 'default', parentId: 'filled-grid-slot' },
+    { id: 'filled-grid-slot-c', position: { x: 0, y: 0 }, size: { width: 48, height: 22 }, shapeId: 'default', parentId: 'filled-grid-slot' },
+
+    {
+      id: 'layout-grid-mixed-modes',
+      position: { x: 930, y: 320 },
+      size: { width: 340, height: 240 },
+      shapeId: 'panel',
+      layout: {
+        mode: 'grid',
+        padding: { x: 12, y: 12 },
+        gap: 12,
+        align: 'center',
+        autoResize: 'grow-shrink',
+        gridTemplate: [4, 4, 4],
+        gridChildWidthResizeEnabled: true,
+        childMinWidth: 52,
+        childMinHeight: 64,
+      },
+    },
+    {
+      id: 'mixed-grid-child',
+      position: { x: 0, y: 0 },
+      size: { width: 88, height: 88 },
+      shapeId: 'default',
+      parentId: 'layout-grid-mixed-modes',
+      layout: {
+        mode: 'grid',
+        padding: { x: 8, y: 8 },
+        gap: 8,
+        align: 'center',
+        autoResize: 'grow-shrink',
+        gridTemplate: [6, 6],
+        gridChildWidthResizeEnabled: true,
+        childMinWidth: 18,
+        childMinHeight: 18,
+      },
+    },
+    {
+      id: 'mixed-column-child',
+      position: { x: 0, y: 0 },
+      size: { width: 92, height: 96 },
+      shapeId: 'default',
+      parentId: 'layout-grid-mixed-modes',
+      layout: {
+        mode: 'vertical',
+        padding: { x: 8, y: 8 },
+        gap: 8,
+        align: 'center',
+        autoResize: 'grow-shrink',
+      },
+    },
+    {
+      id: 'mixed-row-child',
+      position: { x: 0, y: 0 },
+      size: { width: 104, height: 84 },
+      shapeId: 'default',
+      parentId: 'layout-grid-mixed-modes',
+      layout: {
+        mode: 'horizontal',
+        padding: { x: 8, y: 8 },
+        gap: 8,
+        align: 'center',
+        autoResize: 'grow-shrink',
+      },
+    },
+    { id: 'mixed-grid-a', position: { x: 0, y: 0 }, size: { width: 34, height: 22 }, shapeId: 'default', parentId: 'mixed-grid-child' },
+    { id: 'mixed-grid-b', position: { x: 0, y: 0 }, size: { width: 44, height: 24 }, shapeId: 'default', parentId: 'mixed-grid-child' },
+    { id: 'mixed-column-a', position: { x: 0, y: 0 }, size: { width: 60, height: 20 }, shapeId: 'default', parentId: 'mixed-column-child' },
+    { id: 'mixed-column-b', position: { x: 0, y: 0 }, size: { width: 68, height: 24 }, shapeId: 'default', parentId: 'mixed-column-child' },
+    { id: 'mixed-row-a', position: { x: 0, y: 0 }, size: { width: 32, height: 28 }, shapeId: 'default', parentId: 'mixed-row-child' },
+    { id: 'mixed-row-b', position: { x: 0, y: 0 }, size: { width: 44, height: 24 }, shapeId: 'default', parentId: 'mixed-row-child' },
+
+    {
+      id: 'layout-column-grid-tree',
+      position: { x: 40, y: 520 },
+      size: { width: 340, height: 220 },
+      shapeId: 'panel',
+      layout: { mode: 'vertical', padding: { x: 12, y: 12 }, gap: 12, align: 'start', autoResize: 'grow-shrink' },
+    },
+    {
+      id: 'column-grid-tree-top',
+      position: { x: 0, y: 0 },
+      size: { width: 180, height: 88 },
+      shapeId: 'default',
+      parentId: 'layout-column-grid-tree',
+      layout: {
+        mode: 'grid',
+        padding: { x: 8, y: 8 },
+        gap: 8,
+        align: 'center',
+        autoResize: 'grow-shrink',
+        gridTemplate: [6, 6],
+        gridChildWidthResizeEnabled: true,
+        childMinWidth: 18,
+        childMinHeight: 18,
+      },
+    },
+    {
+      id: 'column-grid-tree-branch',
+      position: { x: 0, y: 0 },
+      size: { width: 220, height: 96 },
+      shapeId: 'default',
+      parentId: 'layout-column-grid-tree',
+      layout: { mode: 'horizontal', padding: { x: 8, y: 8 }, gap: 8, align: 'center', autoResize: 'grow-shrink' },
+    },
+    { id: 'column-grid-top-a', position: { x: 0, y: 0 }, size: { width: 52, height: 22 }, shapeId: 'default', parentId: 'column-grid-tree-top' },
+    { id: 'column-grid-top-b', position: { x: 0, y: 0 }, size: { width: 44, height: 24 }, shapeId: 'default', parentId: 'column-grid-tree-top' },
+    {
+      id: 'column-grid-tree-inner-grid',
+      position: { x: 0, y: 0 },
+      size: { width: 120, height: 84 },
+      shapeId: 'default',
+      parentId: 'column-grid-tree-branch',
+      layout: {
+        mode: 'grid',
+        padding: { x: 8, y: 8 },
+        gap: 8,
+        align: 'center',
+        autoResize: 'grow-shrink',
+        gridTemplate: [6, 6],
+        gridChildWidthResizeEnabled: true,
+        childMinWidth: 18,
+        childMinHeight: 18,
+      },
+    },
+    { id: 'column-grid-tree-leaf', position: { x: 0, y: 0 }, size: { width: 58, height: 62 }, shapeId: 'default', parentId: 'column-grid-tree-branch' },
+    { id: 'column-grid-inner-a', position: { x: 0, y: 0 }, size: { width: 30, height: 22 }, shapeId: 'default', parentId: 'column-grid-tree-inner-grid' },
+    { id: 'column-grid-inner-b', position: { x: 0, y: 0 }, size: { width: 42, height: 24 }, shapeId: 'default', parentId: 'column-grid-tree-inner-grid' },
+
     {
       id: 'layout-lock-compare',
       position: { x: 420, y: 410 },
@@ -241,6 +430,50 @@ export const createAutoLayoutState = (lockComparisonChildren = true): DiagramSta
     { id: 'label-deep-grid-b', content: 'grid-b', position: { x: 6, y: -14 }, ownerId: 'deep-grid-b' },
     { id: 'label-deep-grid-c', content: 'grid-c', position: { x: 6, y: -14 }, ownerId: 'deep-grid-c' },
     { id: 'label-deep-grid-d', content: 'grid-d', position: { x: 6, y: -14 }, ownerId: 'deep-grid-d' },
+    {
+      id: 'label-layout-grid-empty-compare',
+      content: 'Grid owner: empty vs filled nested grids',
+      position: { x: 8, y: 6 },
+      ownerId: 'layout-grid-empty-compare',
+      layout: { boundsMode: 'owner-width', wrap: 'word', overflow: 'clip', padding: 0 },
+    },
+    { id: 'label-empty-grid-slot', content: 'empty nested grid', position: { x: 6, y: -16 }, ownerId: 'empty-grid-slot' },
+    { id: 'label-filled-grid-slot', content: 'nested grid with children', position: { x: 6, y: -16 }, ownerId: 'filled-grid-slot' },
+    { id: 'label-empty-grid-compare-leaf', content: 'leaf sibling', position: { x: 6, y: -16 }, ownerId: 'empty-grid-compare-leaf' },
+    { id: 'label-filled-grid-slot-a', content: 'slot-a', position: { x: 6, y: -14 }, ownerId: 'filled-grid-slot-a' },
+    { id: 'label-filled-grid-slot-b', content: 'slot-b', position: { x: 6, y: -14 }, ownerId: 'filled-grid-slot-b' },
+    { id: 'label-filled-grid-slot-c', content: 'slot-c', position: { x: 6, y: -14 }, ownerId: 'filled-grid-slot-c' },
+    {
+      id: 'label-layout-grid-mixed-modes',
+      content: 'Grid owner: mixed child layout modes',
+      position: { x: 8, y: 6 },
+      ownerId: 'layout-grid-mixed-modes',
+      layout: { boundsMode: 'owner-width', wrap: 'word', overflow: 'clip', padding: 0 },
+    },
+    { id: 'label-mixed-grid-child', content: 'grid child', position: { x: 6, y: -16 }, ownerId: 'mixed-grid-child' },
+    { id: 'label-mixed-column-child', content: 'vertical child', position: { x: 6, y: -16 }, ownerId: 'mixed-column-child' },
+    { id: 'label-mixed-row-child', content: 'horizontal child', position: { x: 6, y: -16 }, ownerId: 'mixed-row-child' },
+    { id: 'label-mixed-grid-a', content: 'grid-a', position: { x: 6, y: -14 }, ownerId: 'mixed-grid-a' },
+    { id: 'label-mixed-grid-b', content: 'grid-b', position: { x: 6, y: -14 }, ownerId: 'mixed-grid-b' },
+    { id: 'label-mixed-column-a', content: 'col-a', position: { x: 6, y: -14 }, ownerId: 'mixed-column-a' },
+    { id: 'label-mixed-column-b', content: 'col-b', position: { x: 6, y: -14 }, ownerId: 'mixed-column-b' },
+    { id: 'label-mixed-row-a', content: 'row-a', position: { x: 6, y: -14 }, ownerId: 'mixed-row-a' },
+    { id: 'label-mixed-row-b', content: 'row-b', position: { x: 6, y: -14 }, ownerId: 'mixed-row-b' },
+    {
+      id: 'label-layout-column-grid-tree',
+      content: 'Vertical owner with grid descendants',
+      position: { x: 8, y: 6 },
+      ownerId: 'layout-column-grid-tree',
+      layout: { boundsMode: 'owner-width', wrap: 'word', overflow: 'clip', padding: 0 },
+    },
+    { id: 'label-column-grid-tree-top', content: 'top-level grid child', position: { x: 6, y: -16 }, ownerId: 'column-grid-tree-top' },
+    { id: 'label-column-grid-tree-branch', content: 'row branch with inner grid', position: { x: 6, y: -16 }, ownerId: 'column-grid-tree-branch' },
+    { id: 'label-column-grid-top-a', content: 'top-a', position: { x: 6, y: -14 }, ownerId: 'column-grid-top-a' },
+    { id: 'label-column-grid-top-b', content: 'top-b', position: { x: 6, y: -14 }, ownerId: 'column-grid-top-b' },
+    { id: 'label-column-grid-tree-inner-grid', content: 'nested grid descendant', position: { x: 6, y: -16 }, ownerId: 'column-grid-tree-inner-grid' },
+    { id: 'label-column-grid-tree-leaf', content: 'branch leaf', position: { x: 6, y: -14 }, ownerId: 'column-grid-tree-leaf' },
+    { id: 'label-column-grid-inner-a', content: 'inner-a', position: { x: 6, y: -14 }, ownerId: 'column-grid-inner-a' },
+    { id: 'label-column-grid-inner-b', content: 'inner-b', position: { x: 6, y: -14 }, ownerId: 'column-grid-inner-b' },
     {
       id: 'label-layout-lock-compare',
       content: 'Child drag lock comparison',

package/src/displaybox/demos/basicDemo.ts

@@ -60,12 +60,12 @@ const createBasicState = (): DiagramState => ({
   ],
 });
 
-export const basicDemoConfig: DemoConfig = ({
-  id: 'basic',
-  title: 'Basic Diagram',
-  description: 'Elements, ports, link, and labels.',
-  createState: createBasicState,
-  elementShapes: baseElementShapes,
+export const basicDemoConfig: DemoConfig = ({
+  id: 'basic',
+  title: 'Basic Diagram',
+  description: 'Elements, ports, link, and labels. Drag empty paper to pan; use Shift + drag for marquee selection.',
+  createState: createBasicState,
+  elementShapes: baseElementShapes,
   portShapes: basePortShapes,
   defaultElementShapeId: 'default',
   defaultPortShapeId: 'port-circle',