# ID9 r220 — VSIL Editor Refinement (Marquee Pure Module, Ref-Based Listeners, Snapshot Completeness)

**Date**: 2026-08-31
**Branch**: `feat/id9-r220-refinement` (123f586)
**Status**: SHIPPED to feature branch; awaiting merge to main
**Worktree**: `/workspace/vibecoder-standalone-r220` (port 5308)

## Summary

r220 is the final editor refinement pass for the VibeCoder VSIL editor. It extracts the marquee geometry algorithm to a pure utility module, refactors the Canvas to use ref-based document listeners (no more re-registration on every callback change), adds a visual snap indicator, memoizes the outline renderers, and audits the selection snapshot to include all 6+ layer fields (id, visible, locked, opacity, blendMode, name) plus a monotonic seq counter.

The marquee module (`marquee.ts`) is the canonical example of the r220 pattern: **algorithm in a pure module, presentation in a React component**. It can be tested in isolation without React/DOM, and the Canvas becomes a thin wrapper that calls the pure functions and renders the result.

## What changed

### 1. `src/host/editor/marquee.ts` (NEW, 8560 bytes)

Pure utility module with zero React/DOM dependencies. Exports:

- **`clampToViewport(x, y, w, h)`** — clamps coordinates to viewport bounds using `Math.max(0, Math.min(coord, dim))` on both axes.
- **`computeScale(viewportRect)`** — computes scale factors from viewport dimensions (vs. 1920×1080 scene).
- **`viewportToScene(vx, vy, scale, vw, vh)`** — converts viewport coords to scene coords (0..1920, 0..1080).
- **`collectLayerEdges(layers, scale)`** — collects all layer edges in viewport coords for snap.
- **`computeMarquee(startX, startY, curX, curY, options)`** — the main function. Returns `{ rect, hits, isDegenerate, snappedEdges }`. Strict snap (distance must be < snapPx, not ≤). Supports NaN/Infinity handling.
- **`MarqueeOptions`, `MarqueeResult`, `MarqueeHit`, `LayerBounds`** interfaces.

The snap algorithm collects all candidate edges (start, current, and all 4 edges of every layer), then for each marquee edge finds the closest edge within `snapPx`. If found, snap to it. This is the r220 pattern: pure function, deterministic, testable.

### 2. `src/host/editor/Canvas.tsx` (refactored, 35263 bytes)

Key changes from r219:

- **Marquee geometry delegated to marquee.ts** — the Canvas no longer computes the rect, hits, or snap inline. It calls `computeMarquee(...)` and gets back the result.
- **Ref-based document listeners** — single `useEffect` registers `mouseup`, `mousemove`, `keydown` on the document. The listeners delegate to refs (`marqueeRef`, `didDragRef`, `viewportRef`) so they always see the latest values. No more re-registration when `onMouseUp` changes.
- **Document-level mousemove fallback** — if a marquee is active and the pointer leaves the viewport, the document `mousemove` catches it so the marquee doesn't get stuck at the viewport edge.
- **Memoized outline renderers** — `useMemo` for layer box list, hover outline, multi-select outlines, and snap indicators. Each has its own dep array. Multi-select outlines only re-render when `selectedRegionIds` changes. Hover outline only when `hoveredLayerId` changes.
- **Configurable snap** — `Canvas.snapPx` prop (default 3, was hardcoded 4 in r219). `Canvas.snapDisabled` prop disables snap entirely. The marquee module uses strict `<` comparison.
- **New data attributes** — `data-r220-snap-active="1|0"`, `data-r220-hit-count="N"`, `data-r220-snap-indicator="startX|startY|curX|curY"`.
- **Snap indicator** — yellow `#ffeb3b` dots at snapped edges (4px diameter, zIndex 5). Renders ONLY during active drag AND only for edges that snapped.

### 3. `src/host/editor/selection.ts` (extended)

