@grida/hud 0.1.0 → 0.2.0

package/README.md

@@ -74,6 +74,52 @@ The `event/` layer is the testable core. It dispatches plain objects, returns pl
 
 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.
 
+## Two backends: render and hit-testing
+
+The HUD has two backends, and they deliberately disagree.
+
+Every frame the HUD produces two outputs: a list of render primitives drawn to the canvas, and a registry of hit regions consulted on pointer events. They share no geometry. They are paired per affordance — the rotation handle's hit region is not derived from a rendered shape, and the resize knob's visual is not derived from its hit AABB. One backend is for the eye; the other is for the cursor.
+
+### Why they disagree
+
+The two outputs optimise for different things:
+
+- The renderer optimises for **legibility at any zoom** — small, crisp shapes that don't dominate the document.
+- The hit-tester optimises for **Fitts'-law reach** — fat targets, virtual regions outside the visible shape, priority ladders that resolve overlap by intent rather than topology.
+
+Collapsing them — drawing a 16 px knob just to match the 16 px hit AABB, or shrinking the hit AABB to 8 px just to match the visual — breaks one of the two. The split exists so neither has to compromise.
+
+### `OverlayElement` — the pairing primitive
+
+`OverlayElement` is the public type that holds the discipline together. Each element carries a mandatory `hit` and an _optional_ `render`. Hit is required because every overlay must be reachable; render is optional because some overlays are deliberately invisible.
+
+The renderer never reads from `hit`. The hit-tester never reads from `render`. The asymmetry is the point.
+
+### Four families of overlay
+
+The mental model the package operates under. Every overlay the HUD draws — or the next one anyone adds — falls into one of four shapes:
+
+| Family          | Visual            | Hit region                               | Example                              |
+| --------------- | ----------------- | ---------------------------------------- | ------------------------------------ |
+| **Paired**      | Drawn shape       | Same shape, padded for reach             | Corner resize knob, line endpoint    |
+| **Virtual**     | None              | Region the user can click but never sees | Rotation handles, edge-resize strips |
+| **Decorative**  | Drawn shape       | None                                     | Snap pips, measurement labels        |
+| **Body-region** | Selection outline | Inner region that triggers translate     | Selected shape body                  |
+
+Anything new the HUD learns to do should be a deliberate choice between these — not a side effect of how it happened to be drawn.
+
+### Guidance for new affordances
+
+1. **Decide hit geometry first, visual second.** The user reaches for the hit region; the visual is a hint about where it is.
+2. **If an affordance is virtual, omit `render`.** Don't draw a stand-in just because the type allows it.
+3. **If the visual is smaller than the minimum comfortable touch target, pad the hit region.** Don't pad the visual to compensate.
+
+### Guidance for tests
+
+Tests should assert against `hit` and `render` separately. A test that only checks the rendered shape silently passes when someone removes the hit padding; a test that only checks the hit region silently passes when someone drops the visual.
+
+New affordances should add at least one assertion per side, and — where the two intentionally differ — one assertion that they differ in the expected direction (e.g. `hit` strictly contains the `render` bbox).
+
 ## Public API
 
 ```ts
@@ -96,6 +142,7 @@ surface.setTransform(t);    // camera (screen ↔ doc)
 surface.setSelection(ids);  // read-only mirror from host
 surface.setStyle(partial);
 surface.setReadonly(v);
+surface.setPixelGrid({ enabled, zoomThreshold, color?, steps? }); // or null to disable
 surface.dispose();
 
 // Input
@@ -156,8 +203,21 @@ type SurfaceGesture =
   | { 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 };
+  | {
+      kind: "resize";
+      ids: NodeId[];
+      direction: ResizeDirection;
+      initial_shape: SelectionShape;
+      current_shape: SelectionShape;
+    }
+  | {
+      kind: "rotate";
+      ids: NodeId[];
+      corner: RotationCorner;
+      anchor_angle: number;
+      current_angle: number;
+    }
+  | { kind: "endpoint"; id: NodeId; endpoint: "p1" | "p2" };
 ```
 
 ### Intents
