Module Roles Blueprint

The src/ codebase divides responsibilities among specialized modules. Each module owns a clear, single responsibility.

Module Map

src/
├── types.ts        → Canonical Types & Primitives
├── matrix.ts       → Stateless Coordinate Math
├── shadow-mount.ts → Shadow DOM Director
├── tree.ts         → Hierarchical Tree Model
├── layout.ts       → CSS Introspective Analyzer
├── renderer.ts     → 2D Canvas Painter
├── drop-zone.ts    → DnD Slot Detector
├── handlers/       → Pluggable Interaction & Keyboard Handlers
├── workspace.ts    → Thin Event Dispatcher & Orchestrator
└── index.ts        → Public API Barrel Exports

Module Details

types.ts — Canonical Types & Primitives

Contains structural definitions for vectors (Vec2), rectangles (Rect), transform matrices (ViewportMatrix), operation payloads (Operation), and drag state machine states. This is the single source of truth for all shared data models.

matrix.ts — Stateless Coordinate Math

Translates vectors and rects between Screen space (DOM client pixels) and Canvas space (scale-and-translate coordinates). Handles hit testing, pan accumulation, and zoom anchoring to prevent cursor drift. All functions are pure and stateless.

shadow-mount.ts — Shadow DOM Director

Injects and destroys wrapper elements, mounts styles, suppresses resize observer feedback loops, and isolates CSS. Houses the Flat String Bridge (extractHTML) to export clean, SDK-free HTML fragments. The largest module, managing the entire DOM lifecycle.

tree.ts — Hierarchical Tree Model

Manages the logical NodeTree structure (parentId, childIds, depth). Coordinates sibling sequences and performs ancestor-walk cycle detection to prevent circular references during reparenting.

layout.ts — CSS Introspective Analyzer

Evaluates getComputedStyle() values of content elements. Determines container display modes (flex, grid, block), parses direction axes (row vs. column), checks wrapping bounds, grid configurations, and gaps.

renderer.ts — 2D Canvas Painter

Draws selection frames, resize anchors, spacing adjusters, alignment snap guidelines, grid tracks, layout status badges, and marquee drag borders on the HTML5 Canvas overlay.

drop-zone.ts — DnD Slot Detector

Calculates placement indices inside Flex/Grid layout tracks and Block flows based on current pointer locations, returning insertion coordinates for drag-and-drop operations.

workspace.ts — Thin Event Dispatcher & Orchestrator

Serves as the main entry point for consumer integrations. Binds event listeners (pointer, key, wheel, window) and delegates all gesture and shortcut logic to pluggable interaction handlers using the claim-based dispatch loop. Implements WorkspaceContext to provide shared state and API delegation back to the handlers.

src/handlers/ — Pluggable Interaction & Keyboard Handlers

Focused behavior modules that claim and handle specific gestures or key shortcuts:

• PanHandler: Trackpad and middle-mouse spacebar panning.
• DrawHandler: Box/text node drawing previews and creation.
• ClipboardHandler: Copy, cut, paste, duplicate, and delete shortcuts.
• CommandHandler: Flex wrapping, nudging, and ungrouping commands.
• SpacingHandler: Margin, padding, and corner radius handle dragging.
• ResizeHandler: 8-anchor node scaling with alignment guides.
• DragHandler: Drag-and-drop movement, reparenting, and Alt-drag cloning.
• SelectionHandler: Fallback marquee drag selection and click-to-select scoping.

index.ts — Public API Barrel Exports

Re-exports all public types, classes, and functions from the other modules. Consumers import from this single entry point.

Dependency Flow

workspace.ts (orchestrator / context)
├── handlers/ (interaction behavior layer)
│   ├── types.ts (WorkspaceContext, InteractionHandler)
│   └── (modules: pan, draw, clipboard, command, spacing, resize, drag, selection)
├── shadow-mount.ts (DOM layer)
│   └── types.ts
├── renderer.ts (canvas layer)
│   └── types.ts
├── tree.ts (data model)
│   └── types.ts
├── layout.ts (CSS introspection)
│   └── types.ts
├── drop-zone.ts (DnD logic)
│   ├── layout.ts
│   └── types.ts
└── matrix.ts (coordinate math)
    └── types.ts