- **`LayerSnapshotData` interface** — `{ id, visible, locked, opacity?, blendMode?, name? }`. All 6 fields included; the last 3 are optional for backwards compat.
- **`SelectionSnapshot.seq?: number`** — monotonic counter bumped in `buildSnap`. Used for debug + ordering.
- **`sig()`** — includes all 6 fields for dedup.
- **`setCurrentLayers`** — now calls `notifySubscribers()` so the hook re-renders with the new layers.
- **`__getSelectionSingletonForTest`** — test helper to read the LIVE singleton state. The hook's returned `layers`/`selectedRegionIds` may be stale if the test doesn't wait for re-render.

### 4. Tests

**`src/host/editor/__tests__/editor-r220.test.tsx`** (NEW, 29386 bytes, 74 sections, 74/74 passing):

Sections cover:
- Marquee module: `clampToViewport`, `computeScale`, `viewportToScene`, `computeMarquee` (basic, snap, no-snap, degenerate, NaN/Infinity)
- Canvas: ref-based document listeners registered, `data-r218-marquee` rendered, `data-r220-snap-active` + `data-r220-hit-count` present, snap indicator rendered, hover/multi-select/marquee all `pointer-events: none`
- Selection: `LayerSnapshotData` includes all 6 fields, `seq` counter present, undo/redo of full-surface layers, `batchRename` pattern propagation, `applyTransformToSelected` preserves all fields
- 0 iframes, 0 postMessage in source files (excluding comments)

**`scripts/smoke/r220-smoke.spec.cjs`** (NEW, 12441 bytes, 28/28 passing):

Sections cover:
- 4 default layers mounted
- r220 marquee data attributes (`data-r220-snap-active`, `data-r220-hit-count`, `data-r220-snap-indicator`)
- Pixel-accurate intersection (hit-count reflects geometry)
- Snap-to-edges (3px threshold)
- Shift+drag additive mode (r219 invariant)
- Document-level mousemove fallback (source check)
- Esc-to-cancel mid-drag
- Hover + multi-select outlines (memoized renderers)
- Marquee commit via `setSelectedByRect`
- Snapshot completeness (opacity, blendMode, name, seq in source)
- 0 iframes in DOM, 0 postMessage in source

### 5. Existing test updates

- **`editor-r214.test.tsx`** — updated file count from 10 to 11 (added `marquee.ts`).
- **`editor-r219.test.tsx`** — updated `SNAP_PX` check to reflect r220's configurable `Canvas.snapPx` (default 3) and marquee.ts extraction.
- **`scripts/smoke/r219-smoke.spec.cjs`** — updated marquee startX clamp check to accept `clampToViewport` from marquee.ts.

## Verification sweep

| Test | Result |
|------|--------|
| editor.test.tsx (r207-r213) | 36/36 ✅ |
| editor-r214.test.tsx | 24/24 ✅ |
| editor-r214-1.test.tsx | 18/18 ✅ |
| editor-r215.test.tsx | 25/25 ✅ |
| editor-r216.test.tsx | 41/41 ✅ |
| editor-r217.test.tsx | 30/30 ✅ |
| editor-r218.test.tsx | 33/33 ✅ |
| editor-r219.test.tsx | 74/74 ✅ |
| editor-r220.test.tsx | 74/74 ✅ |
| **Unit total** | **355/355** |
| r218 Playwright | 19/19 (prior) |
| r219 Playwright | 29/29 ✅ (re-verified) |
| r220 Playwright | 28/28 ✅ |
| **Playwright total** | **76/76** |
| **Grand total** | **431/431** |
| 0 iframes in built bundle | ✅ (1 dynamic import reference to `replace-iframe-vsil` chunk — not a DOM iframe) |
| 0 postMessage in source | ✅ |

## Architecture decisions

### Why extract marquee to a pure module?