@@ -171,12 +231,29 @@ type Intent =
   | { kind: "translate"; ids: NodeId[]; dx: number; dy: number; phase: Phase }
   | {
       kind: "resize";
-      id: NodeId;
+      ids: NodeId[];
       anchor: ResizeDirection;
+      /** AABB of the new shape (for axis-aligned hosts). */
       rect: Rect;
+      /** Full new shape — `transformed` carries the matrix so rotated
+       *  hosts can resize in the local frame. Optional for backward-compat. */
+      shape?: SelectionShape;
+      phase: Phase;
+    }
+  | { kind: "rotate"; ids: NodeId[]; angle: number; phase: Phase }
+  | {
+      kind: "marquee_select";
+      rect: Rect;
+      additive: boolean;
+      phase: Phase;
+    }
+  | {
+      kind: "set_endpoint";
+      id: NodeId;
+      endpoint: "p1" | "p2";
+      pos: [number, number];
       phase: Phase;
     }
-  | { kind: "rotate"; id: NodeId; angle: number; phase: Phase }
   | { kind: "enter_content_edit"; id: NodeId }
   | { kind: "cancel_gesture" };
 
@@ -206,6 +283,28 @@ function Viewport() {
 }
 ```
 
+## Cursors
+
+The HUD owns cursor state (`SurfaceState.setCursor` → `surface.cursor()`), but **does not own cursor pixels.** The host receives a `CursorIcon` and decides what CSS `cursor:` value to apply.
+
+For hosts that want Grida's default Figma-style rotation/resize cursors — curved double-arrows for rotate, straight double-arrows for resize, both following the selection's screen-space rotation — wire the opt-in renderer from the dedicated subpath:
+
+```ts
+import { cursors } from "@grida/hud/cursors";
+
+surface.setCursorRenderer(cursors.defaultRenderer());
+```
+
+**Tree-shake invariant.** Nothing in `surface/`, `event/`, or `primitives/` may import from `cursors/`. Hosts that don't import the subpath pay zero bundle cost. Enforced by `__tests__/cursors.test.ts`.
+
+The subpath also exposes the SVG templates and the `data:` URL encoder for hosts that want to render cursor previews in sidebar UI without going through the Surface:
+
+```ts
+import { cursors } from "@grida/hud/cursors";
+const svg = cursors.templates.rotate(45); // angle in degrees
+const url = cursors.svgDataUrl(svg);
+```
+
 ## Selection intent
 
 The full classification table — every named scenario at pointer-down, what
@@ -232,7 +331,13 @@ Skim the spec before changing the classifier or its dispatch.
 - 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.
+- The UI-tier hit registry is built independently of the render path — see [Two backends: render and hit-testing](#two-backends-render-and-hit-testing).
+- `shapeOf(id)` returns a **doc-space** `SelectionShape`:
+  - `{ kind: "rect", rect }` — axis-aligned (most nodes)
+  - `{ kind: "line", p1, p2 }` — vector lines
+  - `{ kind: "transformed", local, matrix }` — anything with a non-identity 2×3 affine (rotation, skew, non-uniform scale, mirror). `local` is the artwork's local-frame AABB; `matrix` maps local → doc. Identity matrix here is byte-equivalent to `{ kind: "rect", rect: local }`.
+
+  See [Transformed selections](#transformed-selections) below for what the HUD does with the `transformed` variant.
 
 Handles are always drawn at a fixed screen-space size regardless of zoom. The primitive layer supports this via `HUDScreenRect` (see below).
 
@@ -249,6 +354,7 @@ Handles are always drawn at a fixed screen-space size regardless of zoom. The pr
 
 Layer order within a frame (back-to-front):
 
+0. Pixel grid (when enabled and `transform[0][0] > zoomThreshold`)
 1. Hover outline
 2. Selection outline
 3. Marquee rect
@@ -256,6 +362,32 @@ Layer order within a frame (back-to-front):
 5. Size meter pill
 6. Host-fed extras (always on top)
 
+## Transformed selections
+
+When a host returns `{ kind: "transformed", local, matrix }` from `shapeOf`, the HUD renders the chrome — outline, knobs, edge strips, rotation halos, size badge, dashed resize preview — in the artwork's own frame. Knobs rotate with the parent. The size badge reads `local.width × local.height`, not the AABB of the rotated rect. The cursor's `baseAngle` follows the matrix so resize/rotate arrows stay aligned with the selection's tilt.
+
+**Render** uses lazy transforms — every rotated primitive carries an optional angle field; the canvas wraps the draw call in a `translate/rotate/restore`:
+
+| Primitive       | Field                                | Effect                                                 |
+| --------------- | ------------------------------------ | ------------------------------------------------------ |
+| `HUDScreenRect` | `angle?: number` (radians, CCW)      | Rotates the rect around its screen-space center.       |
+| `HUDLine`       | `labelAngle?: number` (radians, CCW) | Rotates the label pill around its screen-space center. |
+
+**Hit-test** uses the same lazy transform via a new `HitShape` variant:
+
+```ts
+type HitShape =
+  | { kind: "screen_rect_at_doc"; anchor_doc; width; height }
+  | { kind: "screen_aabb"; rect }
+  | { kind: "screen_obb"; rect; inverse_transform }; // ← new
+```
+
+`screen_obb` carries the un-rotated zone rect (in shadow space, centered at the chrome's screen center) plus an `inverse_transform` that maps a screen-space pointer INTO shadow space. The hit-test loop applies the inverse to the pointer, then runs the usual AABB containment. **No AABB-of-rotated-corners inflation** — clicks outside the visible rotated chrome don't trigger phantom resize regions, regardless of aspect ratio or rotation. The 9-slice priority ladder operates in the same coordinate frame as the axis-aligned `rect` path, so promotion/demotion rules behave identically.
+
+The `resize` gesture operates in the local frame: `applyResize` takes a `SelectionShape` and returns a `SelectionShape`, with deltas inverse-transformed into local space for `transformed` shapes. The emitted `Intent` carries both `rect` (AABB) and `shape` (full local + matrix) so legacy axis-aligned hosts keep working while transform-aware hosts can write the new dims back into the artwork without touching the matrix.
+
+**v1 caveats.** Pure rotation is exact at every level (render, hit, gesture). Skew and non-uniform scale render correctly but use a uniform-scale fallback for handle sizing — anisotropic per-axis sizing is a follow-up.
+
 ## Primitives — what `HUDCanvas` can draw
 
 | Primitive       | Coordinate space                                       | Used by                                       |
@@ -270,6 +402,8 @@ Layer order within a frame (back-to-front):
 
 `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.
 
