@grida/hud 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,340 @@
+# @grida/hud
+
+The surface backend for the Grida editor viewport.
+
+A self-contained, mathematically grounded HUD overlay: handles, selection chrome, hover, marquee, gesture state, hit-testing — all rendered to a single `<canvas>` from a pure-logic state machine. No DOM overlay, no `data-id` traversal, no per-element React reconciliation in the hot path.
+
+## What is the HUD?
+
+The HUD is the non-content visual chrome drawn on top of the viewport: selection rectangles, resize handles, hover outlines, marquees, snap guides, measurement lines, pixel grids. Everything the operator sees that isn't part of the document itself.
+
+In industry terms: Blender calls this "Overlays", Unity calls it "Gizmos", game engines call it "HUD". We use HUD.
+
+## Why a canvas-based surface
+
+The DOM approach — positioned `<div>` handles, `data-grida-id` for hit-test, native dblclick — works until it doesn't. Concrete failures we hit before this package existed:
+
+- **DOM identity is fragile.** Re-rendering the SVG tree on every state change destroys the live element mid-gesture; native dblclick (keyed by DOM identity) breaks and has to be re-implemented manually.
+- **Hit-test relies on attributes.** `data-grida-id` has to be applied and stripped around export; any path-rewrite invalidates the id index.
+- **State and events are hard to propagate.** Gesture, hover, modifier, selection state scatter across the surface and editor; each one re-renders the world.
+- **It does not scale across backends.** SVG-tied DOM overlays can't be reused by the cg/Rust editor.
+
+The fix is to make the HUD a **pure-logic state machine + a canvas renderer**. The state machine takes raw pointer events, owns gesture/hover/modifiers, and emits `Intent`s to the host. The renderer draws a single `HUDDraw` per frame. Both layers are testable in isolation; neither layer touches the DOM.
+
+## Architecture
+
+Three layers. One-directional dependency: **`primitives/` ← `event/` ← `surface/`**.
+
+```text
+┌─────────────────────────────────────────────────┐
+│  Host (svg-editor, grida-canvas-react, …)       │
+│  - Document, scene, selection                   │
+│  - Provides:  pick, shapeOf, onIntent           │
+│  - Pushes pointer events to surface             │
+│  - Commits intents (history.preview, commands)  │
+└───────────────────────┬─────────────────────────┘
+                        │
+┌───────────────────────▼─────────────────────────┐
+│  surface/  — the wired class                    │
+│  - `Surface`: constructor wiring, lifecycle,    │
+│    draw loop                                    │
+│  - `chrome`: builds HUDDraw from state          │
+└───────────┬───────────────────────┬─────────────┘
+            │                       │
+┌───────────▼──────────┐ ┌──────────▼─────────────┐
+│  event/              │ │  primitives/           │
+│  the math core       │ │  dumb render shapes    │
+│  - Gesture state     │ │  - HUDCanvas           │
+│  - Hit-regions       │ │  - HUDDraw primitives  │
+│  - Click-tracker     │ │  - Snap/measure/lasso  │
+│  No canvas. No host. │ │    builders            │
+│  No DOM.             │ │  No state. No host.    │
+└──────────────────────┘ └────────────────────────┘
+```
+
+The `event/` layer is the testable core. It dispatches plain objects, returns plain objects, has zero I/O. Every gesture transition, hit-region resolution, and click-tracker decision is a pure function over its inputs — runnable under vitest with no canvas, no DOM, no React.
+
+## Layer responsibilities
+
+| Layer                      | Owns                                                                           | Reads from                    | Writes to                                                        |
+| -------------------------- | ------------------------------------------------------------------------------ | ----------------------------- | ---------------------------------------------------------------- |
+| **`primitives/HUDCanvas`** | Canvas2D context, DPR, transform, drawing of `HUDDraw` primitives              | —                             | Canvas                                                           |
+| **`event/`**               | Gesture, hover, modifiers, cursor, click-tracker, hit-regions, intent builders | —                             | Returns next state + intents from `dispatch(state, event, deps)` |
+| **`surface/Surface`**      | Current `SurfaceState`, the underlying `HUDCanvas`, host providers, draw loop  | Host providers, surface state | Calls `onIntent`; calls `HUDCanvas.draw`                         |
+| **Host**                   | Document, scene, selection, history                                            | Surface state introspection   | Pushes pointer events; pushes selection mirror; commits intents  |
+
+### What the surface deliberately does NOT own
+
+- **Selection.** Host owns; surface holds a read-only mirror via `setSelection(ids)`. Surface emits `select` / `deselect` / `toggle` intents; host commits.
+- **Document / scene.** Surface never reads node data directly. Only callbacks: `pick(point) → NodeId | null`, `shapeOf(id) → SelectionShape | null`.
+- **History.** Host wraps commits with `history.preview` per its own logic. Intents carry `phase: "preview" | "commit"` so the host knows when to wrap.
+- **`<style>` resolution, defs, paint, anything SVG-specific.** Out of scope.
+
+### What the surface owns because nothing else needs it
+
+Gesture state machine, hover indicator, modifier snapshot, cursor, click-tracker (dblclick). These have no representation outside the surface; making them surface-private is the single-source-of-truth rule.
+
+## Public API
+
+```ts
+import { Surface, HUDCanvas, type HUDDraw, type HUDStyle } from "@grida/hud";
+
+const surface = new Surface(canvasElement, {
+  // required wiring
+  pick:    (point_doc) => editor.hitTest(point_doc),      // (point) => NodeId | null
+  shapeOf: (id)        => editor.shapeOf(id),             // (id)    => SelectionShape | null
+  onIntent:  (intent)    => editor.commitIntent(intent),  // surface → host
+
+  // optional config
+  style: { chromeColor: "#2563eb", handleSize: 8 },
+  readonly: false,
+});
+
+// Lifecycle
+surface.setSize(w, h);
+surface.setTransform(t);    // camera (screen ↔ doc)
+surface.setSelection(ids);  // read-only mirror from host
+surface.setStyle(partial);
+surface.setReadonly(v);
+surface.dispose();
+
+// Input
+const response = surface.dispatch(event);
+// response: { needsRedraw, cursorChanged, hoverChanged }
+// (intents are pushed via onIntent, not returned here)
+
+// Frame
+surface.draw(extra?);        // merges surface chrome + host extras, one canvas draw
+
+// Read-only introspection
+surface.gesture(): SurfaceGesture;
+surface.hover():   NodeId | null;
+surface.cursor():  CursorIcon;
+```
+
+### Event types
+
+```ts
+type SurfaceEvent =
+  | { kind: "pointer_move"; x: number; y: number; mods: Modifiers }
+  | {
+      kind: "pointer_down";
+      x: number;
+      y: number;
+      button: PointerButton;
+      mods: Modifiers;
+    }
+  | {
+      kind: "pointer_up";
+      x: number;
+      y: number;
+      button: PointerButton;
+      mods: Modifiers;
+    }
+  | { kind: "modifiers"; mods: Modifiers }
+  | {
+      kind: "wheel";
+      x: number;
+      y: number;
+      dx: number;
+      dy: number;
+      mods: Modifiers;
+    }
+  | { kind: "key"; phase: "down" | "up"; code: string; mods: Modifiers };
+
+type Modifiers = { shift: boolean; alt: boolean; meta: boolean; ctrl: boolean };
+type PointerButton = "primary" | "secondary" | "middle";
+```
+
+All `SurfaceEvent` coordinates are **screen-space CSS pixels relative to the canvas**. The surface owns the camera and converts internally.
+
+### Gesture state
+
+```ts
+type SurfaceGesture =
+  | { kind: "idle" }
+  | { kind: "pan"; dx: number; dy: number }
+  | { kind: "marquee"; rect: Rect } // screen-space
+  | { kind: "translate"; ids: NodeId[]; dx: number; dy: number }
+  | { kind: "resize"; id: NodeId; anchor: ResizeDirection; rect: Rect }
+  | { kind: "rotate"; id: NodeId; corner: RotationCorner; angle: number };
+```
+
+### Intents
+
+The surface emits `Intent`s through `onIntent`. The host commits — wrapping in `history.preview`, dispatching commands, whatever. The surface itself doesn't mutate the document.
+
+```ts
+type Intent =
+  | { kind: "select"; ids: NodeId[]; mode: "replace" | "add" | "toggle" }
+  | { kind: "deselect_all" }
+  | { kind: "translate"; ids: NodeId[]; dx: number; dy: number; phase: Phase }
+  | {
+      kind: "resize";
+      id: NodeId;
+      anchor: ResizeDirection;
+      rect: Rect;
+      phase: Phase;
+    }
+  | { kind: "rotate"; id: NodeId; angle: number; phase: Phase }
+  | { kind: "enter_content_edit"; id: NodeId }
+  | { kind: "cancel_gesture" };
+
+type Phase = "preview" | "commit";
+```
+
+**Why `phase` matters.** During a drag, the surface emits `phase: "preview"` on every frame; on pointer-up, one final `phase: "commit"`. The host wraps `preview` intents in `history.preview()` (apply + revert) and finalizes on `commit`. This removes guesswork from the host — gesture state is not part of the intent contract.
+
+### React API
+
+A single hook. No provider, no context.
+
+```tsx
+import { useHUDSurface } from "@grida/hud/react";
+
+function Viewport() {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const surface = useHUDSurface(canvasRef, {
+    pick,
+    shapeOf,
+    onIntent,
+    style,
+  });
+  // surface is the imperative instance — same as `new Surface(...)`
+  // wire pointer events as the host wants
+  return <canvas ref={canvasRef} />;
+}
+```
+
+## Selection intent
+
+The full classification table — every named scenario at pointer-down, what
+commits when, and why DOM event order can't express it cleanly — is an
+**implementation-agnostic working-group spec**, alongside its UX-narrative
+sibling:
+
+- Formal classifier: https://grida.co/docs/wg/feat-editor/ux-surface/selection-intent
+- UX-narrative test cases: https://grida.co/docs/wg/feat-editor/ux-surface/selection
+
+This package's implementation:
+
+- [`event/decision.ts`](./event/decision.ts) — `Scenario` enum + `classifyScenario` +
+  dispatch.
+- [`__tests__/decision.test.ts`](./__tests__/decision.test.ts) — one test
+  per named scenario.
+
+Skim the spec before changing the classifier or its dispatch.
+
+## Coordinate model
+
+- All `SurfaceEvent` points are **screen-space** (CSS px relative to the canvas).
+- `setTransform(t)` is the camera — one matrix, screen ↔ doc.
+- Hit-test happens in two tiers on `pointer_down`:
+  1. **UI layer (screen-space AABB)** — surface's own `HitRegions` registry, populated by chrome builder each frame. Resize handle? Rotation handle? Body region (translate)? Direct path; no host involvement.
+  2. **Scene layer (doc-space point)** — if no UI hit, surface converts the point screen→doc and calls `pick(point_doc)`. Host implements this with whatever it has (`elementFromPoint`+`data-id` for SVG-DOM hosts, scene-cache R-tree for cg).
+- `shapeOf(id)` returns a **doc-space** `SelectionShape` (`{ kind: "rect", rect }` for most nodes, `{ kind: "line", p1, p2 }` for vector lines). Surface converts to screen for handle placement and screen-space chrome.
+
+Handles are always drawn at a fixed screen-space size regardless of zoom. The primitive layer supports this via `HUDScreenRect` (see below).
+
+## Render path (one draw per frame)
+
+1. **Surface builds its own `HUDDraw`** from `SurfaceState` + `shapeOf`:
+   - hover outline (if `hover()` set)
+   - selection outline (from selection mirror)
+   - marquee rect (if active gesture is `marquee`)
+   - resize / rotate handles (screen-space)
+   - size meter pill (selection bounds W×H)
+2. **Host extras merge in** if `draw(extra)` was called with a host-fed `HUDDraw` (snap guides, measurement, custom widgets).
+3. **One call to `HUDCanvas.draw(merged)`** — clears the canvas and renders everything immediately.
+
+Layer order within a frame (back-to-front):
+
+1. Hover outline
+2. Selection outline
+3. Marquee rect
+4. Resize/rotate handles
+5. Size meter pill
+6. Host-fed extras (always on top)
+
+## Primitives — what `HUDCanvas` can draw
+
+| Primitive       | Coordinate space                                       | Used by                                       |
+| --------------- | ------------------------------------------------------ | --------------------------------------------- |
+| `HUDLine`       | doc-space (segment), optional label in screen-space    | snap lines, measurement, spacing              |
+| `HUDRule`       | doc-space offset, full-viewport extent in screen-space | guide snapping, ruler                         |
+| `HUDRect`       | doc-space                                              | selection outline, marquee in doc-space hosts |
+| `HUDPolyline`   | doc-space                                              | lasso, complex selections                     |
+| `HUDScreenRect` | screen-space size at doc-space anchor                  | resize/rotate handles                         |
+| Crosshair point | screen-space                                           | snap hit indicators                           |
+| Label pill      | screen-space at doc-space anchor                       | size meters, snap gap labels                  |
+
+`HUDDraw` is a plain command struct grouping these. Builders (`snapGuideToHUDDraw`, `measurementToHUDDraw`, …) take host state and return a `HUDDraw` — the surface uses the same mechanism internally for its chrome.
+
+## Module layout
+
+```
+packages/grida-canvas-hud/
+├── README.md
+├── index.ts                   # Surface, HUDCanvas, public types
+├── react.tsx                  # useHUDSurface hook
+├── primitives/                # UI — dumb render shapes
+│   ├── canvas.ts              # HUDCanvas
+│   ├── types.ts               # HUDDraw, HUDLine, HUDRect, HUDPolyline, HUDRule, HUDScreenRect
+│   ├── snap-guide.ts          # HUDDraw builder
+│   ├── measurement-guide.ts   # HUDDraw builder
+│   ├── marquee.ts             # legacy HUDDraw builder (surface emits its own marquee)
+│   └── lasso.ts               # HUDDraw builder
+├── event/                     # the math core
+│   ├── event.ts               # SurfaceEvent, Modifiers, PointerButton
+│   ├── gesture.ts             # SurfaceGesture + transitions
+│   ├── hit-regions.ts         # screen-space AABB region registry
+│   ├── handles.ts             # 8 resize + 4 rotate geometry & hit-test
+│   ├── click-tracker.ts       # dblclick / multi-click detection
+│   ├── cursor.ts              # CursorIcon, ResizeDirection, RotationCorner
+│   ├── intent.ts              # Intent types + builders
+│   ├── transform.ts           # screen ↔ doc helpers
+│   └── state.ts               # SurfaceState — pure dispatch entry
+└── surface/                   # the wired class
+    ├── surface.ts             # Surface class
+    ├── chrome.ts              # builds HUDDraw from SurfaceState + shapeOf
+    └── style.ts               # HUDStyle defaults + merge
+```
+
+## Naming conventions
+
+- File names are **kebab-case `.ts`** throughout.
+- Inside files, **snake_case is acceptable** for non-filename identifiers.
+- Public method names on `Surface` and `HUDCanvas` are **camelCase** (`setSize`, `setTransform`, `setSelection`) — matches the existing primitive renderer API.
+- The top-level class is **`Surface`**, not `HUDSurface`. The package name already says "hud".
+
+## Testing
+
+`packages/grida-canvas-hud/__tests__/` runs under vitest. No DOM, no canvas mock — the `event/` layer is pure.
+
+| File                    | Tests                                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------------------- |
+| `transform.test.ts`     | screen ↔ doc across translate, scale, DPR                                                         |
+| `hit-regions.test.ts`   | topmost wins, reverse iteration, clear/empty, AABB containment                                    |
+| `handles.test.ts`       | 8 resize + 4 rotate positions; screen-space hit-test; visibility threshold                        |
+| `click-tracker.test.ts` | single vs double within window; position threshold; multi-button isolation                        |
+| `gesture.test.ts`       | legal transitions (idle↔translate/resize/marquee/cancel; deferred selection)                      |
+| `state.test.ts`         | dispatch sequences: click selects, drag-empty marquees, drag-handle resizes, drag-node translates |
+| `intent.test.ts`        | intent stream + `phase` correctness across a full drag (preview\*N → commit)                      |
+| `chrome.test.ts`        | given state + bounds, assert resulting `HUDDraw` shape — primitive counts and coords              |
+
+Render output (visual canvas correctness) is verified in the browser, not unit-tested.
+
+## Anti-goals
+
+- **Not a renderer.** `primitives/HUDCanvas` is intentionally minimal Canvas2D. Skia / WebGL backends are not in scope.
+- **Not a scene graph.** Surface never reads node data — only via `pick` / `shapeOf`.
+- **Not a host of plugins.** No widget registry. Custom HUD elements go through host-fed `HUDDraw` extras.
+- **Not undo-aware.** Intents carry `phase`; host owns undo.
+- **Not a selection store.** Host owns selection; surface mirrors.
+- **Not SVG-aware.** No `data-id`, no DOM IR, no `<style>` resolution.
+
+## Adoption
+
+v1 ships against [`@grida/svg-editor`](../grida-svg-editor/). The svg-editor's `dom.ts` is rewritten as a thin adapter: SVG content on the bottom layer, a `<canvas>` HUD on top, pointer events forwarded to `surface.dispatch`, intents flowing back via `editor.commitIntent`. Selection chrome, handles, and gesture state move out of `dom.ts` entirely.
+
+Main-editor migration (`editor/grida-canvas-react/viewport/ui/*`) is tracked separately. The host contract is the same; the only difference is the `pick` implementation (scene-cache R-tree instead of `elementFromPoint`+`data-id`).