The marquee algorithm is geometry + set intersection. It doesn't need React. By extracting it:
- **Testable in isolation** — no jsdom, no React render, no test wrappers
- **Reusable** — the same module can power marquee, lasso, crop, etc.
- **Deterministic** — pure function, same input → same output
- **Fast** — no React overhead, no virtual DOM

The Canvas becomes a thin wrapper that:
1. Tracks pointer state (ref-based)
2. Calls `computeMarquee(...)` with the current state
3. Renders the result (marquee div + snap indicators)

### Why ref-based document listeners?

The r219 approach registered document listeners in a `useEffect` with `[onMouseUp]` as dep. When `onMouseUp` changed (which it did on every state change), the listeners were removed and re-registered. This was wasteful and could cause subtle bugs.

r220 registers the listeners ONCE on mount and delegates to refs. The listeners always see the latest `marqueeRef.current` / `didDragRef.current` / `viewportRef.current` without re-binding. No leak risk, no stale closures.

### Why a document-level mousemove?

r219 only listened for mouseup at document level. If the user dragged off the canvas (e.g. into the LayersPanel), the canvas's `onMouseMove` stopped firing but the marquee state froze. r220 adds `onDocMouseMove` that updates the marquee state even when the pointer is outside the viewport. Lost drag recovery.

### Why memoize the outline renderers?

The outline renderers (hover, multi-select, snap indicator) are simple divs, but they re-render on every parent re-render. The Canvas re-renders on every state change (zoom, pan, marquee). Without memoization, the outlines re-render too. With `useMemo`, they only re-render when their specific deps change. This is a perf win for large scenes.

### Why audit the snapshot signature?

r216 added `opacity`, `blendMode`, `name` to layers. But the r218 snapshot signature only included `id`, `visible`, `locked` + `name`. r220 extends `LayerSnapshotData` to include all 6 fields and updates `sig()` to match. This ensures undo/redo correctly detects changes to opacity/blendMode. Without this, undoing a opacity change would be a no-op (same sig → deduped).

The `seq` counter is a debug aid. It increments on every `pushSnap` and is included in the snapshot. Tests can verify the order of operations.

## Files changed

```
scripts/smoke/r219-smoke.spec.cjs          |  4 +-
scripts/smoke/r220-smoke.spec.cjs          | 322 ++++++++ (NEW)
scripts/smoke/screenshots-r220/*.png       |  4 files (NEW)
src/host/editor/Canvas.tsx                 |  refactored
src/host/editor/__tests__/editor-r214.test.tsx |  2 +-
src/host/editor/__tests__/editor-r219.test.tsx | 14 +-
src/host/editor/__tests__/editor-r220.test.tsx | 824 +++++++++++ (NEW)
src/host/editor/marquee.ts                 |  (NEW, 8560 bytes)
src/host/editor/selection.ts               |  extended
```

## Next steps

1. Merge `feat/id9-r220-refinement` → `main` with `--no-ff`
2. Tag `r220-shipped`
3. Operator deploys to prod (id 44)
4. Lock r220 pattern in agent memory (12-point reflex)
5. Post bulletin b1879 "r220 SHIPPED"
6. Upload artifacts to HQ (impl report = a845, AI summary = a846, screenshots = a847-a850)

## Locked-in invariants for r221+

- Pure utility module for marquee geometry (no React/DOM deps)
- Ref-based document listeners (single useEffect, single registration)
- Document-level mousemove fallback (lost drag recovery)
- Visual snap indicator (yellow dots at snapped edges)
- Memoized outline renderers (each with own dep array)
- Snapshot includes all 6+ layer fields (id, visible, locked, opacity, blendMode, name)
- Monotonic seq counter for debug + ordering
- Configurable snap (Canvas.snapPx prop, default 3, strict `<`)
- `__getSelectionSingletonForTest` for live state reads in tests
- `setCurrentLayers` calls `notifySubscribers` so the hook re-renders
- Build clean, 0 iframes, 0 postMessage