+Every primitive may also carry an optional semantic `group` string. The HUD package does not define the vocabulary; hosts name their own groups, assign them to surface chrome via `SurfaceOptions.groups`, and return hidden groups from `SurfaceOptions.visibility`. Groups are visibility policy, not paint order, so a host can suppress whole UI families during a gesture while leaving unrelated extras alone.
+
 ## Module layout
 
 ```
@@ -294,10 +428,15 @@ packages/grida-canvas-hud/
 │   ├── 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
+├── surface/                   # the wired class
+│   ├── surface.ts             # Surface class
+│   ├── chrome.ts              # builds HUDDraw from SurfaceState + shapeOf
+│   └── style.ts               # HUDStyle defaults + merge
+└── cursors/                   # opt-in subpath: @grida/hud/cursors
+    ├── index.ts               # cursors.defaultRenderer(), templates, encoder
+    ├── renderer.ts            # CursorIcon → CSS cursor: with rotation-aware SVGs
+    ├── templates.ts           # parameterized SVG cursor templates
+    └── encode.ts              # SVG → data: URL
 ```
 
 ## Naming conventions
@@ -311,19 +450,46 @@ packages/grida-canvas-hud/
 
 `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              |
+| 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                                   |
+| `chrome-transformed.test.ts` | `SelectionShape.transformed` end-to-end: outline, knob anchors, OBB hit-test exactness, identity ≡ rect equivalence    |
+| `cursors.test.ts`            | `cursors.defaultRenderer` produces rotation-aware CSS values; tree-shake invariant (subpath isolated from main bundle) |
+| `decision.test.ts`           | one test per named scenario in the selection-intent classifier                                                         |
 
 Render output (visual canvas correctness) is verified in the browser, not unit-tested.
 
+## Extending the HUD
+
+The HUD intentionally exposes no generic "register a painter" or "register a
+layer" API (see Anti-goals — "Not a host of plugins"). Three paths cover real
+needs, in this order of preference:
+
+1. **Named built-in chrome.** Things every Grida editor wants — pixel grid,
+   selection, snap guides, measurement — live inside this package as
+   first-class features with their own toggles (e.g. `setPixelGrid`,
+   `setStyle`, the chrome built from `SurfaceState`). New canonical chrome
+   lands here; open a PR against `@grida/hud`.
+
+2. **Host-fed `HUDDraw` extras.** Pass extra primitives into `surface.draw(extra)`
+   per frame. Best for transient, gesture-coupled overlays the host already
+   computes (measurement lines, custom snap visualizers). Drawn on top of named
+   chrome — they're foreground, not background.
+
+3. **DOM-level escape hatch.** The host owns the container element; the surface
+   only inserts the SVG and the HUD canvas. Hosts that need a non-canvas overlay
+   (HTML toolbar, popover, debug widget) can splice their own DOM into the
+   container directly. Deliberate escape hatch — reach for it only when (1) and
+   (2) don't fit, and prefer pushing canonical needs into (1) over keeping them
+   here.
+
 ## Anti-goals
 
 - **Not a renderer.** `primitives/HUDCanvas` is intentionally minimal Canvas2D. Skia / WebGL backends are not in scope.

package/dist/cursor-BFGUuD2M.d.mts

@@ -0,0 +1,64 @@
+//#region event/cursor.d.ts
+/** 8 cardinal/diagonal resize directions. */
+type ResizeDirection = "n" | "ne" | "e" | "se" | "s" | "sw" | "w" | "nw";
+/** 4 corner positions for rotation handles. */
+type RotationCorner = "nw" | "ne" | "se" | "sw";
+/**
+ * Logical cursor icon names — the host maps these to CSS `cursor` values.
+ *
+ * `baseAngle` (radians) tilts the rendered arrow by an additional amount
+ * on top of the variant's canonical orientation. Set automatically by the
+ * surface for both variants:
+ *
+ * - **rotate**: `decideIdleCursor` reads the action's `initial_shape`
+ *   and sets `baseAngle` to the matrix's screen-space rotation; the
+ *   in-gesture `pointer_move` arm composes `initial_cursor_angle + delta`
+ *   so the cursor tracks the live rotation, starting from the selection's
+ *   pre-gesture orientation rather than 0.
+ * - **resize**: `decideIdleCursor` reads the action's `initial_shape`
+ *   and sets `baseAngle` to the matrix's screen-space rotation, so the
+ *   resize cursor on a rotated selection tilts to align with the rotated
+ *   edge / corner.
+ *
+ * For `kind: "rect"` selections (the common case) `baseAngle` resolves
+ * to 0 and the cursor behaves identically to the pre-rotation builds.
+ */
+type CursorIcon = "default" | "pointer" | "move" | "crosshair" | "grab" | "grabbing" | "text" | {
+  kind: "resize";
+  direction: ResizeDirection;
+  baseAngle?: number;
+} | {
+  kind: "rotate";
+  corner: RotationCorner;
+  baseAngle?: number;
+};
+/**
+ * Pluggable cursor renderer.
+ *
+ * Maps a logical `CursorIcon` to a complete CSS `cursor:` value
+ * (e.g. a native keyword like `"crosshair"` or a data-URL form like
+ * `"url(data:...) 12 12, auto"`).
+ *
+ * The Surface owns one slot. Default = the built-in `cursorToCss` below.
+ * Hosts opt into the bundled SVG renderer via
+ * `surface.setCursorRenderer(cursors.defaultRenderer())` from
+ * `@grida/hud/cursors`, or supply their own function for full control.
+ */
+type CursorRenderer = (icon: CursorIcon) => string;
+/**
+ * Map a `CursorIcon` to the standard CSS `cursor` value. Hosts can override
+ * for custom cursors.
+ */
+declare function cursorToCss(c: CursorIcon): string;
+/**
+ * Cursor-equality used to detect changes without re-emitting `cursorChanged`.
+ *
+ * Two rotate/resize icons compare equal only when both the
+ * discriminator (corner / direction) AND the bucketed `baseAngle` match.
+ * This is what lets the state machine call `setCursor` every frame
+ * during a rotate gesture and have `cursorChanged` fire only on real
+ * angle changes (≥ `CURSOR_ANGLE_BUCKET_RAD` of motion).
+ */
+declare function cursorEquals(a: CursorIcon, b: CursorIcon): boolean;
+//#endregion
+export { cursorEquals as a, RotationCorner as i, CursorRenderer as n, cursorToCss as o, ResizeDirection as r, CursorIcon as t };

package/dist/cursor-BieMVb71.mjs

@@ -0,0 +1,57 @@
+//#region event/cursor.ts
+/**
+* Angle-comparison bucket — radians. 0.5° in radians. Two icons are
+* considered equal when their `baseAngle`s round to the same bucket;
+* this is what prevents unnecessary `cursorChanged` re-emit during a
+* smooth rotate gesture, so the host repaints only on real motion.
+*
+* 0.5° is below human perception for cursor orientation, so the
+* quantization is visually free.
+*/
+const CURSOR_ANGLE_BUCKET_RAD = Math.PI / 360;
+/**
+* Quantize an angle (radians) to its `CURSOR_ANGLE_BUCKET_RAD` bucket.
+* Used by `cursorEquals` to decide whether two cursors with the same
+* variant differ visibly.
+*/
+function angleBucket(rad) {
+	if (rad === void 0 || rad === 0) return 0;
+	return Math.round(rad / CURSOR_ANGLE_BUCKET_RAD);
+}
+/**
+* Map a `CursorIcon` to the standard CSS `cursor` value. Hosts can override
+* for custom cursors.
+*/
+function cursorToCss(c) {
+	if (typeof c === "string") switch (c) {
+		case "default": return "default";
+		case "pointer": return "pointer";
+		case "move": return "move";
+		case "crosshair": return "crosshair";
+		case "grab": return "grab";
+		case "grabbing": return "grabbing";
+		case "text": return "text";
+	}
+	if (c.kind === "resize") return `${c.direction}-resize`;
+	return "crosshair";
+}
+/**
+* Cursor-equality used to detect changes without re-emitting `cursorChanged`.
+*
+* Two rotate/resize icons compare equal only when both the
+* discriminator (corner / direction) AND the bucketed `baseAngle` match.
+* This is what lets the state machine call `setCursor` every frame
+* during a rotate gesture and have `cursorChanged` fire only on real
+* angle changes (≥ `CURSOR_ANGLE_BUCKET_RAD` of motion).
+*/
+function cursorEquals(a, b) {
+	if (typeof a === "string" && typeof b === "string") return a === b;
+	if (typeof a !== "string" && typeof b !== "string") {
+		if (a.kind === "resize" && b.kind === "resize") return a.direction === b.direction && angleBucket(a.baseAngle) === angleBucket(b.baseAngle);
+		if (a.kind === "rotate" && b.kind === "rotate") return a.corner === b.corner && angleBucket(a.baseAngle) === angleBucket(b.baseAngle);
+		return false;
+	}
+	return false;
+}
+//#endregion
+export { cursorToCss as i, angleBucket as n, cursorEquals as r, CURSOR_ANGLE_BUCKET_RAD as t };

package/dist/cursor-CIYvFshz.d.ts

@@ -0,0 +1,64 @@
+//#region event/cursor.d.ts
+/** 8 cardinal/diagonal resize directions. */
+type ResizeDirection = "n" | "ne" | "e" | "se" | "s" | "sw" | "w" | "nw";
+/** 4 corner positions for rotation handles. */
+type RotationCorner = "nw" | "ne" | "se" | "sw";
+/**
+ * Logical cursor icon names — the host maps these to CSS `cursor` values.
+ *
+ * `baseAngle` (radians) tilts the rendered arrow by an additional amount
+ * on top of the variant's canonical orientation. Set automatically by the
+ * surface for both variants:
+ *
+ * - **rotate**: `decideIdleCursor` reads the action's `initial_shape`
+ *   and sets `baseAngle` to the matrix's screen-space rotation; the
+ *   in-gesture `pointer_move` arm composes `initial_cursor_angle + delta`
+ *   so the cursor tracks the live rotation, starting from the selection's
+ *   pre-gesture orientation rather than 0.
+ * - **resize**: `decideIdleCursor` reads the action's `initial_shape`
+ *   and sets `baseAngle` to the matrix's screen-space rotation, so the
+ *   resize cursor on a rotated selection tilts to align with the rotated
+ *   edge / corner.
+ *
+ * For `kind: "rect"` selections (the common case) `baseAngle` resolves
+ * to 0 and the cursor behaves identically to the pre-rotation builds.
+ */
+type CursorIcon = "default" | "pointer" | "move" | "crosshair" | "grab" | "grabbing" | "text" | {
+  kind: "resize";
+  direction: ResizeDirection;
+  baseAngle?: number;
+} | {
+  kind: "rotate";
+  corner: RotationCorner;
+  baseAngle?: number;
+};
+/**
+ * Pluggable cursor renderer.
+ *
+ * Maps a logical `CursorIcon` to a complete CSS `cursor:` value
+ * (e.g. a native keyword like `"crosshair"` or a data-URL form like
+ * `"url(data:...) 12 12, auto"`).
+ *
+ * The Surface owns one slot. Default = the built-in `cursorToCss` below.
+ * Hosts opt into the bundled SVG renderer via
+ * `surface.setCursorRenderer(cursors.defaultRenderer())` from
+ * `@grida/hud/cursors`, or supply their own function for full control.
+ */
+type CursorRenderer = (icon: CursorIcon) => string;
+/**
+ * Map a `CursorIcon` to the standard CSS `cursor` value. Hosts can override
+ * for custom cursors.
+ */
+declare function cursorToCss(c: CursorIcon): string;
+/**
+ * Cursor-equality used to detect changes without re-emitting `cursorChanged`.
+ *
+ * Two rotate/resize icons compare equal only when both the
+ * discriminator (corner / direction) AND the bucketed `baseAngle` match.
+ * This is what lets the state machine call `setCursor` every frame
+ * during a rotate gesture and have `cursorChanged` fire only on real
+ * angle changes (≥ `CURSOR_ANGLE_BUCKET_RAD` of motion).
+ */
+declare function cursorEquals(a: CursorIcon, b: CursorIcon): boolean;
+//#endregion
+export { cursorEquals as a, RotationCorner as i, CursorRenderer as n, cursorToCss as o, ResizeDirection as r, CursorIcon as t };

package/dist/cursor-DsP9qtN2.js

@@ -0,0 +1,80 @@
+//#region event/cursor.ts
+/**
+* Angle-comparison bucket — radians. 0.5° in radians. Two icons are
+* considered equal when their `baseAngle`s round to the same bucket;
+* this is what prevents unnecessary `cursorChanged` re-emit during a
+* smooth rotate gesture, so the host repaints only on real motion.
+*
+* 0.5° is below human perception for cursor orientation, so the
+* quantization is visually free.
+*/
+const CURSOR_ANGLE_BUCKET_RAD = Math.PI / 360;
+/**
+* Quantize an angle (radians) to its `CURSOR_ANGLE_BUCKET_RAD` bucket.
+* Used by `cursorEquals` to decide whether two cursors with the same
+* variant differ visibly.
+*/
+function angleBucket(rad) {
+	if (rad === void 0 || rad === 0) return 0;
+	return Math.round(rad / CURSOR_ANGLE_BUCKET_RAD);
+}
+/**
+* Map a `CursorIcon` to the standard CSS `cursor` value. Hosts can override
+* for custom cursors.
+*/
+function cursorToCss(c) {
+	if (typeof c === "string") switch (c) {
+		case "default": return "default";
+		case "pointer": return "pointer";
+		case "move": return "move";
+		case "crosshair": return "crosshair";
+		case "grab": return "grab";
+		case "grabbing": return "grabbing";
+		case "text": return "text";
+	}
+	if (c.kind === "resize") return `${c.direction}-resize`;
+	return "crosshair";
+}
+/**
+* Cursor-equality used to detect changes without re-emitting `cursorChanged`.
+*
+* Two rotate/resize icons compare equal only when both the
+* discriminator (corner / direction) AND the bucketed `baseAngle` match.
+* This is what lets the state machine call `setCursor` every frame
+* during a rotate gesture and have `cursorChanged` fire only on real
+* angle changes (≥ `CURSOR_ANGLE_BUCKET_RAD` of motion).
+*/
+function cursorEquals(a, b) {
+	if (typeof a === "string" && typeof b === "string") return a === b;
+	if (typeof a !== "string" && typeof b !== "string") {
+		if (a.kind === "resize" && b.kind === "resize") return a.direction === b.direction && angleBucket(a.baseAngle) === angleBucket(b.baseAngle);
+		if (a.kind === "rotate" && b.kind === "rotate") return a.corner === b.corner && angleBucket(a.baseAngle) === angleBucket(b.baseAngle);
+		return false;
+	}
+	return false;
+}
+//#endregion
+Object.defineProperty(exports, "CURSOR_ANGLE_BUCKET_RAD", {
+	enumerable: true,
+	get: function() {
+		return CURSOR_ANGLE_BUCKET_RAD;
+	}
+});
+Object.defineProperty(exports, "angleBucket", {
+	enumerable: true,
+	get: function() {
+		return angleBucket;
+	}
+});
+Object.defineProperty(exports, "cursorEquals", {
+	enumerable: true,
+	get: function() {
+		return cursorEquals;
+	}
+});
+Object.defineProperty(exports, "cursorToCss", {
+	enumerable: true,
+	get: function() {
+		return cursorToCss;
+	}
+});

package/dist/cursors/index.d.mts

@@ -0,0 +1,98 @@
+import { n as CursorRenderer } from "../cursor-BFGUuD2M.mjs";
+
+//#region cursors/renderer.d.ts
+/**
+ * Build the default cursor renderer.
+ *
+ * Stateless — every call regenerates the data URL from scratch. This is
+ * cheap (`template_*` is a string-concat, `btoa` of ~600 B is
+ * sub-millisecond) AND the upstream `SurfaceState.setCursor` already
+ * gates re-emit via `cursorEquals`, which buckets `baseAngle` to
+ * `CURSOR_ANGLE_BUCKET_RAD`. Net result: this function is invoked at
+ * most once per real bucket change — caching here would be redundant
+ * and, sized wrong (the previous 64-entry LRU thrashed after ~32° of
+ * drag), actively harmful.
+ *
+ * Hosts install via `surface.setCursorRenderer(...)`.
+ *
+ * @example
+ *   import { cursors } from "@grida/hud/cursors";
+ *   surface.setCursorRenderer(cursors.defaultRenderer());
+ */
+declare function defaultRenderer(): CursorRenderer;
+//#endregion
+//#region cursors/encode.d.ts
+/**
+ * SVG → `data:` URL encoding for CSS `cursor:` values.
+ *
+ * Uses base64 (`btoa`) for two reasons:
+ * - Cross-browser support is universal; URL-encoded SVG has historically had
+ *   parser inconsistencies on `#` and `<`.
+ * - It's what the main editor's `cursor-data.ts` uses, so cursor visuals
+ *   compare byte-identical when we A/B during the eventual migration.
+ *
+ * Browser-only — `btoa` is part of the WHATWG HTML spec, available on
+ * Worker / Window. The package's `platform: "neutral"` tsdown config means
+ * we don't pull a Node polyfill; consumers using SSR must avoid evaluating
+ * the renderer on the server (the Surface itself is client-side).
+ */
+/** Encode an SVG string as `data:image/svg+xml;base64,...`. */
+declare function svgDataUrl(svg: string): string;
+//#endregion
+//#region cursors/templates.d.ts
+/**
+ * SVG cursor templates — pure string templates parameterized by angle.
+ *
+ * Two families:
+ *
+ * 1. **Rotate arrow** — a curved double-arrow. Built from one template
+ *    (`template_rotate`) rotated by `angle_deg` around the SVG's
+ *    hotspot. Per-corner orientation comes from caller-supplied
+ *    initial offsets (NW: −45°, NE: +45°, SW: −135°, SE: +135°), in
+ *    Phase A. In Phase B, the host's selection rotation is added on
+ *    top of that.
+ *
+ * 2. **Resize arrow** — a straight double-arrow, also built from one
+ *    template (`template_resize`) rotated per cardinal direction. The
+ *    8 standard directions (N/NE/E/SE/S/SW/W/NW) map to multiples of
+ *    45° from the canonical horizontal arrow.
+ *
+ * **Fixed Grida palette** — black fill, white stroke. Cursors are not
+ * color-themed; hosts wanting custom colors install a custom
+ * `CursorRenderer` (see `renderer.ts`).
+ *
+ * **Hotspots** are documented per template — the click point inside
+ * the SVG that the OS aligns with the actual pointer position. Hotspots
+ * are fixed (SVG center) because the SVG rotates around the same point;
+ * the cursor stays anchored to the pointer regardless of angle.
+ */
+/** Rotate cursor SVG. `angle_deg` rotates the arrow around (13, 12). */
+declare function template_rotate(angle_deg: number): string;
+/**
+ * Resize cursor SVG. `angle_deg` rotates the arrow around (16, 16).
+ *
+ * For the canonical horizontal arrow pass `0`. For the 8 standard
+ * cardinal directions, see `DIRECTION_ANGLE_DEG` in `renderer.ts`.
+ */
+declare function template_resize(angle_deg: number): string;
+//#endregion
+//#region cursors/index.d.ts
+/**
+ * Convenience namespace export. All cursor utilities are also available
+ * as named imports — but `cursors.defaultRenderer()` reads more cleanly
+ * at host call sites, mirroring the main editor's `cursors.*` style.
+ */
+declare const cursors: {
+  readonly defaultRenderer: typeof defaultRenderer;
+  readonly svgDataUrl: typeof svgDataUrl;
+  readonly templates: {
+    readonly rotate: typeof template_rotate;
+    readonly resize: typeof template_resize;
+  };
+  readonly hotspots: {
+    readonly rotate: readonly [number, number];
+    readonly resize: readonly [number, number];
+  };
+};
+//#endregion
+export { type CursorRenderer, cursors, defaultRenderer, svgDataUrl };