headless-vpl 0.1.0

package/README.md

@@ -0,0 +1,829 @@
+# Headless VPL
+
+> Build any Visual Programming Language — block-based, flow-based, or something entirely new.
+
+**Headless VPL** is a framework-agnostic TypeScript library for building Visual Programming Languages. It provides the core engine — drag & drop, snap connections, auto layout, edge routing, undo/redo, selection, and more — while leaving rendering and styling entirely up to you.
+
+- **Headless**: No built-in UI. Use React, Vue, Svelte, or vanilla DOM.
+- **Pure TypeScript**: Zero runtime dependencies. Full type safety.
+- **VPL-specialized**: Not a generic canvas library. Purpose-built APIs for visual programming.
+- **Simple > Easy**: Transparent internals you can understand and control.
+
+## Why Headless VPL?
+
+| | **Headless VPL** | **Blockly** | **ReactFlow** |
+|---|---|---|---|
+| VPL types | Block + Flow + Hybrid | Block only | Flow only |
+| Framework | Any (vanilla TS) | None (own renderer) | React only |
+| Rendering | You own it (DOM overlay) | Locked to Blockly renderer | Locked to React components |
+| Type safety | Full TypeScript generics | JSON/string-based | Partial |
+| Design freedom | Complete | Limited customization | Component-level only |
+| API surface | Thin, composable functions | Large, opinionated | Event-driven, implicit |
+
+## Quick Start
+
+```bash
+npm install headless-vpl
+```
+
+Minimal example — two draggable nodes connected by an edge:
+
+```typescript
+import {
+  Workspace, Container, Connector, Edge, Position,
+  SvgRenderer, screenToWorld,
+} from 'headless-vpl'
+import { getMouseState, getPositionDelta } from 'headless-vpl/util/mouse'
+import { animate } from 'headless-vpl/util/animate'
+import { DragAndDrop } from 'headless-vpl/util/dnd'
+import { isCollision } from 'headless-vpl/util/collision_detecion'
+
+// 1. Create workspace + renderer
+const workspace = new Workspace()
+const svg = document.querySelector('#workspace') as SVGSVGElement
+new SvgRenderer(svg, workspace)
+
+// 2. Create nodes with connectors
+const nodeA = new Container({
+  workspace,
+  position: new Position(100, 50),
+  name: 'nodeA',
+  width: 160, height: 60,
+  children: {
+    output: new Connector({ position: new Position(160, -30), name: 'out', type: 'output' }),
+  },
+})
+
+const nodeB = new Container({
+  workspace,
+  position: new Position(400, 50),
+  name: 'nodeB',
+  width: 160, height: 60,
+  children: {
+    input: new Connector({ position: new Position(0, -30), name: 'in', type: 'input' }),
+  },
+})
+
+// 3. Connect them
+new Edge({ start: nodeA.children.output, end: nodeB.children.input })
+
+// 4. Set up interaction
+const canvas = svg.parentElement!
+const containers = [nodeA, nodeB]
+let dragEligible = false
+let dragContainers: Container[] = []
+let prevMouse = { x: 0, y: 0 }
+let isPanning = false
+
+const mouse = getMouseState(canvas, {
+  mousedown: (state, pos) => {
+    const world = screenToWorld(pos, workspace.viewport)
+    dragEligible = containers.some(c => isCollision(c, world))
+    isPanning = !dragEligible
+  },
+  mouseup: () => { dragEligible = false; dragContainers = []; isPanning = false },
+})
+
+const worldMouse = {
+  get buttonState() { return mouse.buttonState },
+  get mousePosition() { return screenToWorld(mouse.mousePosition, workspace.viewport) },
+}
+
+// 5. Animation loop
+animate(() => {
+  const delta = getPositionDelta(mouse.mousePosition, prevMouse)
+  prevMouse = { ...mouse.mousePosition }
+
+  if (isPanning && mouse.buttonState.leftButton === 'down') {
+    workspace.panBy(delta.x, delta.y)
+  } else {
+    const s = workspace.viewport.scale
+    dragContainers = DragAndDrop(
+      containers, { x: delta.x / s, y: delta.y / s },
+      worldMouse, dragEligible, dragContainers,
+    )
+  }
+})
+```
+
+## Core Concepts
+
+### The Four Patterns
+
+Every VPL can be decomposed into four universal patterns:
+
+| Pattern | What it covers | Headless VPL API |
+|---|---|---|
+| **Rendering** | Responsive sizing, auto layout | `Container`, `AutoLayout`, `SvgRenderer` |
+| **Connection** | Connectors, edges, parent-child | `Connector`, `Edge`, `SnapConnection` |
+| **Movement** | Drag & drop, snap, group move | `DragAndDrop`, `snap`, `moveGroup` |
+| **Input** | Text, numbers, toggles, sliders | Your own DOM (framework-agnostic) |
+
+### Unidirectional Data Flow
+
+```
+Frontend (React / Vue / vanilla)
+  → Mouse/Keyboard events
+    → Headless VPL core (Workspace, Containers, Edges)
+      → EventBus notifications
+        → SvgRenderer (debug wireframe)
+        → Your DOM components (production UI)
+```
+
+### Headless Architecture
+
+Headless VPL draws an SVG wireframe for hit-testing and debugging. Your actual UI is a DOM layer on top, positioned to match the headless coordinates:
+
+```
+┌─ Canvas ─────────────────────────┐
+│  SVG layer (wireframe, invisible)│  ← hit detection, debug
+│  DOM overlay (your components)   │  ← what users see
+└──────────────────────────────────┘
+```
+
+Use `DomController` or manual CSS transforms to sync DOM positions with the headless coordinate system.
+
+---
+
+## API Reference
+
+### Core
+
+#### `Workspace`
+
+The root container for all VPL elements. Manages viewport, selection, history, and event dispatch.
+
+```typescript
+const workspace = new Workspace()
+```
+
+| Property | Type | Description |
+|---|---|---|
+| `eventBus` | `EventBus` | Event system for all workspace events |
+| `viewport` | `Viewport` | Current pan/zoom state `{ x, y, scale }` |
+| `selection` | `SelectionManager` | Selection state manager |
+| `history` | `History` | Undo/redo history stack |
+| `elements` | `readonly IWorkspaceElement[]` | All registered elements |
+| `edges` | `readonly IEdge[]` | All registered edges |
+
+| Method | Description |
+|---|---|
+| `addElement(element)` | Register an element (called automatically by Container/Connector constructors) |
+| `addEdge(edge)` | Register an edge (called automatically by Edge constructor) |
+| `removeElement(element)` | Unregister an element |
+| `removeEdge(edge)` | Unregister an edge |
+| `removeContainer(element)` | Remove a container and its related edges, clear parent/child relations, deselect |
+| `on(type, handler)` | Subscribe to events. Returns an unsubscribe function |
+| `pan(x, y)` | Set viewport position |
+| `panBy(dx, dy)` | Pan viewport by delta |
+| `zoomAt(screenX, screenY, newScale)` | Zoom centered on a screen point |
+| `setScale(scale)` | Set zoom scale directly |
+| `fitView(canvasWidth, canvasHeight, padding?)` | Fit all elements in view (padding default: 50) |
+
+#### `Container<T>`
+
+The primary building block. A rectangular element that can hold connectors, auto layouts, and other movable objects as typed children.
+
+```typescript
+const node = new Container({
+  workspace,
+  position: new Position(100, 50),
+  name: 'myNode',
+  color: 'blue',
+  width: 200,
+  height: 80,
+  widthMode: 'hug',     // 'fixed' | 'hug' | 'fill'
+  heightMode: 'fixed',
+  padding: { top: 10, right: 10, bottom: 10, left: 10 },
+  minWidth: 50,
+  maxWidth: 500,
+  resizable: true,
+  children: {
+    input: new Connector({ position: new Position(0, -40), name: 'in', type: 'input' }),
+    output: new Connector({ position: new Position(200, -40), name: 'out', type: 'output' }),
+  },
+})
+
+// Access typed children
+node.children.input  // Connector — fully typed
+```
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `color` | `string` | `'red'` | Wireframe color |
+| `width` | `number` | `100` | Width in world units |
+| `height` | `number` | `100` | Height in world units |
+| `widthMode` | `SizingMode` | `'fixed'` | `'fixed'` / `'hug'` (fit content) / `'fill'` |
+| `heightMode` | `SizingMode` | `'fixed'` | Same as widthMode |
+| `padding` | `Padding` | `{0,0,0,0}` | Inner padding |
+| `minWidth` / `maxWidth` | `number` | `0` / `Infinity` | Size constraints |
+| `minHeight` / `maxHeight` | `number` | `0` / `Infinity` | Size constraints |
+| `resizable` | `boolean` | `false` | Enable resize handles |
+| `children` | `T` | `{}` | Typed children map |
+| `selected` | `boolean` | `false` | Selection state (inherited from MovableObject) |
+| `Parent` | `MovableObject \| null` | `null` | Snap parent connection |
+| `Children` | `MovableObject \| null` | `null` | Snap child connection |
+
+| Method | Description |
+|---|---|
+| `move(x, y)` | Move to absolute position (updates children) |
+| `setColor(color)` | Change wireframe color |
+| `updateChildren()` | Recalculate child positions |
+| `applyContentSize(w, h)` | Apply content-based sizing (for hug mode) |
+| `toJSON()` | Serialize to plain object |
+
+#### `MovableObject` (abstract)
+
+Base class for all draggable elements. Extended by `Container` and `Connector`.
+
+| Property | Type | Description |
+|---|---|---|
+| `id` | `string` (readonly) | Unique identifier (auto-generated) |
+| `position` | `Position` | Current position |
+| `name` | `string` | Display name |
+| `type` | `string` | Element type identifier |
+| `selected` | `boolean` | Whether currently selected |
+| `Parent` | `MovableObject \| null` | Parent in snap hierarchy |
+| `Children` | `MovableObject \| null` | Child in snap hierarchy |
+| `workspace` | `Workspace` | Associated workspace |
+
+| Method | Description |
+|---|---|
+| `move(x, y)` | Move to position, emit `'move'` event |
+| `update()` | Emit `'update'` event |
+| `toJSON()` | Serialize to `{ id, type, name, position, selected }` |
+
+#### `Connector`
+
+An input or output connection point on a container.
+
+```typescript
+const connector = new Connector({
+  workspace,           // optional if added as Container child
+  position: new Position(0, -30),  // relative to parent container
+  name: 'input1',
+  type: 'input',       // 'input' | 'output'
+})
+```
+
+Connector positions are relative to their parent container. When the parent moves, connectors move with it.
+
+#### `Edge`
+
+A visual connection between two connectors.
+
+```typescript
+const edge = new Edge({
+  start: nodeA.children.output,    // Connector
+  end: nodeB.children.input,       // Connector
+  edgeType: 'bezier',              // 'straight' | 'bezier' | 'step' | 'smoothstep'
+  label: 'data flow',             // optional label at midpoint
+  markerStart: { type: 'none' },
+  markerEnd: { type: 'arrowClosed', color: '#333', size: 10 },
+})
+```
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `edgeType` | `EdgeType` | `'straight'` | Path algorithm |
+| `label` | `string?` | — | Text label at path midpoint |
+| `markerStart` | `EdgeMarker?` | — | Start arrow marker |
+| `markerEnd` | `EdgeMarker?` | — | End arrow marker |
+| `startConnector` | `Connector` | — | Source connector |
+| `endConnector` | `Connector` | — | Target connector |
+
+| Method | Description |
+|---|---|
+| `computePath()` | Returns `{ path: string, labelPosition: IPosition }` |
+| `getLabelPosition()` | Shorthand for `computePath().labelPosition` |
+
+#### `AutoLayout`
+
+Automatic layout manager for child containers (like CSS Flexbox).
+
+```typescript
+const layout = new AutoLayout({
+  position: new Position(10, 10),
+  direction: 'horizontal',  // 'horizontal' | 'vertical'
+  gap: 10,
+  alignment: 'center',      // 'start' | 'center' | 'end'
+  containers: [childA, childB, childC],
+})
+```
+
+Used as a child of a Container:
+
+```typescript
+const parent = new Container({
+  workspace,
+  position: new Position(0, 0),
+  name: 'layoutParent',
+  widthMode: 'hug',
+  heightMode: 'fixed',
+  height: 100,
+  padding: { top: 10, right: 10, bottom: 10, left: 10 },
+  children: { layout },
+})
+```
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction |
+| `gap` | `number` | `10` | Spacing between children |
+| `alignment` | `'start' \| 'center' \| 'end'` | `'center'` | Cross-axis alignment |
+
+#### `Position`
+
+Simple 2D coordinate.
+
+```typescript
+const pos = new Position(100, 200)
+pos.setPosition(150, 250)
+pos.getPosition() // { x: 150, y: 250 }
+```
+
+---
+
+### Event System
+
+#### `EventBus`
+
+Publish-subscribe event system for workspace state changes.
+
+```typescript
+// Subscribe (returns unsubscribe function)
+const unsub = workspace.eventBus.on('move', (event) => {
+  console.log(event.target, event.data)
+})
+
+// Unsubscribe
+unsub()
+```
+
+| Event Type | Emitted When |
+|---|---|
+| `move` | Element position changes |
+| `connect` | Two elements snap together |
+| `disconnect` | Snapped elements separate |
+| `add` | Element added to workspace |
+| `remove` | Element removed from workspace |
+| `update` | Element properties change |
+| `pan` | Viewport pans |
+| `zoom` | Viewport zooms |
+| `select` | Element selected |
+| `deselect` | Element deselected |
+
+#### `SelectionManager`
+
+Manages selected elements with event notifications.
+
+```typescript
+const sel = workspace.selection
+
+sel.select(container)                    // Select one
+sel.toggleSelect(container)              // Toggle selection
+sel.selectAll(workspace.elements as MovableObject[])  // Select all
+sel.deselectAll()                        // Clear selection
+sel.getSelection()                       // readonly MovableObject[]
+sel.isSelected(container)                // boolean
+sel.size                                 // number
+```
+
+Each `select`/`deselect` call sets `element.selected` and emits the corresponding event.
+
+---
+
+### History
+
+#### `History` & `Command`
+
+Undo/redo system with command pattern.
+
+```typescript
+interface Command {
+  execute(): void
+  undo(): void
+}
+
+const history = workspace.history
+
+history.execute(command)   // Execute + push to undo stack
+history.undo()             // Pop undo stack, push to redo
+history.redo()             // Pop redo stack, push to undo
+history.canUndo             // boolean
+history.canRedo             // boolean
+history.clear()            // Clear both stacks
+```
+
+#### Built-in Commands
+
+```typescript
+import { MoveCommand, AddCommand, RemoveCommand, ConnectCommand } from 'headless-vpl'
+
+// Record a move for undo
+new MoveCommand(element, fromX, fromY, toX, toY)
+
+// Record add/remove
+new AddCommand(workspace, element)
+new RemoveCommand(workspace, element)   // also handles related edges
+
+// Record connection
+new ConnectCommand(workspace, parent, child)
+```
+
+---
+
+### Rendering
+
+#### `SvgRenderer`
+
+Debug wireframe renderer. Subscribes to EventBus and draws SVG representations of all workspace elements.
+
+```typescript
+const svg = document.querySelector('#workspace') as SVGSVGElement
+new SvgRenderer(svg, workspace)
+```
+
+Creates SVG elements lazily:
+- **Container** → `<rect>` with stroke and fill
+- **Connector** → `<circle>`
+- **Edge** → `<g>` with `<path>` + optional `<text>` label + markers
+- **AutoLayout** → `<rect>` outline
+
+Handles viewport transforms (pan/zoom) and selection visual feedback (dashed stroke).
+
+---
+
+### Utilities
+
+#### Drag & Drop
+
+```typescript
+import { DragAndDrop } from 'headless-vpl/util/dnd'
+
+// Call every frame in your animation loop
+dragContainers = DragAndDrop(
+  containers,           // all draggable containers
+  worldDelta,           // { x, y } movement in world coordinates
+  mouseState,           // { buttonState, mousePosition } in world coords
+  dragEligible,         // true if mousedown was on a container
+  currentDragContainers, // containers currently being dragged
+  allowMultiple,        // allow dragging multiple containers (default: false)
+  callback,             // optional per-frame callback
+)
+```
+
+#### Snap & SnapConnection
+
+Low-level snap function and high-level connection manager.
+
+```typescript
+import { snap, SnapConnection, childOnly, parentOnly, either } from 'headless-vpl'
+
+// High-level: manages snap + parent/child + events
+const connection = new SnapConnection({
+  source: childNode,
+  sourcePosition: childNode.children.connectorTop.position,
+  target: parentNode,
+  targetPosition: parentNode.children.connectorBottom.position,
+  workspace,
+  snapDistance: 50,       // default: 50
+  strategy: childOnly,   // childOnly | parentOnly | either
+  validator: () => true,  // optional ConnectionValidator
+})
+
+// Call every frame
+connection.tick(mouseState, dragContainers)
+
+// Call on mousedown to allow re-snapping
+connection.unlock()
+```
+
+**Snap Strategies:**
+
+| Strategy | Snaps when... |
+|---|---|
+| `childOnly` | The child (source) is being dragged toward parent |
+| `parentOnly` | The parent (target) is being dragged toward child |
+| `either` | Either element is being dragged |
+
+#### Mouse
+
+```typescript
+import { getMousePosition, getMouseState, getPositionDelta } from 'headless-vpl/util/mouse'
+
+// Track mouse position relative to an element
+const position = getMousePosition(element)  // mutable IPosition
+
+// Track position + button state with callbacks
+const mouse = getMouseState(element, {
+  mousedown: (state, position, event) => { /* ... */ },
+  mouseup: (state, position, event) => { /* ... */ },
+})
+mouse.buttonState    // { leftButton: 'down' | 'up' }
+mouse.mousePosition  // IPosition
+
+// Compute frame delta
+const delta = getPositionDelta(currentPos, previousPos)  // { x, y }
+```
+
+#### Viewport
+
+```typescript
+import { screenToWorld, worldToScreen } from 'headless-vpl'
+
+const worldPos = screenToWorld(screenPos, workspace.viewport)
+const screenPos = worldToScreen(worldPos, workspace.viewport)
+```
+
+#### Edge Paths
+
+Four path algorithms for edge rendering:
+
+```typescript
+import {
+  getStraightPath,     // M...L straight line
+  getBezierPath,       // M...C cubic bezier
+  getStepPath,         // right-angle steps
+  getSmoothStepPath,   // rounded steps (borderRadius param)
+} from 'headless-vpl'
+
+const { path, labelPosition } = getBezierPath(startPos, endPos)
+// path: SVG path string
+// labelPosition: midpoint for label placement
+```
+
+#### Marquee Selection
+
+```typescript
+import { createMarqueeRect, getElementsInMarquee, getElementsInScreenMarquee } from 'headless-vpl'
+
+// Create normalized rect from two drag points
+const rect = createMarqueeRect(startPos, endPos)
+
+// Find elements in marquee (world coordinates)
+const hits = getElementsInMarquee(elements, rect, 'partial')  // 'full' | 'partial'
+
+// Screen-coordinate version (auto-converts via viewport)
+const hits = getElementsInScreenMarquee(elements, screenStart, screenEnd, viewport, 'partial')
+```
+
+Elements must implement `{ id, position, width, height }`.
+
+#### Snap to Grid
+
+```typescript
+import { snapToGrid, snapDeltaToGrid } from 'headless-vpl'
+
+const snapped = snapToGrid({ x: 37, y: 52 }, 24)        // { x: 36, y: 48 }
+const snappedDelta = snapDeltaToGrid({ x: 5, y: 3 }, 24) // rounds delta to grid
+```
+
+#### Clipboard
+
+```typescript
+import { copyElements, pasteElements } from 'headless-vpl'
+
+// Copy selected elements to clipboard data
+const data = copyElements(selectedElements)
+
+// Paste with a factory function
+const newElements = pasteElements(data, (json, position) => {
+  return new Container({
+    workspace,
+    position: new Position(position.x, position.y),
+    name: json.name as string,
+    width: json.width as number,
+    height: json.height as number,
+  })
+}, { x: 40, y: 40 })  // offset from original
+```
+
+#### Keyboard
+
+```typescript
+import { KeyboardManager } from 'headless-vpl'
+
+const keyboard = new KeyboardManager(document.body)
+
+keyboard.bind({
+  key: 'z',
+  modifiers: ['ctrl'],          // 'ctrl' matches both Ctrl and Cmd
+  handler: () => workspace.history.undo(),
+})
+
+keyboard.bind({
+  key: 'z',
+  modifiers: ['ctrl', 'shift'],
+  handler: () => workspace.history.redo(),
+})
+
+// Cleanup
+keyboard.unbind('z', ['ctrl'])
+keyboard.destroy()
+```
+
+#### Auto Pan
+
+```typescript
+import { computeAutoPan } from 'headless-vpl'
+
+const result = computeAutoPan(
+  mousePos,       // screen coordinates
+  canvasBounds,   // { x, y, width, height }
+  isDragging,     // only active while dragging
+  40,             // threshold (px from edge, default: 40)
+  10,             // speed (px/frame, default: 10)
+)
+
+if (result.active) {
+  workspace.panBy(result.dx, result.dy)
+}
+```
+
+#### Resize
+
+```typescript
+import { detectResizeHandle, beginResize, applyResize } from 'headless-vpl'
+
+// On mousedown: check if mouse is on a resize handle
+const handle = detectResizeHandle(worldMousePos, container, 8)  // handleSize
+
+if (handle) {
+  // Start resize
+  const state = beginResize(handle, worldMousePos, container)
+
+  // Each frame during resize:
+  const bounds = applyResize(worldMousePos, state, {
+    minWidth: 50, maxWidth: 500,
+    minHeight: 50, maxHeight: 300,
+  })
+
+  container.move(bounds.x, bounds.y)
+  container.width = bounds.width
+  container.height = bounds.height
+  container.update()
+}
+```
+
+Handle directions: `'n'` | `'s'` | `'e'` | `'w'` | `'ne'` | `'nw'` | `'se'` | `'sw'`
+
+#### Animation
+
+```typescript
+import { animate } from 'headless-vpl/util/animate'
+
+animate((deltaTime, frame) => {
+  // deltaTime: ms since last frame
+  // frame: incrementing counter
+})
+```
+
+#### Collision Detection
+
+```typescript
+import { isCollision } from 'headless-vpl/util/collision_detecion'
+
+const hit = isCollision(container, worldMousePos)  // AABB point-in-rect
+```
+
+#### Distance & Angle
+
+```typescript
+import { getDistance, getAngle } from 'headless-vpl'
+
+getDistance(pointA, pointB)  // Euclidean distance
+getAngle(pointA, pointB)    // Angle in radians (atan2)
+```
+
+#### DOM Controller
+
+```typescript
+import { DomController } from 'headless-vpl/util/domController'
+
+const ctrl = new DomController('#my-node')  // CSS selector
+ctrl.move(100, 200)         // Set absolute position via CSS transform
+ctrl.moveBy(10, 5)          // Relative move
+ctrl.getPosition()          // { x, y }
+```
+
+---
+
+### Types
+
+All exported types from `headless-vpl`:
+
+| Type | Description |
+|---|---|
+| `IWorkspaceElement` | Interface for workspace elements (`id`, `position`, `move()`, `update()`, `toJSON()`) |
+| `IEdge` | Interface for edges (`id`, `startPosition`, `endPosition`, `toJSON()`) |
+| `IPosition` | `{ x: number, y: number }` |
+| `Viewport` | `{ x: number, y: number, scale: number }` |
+| `VplEvent` | Event object `{ type, target, data? }` |
+| `VplEventType` | `'move' \| 'connect' \| 'disconnect' \| 'add' \| 'remove' \| 'update' \| 'pan' \| 'zoom' \| 'select' \| 'deselect'` |
+| `SizingMode` | `'fixed' \| 'hug' \| 'fill'` |
+| `Padding` | `{ top, right, bottom, left }` |
+| `EdgeType` | `'straight' \| 'bezier' \| 'step' \| 'smoothstep'` |
+| `MarkerType` | `'arrow' \| 'arrowClosed' \| 'none'` |
+| `EdgeMarker` | `{ type: MarkerType, color?: string, size?: number }` |
+| `ResizeHandleDirection` | `'n' \| 's' \| 'e' \| 'w' \| 'ne' \| 'nw' \| 'se' \| 'sw'` |
+| `Command` | `{ execute(): void, undo(): void }` |
+| `EdgePathResult` | `{ path: string, labelPosition: IPosition }` |
+| `MarqueeRect` | `{ x, y, width, height }` |
+| `MarqueeMode` | `'full' \| 'partial'` |
+| `MarqueeElement` | `{ id, position, width, height }` |
+| `ClipboardData` | `{ elements: Record<string, unknown>[] }` |
+| `KeyBinding` | `{ key, modifiers?, handler }` |
+| `CanvasBounds` | `{ x, y, width, height }` |
+| `AutoPanResult` | `{ dx, dy, active }` |
+| `ResizableElement` | `{ position, width, height, minWidth?, maxWidth?, minHeight?, maxHeight? }` |
+| `ResizeState` | `{ handle, startMousePos, startBounds }` |
+| `ConnectionValidator` | `() => boolean` |
+| `SnapStrategy` | `(source, target, dragContainers) => boolean` |
+| `SnapConnectionConfig` | Config object for `SnapConnection` constructor |
+
+---
+
+## Recipes
+
+### Block-type VPL (Scratch-style)
+
+```typescript
+// Vertical stacking blocks with snap connections
+const blockA = new Container({
+  workspace, position: new Position(100, 50), name: 'move',
+  width: 200, height: 60,
+  children: {
+    top: new Connector({ position: new Position(50, 0), name: 'top', type: 'input' }),
+    bottom: new Connector({ position: new Position(50, -60), name: 'bottom', type: 'output' }),
+  },
+})
+
+const blockB = new Container({
+  workspace, position: new Position(100, 200), name: 'turn',
+  width: 200, height: 60,
+  children: {
+    top: new Connector({ position: new Position(50, 0), name: 'top', type: 'input' }),
+    bottom: new Connector({ position: new Position(50, -60), name: 'bottom', type: 'output' }),
+  },
+})
+
+// Snap blockB's top to blockA's bottom
+const connection = new SnapConnection({
+  source: blockB,
+  sourcePosition: blockB.children.top.position,
+  target: blockA,
+  targetPosition: blockA.children.bottom.position,
+  workspace,
+  strategy: childOnly,
+})
+```
+
+### Flow-type VPL (ReactFlow-style)
+
+```typescript
+// Horizontal flow with bezier edges
+const start = new Container({
+  workspace, position: new Position(50, 100), name: 'Start',
+  width: 140, height: 50,
+  children: {
+    out: new Connector({ position: new Position(140, -25), name: 'out', type: 'output' }),
+  },
+})
+
+const process = new Container({
+  workspace, position: new Position(300, 100), name: 'Process',
+  width: 140, height: 50,
+  children: {
+    in: new Connector({ position: new Position(0, -25), name: 'in', type: 'input' }),
+    out: new Connector({ position: new Position(140, -25), name: 'out', type: 'output' }),
+  },
+})
+
+const end = new Container({
+  workspace, position: new Position(550, 100), name: 'End',
+  width: 140, height: 50,
+  children: {
+    in: new Connector({ position: new Position(0, -25), name: 'in', type: 'input' }),
+  },
+})
+
+new Edge({ start: start.children.out, end: process.children.in, edgeType: 'bezier' })
+new Edge({
+  start: process.children.out, end: end.children.in,
+  edgeType: 'bezier',
+  label: 'result',
+  markerEnd: { type: 'arrowClosed' },
+})
+```
+
+## Development
+
+```bash
+npm install && npm run dev     # Start dev server
+npm run build                  # Production build
+```
+
+## License
+
+MIT