@grida/hud 0.2.0 → 0.2.1

package/dist/index-Cmbe2X5b.d.mts

@@ -0,0 +1,3140 @@
+import { a as HUDPaintStripes, f as HUDSemanticGroup, r as HUDPaint, t as HUDDraw } from "./types-3wwFisZs.mjs";
+import { i as RotationCorner, n as CursorRenderer, r as ResizeDirection, t as CursorIcon } from "./cursor-CxS8EMvm.mjs";
+import cmath from "@grida/cmath";
+import { Measurement } from "@grida/cmath/_measurement";
+import { guide } from "@grida/cmath/_snap";
+
+//#region primitives/pixel-grid.d.ts
+declare const DEFAULT_PIXEL_GRID_COLOR = "rgba(150, 150, 150, 0.15)";
+declare const DEFAULT_PIXEL_GRID_STEPS: [number, number];
+interface PixelGridConfig {
+  enabled: boolean;
+  /** Minimum `transform[0][0]` (uniform scale) at which the grid renders. */
+  zoomThreshold: number;
+  /**
+   * Optional camera transform used to space the grid. Hosts that drive the
+   * HUD canvas's own `setTransform` can omit this — the pixel grid falls
+   * back to the canvas's chrome transform. Hosts that keep the HUD at
+   * identity (applying the camera elsewhere — e.g. as a CSS transform on
+   * an outer element) must supply this explicitly and update it on every
+   * camera change via `setPixelGridTransform`.
+   */
+  transform?: cmath.Transform;
+  color?: string;
+  steps?: [number, number];
+}
+interface DrawPixelGridParams {
+  ctx: CanvasRenderingContext2D;
+  transform: cmath.Transform;
+  width: number;
+  height: number;
+  dpr: number;
+  color?: string;
+  steps?: [number, number];
+}
+declare function drawPixelGrid(p: DrawPixelGridParams): void;
+//#endregion
+//#region primitives/ruler.d.ts
+type RulerAxis = "x" | "y";
+/**
+ * Width (in CSS pixels) of the strip the top ruler occupies along the
+ * top edge of the viewport, and equivalently the width of the strip the
+ * left ruler occupies along the left edge. Same value for both so the
+ * corner clip is square — change one and the L-shape stops aligning.
+ */
+declare const DEFAULT_RULER_STRIP = 20;
+declare const DEFAULT_RULER_TICK_HEIGHT = 6;
+declare const DEFAULT_RULER_OVERLAP_THRESHOLD = 80;
+declare const DEFAULT_RULER_TEXT_SIDE_OFFSET = 12;
+declare const DEFAULT_RULER_FONT = "10px sans-serif";
+declare const DEFAULT_RULER_COLOR = "rgba(128, 128, 128, 0.5)";
+declare const DEFAULT_RULER_ACCENT_BACKGROUND = "rgba(80, 200, 255, 0.25)";
+declare const DEFAULT_RULER_ACCENT_COLOR = "rgba(80, 200, 255, 1)";
+declare const DEFAULT_RULER_BACKGROUND = "transparent";
+declare const DEFAULT_RULER_STEPS: readonly number[];
+/**
+ * Recommended drag distance threshold (in CSS pixels) for the ruler's
+ * create-guide gesture. Hosts implementing drag-from-strip should not
+ * commit a new guide until the pointer has moved this far from
+ * pointer-down — without it, a stray click on the strip creates an
+ * unwanted guide.
+ *
+ * Threshold-only — hud does not own the gesture. It owns the value
+ * because the value is a property of the ruler chrome's UX, not of
+ * any particular host's gesture pipeline.
+ */
+declare const DEFAULT_RULER_DRAG_THRESHOLD = 4;
+type RulerRange = [a: number, b: number];
+/**
+ * A priority mark on a ruler strip — typically a guide position the host
+ * wants the user to see at all zooms, regardless of where the regular
+ * step ticks land.
+ *
+ * With only `pos` set, the mark renders identically to a regular step
+ * tick — short stroke at `tickHeight`, label color = `color`. The extra
+ * fields below let a consumer render a mark as a full-strip line with
+ * an accent stroke + label color — the standard guide-position
+ * affordance every editor ships:
+ *
+ * ```ts
+ * { pos: 120, strokeHeight: strip, strokeColor: red, color: red, text: "120" }
+ * ```
+ *
+ * Defaults are chosen so an existing minimal `{ pos }` mark keeps
+ * rendering exactly as before. All extra fields are optional.
+ */
+interface RulerMark {
+  pos: number;
+  /** Tick stroke + (default) label color. */
+  color?: string;
+  /** Label text. */
+  text?: string;
+  /** Override the stroke color independently of the label color. */
+  strokeColor?: string;
+  /** Stroke width in CSS pixels. Default 1. */
+  strokeWidth?: number;
+  /**
+   * Stroke height in CSS pixels. Default `tickHeight`. Pass `strip`
+   * (the strip width) for a full-strip mark — the standard
+   * guide-position affordance.
+   */
+  strokeHeight?: number;
+  /** Label color. Defaults to `color` if omitted. */
+  textColor?: string;
+  /** Label alignment. Default "center". */
+  textAlign?: CanvasTextAlign;
+  /** Label position offset from `pos`. Default 0. */
+  textAlignOffset?: number;
+}
+/**
+ * Public config for the back-most ruler chrome.
+ *
+ * The HUD draws both axes in one pass: a horizontal strip across the top
+ * edge and a vertical strip down the left edge, with the corner square
+ * left blank. This is the L-shape every editor ruler ships.
+ *
+ * Coordinate model: identical to `PixelGridConfig` — `transform` is the
+ * camera (screen ↔ doc). If omitted, the HUD's chrome transform is used.
+ * Hosts that drive the HUD canvas at identity (e.g. the camera is on the
+ * underlying SVG/canvas) MUST supply this and update it on camera change
+ * via `setRulerTransform`.
+ */
+interface RulerConfig {
+  enabled: boolean;
+  /** Optional camera transform. See `PixelGridConfig.transform` for the
+   *  two-transform contract. */
+  transform?: cmath.Transform;
+  /** Which axes to render. Default both. */
+  axes?: readonly RulerAxis[];
+  /** Strip width in CSS pixels. Default {@link DEFAULT_RULER_STRIP}. */
+  strip?: number;
+  /** Tick line height in CSS pixels. */
+  tickHeight?: number;
+  /** Ranges to highlight (in doc-space units), per axis. */
+  ranges?: {
+    x?: readonly RulerRange[];
+    y?: readonly RulerRange[];
+  };
+  /** Priority marks (in doc-space units), per axis. */
+  marks?: {
+    x?: readonly RulerMark[];
+    y?: readonly RulerMark[];
+  };
+  /** Minimum tick spacing in screen px before ticks fade near priority points. */
+  overlapThreshold?: number;
+  /** Offset from the strip edge for the label text. */
+  textSideOffset?: number;
+  /** Label font. */
+  font?: string;
+  /** Background fill for the ruler strip. */
+  backgroundColor?: string;
+  /** Tick + label color. */
+  color?: string;
+  /**
+   * Color of the 1-px inner-edge separator (the line where the strip
+   * meets the editing area). Defaults to `color` — the tick color —
+   * so existing consumers don't regress.
+   *
+   * Every production editor (Figma, Sketch, XD, Illustrator, Affinity)
+   * paints this line distinctly LIGHTER than the ticks. With shared
+   * color the host has to choose: ticks readable but separator looks
+   * like a heavy underline, OR separator correct but ticks too faint.
+   * Pass a lighter value here to match the universal convention; e.g.
+   * the OKLCH `border` token most design systems already define.
+   *
+   * The separator field is decoupled from `color` precisely because
+   * the two responsibilities (read-the-number vs. mark-the-edge) want
+   * different weights, and no single token gets both right.
+   */
+  borderColor?: string;
+  /** Range fill color. */
+  accentBackgroundColor?: string;
+  /** Range label / boundary color. */
+  accentColor?: string;
+  /** Custom step series, e.g. for non-decimal units. */
+  steps?: readonly number[];
+  /**
+   * Subdivisions between major ticks. See `@grida/ruler` for the heuristic.
+   * - `false` / `0`: no subticks (default)
+   * - `true` / `"auto"`: 1-2-5 heuristic
+   * - `number`: fixed subdivision count
+   */
+  subticks?: false | true | "auto" | number;
+  /** Subtick line height. Defaults to `round(tickHeight * 0.4)`. */
+  subtickHeight?: number;
+  /** Subtick color. Defaults to `color`. */
+  subtickColor?: string;
+}
+interface DrawRulerParams {
+  ctx: CanvasRenderingContext2D;
+  transform: cmath.Transform;
+  /** Viewport width in CSS pixels. */
+  width: number;
+  /** Viewport height in CSS pixels. */
+  height: number;
+  /** Device pixel ratio of the canvas. */
+  dpr: number;
+  config: RulerConfig;
+}
+/**
+ * Paint the L-shape ruler chrome (top + left strips) into the canvas
+ * context. Stateless: every call clears and redraws the strips in
+ * screen-space.
+ *
+ * The function assumes the caller has reset the ctx transform to identity
+ * for the device pixel scale; it applies `dpr` itself via `setTransform`.
+ *
+ * The corner square (`strip × strip` at origin) is deliberately left
+ * blank — neither axis is in charge of it. Hosts that want a corner fill
+ * draw it as a host-fed extra above the HUD.
+ */
+declare function drawRuler(p: DrawRulerParams): void;
+//#endregion
+//#region primitives/transform-box.d.ts
+/**
+ * 2×3 affine transform. Structurally compatible with `AffineTransform`
+ * from `@grida/cg` — the HUD package keeps a local alias to avoid
+ * acquiring a `@grida/cg` workspace dep just for the type.
+ */
+type AffineTransform = [[number, number, number], [number, number, number]];
+type TransformBoxAction = {
+  type: "translate";
+  delta: cmath.Vector2;
+} | {
+  type: "scale-side";
+  side: cmath.RectangleSide;
+  delta: cmath.Vector2;
+} | {
+  type: "rotate";
+  corner: cmath.IntercardinalDirection;
+  delta: cmath.Vector2;
+};
+interface TransformBoxOptions {
+  size: cmath.Vector2;
+}
+type TransformBoxCorners = {
+  nw: cmath.Vector2;
+  ne: cmath.Vector2;
+  se: cmath.Vector2;
+  sw: cmath.Vector2;
+};
+/**
+ * Reduces a transform-box affine in response to a UI action.
+ */
+declare function reduceTransformBox(base: AffineTransform, action: TransformBoxAction, options: TransformBoxOptions): AffineTransform;
+/**
+ * Given a transform-box matrix and the box size, returns the four
+ * transformed corners in pixel space.
+ *
+ *   Each corner = transform * box_corner
+ */
+declare function getTransformBoxCorners(transform: AffineTransform, size: cmath.Vector2): TransformBoxCorners;
+/**
+ * Decomposes an affine transform into rotation (deg), scale [sx, sy],
+ * and translation [tx, ty] components.
+ */
+declare function decompose(transform: AffineTransform): {
+  rotation: number;
+  scale: cmath.Vector2;
+  translation: cmath.Vector2;
+};
+/**
+ * Composes rotation (deg), scale, and translation into an affine
+ * transform, anchored so the supplied `center` is preserved.
+ */
+declare function compose(rotation: number, scale: cmath.Vector2, translation: cmath.Vector2, center: cmath.Vector2): AffineTransform;
+/**
+ * Convert pixel-space corners back to a box-relative transform.
+ */
+declare function cornersToBoxTransform(corners: TransformBoxCorners, size: cmath.Vector2): AffineTransform;
+//#endregion
+//#region event/shape.d.ts
+/**
+ * Selection shape — what the chrome wraps.
+ *
+ * Hosts return a `SelectionShape` from `shapeOf(id)` so the HUD can lay out
+ * the right kind of chrome:
+ *
+ * - **`rect`** — standard bounding box. Renders selection outline + 4 corner
+ *   knobs, with virtual edge / rotation hit regions.
+ * - **`transformed`** — an axis-aligned local bbox PLUS a 2×3 affine matrix
+ *   mapping local-frame points into doc-space. Covers rotation, skew,
+ *   non-uniform scale, and mirror with one code path. `local.width × local.height`
+ *   are the artwork's true dims (read by the size badge and by `applyResize`
+ *   in local space). Identity matrix here is byte-equivalent to
+ *   `{ kind: "rect", rect: local }`.
+ * - **`line`** — two-endpoint primitive (e.g. SVG `<line>`). Renders the
+ *   line segment + 2 endpoint knobs. No edge / rotation regions.
+ * - **`unresolved`** — internal-only. Used inside `SelectionGroup` when the
+ *   host gave a flat `NodeId[]` to `setSelection` — the chrome builder
+ *   resolves the real shape by calling `shapeOf(id)` at frame build time.
+ *   Hosts never emit this; treating it as host-facing would be a bug.
+ *
+ * Future kinds (e.g. `polyline`, `ellipse_oriented`) can be added without
+ * breaking the existing kinds — the chrome builder branches on `kind`.
+ */
+type SelectionShape = {
+  kind: "rect";
+  rect: Rect;
+} | {
+  kind: "transformed"; /** Local-frame AABB; width/height are artwork's true dims. */
+  local: Rect; /** 2×3 affine mapping local-frame points → doc-space. */
+  matrix: cmath.Transform;
+} | {
+  kind: "line";
+  p1: cmath.Vector2;
+  p2: cmath.Vector2;
+} | {
+  kind: "unresolved";
+  id: string;
+};
+/**
+ * A logical selection group. The HUD renders one chrome instance per group.
+ *
+ * The host pre-computes `shape` (typically the union of member bounds for
+ * multi-node groups). Member `ids` are the gesture target — they all
+ * translate/resize together as a unit.
+ */
+interface SelectionGroup {
+  ids: readonly NodeId[];
+  shape: SelectionShape;
+}
+//#endregion
+//#region event/gesture.d.ts
+/**
+ * Rect type local to the event/ layer.
+ *
+ * Mirrors `cmath.Rectangle` shape; declared here to keep `event/` free of
+ * imports beyond `cmath` types.
+ */
+interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+type NodeId = string;
+/**
+ * Active interaction state for the surface.
+ *
+ * Coordinates inside each variant are documented per-field. The surface
+ * stores anchor points in document-space (so they survive camera pans during
+ * a gesture); incremental deltas are computed against the anchor each move.
+ */
+type SurfaceGesture = {
+  kind: "idle";
+} | {
+  kind: "pan"; /** Last screen-space pointer position. */
+  prev_screen: cmath.Vector2;
+} | {
+  kind: "marquee"; /** Anchor (pointer-down) in document-space. */
+  anchor_doc: cmath.Vector2; /** Current pointer in document-space. */
+  current_doc: cmath.Vector2;
+} | {
+  /**
+   * Freeform polygon selection. Sibling to `marquee` — empty-space drag
+   * promotes here when the host has set the surface's
+   * `vectorSelectionMode` to `"lasso"`. The HUD doesn't decide which
+   * gesture to use; the host pushes the mode in alongside its tool
+   * toggle. See `Surface.setVectorSelectionMode`.
+   */
+  kind: "lasso"; /** First sample (pointer-down position in document-space). */
+  anchor_doc: cmath.Vector2;
+  /**
+   * Polyline samples in document-space, oldest-first.
+   * `points[0] === anchor_doc`. Per pointer_move samples are appended
+   * only when the rounded screen-pixel differs from the last sample,
+   * keeping growth bounded on slow drags. The host's hit-test closes
+   * the polygon implicitly (last → first) — matches
+   * `cmath.polygon.pointInPolygon`'s ray-cast.
+   */
+  points: cmath.Vector2[];
+} | {
+  kind: "translate"; /** Selected ids at the start of the gesture. */
+  ids: NodeId[]; /** Anchor (pointer-down) in document-space. */
+  anchor_doc: cmath.Vector2; /** Last reported pointer in document-space. */
+  last_doc: cmath.Vector2;
+} | {
+  kind: "resize"; /** Member ids of the group being resized (1 or more). */
+  ids: NodeId[]; /** Which handle the user grabbed. */
+  direction: ResizeDirection;
+  /**
+   * Selection shape at gesture start. For `kind: "rect"` this is the
+   * doc-space bbox; for `kind: "transformed"` it carries the local-frame
+   * AABB + matrix so resize math runs in the rotated/skewed local frame.
+   */
+  initial_shape: SelectionShape; /** Anchor (pointer-down) in document-space. */
+  anchor_doc: cmath.Vector2; /** Current shape during the gesture. Same kind as `initial_shape`. */
+  current_shape: SelectionShape;
+} | {
+  kind: "rotate";
+  ids: NodeId[];
+  corner: RotationCorner; /** Subject center in document-space. */
+  center_doc: cmath.Vector2; /** Angle at gesture start (radians). */
+  anchor_angle: number; /** Current angle (radians). */
+  current_angle: number;
+  /**
+   * Selection's screen-space rotation at gesture start (radians).
+   * Composed with `current_angle - anchor_angle` each frame to set
+   * the rotate-cursor's `baseAngle` — so cursors on already-rotated
+   * selections continue tilting correctly mid-gesture instead of
+   * snapping back to 0 + delta.
+   */
+  initial_cursor_angle: number;
+} | {
+  kind: "endpoint";
+  id: NodeId;
+  endpoint: "p1" | "p2"; /** Current endpoint position in document-space. */
+  pos_doc: cmath.Vector2;
+} | {
+  /**
+   * Dragging one or more vertices of a path under content-edit. The
+   * `indices` are captured at gesture start; intra-gesture selection
+   * mirror changes do not affect what the gesture moves.
+   */
+  kind: "translate_vertex"; /** Path node id under content-edit. */
+  node_id: NodeId; /** Vertex indices being moved. */
+  indices: number[]; /** Anchor (pointer-down) in document-space. */
+  anchor_doc: cmath.Vector2; /** Last reported pointer in document-space. */
+  last_doc: cmath.Vector2;
+} | {
+  /**
+   * Dragging the path-edit sub-selection. Triggered by segment-body
+   * drag (the default — Meta switches to `bend_segment` instead) and
+   * any future drag origin that targets the whole sub-selection
+   * (multi-vertex drag is the planned follow-up).
+   *
+   * The HUD doesn't know which vertices are in the sub-selection
+   * (host owns it). It DOES know "this gesture additionally targets
+   * these vertex indices" — e.g. the endpoints of the segment that
+   * initiated the drag, when that segment isn't yet in the
+   * sub-selection. The host UNIONs `additional_vertex_indices` with
+   * its authoritative sub-selection on each preview frame.
+   */
+  kind: "translate_vector_selection";
+  node_id: NodeId;
+  additional_vertex_indices: readonly number[];
+  anchor_doc: cmath.Vector2;
+  last_doc: cmath.Vector2;
+} | {
+  /**
+   * Dragging a tangent control point. The host applies the mirror
+   * policy (`auto` by default — infer smooth-vs-broken). The chrome
+   * builder owned the anchor; this gesture only tracks the moving
+   * end of the handle line.
+   */
+  kind: "translate_tangent";
+  node_id: NodeId;
+  tangent: readonly [number, 0 | 1];
+  /** Tangent control point's doc-space position at gesture start
+   *  (carried from chrome via `decision.pos`). */
+  anchor_doc: cmath.Vector2;
+  last_doc: cmath.Vector2;
+  /** Pointer's doc-space position at gesture start. Distinct from
+   *  `anchor_doc` because the cursor lands within the knob's Fitts'-
+   *  tolerant hit area, not pixel-perfect on the control point.
+   *  Used to detect "click-no-drag": commit is skipped when
+   *  `last_doc === down_doc`, otherwise the absolute set_tangent
+   *  would snap the control point to the cursor's down position. */
+  down_doc: cmath.Vector2;
+} | {
+  /**
+   * Bending a segment. Press-down sampled a point on the curve at
+   * parameter `ca`; drag moves that point toward `last_doc`. The
+   * host re-solves tangents on every frame. Endpoints (a, b) stay
+   * fixed for the duration of the gesture.
+   */
+  kind: "bend_segment";
+  node_id: NodeId;
+  segment: number; /** Frozen parametric position of the sampled point. */
+  ca: number;
+  anchor_doc: cmath.Vector2;
+  last_doc: cmath.Vector2;
+} | {
+  /**
+   * Dragging a corner-radius handle.
+   *
+   * For RECT geometry the gesture carries the rect AABB and the
+   * candidate-anchor set captured at pointer_down. When the user
+   * grabs a single-corner knob (sub-max radii), `candidates` has
+   * length 1 and `anchor` is set. When the user grabs a
+   * coincidence group (oblong-max pair, square-max quadruple),
+   * `candidates` has length 2+ and `anchor` is `null` until the
+   * drag crosses the threshold; the state machine resolves the
+   * anchor from drag direction AMONG `candidates` only.
+   *
+   * For LINE geometry the gesture carries `a` and `b`; the
+   * projection axis is `a → b`. `anchor` is always `null` and
+   * `candidates` is empty.
+   *
+   * The new radius is derived each frame by projecting the
+   * cursor onto the relevant axis (rect: corner →
+   * `corner + (sign_x, sign_y)`; line: `a → b`). `explicit`
+   * latches the alt modifier at gesture start — the intent kind
+   * is decided once.
+   */
+  kind: "corner_radius";
+  node_id: NodeId;
+  geometry: "rect" | "line";
+  /** RECT only — the rect AABB in LOCAL space. Used to derive
+   *  per-anchor corner positions for projection. Undefined for
+   *  line. */
+  rect?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  /** RECT only — optional local → doc transform. Threaded
+   *  through from the input so the gesture projects the cursor
+   *  along the ROTATED axis on a rotated rect. */
+  transform?: cmath.Transform;
+  /** RECT only — the candidate anchors this gesture was opened
+   *  for. Length 1 means anchor is locked at start; length 2 or
+   *  4 means anchor is `null` until threshold + direction
+   *  resolution picks one. Empty for line. */
+  candidates: readonly ("nw" | "ne" | "se" | "sw")[];
+  /** Resolved corner anchor for rect (one of `candidates`).
+   *  `null` while pre-resolution on a multi-candidate group, OR
+   *  always for line geometry. */
+  anchor: "nw" | "ne" | "se" | "sw" | null; /** LINE only — the line endpoints. Undefined for rect. */
+  a?: cmath.Vector2;
+  b?: cmath.Vector2;
+  /** Screen-space pointer-down anchor — used by the multi-
+   *  candidate threshold + direction resolution. */
+  anchor_screen: cmath.Vector2;
+  /** Doc-space pointer-down anchor — paired with `transform` to
+   *  resolve the right corner on a rotated rect. The threshold
+   *  check stays in screen-space (pixels), but the
+   *  direction-resolution dot-product compares the doc-space drag
+   *  delta (`point_doc - anchor_doc`) against the rect's
+   *  rotated-into-doc sign vectors (`T.linear · sign_local`). */
+  anchor_doc: cmath.Vector2;
+  /** Whether alt was held at pointer_down. Latches at gesture
+   *  start; intent kind is decided once. */
+  explicit: boolean; /** Most-recent doc-space pointer. */
+  last_doc: cmath.Vector2; /** Most-recent computed radius value (doc-space units). */
+  value: number;
+  /** Flips to `true` the first time `pointer_move` advances the
+   *  gesture state (resolves the anchor or updates `value`).
+   *  Pointer-up consults this to skip the commit on click-only
+   *  interactions — `value` is seeded from the inset-padded knob
+   *  position at pointer-down, so a pure click would otherwise
+   *  commit a non-zero radius the user never intended. */
+  dragged: boolean;
+} | {
+  /**
+   * Drag of a `parametric_handle` knob — opened from a
+   * `parametric_knob` overlay action and emits `parametric_handle`
+   * intents on every move + commit.
+   *
+   * When the action carries multiple `candidates` (a coincident
+   * group), `handle_id` is `null` until the drag crosses the
+   * threshold and direction-resolution picks one. `candidates`
+   * is the ordered list of (handle_id, curve, domain) tuples
+   * that hit-region stood in for.
+   *
+   * `modifiers` is the latched alt/shift state at pointer_down —
+   * intent payload reports it unchanged; host interprets.
+   */
+  kind: "parametric_handle";
+  node_id: NodeId;
+  candidates: readonly {
+    handle_id: string;
+    track_doc: cmath.ui.Curve | cmath.ui.PointSet;
+    domain: {
+      min: number;
+      max: number;
+      step?: number;
+    };
+  }[];
+  handle_id: string | null;
+  anchor_screen: cmath.Vector2;
+  modifiers: {
+    alt: boolean;
+    shift: boolean;
+  };
+  last_doc: cmath.Vector2; /** Last computed value in host units (post-step-quantization). */
+  value: number;
+  /** Flips to `true` the first time `pointer_move` advances the
+   *  gesture state (resolves the handle or updates `value`).
+   *  Pointer-up skips commit on click-only interactions because
+   *  `value` is seeded from the inset-padded knob position at
+   *  pointer-down. */
+  dragged: boolean;
+} | {
+  /**
+   * Drag of a `padding_handle` knob (padding named class). Opened
+   * eagerly from a `padding_handle` overlay action; emits
+   * `padding_handle` intents on every move + commit.
+   *
+   * `mirror` is NOT latched at gesture start — read live on each
+   * frame from `state.modifiers.alt`. Per the doctrine: "modifier
+   * change mid-gesture updates `mirror` on subsequent previews."
+   *
+   * The container `rect` and starting value are captured at
+   * pointer_down so subsequent value projection (`projectPaddingValue`)
+   * stays exact through camera moves — value math runs in doc-space
+   * against the rect snapshot, not the live geometry.
+   */
+  kind: "padding_handle";
+  node_id: NodeId;
+  side: cmath.RectangleSide; /** Container rect snapshot at gesture start (doc-space). */
+  rect: Rect; /** Initial padding value at gesture start (doc-space units). */
+  initial_value: number; /** Most-recent doc-space pointer. */
+  last_doc: cmath.Vector2; /** Most-recent computed value (doc-space units, clamped to [0, max]). */
+  value: number;
+  /** Flips to `true` the first time `pointer_move` advances the
+   *  gesture state. Pointer-up skips commit on click-only
+   *  interactions — `value === initial_value` on first frame. */
+  dragged: boolean;
+} | {
+  /**
+   * Drag of a transform-box handle (transform-box named class).
+   * Opened eagerly from a `transform_box_{body,side,corner}` overlay
+   * action; emits `transform_box` intents on every move + commit.
+   *
+   * `base_transform` is the transform at gesture start (frozen);
+   * each preview reduces from `base_transform` against the
+   * cumulative doc-space delta. `size` and `rotation` are the
+   * container parameters at gesture start (frozen — container
+   * doesn't change shape mid-gesture).
+   */
+  kind: "transform_box";
+  id: string;
+  op: {
+    type: "translate";
+  } | {
+    type: "scale_side";
+    side: cmath.RectangleSide;
+  } | {
+    type: "rotate";
+    corner: cmath.IntercardinalDirection;
+  }; /** Box size in doc-space units (frozen at gesture start). */
+  size: cmath.Vector2;
+  /** Container rotation (degrees) at gesture start. Used to de-rotate
+   *  doc-space cursor delta into box-local frame before reducing. */
+  rotation: number; /** Transform at gesture start (frozen). */
+  base_transform: AffineTransform; /** Pointer-down doc-space position. */
+  start_doc: cmath.Vector2; /** Most-recent doc-space pointer. */
+  last_doc: cmath.Vector2; /** Most-recent reduced transform (used for the commit emit). */
+  transform: AffineTransform; /** Flips to `true` once `pointer_move` advances. Click-no-drag → no commit. */
+  dragged: boolean;
+};
+//#endregion
+//#region primitives/corner-radius.d.ts
+/**
+ * Screen-px inset of the handle's RESTING position from its anchoring
+ * corner (rect) or endpoint (line).
+ *
+ * The handle is floored to this distance whenever no gesture is in
+ * flight, so a radius=0 knob still sits inside the rect — visible and
+ * grabbable, not occluded by the resize-corner knob. During a gesture
+ * the floor is lifted: position follows the cursor.
+ *
+ * Locked, not configurable. Per `/sdk-design`: "core, not customizable."
+ */
+declare const DEFAULT_CORNER_RADIUS_HANDLE_INSET = 16;
+/** Default screen-px size of the knob. Matches the visual size of
+ *  resize-corner knobs by convention. */
+declare const DEFAULT_CORNER_RADIUS_HANDLE_SIZE = 8;
+/** Default screen-px hit-rect size. Padded above the visual knob per
+ *  the package's render/hit asymmetry rule. */
+declare const DEFAULT_CORNER_RADIUS_HIT_SIZE = 16;
+/**
+ * One of the four named corners of a rect. Matches the package's
+ * existing `IntercardinalDirection` convention used by resize handles.
+ */
+type CornerRadiusAnchor = "nw" | "ne" | "se" | "sw";
+/**
+ * Per-corner rectangular radius. Hosts populate all four — even
+ * "all-uniform" rounded rects pass `{ tl, tr, br, bl }` with the same
+ * value. The HUD never assumes uniformity; the surface dedup-collapses
+ * geometrically (when handles coincide) rather than value-checking.
+ */
+interface CornerRadiusRectangular {
+  tl: number;
+  tr: number;
+  br: number;
+  bl: number;
+}
+/**
+ * Public input handed to `surface.setCornerRadius(...)`.
+ *
+ * - `rect` ↔ `CornerRadiusRectangular` (four per-corner values, each
+ *   knob travels at 45° from its corner; max radius `min(w,h)/2`).
+ * - `line` ↔ `{ value }` (one radius, knob travels along a→b).
+ *
+ * Illegal combinations (uniform-on-rect, rectangular-on-line) are
+ * unreachable by type.
+ */
+type CornerRadiusInput = {
+  node_id: NodeId;
+  geometry: {
+    kind: "rect";
+    /** Rect in LOCAL space (axis-aligned). When `transform` is
+     *  omitted, "local" and "doc" coincide and the rect is the
+     *  doc-space AABB. */
+    rect?: Rect;
+    /**
+     * Optional local → doc transform (2×3 affine). When set,
+     * handle positions are computed in local space (the four
+     * intercardinal diagonals from each corner) and then
+     * transformed into doc space — so rotated rects show their
+     * knobs along the ROTATED diagonals, not the doc-axis ones.
+     * Pure rotation (orthonormal) is the supported common case;
+     * non-orthonormal transforms work for rendering but are
+     * untested for the gesture's projection math.
+     */
+    transform?: cmath.Transform;
+  };
+  radius: CornerRadiusRectangular;
+} | {
+  node_id: NodeId;
+  geometry: {
+    kind: "line";
+    a: cmath.Vector2;
+    b: cmath.Vector2;
+  };
+  radius: {
+    value: number;
+  };
+};
+/**
+ * One handle the producer wants on screen: the doc-space anchor it
+ * sits at (so the camera moves it with the document), the screen-px
+ * size of the knob and its hit AABB, and a stable label identifying
+ * which interaction it triggers.
+ *
+ * `anchor` is `"nw" | "ne" | "se" | "sw"` for per-corner rect handles,
+ * `"line"` for line geometry. The surface owns the coincidence
+ * collapsing (and `cornerRadiusLayoutGroups` exposes the grouping
+ * predicate); the pure layout always returns one entry per corner.
+ */
+interface CornerRadiusHandleLayout {
+  /** Doc-space anchor — projected through the camera each frame. */
+  pos: cmath.Vector2;
+  /** Screen-px visual knob size. */
+  size: number;
+  /** Screen-px hit AABB size (>= size, padded per Fitts'). */
+  hit_size: number;
+  /** `nw/ne/se/sw` for per-corner rect handles, `"line"` for line. */
+  anchor: CornerRadiusAnchor | "line";
+  /** Stable identifier — `"corner_radius:<anchor>"` or
+   *  `"corner_radius:line"`. */
+  label: string;
+}
+/**
+ * Sign of the intercardinal direction from a corner toward the rect's
+ * interior. NW corner → (+1, +1); NE → (-1, +1); SE → (-1, -1);
+ * SW → (+1, -1). The handle travels in this direction from the corner
+ * by `r` in BOTH x and y.
+ */
+declare function cornerRadiusAnchorSign(anchor: CornerRadiusAnchor): readonly [-1 | 1, -1 | 1];
+/**
+ * Compute the handle position for one corner of a rect.
+ *
+ * The math — the handle IS the arc center of the rounded corner:
+ *
+ *   reach      = radius                            (during gesture)
+ *   reach      = max(radius, pad_screen / zoom)    (at rest / commit)
+ *   reach_cap  = min(w, h) / 2                     (closest-edge half)
+ *   reach      = clamp(reach, 0, reach_cap)
+ *   handle     = corner + (sign_x · reach, sign_y · reach)
+ *
+ * `reach` is the doc-space distance the arc center sits from the
+ * corner along EACH axis (x AND y). For a square at max, all four
+ * arc centers land at the rect's center. For an oblong at max
+ * (reach = min(w,h)/2), pairs along the SHORTER axis coincide:
+ *
+ *   - w > h: TL/BL share `(r, h/2)`; TR/BR share `(w-r, h/2)`
+ *   - h > w: TL/TR share `(w/2, r)`; BL/BR share `(w/2, h-r)`
+ *
+ * `during_gesture` lifts the padded floor: the handle can sit AT the
+ * corner at radius=0. After release the floor is re-applied and the
+ * handle snaps back to a grabbable position.
+ *
+ * `zoom` is the camera's uniform scale (`transform[0][0]`); pass `1`
+ * for unit tests against doc-space math.
+ */
+declare function cornerRadiusHandlePosRect(rect: Rect, anchor: CornerRadiusAnchor, radius: number, zoom: number, opts?: {
+  pad?: number;
+  during_gesture?: boolean;
+  transform?: cmath.Transform;
+}): cmath.Vector2;
+/**
+ * Compute the handle position along a line's `a → b` axis. Single
+ * handle for `line` geometry; same gesture-aware padding rule as the
+ * rect case. The saturation cap is `dist(a, b)`.
+ *
+ * The track here is the a→b segment of arbitrary direction, so the
+ * per-axis convention used by the rect case doesn't apply — `pad`
+ * converts to track-units as `pad / zoom`.
+ */
+declare function cornerRadiusHandlePosLine(a: cmath.Vector2, b: cmath.Vector2, radius: number, zoom: number, opts?: {
+  pad?: number;
+  during_gesture?: boolean;
+}): cmath.Vector2;
+/**
+ * Compute the layout for the corner-radius handles of one input.
+ *
+ * Pure: same inputs → same handles. No camera reads, no DOM.
+ *
+ * - `rect` geometry → 4 handles in `nw/ne/se/sw` declaration order.
+ *   The center coincidence collapse is a downstream concern of the
+ *   surface (which registers one hit region per coincidence group)
+ *   and the renderer (which dedup-paints overlapping circles). The
+ *   pure layout stays four-entry so consumers can inspect per-corner
+ *   positions.
+ * - `line` geometry → 1 handle labelled `corner_radius:line`.
+ *
+ * `during_gesture` flips the handle position from "floored to padded
+ * inset" (at rest / on commit) to "raw radius value" (during drag).
+ * The surface passes `true` when its gesture machine is in a
+ * `corner_radius` state, `false` otherwise.
+ */
+declare function computeCornerRadiusLayout(input: CornerRadiusInput, fallback_rect: Rect | null, zoom: number, opts?: {
+  size?: number;
+  hit_size?: number;
+  pad?: number;
+  during_gesture?: boolean;
+}): CornerRadiusHandleLayout[];
+/**
+ * Group the four rect handle entries by doc-space coincidence (within
+ * `eps_doc`). Returns one group per distinct position, in nw/ne/se/sw
+ * iteration order. Each inner array is the list of anchors sharing
+ * that position.
+ *
+ * Geometric truth:
+ *   - sub-max (each radius < min(w,h)/2)  →  4 groups, one per corner
+ *   - oblong max (w > h, each radius = h/2)  →  2 groups:
+ *       [['nw','sw'], ['ne','se']]     (left pair, right pair)
+ *   - oblong max (h > w, each radius = w/2)  →  2 groups:
+ *       [['nw','ne'], ['sw','se']]     (top pair, bottom pair)
+ *   - square max (each radius = w/2 = h/2)  →  1 group:
+ *       [['nw','ne','se','sw']]         (all at the center)
+ *
+ * Returns `[]` for non-rect layouts (line geometry — there's no
+ * notion of multi-corner coincidence on a single-handle layout).
+ */
+declare function cornerRadiusLayoutGroups(layout: readonly CornerRadiusHandleLayout[], eps_doc?: number): CornerRadiusAnchor[][];
+/**
+ * Resolve a drag's direction to the anchor whose intercardinal
+ * direction `(sign_x, sign_y)` best matches the drag delta.
+ *
+ * Used when a coincidence group has more than one candidate
+ * (oblong max — 2 candidates; square max — 4 candidates). Picks
+ * AMONG `candidates` only — never invents a corner outside the
+ * group. Tie-break: first listed candidate wins.
+ *
+ * `dx, dy` is the drag delta (cursor moved by). The user pulls the
+ * handle TOWARD the corner the radius will shrink at — so the drag
+ * direction matches `(sign_x, sign_y)` directly (TL knob exists at
+ * (r, r); pulling toward TL means cursor moves in (-x, -y); but
+ * that's the SAME as cursor moves "back along the (sign_x, sign_y)
+ * direction" which means delta · sign is negative). To keep the
+ * intent intuitive — "pulling toward NW selects NW" — we pick the
+ * candidate whose `(sign_x, sign_y)` minimizes the dot product
+ * (i.e. delta most opposite the corner→interior vector).
+ *
+ * Equivalent (and what the code does): maximize the dot product
+ * with the NEGATED delta.
+ *
+ * For a rotated rect, callers pass the rect's local→doc `transform`
+ * along with a DOC-space drag delta; the function rotates the local
+ * sign vectors through `T.linear` before comparing so the resolved
+ * corner is the one the user actually dragged toward — not the one
+ * that happens to line up with world axes. With `transform`
+ * omitted, the local frame coincides with the doc frame and the
+ * rotation is a no-op (back-compatible with axis-aligned callers).
+ */
+declare function resolveCornerDragAnchor(dx: number, dy: number, candidates: readonly CornerRadiusAnchor[], transform?: cmath.Transform): CornerRadiusAnchor;
+/** @deprecated use `resolveCornerDragAnchor`. */
+declare function resolveCenterDragAnchor(dx: number, dy: number): CornerRadiusAnchor;
+interface DrawCornerRadiusParams {
+  ctx: CanvasRenderingContext2D;
+  transform: cmath.Transform;
+  /** Viewport width in CSS pixels. */
+  width: number;
+  /** Viewport height in CSS pixels. */
+  height: number;
+  /** Device pixel ratio of the canvas. */
+  dpr: number;
+  /** Pre-computed handle layout. Always one entry per corner (rect)
+   *  or one entry (line); the painter dedups by screen-pixel so
+   *  coincident handles paint as one circle. */
+  handles: readonly CornerRadiusHandleLayout[];
+  /** Stroke + fill color for the knob. */
+  color: string;
+  /** Fill color for the interior. Falls back to white for the standard
+   *  hollow-ring look. */
+  fillColor?: string;
+}
+/**
+ * Paint corner-radius handles into the canvas context. Stateless.
+ *
+ * Coincident handles are dedup-painted at integer-pixel granularity:
+ * when multiple entries project to the same pixel (oblong-max pairs,
+ * square-max quadruple) only one circle is drawn. The deduplication
+ * mirrors `cornerRadiusLayoutGroups` — same geometric truth, two
+ * different consumers.
+ */
+declare function drawCornerRadius(p: DrawCornerRadiusParams): void;
+//#endregion
+//#region primitives/parametric-handle.d.ts
+type ParametricHandle = cmath.parametric.ParametricHandle;
+type ParametricHandleGroup = cmath.parametric.ParametricHandleGroup;
+/**
+ * Hud-local protocol record: one node's `ParametricHandleSet` plus
+ * the `node_id` the surface uses to route per-handle intents back to
+ * the host. The math content (handles / groups / transform) carries
+ * the same semantics as `cmath.parametric.ParametricHandleSet`; the
+ * `node_id` is the hud-side routing tag.
+ *
+ * `inset` on each handle is in **track-units** (cmath contract).
+ * Hud's convention for translating its 16-screen-px snap-back to
+ * track-units lives in the corner-radius primitive (see
+ * `primitives/corner-radius.ts`); other producers that want the same
+ * convention compute `inset = screen_px / zoom · k` for whatever
+ * geometric factor `k` their track demands.
+ *
+ * `groups`, if provided, MUST be disjoint — each handle id may appear
+ * in at most one group. Overlapping declarations would register the
+ * same handle in multiple hit regions and make routing ambiguous.
+ * The layout-grouper enforces this at runtime by first-declared-wins:
+ * later groups that mention an already-claimed id are dropped (with a
+ * dev-mode warning).
+ */
+interface ParametricHandleInput {
+  node_id: NodeId;
+  handles: readonly ParametricHandle[];
+  groups?: readonly ParametricHandleGroup[];
+  transform?: cmath.Transform;
+}
+/**
+ * Hud's screen-px convention for the knob's resting floor from the
+ * curve's `t = 0` endpoint, used so a knob at value=0 doesn't collide
+ * with the resize-corner knob beneath it.
+ *
+ * This is hud's UX choice, NOT the unit the math layer reads.
+ * `ParametricHandle.inset` (in cmath) is documented in track-units;
+ * each producer translates this screen-px value through `zoom` (and
+ * any track-geometry factor) before populating the field.
+ */
+declare const DEFAULT_PARAMETRIC_HANDLE_INSET = 16;
+/** Default screen-px size of the knob. Matches resize-corner knobs. */
+declare const DEFAULT_PARAMETRIC_HANDLE_SIZE = 8;
+/**
+ * Default screen-px hit AABB size. Padded above the visual knob per
+ * the package's render/hit asymmetry rule.
+ */
+declare const DEFAULT_PARAMETRIC_HIT_SIZE = 16;
+/**
+ * One handle's render-time layout. `pos` is doc-space (after the
+ * input's `transform` has been applied); `track_doc` is the doc-space
+ * track (curve or point set) used by the gesture's projection.
+ * `domain` is the effective domain with defaults filled in
+ * (`min = 0`, `max = 1`).
+ */
+interface ParametricHandleLayout {
+  /** The node id of the owning input — routes intents back. */
+  node_id: NodeId;
+  /** The handle id within the input — names the manipulated parameter. */
+  handle_id: string;
+  /** Doc-space position of the knob center. */
+  pos: cmath.Vector2;
+  /** Screen-px visual knob size. */
+  size: number;
+  /** Screen-px hit AABB size (>= size, padded). */
+  hit_size: number;
+  /** Stable label — `parametric:<node_id>:<handle_id>`. */
+  label: string;
+  /** Doc-space track for the gesture's projection — continuous curve
+   *  OR discrete point set. */
+  track_doc: cmath.ui.Curve | cmath.ui.PointSet;
+  /** Effective domain (`min`/`max` defaulted; `step` preserved). */
+  domain: {
+    min: number;
+    max: number;
+    step?: number;
+  };
+}
+/**
+ * Compute the per-frame layout for every handle in an input. One
+ * layout entry per declared handle, in declaration order. Coincidence
+ * detection (the "4-corner collapse" semantic of corner-radius) is a
+ * separate concern — call {@link parametricHandleLayoutGroups} on the
+ * result.
+ *
+ * `during_gesture` lifts the snap-back floor: at rest, a handle whose
+ * `value` lands closer to `t = 0` than the input's `inset` (in
+ * track-units) is floored to `t_inset`; during a drag the knob
+ * follows the cursor down to `t = 0` so the gesture feels honest.
+ *
+ * Pure geometry; no zoom dependence — callers express `inset` in
+ * track-units, so screen-px → track-units conversion (if any) has
+ * already happened before this call.
+ */
+declare function computeParametricHandleLayout(input: ParametricHandleInput, opts?: {
+  size?: number;
+  hit_size?: number;
+  during_gesture?: boolean;
+}): ParametricHandleLayout[];
+/**
+ * Partition a layout into hit-region groups using the input's
+ * declared coincidence groups.
+ *
+ * A declared group "fires" only when ALL its members are within
+ * `eps_doc` of each other in doc-space — i.e. the handles have
+ * geometrically collapsed onto one point. When a group fires, its
+ * members are returned as one sublist and the producer registers a
+ * single hit region with `candidates = members`; the gesture resolves
+ * which member the pointer meant from drag direction.
+ *
+ * When a declared group doesn't fire (members are spread out), its
+ * members are returned as singletons — one hit region per handle.
+ *
+ * Handles not mentioned in any declared group are always singletons.
+ *
+ * The function never invents groupings the input didn't declare —
+ * that's an `/sdk-design` invariant ("coincidence is opt-in").
+ */
+declare function parametricHandleLayoutGroups(input: ParametricHandleInput, layout: readonly ParametricHandleLayout[], eps_doc?: number): ParametricHandleLayout[][];
+/**
+ * Resolve which handle in a coincident group the user is dragging.
+ *
+ * Each candidate has a curve whose tangent at the coincident position
+ * points toward `t = 1`. The user "pulls the knob back along that
+ * direction" to decrease value, so the drag delta most OPPOSITE the
+ * tangent identifies the intended handle. Equivalent: maximize
+ * `tangent · (-delta)`.
+ *
+ * Ties (rare — would require two curves with identical tangents
+ * passing through the same point) break by first-listed candidate.
+ */
+declare function resolveParametricHandleByDirection(group: readonly ParametricHandleLayout[], dx: number, dy: number): ParametricHandleLayout;
+/**
+ * Project a doc-space point onto a handle's track and return both
+ * the parameter `t` and the host-units `value` (denormalized through
+ * `domain`, then snapped to `step` if set).
+ *
+ * The producer calls this once per pointer_move during a drag. The
+ * `value` is what flows back to the host on the intent's `value`
+ * field; `t` is internal (useful for tests and debug overlays).
+ *
+ * Dispatches on `track.kind`: continuous curves use
+ * {@link cmath.ui.projectPointOnCurve}; point sets use
+ * {@link cmath.ui.projectPointOnSet}, which snaps to the nearest
+ * point. `step` quantization (if `domain.step > 0`) is applied on
+ * top of either, then clamped to `[min, max]`.
+ */
+declare function projectParametricHandleValue(layout: ParametricHandleLayout, point: cmath.Vector2): {
+  t: number;
+  value: number;
+};
+interface DrawParametricHandlesParams {
+  ctx: CanvasRenderingContext2D;
+  transform: cmath.Transform;
+  /** Viewport width in CSS pixels. */
+  width: number;
+  /** Viewport height in CSS pixels. */
+  height: number;
+  /** Device pixel ratio of the canvas. */
+  dpr: number;
+  /** Pre-computed handle layouts. Coincident handles are dedup-painted
+   *  by screen pixel — overlapping knobs paint as one circle. */
+  handles: readonly ParametricHandleLayout[];
+  /** Stroke + fill color for the knob. */
+  color: string;
+  /** Fill color for the interior. Defaults to white for the standard
+   *  hollow-ring look (matches `drawCornerRadius`). */
+  fillColor?: string;
+}
+/**
+ * Paint parametric handles into the canvas context. Stateless,
+ * pixel-dedup'd. Same visual shape as `drawCornerRadius` — the two
+ * collapse into one painter in Phase 2 when corner-radius migrates.
+ */
+declare function drawParametricHandles(p: DrawParametricHandlesParams): void;
+//#endregion
+//#region primitives/canvas.d.ts
+interface HUDCanvasOptions {
+  color?: string;
+}
+/**
+ * Imperative Canvas 2D renderer for the HUD overlay.
+ *
+ * Owns a single `<canvas>` element and draws {@link HUDDraw} command lists
+ * each frame. All drawing is immediate-mode: the canvas is cleared and
+ * fully redrawn on every `draw()` call.
+ *
+ * The viewport transform is assumed to be axis-aligned (scale + translate only,
+ * no rotation/shear). The off-diagonal components of the transform matrix are
+ * ignored.
+ */
+declare class HUDCanvas {
+  private canvas;
+  private ctx;
+  private dpr;
+  private transform;
+  private color;
+  private width;
+  private height;
+  private pixelGrid;
+  private ruler;
+  private cornerRadiusHandles;
+  private parametricHandles;
+  constructor(canvas: HTMLCanvasElement, options?: HUDCanvasOptions);
+  setColor(color?: string): void;
+  setSize(w: number, h: number): void;
+  setTransform(transform: cmath.Transform): void;
+  /**
+   * Configure the back-most pixel-grid layer. Pass `null` to disable.
+   * Drawn before any HUD primitive, gated by `zoomThreshold`. See
+   * `PixelGridConfig.transform` for the two-transform contract.
+   */
+  setPixelGrid(config: PixelGridConfig | null): void;
+  /**
+   * Update only the pixel grid's transform, without replacing the rest of
+   * the config. Cheap to call per camera tick.
+   */
+  setPixelGridTransform(transform: cmath.Transform): void;
+  /**
+   * Configure the top-most ruler chrome (top + left strips). Pass `null`
+   * to disable. Painted LAST in the frame — after the pixel grid,
+   * selection chrome, marquee, handles, size meter, and host extras —
+   * so the strips visually frame the viewport instead of being clipped
+   * by anything drawn at the edges. See `RulerConfig.transform` for
+   * the two-transform contract — same shape as the pixel grid.
+   *
+   * Paint-order rationale: pixel grid is a substrate (content-space,
+   * the user reads it "under" the document), ruler is a frame
+   * (viewport-space, the user reads it "around" the document). Frames
+   * sit on top of everything they frame; substrates sit beneath. See
+   * the README "Render path" section.
+   */
+  setRuler(config: RulerConfig | null): void;
+  /**
+   * Update only the ruler's transform. Cheap to call per camera tick.
+   * No-op when no ruler config is set.
+   */
+  setRulerTransform(transform: cmath.Transform): void;
+  /**
+   * Configure the corner-radius handle overlay. Pass `null` to clear.
+   *
+   * Painted in the chrome band — ABOVE the surface's selection
+   * outlines / resize knobs / host extras (which is the "handles, not
+   * frame" band) and BELOW the ruler (the frame strip). The position
+   * inside the chrome band — strictly above `screenRects` — matches
+   * the layered-handle convention: a feature-specific knob always
+   * sits over the generic resize chrome that draws under it.
+   *
+   * Hit-test entries are NOT registered from here; the Surface owns
+   * the registry and pushes corner-radius regions alongside its
+   * regular chrome regions. Render and hit live on independent
+   * shapes per the package's render/hit asymmetry rule.
+   */
+  setCornerRadiusHandles(handles: readonly CornerRadiusHandleLayout[] | null): void;
+  /**
+   * Push the per-frame parametric-handle layouts. Painted in the same
+   * z-band as corner-radius handles (knob, not frame) — feature-
+   * specific knobs above generic resize chrome, below marquee/lasso
+   * and the ruler.
+   *
+   * Hit-test entries are NOT registered here; the Surface owns the
+   * registry and pushes parametric regions alongside its other
+   * chrome regions. Render and hit live on independent shapes per the
+   * package's render/hit asymmetry rule.
+   */
+  setParametricHandles(handles: readonly ParametricHandleLayout[] | null): void;
+  /**
+   * Clear the canvas and draw all primitives in `commands`.
+   * Pass `undefined` to clear without drawing (e.g. when no overlay is active).
+   */
+  draw(commands: HUDDraw | undefined): void;
+  private applyViewTransform;
+  private applyScreenTransform;
+  /** Project a scalar offset on `axis` to screen-space. */
+  private deltaToScreen;
+  private drawRules;
+  /**
+   * Resolve an optional `HUDPaint` to a Canvas 2D fill/stroke value,
+   * falling back to the legacy `color` + `opacity` fields when absent.
+   *
+   * Used by the primitive renderers to switch through `HUDPaint` when
+   * present; the legacy color path is preserved for callers that haven't
+   * adopted paint yet. Pattern resolution happens here — including the
+   * counter-CTM transform that keeps stripes screen-aligned.
+   */
+  private resolvePaintOrFallback;
+  private drawLines;
+  private drawRects;
+  private drawPolylines;
+  private drawPoints;
+  /**
+   * Draw rects whose **size is in screen-space** but whose **anchor is in
+   * document-space**. The doc-space point is projected via the current
+   * transform; the rect is then drawn at fixed CSS-pixel dimensions.
+   *
+   * This is the primitive used to draw resize / rotate handles — they must
+   * remain a constant visual size regardless of viewport zoom.
+   */
+  private drawScreenRects;
+}
+//#endregion
+//#region primitives/paint.d.ts
+declare const DEFAULT_STRIPES_ANGLE_DEG = 45;
+declare const DEFAULT_STRIPES_SPACING_PX = 8;
+declare const DEFAULT_STRIPES_THICKNESS_PX = 1.5;
+/**
+ * Result of `resolvePaint`. The caller assigns `style` to
+ * `ctx.fillStyle` / `ctx.strokeStyle` and uses `opacity` as `globalAlpha`
+ * for the operation (caller is responsible for save/restore).
+ */
+interface ResolvedPaint {
+  style: string | CanvasPattern;
+  opacity: number;
+}
+/**
+ * Pure geometry for a stripes tile. Computes the cross-stripe period
+ * (tile height) and the per-stripe parameters in device pixels.
+ * Separated from the rasterizer so the math is testable in Node.
+ *
+ * The tile is `1 × size`: one horizontal stripe period, axis-aligned.
+ * Rotation is applied at draw time via `CanvasPattern.setTransform`,
+ * NOT baked into the rasterized tile — baking rotation would force the
+ * tile's axis-aligned period to `spacing / sin(angle)`, irrational for
+ * the canonical 45° case, and produce visible breaks within each
+ * rendered stripe (the previous behavior).
+ *
+ * To keep stripes screen-aligned regardless of viewport zoom, the tile
+ * is built in *device pixels* and the consumer composes a counter-CTM
+ * with the rotation in `setTransform`.
+ */
+declare function computeStripesTileGeometry(paint: HUDPaintStripes, dpr: number): {
+  /**
+   * Tile height in device pixels — one cross-stripe period. The tile's
+   * width is fixed at 1 (the stripe is constant along the stripe
+   * direction; horizontal width doesn't carry information).
+   */
+  size: number;
+  spacingPx: number;
+  thicknessPx: number;
+  angleRad: number;
+};
+/**
+ * Rasterize an unrotated, axis-aligned stripes tile (device pixels).
+ * The tile is `1 × size` — one horizontal stripe band wrapping the
+ * `y=0` / `y=size` seam, so it tiles cleanly under `repeat`.
+ *
+ * Rotation is applied at draw time via the pattern transform in
+ * `resolvePaint`. Baking rotation here would force the axis-aligned
+ * tile dimensions to align with the rotated stripe lattice — irrational
+ * for the canonical 45° case — and produce visible breaks within each
+ * rendered stripe.
+ */
+declare function buildStripesTile(paint: HUDPaintStripes, dpr: number): OffscreenCanvas;
+/**
+ * Resolve an `HUDPaint` to a Canvas 2D paint value.
+ *
+ * Solid → CSS color string. Stripes → `CanvasPattern` (with the pattern
+ * transform pre-applied to keep tiles aligned to device pixels).
+ *
+ * Throws on unknown `kind` — closed-taxonomy enforcement; HUD does not
+ * silently passthrough unknown paint kinds.
+ */
+declare function resolvePaint(ctx: CanvasRenderingContext2D, paint: HUDPaint, dpr: number): ResolvedPaint;
+//#endregion
+//#region primitives/draw.d.ts
+interface HUDGroupFilter {
+  hidden?: Iterable<HUDSemanticGroup>;
+}
+/**
+ * Filter a draw command list by semantic group.
+ *
+ * Ungrouped primitives are always kept. The function is intentionally shallow:
+ * primitives are immutable command objects on the hot draw path, so preserving
+ * object identity keeps this as a visibility pass rather than a rewrite.
+ */
+declare function filterHUDDrawByGroup(draw: HUDDraw | undefined, filter: HUDGroupFilter): HUDDraw | undefined;
+//#endregion
+//#region primitives/snap-guide.d.ts
+/**
+ * Convert a `guide.SnapGuide` (the output of `guide.plot()`) into a
+ * generic {@link HUDDraw} command list.
+ *
+ * `color`, when supplied, is applied as the per-item stroke override
+ * for every emitted line, rule, and point. When absent, the HUD
+ * canvas's current color is used.
+ */
+declare function snapGuideToHUDDraw(sg: guide.SnapGuide | undefined, color?: string): HUDDraw | undefined;
+//#endregion
+//#region primitives/measurement-guide.d.ts
+/**
+ * Convert a {@link Measurement} (the output of `measure()`) into a
+ * generic {@link HUDDraw} command list.
+ *
+ * All coordinates are in **document space** — the HUD canvas applies
+ * the viewport transform.
+ *
+ * Produces:
+ * - Two stroke-only rects for the A and B bounding boxes
+ * - One labelled guide line per non-zero distance (solid)
+ * - One auxiliary line per non-zero side connecting the guide to B (dashed)
+ *
+ * If `color` is provided, every emitted line and rect carries that color so
+ * the guides render distinctly from the canvas's chrome color. When used via
+ * `surface.draw(extra)` (the host-fed-extras channel) this is required to
+ * separate measurement from selection chrome on a shared canvas.
+ */
+declare function measurementToHUDDraw(m: Measurement, color?: string): HUDDraw;
+//#endregion
+//#region primitives/marquee.d.ts
+/**
+ * Convert two marquee corner points into a {@link HUDDraw} command list.
+ *
+ * All coordinates are in **document space**.
+ *
+ * Produces a single rectangle with a stroke outline and a semi-transparent fill.
+ */
+declare function marqueeToHUDDraw(a: cmath.Vector2, b: cmath.Vector2): HUDDraw;
+//#endregion
+//#region primitives/lasso.d.ts
+/**
+ * Convert a lasso point sequence into a {@link HUDDraw} command list.
+ *
+ * All coordinates are in **document space**.
+ *
+ * Produces a single polyline with a dashed stroke and a semi-transparent fill.
+ * The polyline lives on the {@link HUDDraw} TOP layer (`topPolylines`) so it
+ * always paints above knobs, handles, outlines, and any other surface chrome
+ * — the user must always see the live lasso region they are drawing,
+ * regardless of what it overlaps. Standalone `<Lasso/>` overlays render on
+ * their own canvas and don't need this guarantee, but routing through the
+ * top slot makes hosts that inline the draw into the surface canvas behave
+ * identically.
+ */
+declare function lassoToHUDDraw(points: cmath.Vector2[]): HUDDraw | undefined;
+//#endregion
+//#region event/event.d.ts
+/** Modifier-key snapshot at the moment an event was produced. */
+interface Modifiers {
+  shift: boolean;
+  alt: boolean;
+  meta: boolean;
+  ctrl: boolean;
+}
+declare const NO_MODS: Modifiers;
+type PointerButton = "primary" | "secondary" | "middle";
+/**
+ * Input event consumed by `Surface.dispatch`.
+ *
+ * All coordinates are **screen-space CSS pixels relative to the canvas**.
+ * The surface owns the camera and converts to document-space internally.
+ */
+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;
+} | {
+  kind: "blur";
+};
+/** Result of a `Surface.dispatch` call. */
+interface SurfaceResponse {
+  needsRedraw: boolean;
+  cursorChanged: boolean;
+  hoverChanged: boolean;
+}
+//#endregion
+//#region classes/padding/intent.d.ts
+/**
+ * Drag of a padding handle on a flex-parent container's side. The host
+ * applies the new `value` to the node's `layout_padding_{side}` field.
+ * When `mirror` is true (alt-held), host also applies the same value to
+ * the opposite side; HUD paints both sides "selected" for the duration of
+ * the gesture.
+ *
+ * The intent carries the resolved next padding value — not a pointer
+ * delta. HUD owns the math; the host commits the outcome (D1).
+ *
+ * `value` is in doc-space units. The HUD clamps to 0 (no negative padding);
+ * hosts wanting different clamps post-process.
+ */
+type PaddingIntent = {
+  kind: "padding_handle";
+  node_id: NodeId;
+  side: cmath.RectangleSide;
+  value: number;
+  mirror: boolean;
+  phase: IntentPhase;
+};
+//#endregion
+//#region classes/transform-box/intent.d.ts
+/**
+ * Drag of a transform-box handle. HUD has already reduced the gesture;
+ * the host commits `transform` to whatever field it bound the input to
+ * (image-fit paint transform, free-transform node local transform, …).
+ *
+ * `op` carries the gesture's TYPE and TARGET so the host can
+ * route / log / debug, but never the pointer delta — the host doesn't
+ * need to re-reduce. HUD's reduction is the public outcome (D1 —
+ * subscribe to outcomes, not events).
+ *
+ * `transform` is box-relative (translation normalized [0..1] against
+ * `TransformBoxInput.size`).
+ */
+type TransformBoxIntent = {
+  kind: "transform_box";
+  id: string;
+  op: {
+    type: "translate";
+  } | {
+    type: "scale_side";
+    side: cmath.RectangleSide;
+  } | {
+    type: "rotate";
+    corner: cmath.IntercardinalDirection;
+  };
+  transform: AffineTransform;
+  phase: IntentPhase;
+};
+//#endregion
+//#region classes/vector-path/intent.d.ts
+type VectorPathIntent = {
+  /**
+   * Select a single vertex within a path under content-edit. Mode
+   * mirrors the node-level `select` intent. Hosts dispatch to their
+   * path-edit session's sub-selection state.
+   */
+  kind: "select_vertex";
+  node_id: NodeId;
+  index: number;
+  mode: SelectMode;
+} | {
+  /**
+   * Translate one or more vertices of a path under content-edit. The
+   * delta is in document-space, measured from gesture start to the
+   * current frame. Hosts apply the delta to each indexed vertex.
+   */
+  kind: "translate_vertices";
+  node_id: NodeId;
+  indices: number[];
+  dx: number;
+  dy: number;
+  phase: IntentPhase;
+} | {
+  /**
+   * Translate the path-edit sub-selection. The host expands its
+   * authoritative sub-selection (selected vertices ∪ endpoints of
+   * selected segments) and UNIONs with `additional_vertex_indices`
+   * before translating. Used by segment-body drag (default — Meta
+   * switches to bend) so a drag of an unselected segment can still
+   * translate its endpoints, and a drag of any item within a multi-
+   * selection translates the whole selection coherently.
+   */
+  kind: "translate_vector_selection";
+  node_id: NodeId;
+  additional_vertex_indices: readonly number[];
+  dx: number;
+  dy: number;
+  phase: IntentPhase;
+} | {
+  /**
+   * Clear the path-edit sub-selection (vertices / segments / tangents)
+   * WITHOUT exiting content-edit mode and WITHOUT touching the
+   * host's node-level selection.
+   *
+   * Fires when the user single-clicks empty space while in content-
+   * edit. Mirrors the dblclick `exit_content_edit` pattern — same
+   * "click outside to back off" gesture, one fewer step. Without this
+   * the user has no mouse way to drop a vertex sub-selection short of
+   * leaving content-edit entirely.
+   */
+  kind: "clear_vector_selection";
+} | {
+  /**
+   * Select a single segment within a path under content-edit. Mode
+   * mirrors the node-level `select` intent. Fires when the user clicks
+   * a segment OFF the ghost insertion knob — clicking the ghost itself
+   * fires `split_segment` instead.
+   */
+  kind: "select_segment";
+  node_id: NodeId;
+  segment: number;
+  mode: SelectMode;
+} | {
+  /**
+   * Select a single closed-loop "region" within a path under
+   * content-edit. Fires when the user clicks the interior body of
+   * a closed loop (no vertex / tangent / segment-strip control
+   * intercepted the click). Mode mirrors the node-level `select`
+   * intent.
+   *
+   * Subsequent drag (if any) promotes to `translate_vector_selection`
+   * — the host applies the delta to the loop's segments and their
+   * endpoint vertices, the same way segment-body drag works today.
+   * No new translate intent kind.
+   *
+   * The host's region commit policy is its own choice: typical
+   * hosts also push the loop's segment indices into
+   * `VectorSubSelection.segments` (so segment chrome highlights too)
+   * and the picked region's id into `VectorSubSelection.regions`
+   * (so the region's `selected` paint shows). The HUD doesn't
+   * presume — it only reports "the user clicked region N."
+   */
+  kind: "select_region";
+  node_id: NodeId;
+  region: number;
+  mode: SelectMode;
+} | {
+  /**
+   * Select a single tangent within a path under content-edit. Mode
+   * mirrors the node-level `select` intent.
+   */
+  kind: "select_tangent";
+  node_id: NodeId; /** `[vertex_idx, 0]` = ta on segment whose a===v; `[v, 1]` = tb where b===v. */
+  tangent: readonly [number, 0 | 1];
+  mode: SelectMode;
+} | {
+  /**
+   * Move a single tangent control point to a new doc-space position.
+   * The host applies the mirror policy (`auto` infers from current
+   * smooth-join state, `none` only moves the one tangent, `angle`
+   * mirrors the opposite tangent's angle while preserving its length,
+   * `all` mirrors both angle and length).
+   */
+  kind: "set_tangent";
+  node_id: NodeId;
+  tangent: readonly [number, 0 | 1];
+  pos: cmath.Vector2;
+  mirror: "auto" | "none" | "angle" | "all";
+  phase: IntentPhase;
+} | {
+  /**
+   * Insert a new vertex on segment `segment` at parametric position
+   * `t ∈ [0,1]`. The split halves inherit the original's verb if
+   * possible; arc groups are broken. Fires once per click — no
+   * preview phase (split is atomic).
+   */
+  kind: "split_segment";
+  node_id: NodeId;
+  segment: number;
+  t: number;
+} | {
+  /**
+   * Bend segment `segment` by dragging a point originally at parameter
+   * `ca` toward a doc-space target `cb`. The host re-solves the
+   * segment's tangents to put `B(ca) === cb`, holding the endpoints
+   * fixed. `phase` lets the host bracket a history preview the same
+   * way translate does.
+   */
+  kind: "bend_segment";
+  node_id: NodeId;
+  segment: number;
+  ca: number;
+  cb: cmath.Vector2;
+  phase: IntentPhase;
+};
+//#endregion
+//#region event/intent.d.ts
+/** "preview" is emitted on every gesture move; "commit" once on release. */
+type IntentPhase = "preview" | "commit";
+/**
+ * Selection mode for `select` intents.
+ *
+ * - `replace` — clear selection, then select the given ids
+ * - `add` — union into the current selection
+ * - `toggle` — flip each given id's membership
+ */
+type SelectMode = "replace" | "add" | "toggle";
+/**
+ * Actionable change emitted by the surface. The host commits the intent
+ * (wrapping in `history.preview` for `phase: "preview"`, finalizing for
+ * `phase: "commit"`).
+ *
+ * The surface itself never mutates the document.
+ */
+type Intent = {
+  kind: "select";
+  ids: NodeId[];
+  mode: SelectMode;
+} | {
+  kind: "deselect_all";
+} | {
+  kind: "translate";
+  ids: NodeId[]; /** Total delta in document-space, from gesture start. */
+  dx: number;
+  dy: number;
+  phase: IntentPhase;
+} | {
+  kind: "resize"; /** Member ids of the group being resized (1 or more). */
+  ids: NodeId[];
+  anchor: ResizeDirection;
+  /**
+   * Target rect in document-space. For `transformed` selections this
+   * is the AABB of the new shape — preserved so axis-aligned hosts
+   * that ignore `shape` keep working unchanged.
+   */
+  rect: Rect;
+  /**
+   * Full target shape. Present whenever the gesture produced one
+   * (which is always, post-Commit 2 of the affine-first plan).
+   * Hosts that handle rotated/sheared selections consume this
+   * directly; legacy hosts can read `rect` and ignore `shape`.
+   */
+  shape?: SelectionShape;
+  phase: IntentPhase;
+} | {
+  kind: "rotate"; /** Member ids of the group being rotated (typically 1). */
+  ids: NodeId[]; /** Target angle delta in radians (relative to gesture start). */
+  angle: number;
+  phase: IntentPhase;
+} | {
+  kind: "marquee_select"; /** Marquee rect in document-space (normalized). */
+  rect: Rect;
+  additive: boolean;
+  phase: IntentPhase;
+} | {
+  /**
+   * Lasso (freeform polygon) selection. Symmetric to `marquee_select`
+   * — emitted every pointer_move with `phase: "preview"` and on
+   * pointer_up with `phase: "commit"`. The host runs its own hit-test;
+   * for vector content-edit the predicate is
+   * `cmath.polygon.pointInPolygon` against `polygon`.
+   *
+   * Lasso targets vertices and tangents only — segments are NOT tested
+   * against the polygon. The host enforces that constraint; the HUD
+   * just delivers the polygon.
+   */
+  kind: "lasso_select";
+  /**
+   * Doc-space polygon, oldest-first. Treated as closed
+   * (`polygon[last] → polygon[0]` implicit).
+   */
+  polygon: cmath.Vector2[];
+  additive: boolean;
+  phase: IntentPhase;
+} | {
+  kind: "set_endpoint"; /** Subject node id (line-shape selection). */
+  id: NodeId; /** Which endpoint is being moved. */
+  endpoint: "p1" | "p2"; /** Target position in document-space. */
+  pos: cmath.Vector2;
+  phase: IntentPhase;
+} | {
+  kind: "enter_content_edit";
+  id: NodeId;
+} | {
+  /**
+   * Exit content-edit mode. Fired by the HUD when the user dblclicks
+   * "away" from the active edit (anywhere not on a vertex / tangent /
+   * segment-strip overlay). No payload — the host knows which node
+   * is under edit (it's the one it most recently pushed a vector
+   * mirror for via `setVectorSelection`).
+   *
+   * Host policy: discard any in-flight preview, clear the vector
+   * mirror (`setVectorSelection(null)`), return to whatever mode the
+   * host considers "outside content-edit." The HUD doesn't presume
+   * what that next mode is.
+   */
+  kind: "exit_content_edit";
+} | VectorPathIntent | {
+  /**
+   * Drag of a corner-radius handle on `rect` geometry, default
+   * branch (no alt). For the per-corner case (radii NOT all
+   * equal) `anchor` is the corner the user grabbed; for the
+   * center-handle case (radii all equal) `anchor` is RESOLVED
+   * after the drag-threshold from the pull direction
+   * (`corner → center` vector best matching the negated drag
+   * delta).
+   *
+   * The host decides whether to apply the new `value` to all
+   * four radii or only to the named `anchor`. The HUD doesn't
+   * presume — it tells the host which corner the gesture
+   * names, and the host's interaction model (e.g. "all-equal
+   * stays all-equal during a center drag") picks the policy.
+   * Hosts that want unambiguous single-corner semantics gate
+   * on alt and read `corner_radius_explicit` instead.
+   */
+  kind: "corner_radius";
+  node_id: NodeId;
+  anchor: "nw" | "ne" | "se" | "sw"; /** Target radius in doc-space units. */
+  value: number;
+  phase: IntentPhase;
+} | {
+  /**
+   * Same payload as `corner_radius`, but the user held alt
+   * during the drag. Host MUST apply to the named `anchor`
+   * only — never broadcast to other corners regardless of the
+   * surrounding interaction model. Lets the user override an
+   * all-equal default ("alt + drag a single corner makes it
+   * different").
+   *
+   * Distinct kind, not a flag on `corner_radius`, so the host's
+   * commit pipe doesn't have to branch on a hidden modifier
+   * inside the payload — the modifier IS the intent.
+   */
+  kind: "corner_radius_explicit";
+  node_id: NodeId;
+  anchor: "nw" | "ne" | "se" | "sw";
+  value: number;
+  phase: IntentPhase;
+} | {
+  /**
+   * Drag of a corner-radius handle on `line` geometry. Lines
+   * have a single `corner_radius` field on the node (not four
+   * per-corner radii), so there is no anchor to resolve and no
+   * alt branch — there's only one knob.
+   *
+   * Host applies the new `value` to the node's singular
+   * `corner_radius` field.
+   */
+  kind: "corner_radius_uniform";
+  node_id: NodeId;
+  value: number;
+  phase: IntentPhase;
+} | {
+  /**
+   * Drag of a parametric handle (the universal value-on-curve
+   * affordance introduced by `surface.setParametricHandles`).
+   * Hosts route to their reducer by `(node_id, handle_id)` and
+   * decide policy from `modifiers` themselves — the producer
+   * doesn't interpret `alt` / `shift` semantically.
+   *
+   * `value` is in host-units (whatever the host set on the
+   * handle's `domain`), already snapped to `domain.step` if
+   * configured.
+   *
+   * One intent kind for all consumers — corner-radius's
+   * `corner_radius` / `corner_radius_explicit` / `corner_radius_uniform`
+   * trio is a special case still emitted by `setCornerRadius`
+   * for backward compatibility; new hosts standardize on this.
+   */
+  kind: "parametric_handle";
+  node_id: NodeId;
+  handle_id: string;
+  value: number;
+  modifiers: {
+    alt: boolean;
+    shift: boolean;
+  };
+  phase: IntentPhase;
+} | PaddingIntent | TransformBoxIntent | {
+  kind: "cancel_gesture";
+};
+/** Callback the host implements to receive intents. */
+type IntentHandler = (intent: Intent) => void;
+//#endregion
+//#region event/transform.d.ts
+/**
+ * Surface camera transform: axis-aligned (scale + translate only).
+ *
+ * Stored as a `cmath.Transform`:
+ *   `[[sx, 0, tx], [0, sy, ty]]`
+ *
+ * Off-diagonal components are ignored; the surface does not support rotation
+ * or shear at the camera level.
+ */
+type Transform = cmath.Transform;
+//#endregion
+//#region surface/style.d.ts
+/**
+ * HUD style — colors, sizes, and offsets for the surface-owned chrome.
+ *
+ * All fields are optional; defaults follow.
+ */
+interface HUDStyle {
+  /** Primary chrome color (selection outline, handle border). */
+  chromeColor: string;
+  /** Secondary color used for hover outline (lighter than chrome). */
+  hoverColor: string;
+  /** Handle visual size in screen-px. */
+  handleSize: number;
+  /** Handle fill color. */
+  handleFill: string;
+  /** Handle stroke color. */
+  handleStroke: string;
+  /** Selection outline stroke width (in screen-px). */
+  selectionOutlineWidth: number;
+  /** Hover outline stroke width (in screen-px). Typically thicker than selection. */
+  hoverOutlineWidth: number;
+  /** Whether to render rotation handles in addition to resize handles. */
+  showRotationHandles: boolean;
+  /**
+   * Color used for IDLE vector segment outlines. Painted as a thin overlay
+   * stroke on top of each segment to indicate "you are in path edit mode
+   * and these segments are interactive" — independent of the document's
+   * own stroke style. Default is a neutral gray affordance stroke.
+   */
+  segmentIdleColor: string;
+  /** Stroke width (screen-px) for IDLE segment outlines. */
+  segmentIdleWidth: number;
+  /**
+   * Color used for HOVERED or SELECTED vector segment outlines. Same color
+   * for both — hover differentiates via lower opacity (see `segmentHoverOpacity`).
+   */
+  segmentActiveColor: string;
+  /** Stroke width (screen-px) for hovered/selected segment outlines. */
+  segmentActiveWidth: number;
+  /** Opacity (0..1) applied to the hovered (not selected) segment outline. */
+  segmentHoverOpacity: number;
+  /** Color for tangent handle lines (vertex → control point). */
+  tangentLineColor: string;
+  /** Stroke width (screen-px) for tangent lines when their tangent is NOT
+   *  selected. */
+  tangentLineIdleWidth: number;
+  /** Stroke width (screen-px) for tangent lines when their tangent IS
+   *  selected. */
+  tangentLineActiveWidth: number;
+  /**
+   * Paint applied to a region's interior when the cursor is hovering
+   * the loop body (no other vector control claimed the pixel). Hosts
+   * typically use `HUDPaintStripes` here — the canonical
+   * "highlighted region, not committed selection" affordance.
+   *
+   * @see {@link HUDPaintStripes}
+   */
+  vectorRegionHoverPaint: HUDPaint;
+  /**
+   * Paint applied to a region's interior when the loop is in the
+   * host-pushed `VectorSubSelection.regions` array. Same shape vocabulary
+   * as `vectorRegionHoverPaint`; conventionally a brighter / higher-
+   * opacity variant so selected reads stronger than hover. Hover wins
+   * over selected when both apply (existing precedence in vector chrome).
+   */
+  vectorRegionSelectedPaint: HUDPaint;
+  /**
+   * Paint applied to a padding-overlay side rect when the cursor is
+   * hovering it (HUD-owned; reads modifier state for axis-mirror).
+   *
+   * @see {@link HUDPaintStripes}
+   */
+  paddingHoverPaint: HUDPaint;
+  /**
+   * Stroke color for the padding-overlay side rect when a `padding_handle`
+   * gesture is in flight (HUD-derived from `state.gesture`). Painted as an
+   * outline of the side rect — communicating "this is the padding box at
+   * the current value" — instead of the hover stripe pattern. Cleaner read
+   * during the drag than stripes, which clutter the geometry.
+   *
+   * Stroke width: `selectionOutlineWidth`. Fill: none.
+   *
+   * With axis-mirror on (alt-held), the opposite side also outlines.
+   */
+  paddingSelectedStroke: string;
+  /** Fill color for the padding mid-edge drag handle (visual knob). */
+  paddingHandleFill: string;
+  /** Stroke color (ring) for the padding mid-edge drag handle. */
+  paddingHandleStroke: string;
+  /**
+   * Stroke color for the transform-box quad outline. The quad is the
+   * only visible chrome of the transform-box model in idle — handles
+   * are invisible hit-only by default.
+   *
+   * Default `#a3a3a3` (neutral-400) — a muted stroke that reads as
+   * "transform target boundary" without competing with selection chrome.
+   */
+  transformBoxStroke: string;
+  /** Fill color for the (invisible by default) transform-box handles. */
+  transformBoxHandleFill: string;
+  /** Stroke color for transform-box handles (visible only in debug). */
+  transformBoxHandleStroke: string;
+}
+//#endregion
+//#region classes/padding/input.d.ts
+/**
+ * Input pushed by the host to enable padding chrome on a flex-parent
+ * container. Schema-level feature flag — pass `null` (or never call
+ * `setPaddingOverlay`) to disable. Hosts re-push on every padding /
+ * container-rect change.
+ *
+ * @unstable Public shape may change until a second independent integration
+ * ratifies it.
+ */
+interface PaddingOverlayInput {
+  node_id: NodeId;
+  /** Container rect in doc-space (the node's bounding rect). */
+  rect: Rect;
+  /**
+   * Per-side padding in doc-space units. Absent or `<= 0` = side not
+   * drawn. Matches the 4-value model used by `layout_padding_{side}`.
+   */
+  padding: {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+  };
+  /**
+   * Optional semantic group for visibility policy. The full overlay
+   * fans out per-side rects + per-side handles; all carry the same
+   * group so a single `SurfaceVisibilityPolicy` toggle suppresses the
+   * whole model atomically.
+   */
+  group?: HUDSemanticGroup;
+}
+/**
+ * Hover state for the padding model — HUD-owned. The padding region's
+ * hover is set on every idle `pointer_move` from the hit-regions
+ * registry; the chrome reads it each frame to render the stripe fill.
+ *
+ * `mirror_side` is non-null when alt is held AND the pointer is on a
+ * `padding_region` — the renderer paints both the hovered side and its
+ * opposite. Cleared on alt release on the next pointer-move (modifier
+ * events alone don't re-derive hover; that's an acceptable v1 cost —
+ * the user will be moving the mouse over the region to see the effect
+ * anyway).
+ */
+type PaddingHover = {
+  kind: "padding_region";
+  node_id: NodeId;
+  side: cmath.RectangleSide;
+  mirror_side?: cmath.RectangleSide;
+} | {
+  kind: "padding_handle";
+  node_id: NodeId;
+  side: cmath.RectangleSide;
+};
+//#endregion
+//#region classes/transform-box/input.d.ts
+/**
+ * Input pushed by the host to enable transform-box chrome.
+ * Schema-level feature flag — pass `null` (or never call
+ * `setTransformBox`) to disable.
+ *
+ * @unstable Public shape may change as the transform-box model
+ * stabilises. The contract is shaped by a single integration today;
+ * a second independent consumer will ratify it.
+ */
+interface TransformBoxInput {
+  /**
+   * Host-defined identity, echoed back on every intent so the host
+   * can correlate (e.g. `"node-1:fill[2]"` for an image-paint
+   * transform, `"node-1:local"` for a free-transform). NOT a NodeId
+   * — the granularity is "one transform" per setter call.
+   */
+  id: string;
+  /**
+   * Box-relative affine — same shape as AffineTransform (2×3).
+   * Translation components ([0][2], [1][2]) are normalized [0..1]
+   * against `size`.
+   */
+  transform: AffineTransform;
+  /** Box size in doc-space units. */
+  size: cmath.Vector2;
+  /**
+   * Doc-space anchor for the box's [0,0]. Combined with `rotation`
+   * to project box-local → doc-space. The box's local frame is
+   * rotated by `+rotation` around `origin` to land in doc-space.
+   */
+  origin: cmath.Vector2;
+  /**
+   * Container rotation in degrees (CCW). When non-zero, the
+   * gesture's doc-space cursor delta is de-rotated by `-rotation`
+   * before being fed to the math reducer.
+   */
+  rotation?: number;
+  /**
+   * Optional semantic group for visibility policy. All emitted
+   * overlays carry the same group so a single `SurfaceVisibilityPolicy`
+   * toggle suppresses the whole model atomically.
+   */
+  group?: HUDSemanticGroup;
+}
+/**
+ * Hover state for the transform-box model — HUD-owned. The chrome
+ * reads this each frame; in the current model nothing differs
+ * visually per hover (handles are transparent by default), but the
+ * cursor mapping reads it (`grab` for corner, `ns/ew-resize` for
+ * sides, `move` for body). Cleared on pointer-out / blur.
+ */
+type TransformBoxHover = {
+  kind: "transform_box_body";
+  id: string;
+} | {
+  kind: "transform_box_side";
+  id: string;
+  side: cmath.RectangleSide;
+} | {
+  kind: "transform_box_corner";
+  id: string;
+  corner: cmath.IntercardinalDirection;
+};
+/**
+ * Active gesture descriptor that the host's chrome rebuilder uses to
+ * suppress handles during a drag (mirrors padding-overlay). The
+ * Surface derives this from `state.gesture` when the gesture matches
+ * this input's `id`.
+ */
+type TransformBoxActiveOp = {
+  type: "translate";
+} | {
+  type: "scale_side";
+  side: cmath.RectangleSide;
+} | {
+  type: "rotate";
+  corner: cmath.IntercardinalDirection;
+};
+//#endregion
+//#region event/hit-regions.d.ts
+/**
+ * Action a UI hit-region triggers when clicked.
+ *
+ * Each variant carries a snapshot of the relevant shape state at the time
+ * the chrome was built — so the surface can start a gesture without an
+ * extra round-trip to host providers. The chrome builder is the single
+ * source of truth for "what does this hit region act on?"
+ *
+ * - `select_node` — user clicked on a node-representative UI region.
+ * - `resize_handle` — one of 8 resize regions (4 corner knobs + 4 virtual
+ *   edges). Carries the group's member ids and the group's initial
+ *   `SelectionShape` — `rect` for axis-aligned groups, `transformed` for
+ *   rotated/sheared groups (so resize math runs in the local frame).
+ * - `rotate_handle` — one of 4 virtual rotation regions outside the group's
+ *   corners. Carries the group's initial `SelectionShape` for center math
+ *   (pivot = center of `shapeBounds(initial_shape)`).
+ * - `endpoint_handle` — endpoint of a line-shape selection. Carries the
+ *   line's current p1/p2 so dragging is relative to a stable snapshot.
+ * - `translate_handle` — body region covering a selection group's bbox.
+ *   Pushed under the corner / edge / rotation regions so resize wins on
+ *   overlap. Lets the user grab any part of the selection chrome — including
+ *   transparent corners of a circle's bbox — to start a translate. Hud is
+ *   the event source once present.
+ */
+type OverlayAction = {
+  kind: "select_node";
+  id: NodeId;
+} | {
+  kind: "resize_handle";
+  direction: ResizeDirection;
+  ids: readonly NodeId[];
+  initial_shape: SelectionShape;
+} | {
+  kind: "rotate_handle";
+  corner: RotationCorner;
+  ids: readonly NodeId[];
+  initial_shape: SelectionShape;
+} | {
+  kind: "endpoint_handle";
+  endpoint: "p1" | "p2";
+  id: NodeId; /** Snapshot of the line endpoints in doc-space at chrome build time. */
+  p1: [number, number];
+  p2: [number, number];
+} | {
+  kind: "translate_handle";
+  ids: readonly NodeId[];
+} | {
+  /**
+   * A vertex knob on a path being content-edited. Drag → translate the
+   * vertex (and any other vertices co-selected at down-time) in the
+   * path's local frame; click → replace-select the vertex.
+   */
+  kind: "vertex_handle"; /** Path node id under content-edit. */
+  node_id: NodeId; /** Index of the vertex within the path's vector network. */
+  index: number; /** Doc-space position of the vertex at chrome build time. */
+  pos: [number, number];
+} | {
+  /**
+   * A tangent control-point knob on a path under content-edit. Drag →
+   * translate the tangent (the host applies mirror policy); click →
+   * replace-select the tangent.
+   */
+  kind: "tangent_handle";
+  node_id: NodeId; /** `[vertex_idx, 0]` for ta on segment with a===v; `[v, 1]` for tb where b===v. */
+  tangent: readonly [number, 0 | 1]; /** Doc-space position of the tangent control point at chrome build time. */
+  pos: [number, number];
+} | {
+  /**
+   * A path segment under content-edit, claimed by the chrome's single
+   * per-segment region. Click → split the segment at the **projected**
+   * t (cursor → nearest point on curve). Drag → start a bend gesture
+   * with `ca` frozen to that same projected t.
+   *
+   * Single-candidate insertion model: at any cursor position there is
+   * EXACTLY ONE candidate insertion point per segment — the point on
+   * the cubic closest to the cursor. The action carries the segment's
+   * four doc-space control points; `event/state.ts` computes `t` on
+   * demand via `cmath.bezier.project` at the cursor's current doc-space
+   * position. No pre-sampled grid.
+   */
+  kind: "segment_strip";
+  node_id: NodeId;
+  segment: number;
+  /** Vertex index of endpoint `a` (used by the segment-drag → translate
+   *  path so the host can route the gesture to a vertex translation
+   *  without consulting its own segment table). */
+  a_idx: number; /** Vertex index of endpoint `b`. */
+  b_idx: number;
+  /** Doc-space cubic control points. The consumer projects the cursor
+   *  against these on demand to get the live `t`. */
+  a: readonly [number, number];
+  b: readonly [number, number];
+  a_control: readonly [number, number];
+  b_control: readonly [number, number];
+} | {
+  /**
+   * Ghost insertion knob — the visible half-point preview on a hovered
+   * segment. Sits in the priority ladder ABOVE `segment_strip` (so it
+   * wins clicks at the marker) and BELOW `vertex_handle` (so a real
+   * vertex collapsed onto the ghost still wins). Carries the segment's
+   * cubic control points so the consumer can recompute `t` live —
+   * mirrors `segment_strip`, but with explicitly "this is the half-
+   * point control" semantics. Pointer-down dispatches to `split_segment`;
+   * drag promotes to `bend_segment` with `ca` = the live `t`.
+   */
+  kind: "ghost_handle";
+  node_id: NodeId;
+  segment: number; /** Vertex indices of the segment's endpoints, mirrors `segment_strip`. */
+  a_idx: number;
+  b_idx: number;
+  a: readonly [number, number];
+  b: readonly [number, number];
+  a_control: readonly [number, number];
+  b_control: readonly [number, number];
+} | {
+  /**
+   * Corner-radius handle — the built-in chrome promoted from labs to
+   * `surface.setCornerRadius(input)`. One action variant covers all
+   * three intent flavors the gesture emits (`corner_radius`,
+   * `corner_radius_explicit`, `corner_radius_uniform`); the surface
+   * branches on `geometry` + modifiers to pick the intent kind at
+   * preview/commit time.
+   *
+   * - `geometry: "rect"`, `anchor: "nw"|"ne"|"se"|"sw"` — one of four
+   *   per-corner knobs. Carries the corner being acted on directly;
+   *   alt-held drag emits `corner_radius_explicit`, otherwise
+   *   `corner_radius`.
+   * - `geometry: "rect"`, `anchor: null` — the singleton center
+   *   handle on an all-equal-radii rect. The surface resolves the
+   *   pulled-toward corner after the drag-threshold and emits
+   *   `corner_radius` / `corner_radius_explicit` from there. Alt
+   *   semantics still apply (after the resolution).
+   * - `geometry: "line"`, `anchor: null` — single uniform handle on
+   *   the line's `a → b` axis. Emits `corner_radius_uniform`. Alt
+   *   has no effect (no anchor to pin).
+   *
+   * The action stores the original `pos` (doc-space anchor of the
+   * handle at chrome build time). The gesture computes the new
+   * radius from the cursor's projection onto the corresponding
+   * geometry axis each frame.
+   */
+  kind: "corner_radius_handle";
+  node_id: NodeId;
+  geometry: "rect" | "line"; /** Doc-space position of the handle at chrome build time. */
+  pos: readonly [number, number];
+  /**
+   * RECT geometry only — the rect in LOCAL space (axis-aligned).
+   * The gesture re-derives per-anchor corner positions from
+   * this on every projection. When the input carries a
+   * `transform`, this rect is the local AABB and `transform`
+   * maps it to doc space; otherwise the rect IS in doc space.
+   */
+  rect?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  /**
+   * RECT geometry only — optional local → doc affine transform.
+   * Present when the host's selection is a rotated / sheared
+   * rect; absent when axis-aligned. The state machine applies
+   * this when projecting the cursor onto each anchor's
+   * diagonal so a knob on a rotated rect tracks the rotated
+   * axis, not the doc-space one.
+   */
+  transform?: cmath.Transform;
+  /**
+   * RECT geometry only — the corner anchors this hit region
+   * stands in for. Length 1 for a single-corner knob (sub-max
+   * radii); length 2 for an oblong-max pair (TL/BL or TR/BR);
+   * length 4 for square-max (all four collapsed to one). When
+   * the length is > 1, the state machine resolves the user's
+   * intended anchor from drag direction after a small
+   * threshold, picking AMONG these candidates only.
+   */
+  candidates?: readonly ("nw" | "ne" | "se" | "sw")[];
+  /**
+   * LINE geometry only — the line endpoints. `a` is the radius-
+   * zero end; `b` is saturation. The gesture projects the cursor
+   * onto a → b.
+   */
+  a?: readonly [number, number];
+  b?: readonly [number, number];
+} | {
+  /**
+   * Closed-loop "region" body within a path under content-edit. The
+   * user can click the interior of a closed sub-path to select that
+   * region. Drag from the region body promotes to
+   * `translate_vector_selection` over the loop's segments.
+   *
+   * Hit detection is **polygon-in-screen-space**: the chrome
+   * builder rasterises the cubic loop to N samples per segment,
+   * registers the screen-space AABB of the rasterised polygon,
+   * and pairs it with a `customHitTest` closure that runs
+   * `pointInPolygon`. Mirrors the segment-strip's AABB-plus-
+   * refinement model — see `surface/vector-chrome.ts`.
+   *
+   * Hit-priority (`REGION_PRIORITY = 9` in vector-chrome.ts):
+   * sits just below `SEGMENT_STRIP_PRIORITY` (8), so any vertex /
+   * tangent / ghost / segment-strip control within the loop wins.
+   * The region claims only the "empty body" of the loop.
+   */
+  kind: "region";
+  node_id: NodeId; /** Region index within `VectorOverlay.regions`. */
+  region: number;
+  /** Segment indices forming the closed loop (carried so the host
+   *  can route a region select intent to its segment-aware
+   *  selection state without a separate lookup). */
+  segments: readonly number[];
+  /** Union of the loop's endpoint vertex indices. Used by drag
+   *  promotion to seed `translate_vector_selection.additional_vertex_indices`
+   *  so the gesture can translate the whole loop even before the
+   *  host has echoed the select_region back into the sub-selection
+   *  mirror. */
+  vertices: readonly number[];
+} | {
+  /**
+   * Body of a padding-overlay side on a flex-parent container. The
+   * user can hover the inset rect to see the diagonal-stripe affordance
+   * (HUD-owned hover paint). Click without drag is a no-op; drag is
+   * claimed by the paired `padding_handle` action at higher priority.
+   *
+   * The region itself emits no intent; only the handle does.
+   */
+  kind: "padding_region";
+  node_id: NodeId;
+  side: cmath.RectangleSide;
+} | {
+  /**
+   * Mid-edge drag knob on a padding-overlay side. Pointer-down opens
+   * a `padding_handle` gesture; drag emits `padding_handle` intents
+   * with the current `value` (clamped at 0) and `mirror` flag (alt
+   * latched per frame). Click-no-drag is a no-op (no commit).
+   *
+   * Carries the container `rect` and the dragged `side` so the gesture
+   * can project the cursor onto the axis and derive `value` without
+   * an extra round-trip through the chrome builder.
+   */
+  kind: "padding_handle";
+  node_id: NodeId;
+  side: cmath.RectangleSide; /** Container rect at chrome build time (doc-space). */
+  rect: Rect; /** Initial padding value at chrome build time (doc-space units). */
+  initial_value: number;
+} | {
+  /**
+   * Body interior of a transform-box. Click + drag emits the
+   * `translate` op for the bound transform; pointer-down without
+   * drag is a no-op (no commit).
+   *
+   * `id` is host-defined and echoes back on the intent — see
+   * `TransformBoxInput.id`.
+   */
+  kind: "transform_box_body";
+  id: string;
+} | {
+  /**
+   * Side mid-edge of a transform-box. Drag emits the `scale_side`
+   * op. Hit AABB is 12px-thick × side-length, Fitts'-
+   * reach over the visible 1px stroke (D3 — asymmetric outputs).
+   *
+   * `base_angle` is the box's effective screen-space rotation in
+   * RADIANS (CCW positive), i.e. `container.rotation +
+   * decompose(transform).rotation`. The cursor branch in
+   * `decideIdleCursor` passes it through to the `resize` cursor so
+   * the arrow tilts with the visual axis instead of staying
+   * axis-aligned. Mirrors `resize_handle.initial_shape` → cursor
+   * baseAngle.
+   */
+  kind: "transform_box_side";
+  id: string;
+  side: cmath.RectangleSide;
+  base_angle: number;
+} | {
+  /**
+   * Corner knob of a transform-box. Drag emits the `rotate` op.
+   * Hit AABB is 16×16 screen-px, Fitts'-reach over the invisible
+   * corner point. `base_angle` — see `transform_box_side`.
+   */
+  kind: "transform_box_corner";
+  id: string;
+  corner: cmath.IntercardinalDirection;
+  base_angle: number;
+} | {
+  /**
+   * Parametric handle knob — the user-facing element of a
+   * `surface.setParametricHandles(...)` input. ONE region per
+   * coincidence group (per `parametricHandleLayoutGroups`); when
+   * the group has 2+ members the state machine resolves which
+   * handle the pointer meant from drag direction.
+   *
+   * Carries everything the gesture needs to project the cursor
+   * each frame without consulting the input table again:
+   *
+   * - `pos` — doc-space anchor of the knob at chrome build time.
+   *   Used as the screen-space hit anchor too (the gesture
+   *   computes a fresh `value` from `point_doc → track`).
+   * - `candidates` — the layout entries this region stands in
+   *   for. Single-handle regions have one entry; coincident
+   *   regions have N. Each entry carries its handle id, doc-space
+   *   track (curve OR point set), and effective domain so the
+   *   gesture doesn't need to re-derive them.
+   */
+  kind: "parametric_knob";
+  node_id: NodeId;
+  pos: readonly [number, number];
+  candidates: readonly {
+    handle_id: string;
+    track_doc: cmath.ui.Curve | cmath.ui.PointSet;
+    domain: {
+      min: number;
+      max: number;
+      step?: number;
+    };
+  }[];
+};
+//#endregion
+//#region event/state.d.ts
+/**
+ * Vector edit sub-selection — what vertices / segments / tangents of a path
+ * are selected during content-edit. Host pushes this via
+ * `Surface.setVectorSelection(...)` whenever its authoritative state changes;
+ * the chrome reads it each frame.
+ */
+interface VectorSubSelection {
+  /** Path node id under content-edit. */
+  node_id: NodeId;
+  vertices: readonly number[];
+  segments: readonly number[];
+  /** `[vertex_idx, 0]` for ta on segment whose a === vertex_idx;
+   *  `[vertex_idx, 1]` for tb where b === vertex_idx. */
+  tangents: readonly (readonly [number, 0 | 1])[];
+  /**
+   * Selected region indices (= closed-loop ids in
+   * `VectorOverlay.regions`). Optional for backward compat — hosts that
+   * don't enumerate regions (or don't push a region mirror) leave it
+   * undefined; the chrome treats `undefined` and `[]` identically.
+   *
+   * Drives the region's `selected` visual state. The chrome reads it
+   * each frame.
+   */
+  regions?: readonly number[];
+}
+/**
+ * Which vector chrome control (if any) is currently under the pointer.
+ * Derived from `hit_regions.hitTest(...)` on every idle pointer_move; the
+ * vector chrome reads it to render hover affordances (segment highlight,
+ * vertex/tangent stroke variant).
+ *
+ * Owned by the HUD — mirrors the "HUD owns hover, host owns selection"
+ * boundary in the README.
+ */
+type VectorHover = {
+  kind: "vertex";
+  node_id: NodeId;
+  index: number;
+} | {
+  kind: "tangent";
+  node_id: NodeId;
+  tangent: readonly [number, 0 | 1];
+}
+/**
+ * Cursor is over the segment body, OFF the ghost insertion knob. Drives
+ * the segment's hovered outline + emits the ghost in DEFAULT (idle)
+ * render state at evaluate(t) so the user can see "the insertion point
+ * lives HERE; reach for it."
+ */
+| {
+  kind: "segment";
+  node_id: NodeId;
+  segment: number;
+  t: number;
+}
+/**
+ * Cursor is over the ghost insertion knob itself (a higher-priority hit
+ * region that sits on top of the segment-strip — see chrome). Drives
+ * the ghost render in HOVER state and gates the split-on-click: only
+ * this hover variant deferred-clicks to `split_segment`.
+ */
+| {
+  kind: "ghost";
+  node_id: NodeId;
+  segment: number;
+  t: number;
+}
+/**
+ * Cursor is inside a closed-loop "region" (a body hit, not a control
+ * knob). Drives the region's hover paint (diagonal stripes). Loses
+ * priority to vertex / tangent / ghost / segment-strip controls
+ * within the same loop's bbox — those win on overlap so the user can
+ * always reach a specific control without the region claiming the
+ * pixel.
+ */
+| {
+  kind: "region";
+  node_id: NodeId;
+  region: number;
+};
+//#endregion
+//#region event/overlay.d.ts
+/**
+ * Minimum hit-target size in screen-px.
+ *
+ * Visual knobs are typically 8px, but the hit region is 16px so users don't
+ * need pixel-perfect aim. Matches `MIN_HIT_SIZE` in the Rust overlay.
+ */
+declare const MIN_HIT_SIZE = 16;
+/**
+ * Below this selection size (in screen-px on either axis), chrome is
+ * suppressed — both the visual handles AND the hit regions. Matches
+ * `MIN_HANDLES_VISIBLE_SIZE` in the Rust overlay.
+ */
+declare const MIN_CHROME_VISIBLE_SIZE = 12;
+/**
+ * A hit region for one overlay element. Always screen-space; either anchored
+ * to a doc-space point (so the hit region tracks the document under camera
+ * changes) or expressed as a pre-projected screen-space AABB (for things
+ * like edge regions whose layout is fundamentally screen-space).
+ */
+type HitShape =
+/**
+ * Fixed screen-space rectangle, centered (or otherwise anchored) on a
+ * doc-space point. The surface projects `anchor_doc` through the current
+ * transform each frame; rect dimensions stay constant in CSS px.
+ */
+{
+  kind: "screen_rect_at_doc";
+  anchor_doc: cmath.Vector2; /** Screen-space size in CSS px. */
+  width: number;
+  height: number; /** Which point of the rect sits on the anchor. Default: "center". */
+  placement?: "center" | "tl" | "tr" | "bl" | "br";
+}
+/**
+ * Screen-space AABB at pre-projected screen coordinates. Used for elements
+ * whose layout the chrome builder already projected (e.g. edge strips).
+ */
+| {
+  kind: "screen_aabb";
+  rect: Rect;
+}
+/**
+ * Oriented bounding-box hit shape — an axis-aligned `rect` in a *shadow*
+ * coordinate space, plus the affine that maps a screen-space pointer
+ * INTO that space. The hit-test pipeline applies `inverse_transform` to
+ * the pointer and then tests against `rect` with normal AABB containment.
+ *
+ * Used by transformed-chrome zones: the 9-slice runs in an axis-aligned
+ * shadow rect centered at the chrome's screen center, and a rotation
+ * (typically around the same center) maps shadow → screen. Storing the
+ * inverse here lets hit-test stay exact at any rotation/skew without
+ * inflating to an AABB-of-rotated-corners.
+ */
+| {
+  kind: "screen_obb";
+  rect: Rect; /** screen → shadow. Applied to the pointer before AABB containment. */
+  inverse_transform: cmath.Transform;
+};
+/**
+ * Visual representation for one overlay element. Maps directly to the
+ * primitive layer's `HUDDraw` entries — the surface fans these out into the
+ * one merged `HUDDraw` it hands to `HUDCanvas.draw()` each frame.
+ *
+ * Virtual elements (rotation, side resize) omit `render`.
+ */
+type RenderShape = /** Screen-space sized rect at doc anchor — e.g. resize knob. */{
+  kind: "screen_rect";
+  anchor_doc: cmath.Vector2;
+  width: number;
+  height: number;
+  placement?: "center" | "tl" | "tr" | "bl" | "br";
+  fill?: boolean;
+  stroke?: boolean;
+  fillColor?: string;
+  strokeColor?: string;
+  /**
+   * Rotation around the rect's screen-space center, in radians (CCW).
+   * Defaults to 0. Used for knobs/badges rendered for a transformed
+   * selection so they rotate with the parent.
+   */
+  angle?: number;
+  /**
+   * Render shape — `"rect"` (default) or `"circle"` (ellipse inscribed
+   * in the same bbox). Hit shape is unaffected; this only changes what
+   * the canvas paints. Used by vector chrome for round vertex knobs.
+   */
+  shape?: "rect" | "circle";
+} /** Doc-space rect — e.g. selection outline, marquee. */ | {
+  kind: "doc_rect";
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  stroke?: boolean;
+  fill?: boolean;
+  fillOpacity?: number;
+  dashed?: boolean;
+} /** Doc-space line — e.g. line-shape selection outline. */ | {
+  kind: "doc_line";
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  dashed?: boolean; /** Stroke width in screen-space CSS px. */
+  strokeWidth?: number; /** Override the canvas color for this line. */
+  color?: string;
+}
+/** Doc-space polyline — used to draw an open curve as a sequence of
+ *  flattened samples, or a closed polygon when `points[last] === points[0]`.
+ *  Stroke width is in screen-px (the renderer divides by zoom). Used by
+ *  vector chrome to outline each segment of a path under content-edit,
+ *  and to fill closed-loop regions with `HUDPaint` (stripes / solid). */
+| {
+  kind: "doc_polyline";
+  points: ReadonlyArray<readonly [number, number]>;
+  stroke?: boolean;
+  fill?: boolean;
+  fillOpacity?: number;
+  strokeOpacity?: number;
+  strokeWidth?: number;
+  dashed?: boolean;
+  color?: string;
+  /**
+   * Paint applied to the fill. When set, takes precedence over
+   * `color` + `fillOpacity` for the fill. Used by closed-loop
+   * region overlays to apply `HUDPaintStripes` for hover / selected
+   * affordance.
+   *
+   * @unstable
+   */
+  fillPaint?: HUDPaint;
+};
+/**
+ * One interactable element of overlay UI.
+ *
+ * Pairs (visual, event, action) into a single struct so the discipline of
+ * "render box ≠ event box" is explicit. The chrome builder emits a list of
+ * these per frame; the surface fans them into render commands and hit
+ * regions.
+ *
+ * - **Virtual elements** (e.g. rotation handles, edge resize strips) omit
+ *   `render` — they exist only as hit regions.
+ * - **Padded elements** have `hit` larger than the corresponding `render`
+ *   shape (e.g. 16px hit AABB around an 8px visual knob).
+ *
+ * TODO(rotation): when the first base-rotated overlay lands (e.g. an
+ * in-canvas rotation pip), add an `orientation: "screen" | "base"` field.
+ * Existing call sites default to `"screen"` and don't change.
+ */
+interface OverlayElement {
+  /** Stable semantic identifier. Format: `"<kind>[:<param>]"`. Examples:
+   *  `"translate"`, `"resize_handle:nw"`, `"resize_edge:n"`,
+   *  `"rotate:ne"`, `"endpoint:p1"`. Used by tests and debug tooling. */
+  label: string;
+  /** Semantic owner for group-level visibility policy. */
+  group?: HUDSemanticGroup;
+  action: OverlayAction;
+  hit: HitShape;
+  render?: RenderShape;
+  /** Lower wins. See `HUDHitPriority` in `selection-controls.ts`. */
+  priority: number;
+  cursor?: CursorIcon;
+  /**
+   * Optional refinement layered on top of the AABB hit check. Receives the
+   * screen-space pointer (or shadow-space, when `hit.kind === "screen_obb"`
+   * and the registry has applied `inverse_transform`). Returns false to
+   * reject the hit even though the AABB matched.
+   *
+   * Used by curve-shaped hit regions (e.g. path segments) — the AABB is
+   * the bezier's bbox, the refinement asks "are you actually near the
+   * curve in screen-px?"
+   */
+  customHitTest?: (point: cmath.Vector2) => boolean;
+}
+//#endregion
+//#region surface/chrome.d.ts
+interface SurfaceChromeGroups {
+  hover?: HUDSemanticGroup;
+  selection?: HUDSemanticGroup;
+  selectionControls?: HUDSemanticGroup;
+  marquee?: HUDSemanticGroup;
+  /** Lasso polygon (sibling of `marquee`). */
+  lasso?: HUDSemanticGroup;
+  transformPreview?: HUDSemanticGroup;
+}
+//#endregion
+//#region classes/vector-path/input.d.ts
+/**
+ * Doc-space POJO returned by the host's `vectorOf` callback. The HUD never
+ * imports `@grida/vn` — this minimal shape carries everything chrome needs.
+ *
+ * All coordinates are in doc-space (the HUD's container CSS-px frame). The
+ * host is responsible for projecting from its local frame (e.g. SVG viewBox)
+ * through the camera CTM before handing the data over.
+ */
+interface VectorOverlay {
+  /** Vertex positions in doc-space. Index === VertexId. */
+  vertices: ReadonlyArray<readonly [number, number]>;
+  /** Optional — present when the host wants segment chrome, tangent
+   *  handles, and segment hit-strips. Each segment carries the four
+   *  cubic control points in doc-space (already projected). */
+  segments?: ReadonlyArray<{
+    a: number;
+    b: number;
+    /** Absolute doc-space position of the first cubic control point
+     *  (= vertices[a] + ta_local, projected through the host's CTM). */
+    a_control: readonly [number, number];
+    /** Absolute doc-space position of the second cubic control point
+     *  (= vertices[b] + tb_local, projected). */
+    b_control: readonly [number, number];
+  }>;
+  /** Vertices whose tangent handles should render. The host computes
+   *  this — selected vertices ∪ their 1-hop neighbours (see
+   *  `PathModel.neighbouringVertices`). Empty list = no tangent handles
+   *  rendered. Spelled `neighbours` (not `neighbouring_vertices`) for
+   *  brevity and so it doesn't collide with the main canvas editor's
+   *  `selection_neighbouring_vertices` state field — if/when the main
+   *  editor adopts this overlay shape, no field-name friction. */
+  neighbours?: ReadonlyArray<number>;
+  /**
+   * Optional — closed-loop "regions" of the path. Each entry names the
+   * segment indices forming one closed loop, in traversal order. The
+   * loop must close (each segment's `b` must match the next segment's
+   * `a`, and the last segment's `b` must match the first's `a`); the
+   * HUD does not validate.
+   *
+   * Schema-level feature flag: absence of this field = backend doesn't
+   * enumerate loops, no region chrome renders. Hosts that can derive
+   * loops (e.g. via `vn.VectorNetworkEditor.getLoops()`) populate it
+   * and pick up the chrome + intent + selection mirror for free.
+   */
+  regions?: ReadonlyArray<{
+    segments: ReadonlyArray<number>;
+  }>;
+  /** Doc-space offset to add to local vertex coords before rendering.
+   *  For hosts that already project to doc-space (most), pass `[0, 0]`. */
+  origin?: readonly [number, number];
+}
+//#endregion
+//#region classes/padding/priority.d.ts
+/**
+ * Padding drag-handle priority slot. Lower wins.
+ *
+ * 12 — wins over corner-radius (15), every resize control (≥30), translate
+ * body (40), rotate (50). The handle sits at the inner edge of the padding
+ * rect; in practice it doesn't overlap perimeter resize/rotate but the
+ * priority is insurance.
+ */
+declare const PADDING_HANDLE_PRIORITY = 12;
+/**
+ * Padding hover-region priority slot. Lower wins.
+ *
+ * 35 — wins over translate body (40), loses to all resize controls (30/31).
+ * Clicking inside the padding zone of a selected flex container fires
+ * padding hover instead of translate; clicking a corner still resizes.
+ * The padding overlay paints over the selection chrome but loses to
+ * the corner resize handles.
+ */
+declare const PADDING_REGION_PRIORITY = 35;
+/**
+ * Screen-px length of the drag-handle's long axis. The short axis is
+ * `PADDING_HANDLE_THICKNESS`. The 16×2 pill is sized for Fitts'-reach
+ * without dominating the inset side rect visually.
+ */
+declare const PADDING_HANDLE_LENGTH = 16;
+/** Screen-px thickness of the drag-handle's short axis. */
+declare const PADDING_HANDLE_THICKNESS = 2;
+//#endregion
+//#region classes/padding/surface.d.ts
+/**
+ * Build the per-frame padding overlay primitives.
+ *
+ * Emits one `OverlayElement` per side rect (hover-only, no intent) and
+ * one per drag handle (per-side `padding_handle` action). The two are
+ * keyed by side and share the same semantic `group`.
+ *
+ * Paint resolution:
+ *   - idle → no render (transparent body; hit still active)
+ *   - hover → `style.paddingHoverPaint`
+ *   - selected (= side === active_side, OR alt and side === opposite of
+ *     active_side) → outline stroke (no stripe)
+ *
+ * The drag handles are suppressed while any padding drag is in flight —
+ * don't paint knobs the user can't grab.
+ *
+ * The region's hit shape is pre-projected to **screen-space AABB** here
+ * — `transform` is needed so the hit area scales with zoom.
+ */
+declare function buildPaddingOverlay(input: {
+  overlay: PaddingOverlayInput;
+  style: HUDStyle;
+  hover: PaddingHover | null;
+  alt_held: boolean;
+  transform: cmath.Transform;
+  active_side?: cmath.RectangleSide;
+}): OverlayElement[];
+//#endregion
+//#region classes/transform-box/priority.d.ts
+/**
+ * 13 — wins over corner-radius (15) and everything below; loses to
+ * padding-handle (12). Rotate grab should win over corner-radius if
+ * both models overlap on the same node (free-transform case).
+ */
+declare const TRANSFORM_BOX_CORNER_PRIORITY = 13;
+/** 14 — peer to corners on this model; wins over corner-radius (15). */
+declare const TRANSFORM_BOX_SIDE_PRIORITY = 14;
+/**
+ * 38 — body translate beats marquee start (40) and selection-translate
+ * body (40); loses to padding-region (35), every resize control (30/31),
+ * and every other handle.
+ */
+declare const TRANSFORM_BOX_BODY_PRIORITY = 38;
+/** Screen-px size of a corner knob (the rotate hit AABB). */
+declare const TRANSFORM_BOX_CORNER_HIT_SIZE = 16;
+/** Screen-px thickness of a side mid-edge hit strip. */
+declare const TRANSFORM_BOX_SIDE_HIT_THICKNESS = 12;
+//#endregion
+//#region classes/transform-box/surface.d.ts
+/**
+ * Build the per-frame transform-box overlay primitives.
+ *
+ * Emits:
+ *   - 1 quad outline (visible — `HUDPolyline` stroke).
+ *   - 1 body hit polygon (invisible, fill transparent; intercepts events).
+ *   - 4 corner hits (invisible 16×16 rects centered on each corner).
+ *   - 4 side hit strips (invisible 12px-thick rotated rects along each side).
+ */
+declare function buildTransformBox(input: {
+  overlay: TransformBoxInput;
+  style: HUDStyle;
+  /** Reserved — handles are invisible today, so hover does not drive
+   *  render. Kept on the contract for the eventual visible-handle
+   *  variant (debug overlay, themed knobs). */
+  hover: TransformBoxHover | null;
+  transform: cmath.Transform; /** Reserved — see `hover`. */
+  active_op?: TransformBoxActiveOp;
+}): OverlayElement[];
+//#endregion
+//#region surface/surface.d.ts
+interface SurfaceVisibilityContext {
+  gesture: SurfaceGesture;
+}
+interface SurfaceVisibility {
+  hidden?: Iterable<HUDSemanticGroup>;
+}
+type SurfaceVisibilityPolicy = (context: SurfaceVisibilityContext) => SurfaceVisibility | undefined;
+interface SurfaceOptions {
+  /**
+   * Content pick. Given a doc-space point, return the topmost node id under
+   * the pointer, or `null`. Host wraps its scene query however it wants
+   * (e.g. `elementFromPoint` + `data-id` for SVG-DOM hosts).
+   */
+  pick: (point_doc: [number, number]) => NodeId | null;
+  /**
+   * Selection shape for a node — what the chrome should wrap. Most nodes
+   * return `{ kind: "rect", rect }`; vector lines return
+   * `{ kind: "line", p1, p2 }`.
+   */
+  shapeOf: (id: NodeId) => SelectionShape | null;
+  /**
+   * Optional — vector geometry for a node under content-edit. When set
+   * AND `setVectorSelection` has been called with a non-null mirror, the
+   * surface renders vertex chrome (knobs, hit regions) for the named node.
+   *
+   * Hosts that never enter vector-edit mode (or that don't have path-aware
+   * content-edit) can omit this. The chrome simply won't render.
+   */
+  vectorOf?: (id: NodeId) => VectorOverlay | null;
+  /** Surface emits intents the host commits. */
+  onIntent: IntentHandler;
+  /** Initial style (partial; merged with defaults). */
+  style?: Partial<HUDStyle>;
+  /** Initial readonly flag. Default `false`. */
+  readonly?: boolean;
+  /** Optional HUDCanvas color override. */
+  color?: string;
+  /**
+   * Optional pixel-grid configuration. Drawn back-most in the HUD canvas
+   * when `enabled` and the current zoom exceeds `zoomThreshold`. Hosts can
+   * also call `surface.setPixelGrid(...)` later.
+   */
+  pixelGrid?: PixelGridConfig | null;
+  /**
+   * Optional ruler configuration. Paints a top + left ruler strip (L-shape)
+   * in screen-space, behind every other HUD primitive. Same two-transform
+   * contract as `pixelGrid`. Hosts can also call `surface.setRuler(...)`
+   * later. The corner square is deliberately left blank.
+   */
+  ruler?: RulerConfig | null;
+  /**
+   * Optional semantic groups for surface-owned chrome. The HUD package does
+   * not define a group vocabulary; hosts pass the strings they want to use.
+   */
+  groups?: SurfaceChromeGroups;
+  /**
+   * Host-owned visibility policy. Called per frame with the current surface
+   * gesture; returned groups are filtered from surface chrome and host extras.
+   */
+  visibility?: SurfaceVisibilityPolicy;
+  /**
+   * Where a click on a segment inserts the new vertex.
+   *
+   * - `"midpoint"` (default) — always at `t=0.5`. The ghost preview appears
+   *   at the segment's geometric midpoint on hover; the position is
+   *   independent of where on the segment the cursor lands. Predictable
+   *   and matches the "owning segment hovers → midpoint becomes visible"
+   *   mental model.
+   * - `"projected"` — at the nearest point on the curve to the cursor
+   *   (`cmath.bezier.project`). The ghost tracks the cursor along the
+   *   curve. More expressive but adds a "where exactly will this land?"
+   *   cognitive step.
+   *
+   * Both modes share the same hit-test, chrome rendering, and intent
+   * vocabulary — only the projected `t` differs. Hosts that don't set
+   * this get `"midpoint"` (the predictable default).
+   */
+  vectorInsertionMode?: VectorInsertionMode;
+  /**
+   * Which gesture an empty-space drag promotes to:
+   * - `"marquee"` (default) — axis-aligned rect selection.
+   * - `"lasso"` — freeform polygon selection.
+   *
+   * Pushed by the host alongside its own tool toggle (e.g. when the host
+   * swaps cursor ↔ lasso tools) via `setVectorSelectionMode`. The HUD reads
+   * it only at empty-space drag promotion; no other branch consults it.
+   * Symmetric with `vectorInsertionMode`.
+   */
+  vectorSelectionMode?: VectorSelectionMode;
+  /**
+   * Sticky-bend toggle for segment-body drag:
+   * - `"auto"` (default) — Meta-modifier gates the bend gesture.
+   *   No Meta → translate; Meta-held → bend.
+   * - `"always"` — segment drag bends regardless of Meta. The host's
+   *   bend tool sets this. Released by setting back to `"auto"`.
+   *
+   * Same host-pushed pattern as `vectorSelectionMode`. Affects only the
+   * NEXT segment-drag promotion; in-flight gestures keep their committed
+   * mode.
+   */
+  vectorBendMode?: VectorBendMode;
+}
+/** See {@link SurfaceOptions.vectorInsertionMode}. */
+type VectorInsertionMode = "midpoint" | "projected";
+/** See {@link SurfaceOptions.vectorSelectionMode}. */
+type VectorSelectionMode = "marquee" | "lasso";
+/** See {@link SurfaceOptions.vectorBendMode}. */
+type VectorBendMode = "auto" | "always";
+/**
+ * Top-level wired surface.
+ *
+ * Owns an internal `HUDCanvas`, a `SurfaceState` (gesture/hover/...) and
+ * the host providers. On every `dispatch`, the state machine runs;
+ * `draw` composes surface chrome + host-fed extras into a single canvas
+ * paint.
+ */
+declare class Surface {
+  private hudCanvas;
+  private state;
+  private style;
+  private opts;
+  /**
+   * Current corner-radius input, or `null`. Owned here (not in
+   * `SurfaceState`) because the chrome builder needs it AND the
+   * pointer_down handler needs it AND the registry rebuild needs
+   * it — placing it on `SurfaceState` would pull a primitive type
+   * into the event-layer's dependencies, which the README's
+   * dependency arrow forbids. Surface is the wired class; the
+   * setter passes the input to both the canvas (for paint) and
+   * the state (via hit-region overlays each frame).
+   */
+  private cornerRadius;
+  private parametricHandles;
+  /**
+   * Padding-overlay input. `null` = no chrome drawn. Hosts push on
+   * flex-parent selection; clear on deselect / mode exit. See
+   * `setPaddingOverlay`.
+   */
+  private paddingOverlay;
+  private colorOverride;
+  private width;
+  private height;
+  private cursor_renderer;
+  constructor(canvas: HTMLCanvasElement, options: SurfaceOptions);
+  /** Switch the vector insertion mode at runtime. Affects both the
+   *  hover preview position and the split/bend `t` for the NEXT
+   *  pointer event. See {@link SurfaceOptions.vectorInsertionMode}. */
+  setVectorInsertionMode(mode: VectorInsertionMode): void;
+  /** Switch the empty-space-drag selection gesture at runtime
+   *  (`marquee` vs `lasso`). Affects only the NEXT pending → drag
+   *  promotion; any in-flight gesture keeps running. See
+   *  {@link SurfaceOptions.vectorSelectionMode}. */
+  setVectorSelectionMode(mode: VectorSelectionMode): void;
+  /** Switch the sticky-bend toggle at runtime (`auto` vs `always`).
+   *  `"always"` is the host's bend tool talking — every segment-drag
+   *  bends as if Meta were held. Affects only the NEXT segment-drag
+   *  promotion. See {@link SurfaceOptions.vectorBendMode}. */
+  setVectorBendMode(mode: VectorBendMode): void;
+  /** Configure / disable the back-most pixel-grid layer. */
+  setPixelGrid(config: PixelGridConfig | null): void;
+  /**
+   * Update just the pixel grid's transform. Cheap to call per camera tick.
+   * No-op when no pixel-grid config is set.
+   */
+  setPixelGridTransform(transform: Transform): void;
+  /** Configure / disable the back-most ruler chrome (top + left strips). */
+  setRuler(config: RulerConfig | null): void;
+  /**
+   * Configure or clear the built-in corner-radius chrome.
+   *
+   * Accepts a single input (one node's corner-radius chrome) OR an
+   * array of inputs (multiple nodes editable at once — typical for
+   * a multi-selection of rect-bearing nodes, or for demos that
+   * compare axis-aligned vs rotated rects in the same viewport).
+   * Pass `null` to remove everything. The chrome for each input is
+   * independent: each input's handles, hit regions, and emitted
+   * intents carry the input's own `node_id`. The host distinguishes
+   * by `node_id` when applying the intent.
+   *
+   * The HUD paints handles along the corner→arc-center diagonal
+   * (rect geometry) or the a→b axis (line geometry); on pointer_down
+   * it owns the hit-test; on drag it emits one of `corner_radius` /
+   * `corner_radius_explicit` / `corner_radius_uniform` per the
+   * geometry + modifier table.
+   *
+   * The handle layout is recomputed every frame from the inputs —
+   * camera changes and radius changes both reflect on the next
+   * `draw()` without a host-side `setCornerRadius` round-trip.
+   *
+   * See `@grida/hud/primitives/corner-radius` for the input shape.
+   */
+  setCornerRadius(input: CornerRadiusInput | readonly CornerRadiusInput[] | null): void;
+  /**
+   * Push one or more parametric-handle inputs — the universal
+   * "scalar value on a 1D manifold" affordance. Each input declares
+   * a node_id, one or more handles (each with curve + value +
+   * optional domain + optional snap-back inset), optional coincidence
+   * groups, and an optional local→doc transform.
+   *
+   * The HUD paints handles along their curves on every `draw()`, owns
+   * the hit-test for the knobs, and emits `parametric_handle` intents
+   * on drag with `{ node_id, handle_id, value, modifiers, phase }`.
+   * Modifier semantics (alt → explicit, etc.) are host-decided —
+   * the producer reports flags only.
+   *
+   * Pass `null` (or `[]`) to remove all parametric chrome. Single
+   * input or array; arrays let one viewport edit multiple nodes
+   * simultaneously. Intents carry their input's `node_id` so the
+   * host routes per-node.
+   *
+   * Hosts typically build inputs through use-case-specific composers
+   * (e.g. the corner-radius primitive builds a 4-handle input over a
+   * rect). The shape itself is generic — anything that can be
+   * expressed as scalars on 1D tracks fits.
+   */
+  setParametricHandles(input: ParametricHandleInput | readonly ParametricHandleInput[] | null): void;
+  /**
+   * Configure or clear the built-in padding-overlay chrome — the
+   * `padding` named class for flex-parent container padding editing.
+   *
+   * Pass an input to enable the chrome (four inset side rects with
+   * diagonal-stripe hover/selected paint + four mid-edge drag handles).
+   * Pass `null` to disable. Schema-level feature flag — absence is the
+   * off-state, no separate boolean to drift.
+   *
+   * The HUD owns hover (including alt-held axis-mirror visual), reads
+   * the `alt` modifier directly for the intent's `mirror` flag, and
+   * emits `padding_handle` intents on drag (preview-stream + commit).
+   * The host applies the value to its node's `layout_padding_{side}`
+   * field and pushes a re-rendered input back via `setPaddingOverlay`
+   * so the chrome reflects the new value.
+   *
+   * Mid-gesture state mirror: hosts SHOULD push `active_side` while a
+   * `padding_handle` gesture is in flight so the dragged side paints
+   * with the "selected" stripe variant (and the opposite side too,
+   * when alt is held). Clear `active_side` on commit.
+   *
+   * See `@grida/hud/classes/padding` for the input shape and
+   * paint/hit/priority details.
+   */
+  setPaddingOverlay(input: PaddingOverlayInput | null): void;
+  /**
+   * Push a transform-box input — the `transform-box` named class for
+   * a 2×3 affine transform manipulated via quad outline + 4 corners +
+   * 4 sides + body. `null` = no chrome drawn (schema-level feature
+   * flag).
+   *
+   * Hosts re-push input whenever the bound transform / size / origin
+   * / rotation changes (driven by the host's reducer applying the
+   * `transform_box` intent). The chrome rebuilds every draw.
+   *
+   * See `@grida/hud/classes/transform-box` for the input shape and
+   * hit/priority/anti-goals details.
+   *
+   * @unstable
+   */
+  setTransformBox(input: TransformBoxInput | null): void;
+  /**
+   * Update just the ruler's transform. Cheap to call per camera tick.
+   * No-op when no ruler config is set.
+   */
+  setRulerTransform(transform: Transform): void;
+  setSize(w: number, h: number): void;
+  setTransform(t: Transform): void;
+  /**
+   * Push a new selection from the host.
+   *
+   * Accepts either:
+   * - `NodeId[]` — each id becomes its own single-member group, shape
+   *   resolved via `shapeOf(id)` by the chrome builder.
+   * - `SelectionGroup[]` — pre-computed groups with their union shape.
+   *
+   * See `SurfaceState.setSelection` for details.
+   */
+  setSelection(input: readonly NodeId[] | readonly SelectionGroup[]): void;
+  /**
+   * Push a vector-edit sub-selection. Pass `null` to exit vector chrome.
+   *
+   * Non-null: the surface renders vertex knobs for the named path on every
+   * subsequent `draw()`, with selected vertices highlighted. Requires the
+   * host to have wired `vectorOf` in `SurfaceOptions` — otherwise the
+   * chrome silently skips.
+   *
+   * Host calls this on enter / exit of content-edit AND on every sub-
+   * selection change (click, marquee, etc.). Cheap — just swaps a field.
+   */
+  setVectorSelection(input: VectorSubSelection | null): void;
+  setStyle(partial: Partial<HUDStyle>): void;
+  /**
+   * Set or clear the host color override. `null` clears the override and
+   * lets `style.chromeColor` win on the next paint.
+   */
+  setColor(color: string | null): void;
+  setReadonly(v: boolean): void;
+  /**
+   * Set or clear a host-driven hover override.
+   *
+   * The surface tracks two hover sources:
+   * - **Pointer pick** — what scene content is under the cursor (updated
+   *   automatically on `pointer_move`).
+   * - **Host override** — what the host wants to show as hovered, e.g.
+   *   from a layers panel row mouseenter.
+   *
+   * The override (when non-null) wins. `hover()` returns the effective
+   * value; chrome renders the effective value. Pass `null` to clear and
+   * fall back to pointer pick.
+   *
+   * Returns the same response shape as `dispatch` so the host can react
+   * to whether anything actually changed.
+   */
+  setHoverOverride(id: NodeId | null): SurfaceResponse;
+  dispose(): void;
+  dispatch(event: SurfaceEvent): SurfaceResponse;
+  draw(extra?: HUDDraw): void;
+  /** Convenience: clear the canvas (e.g. when the host stops the surface). */
+  clear(): void;
+  gesture(): SurfaceGesture;
+  /**
+   * The effective hover: host override (when set) wins over pointer pick.
+   * Use this for chrome decisions and host-side reads.
+   */
+  hover(): NodeId | null;
+  cursor(): CursorIcon;
+  /**
+   * Resolve the current cursor to a CSS `cursor:` value. Runs the
+   * installed renderer (or the built-in `cursorToCss` if none installed).
+   *
+   * Host wires it like:
+   *
+   *     const r = surface.dispatch(event);
+   *     if (r.cursorChanged) el.style.cursor = surface.cursorCss();
+   *
+   * Saves the host from re-importing `cursorToCss` after every dispatch
+   * and gives one place to change behavior when a renderer is swapped in.
+   */
+  cursorCss(): string;
+  /**
+   * Install (or clear) a custom cursor renderer.
+   *
+   * `null` restores the built-in `cursorToCss` behavior (native CSS
+   * keywords for every variant). Pass `cursors.defaultRenderer()` from
+   * `@grida/hud/cursors` for the bundled SVG cursor set.
+   *
+   * Re-callable mid-session; the next `cursorCss()` reads the new value.
+   */
+  setCursorRenderer(fn: CursorRenderer | null): void;
+  modifiers(): Modifiers;
+  /**
+   * Resolve the current corner-radius layout against `shapeOf` (for
+   * the rect-fallback) and the camera. Always returns an array;
+   * empty when the input is null or when the rect can't be
+   * resolved.
+   */
+  private buildCornerRadiusHandles;
+  /**
+   * Push one hit region per handle onto the state's registry. Called
+   * AFTER `fanOverlays` so the regions survive the per-frame clear.
+   */
+  private registerCornerRadiusHitRegions;
+  /**
+   * Resolve the current parametric-handle layout for one input. The
+   * snap-back floor is lifted while this specific input is being
+   * dragged — match by `node_id` so other inputs in the same canvas
+   * keep their resting positions.
+   */
+  private buildParametricHandleLayout;
+  /**
+   * Push one hit region per coincidence group onto the state's
+   * registry. Coincidence is geometric — a declared group only
+   * collapses when its members actually overlap in doc-space. Open
+   * groups produce one region per handle.
+   */
+  private registerParametricHandleHitRegions;
+}
+//#endregion
+export { computeStripesTileGeometry as $, DEFAULT_RULER_STRIP as $t, TransformBoxHover as A, resolveCenterDragAnchor as At, PointerButton as B, compose as Bt, MIN_CHROME_VISIBLE_SIZE as C, DrawCornerRadiusParams as Ct, VectorHover as D, cornerRadiusHandlePosRect as Dt, RenderShape as E, cornerRadiusHandlePosLine as Et, Intent as F, SelectionShape as Ft, measurementToHUDDraw as G, DEFAULT_RULER_ACCENT_BACKGROUND as Gt, SurfaceResponse as H, decompose as Ht, IntentPhase as I, AffineTransform as It, DEFAULT_STRIPES_ANGLE_DEG as J, DEFAULT_RULER_COLOR as Jt, snapGuideToHUDDraw as K, DEFAULT_RULER_ACCENT_COLOR as Kt, SelectMode as L, TransformBoxAction as Lt, PaddingHover as M, Rect as Mt, PaddingOverlayInput as N, SurfaceGesture as Nt, VectorSubSelection as O, cornerRadiusLayoutGroups as Ot, HUDStyle as P, SelectionGroup as Pt, buildStripesTile as Q, DEFAULT_RULER_STEPS as Qt, Modifiers as R, TransformBoxCorners as Rt, HitShape as S, DEFAULT_CORNER_RADIUS_HIT_SIZE as St, OverlayElement as T, cornerRadiusAnchorSign as Tt, lassoToHUDDraw as U, getTransformBoxCorners as Ut, SurfaceEvent as V, cornersToBoxTransform as Vt, marqueeToHUDDraw as W, reduceTransformBox as Wt, DEFAULT_STRIPES_THICKNESS_PX as X, DEFAULT_RULER_FONT as Xt, DEFAULT_STRIPES_SPACING_PX as Y, DEFAULT_RULER_DRAG_THRESHOLD as Yt, ResolvedPaint as Z, DEFAULT_RULER_OVERLAP_THRESHOLD as Zt, PADDING_HANDLE_PRIORITY as _, CornerRadiusHandleLayout as _t, SurfaceVisibilityPolicy as a, RulerMark as an, DEFAULT_PARAMETRIC_HIT_SIZE as at, VectorOverlay as b, DEFAULT_CORNER_RADIUS_HANDLE_INSET as bt, VectorSelectionMode as c, DEFAULT_PIXEL_GRID_COLOR as cn, ParametricHandleGroup as ct, TRANSFORM_BOX_CORNER_HIT_SIZE as d, PixelGridConfig as dn, computeParametricHandleLayout as dt, DEFAULT_RULER_TEXT_SIDE_OFFSET as en, resolvePaint as et, TRANSFORM_BOX_CORNER_PRIORITY as f, drawPixelGrid as fn, drawParametricHandles as ft, PADDING_HANDLE_LENGTH as g, CornerRadiusAnchor as gt, buildPaddingOverlay as h, resolveParametricHandleByDirection as ht, SurfaceVisibilityContext as i, RulerConfig as in, DEFAULT_PARAMETRIC_HANDLE_SIZE as it, TransformBoxInput as j, resolveCornerDragAnchor as jt, TransformBoxActiveOp as k, drawCornerRadius as kt, buildTransformBox as l, DEFAULT_PIXEL_GRID_STEPS as ln, ParametricHandleInput as lt, TRANSFORM_BOX_SIDE_PRIORITY as m, projectParametricHandleValue as mt, SurfaceOptions as n, DrawRulerParams as nn, HUDCanvasOptions as nt, VectorBendMode as o, RulerRange as on, DrawParametricHandlesParams as ot, TRANSFORM_BOX_SIDE_HIT_THICKNESS as p, parametricHandleLayoutGroups as pt, filterHUDDrawByGroup as q, DEFAULT_RULER_BACKGROUND as qt, SurfaceVisibility as r, RulerAxis as rn, DEFAULT_PARAMETRIC_HANDLE_INSET as rt, VectorInsertionMode as s, drawRuler as sn, ParametricHandle as st, Surface as t, DEFAULT_RULER_TICK_HEIGHT as tn, HUDCanvas as tt, TRANSFORM_BOX_BODY_PRIORITY as u, DrawPixelGridParams as un, ParametricHandleLayout as ut, PADDING_HANDLE_THICKNESS as v, CornerRadiusInput as vt, MIN_HIT_SIZE as w, computeCornerRadiusLayout as wt, SurfaceChromeGroups as x, DEFAULT_CORNER_RADIUS_HANDLE_SIZE as xt, PADDING_REGION_PRIORITY as y, CornerRadiusRectangular as yt, NO_MODS as z, TransformBoxOptions as zt };