@grida/hud 0.1.0

package/dist/index-DRBeSiI2.d.ts

@@ -0,0 +1,734 @@
+import cmath from "@grida/cmath";
+import { guide } from "@grida/cmath/_snap";
+import { Measurement } from "@grida/cmath/_measurement";
+
+//#region primitives/types.d.ts
+/**
+ * A line segment in document space, extending `cmath.ui.Line` with
+ * an optional `dashed` style.
+ */
+interface HUDLine extends cmath.ui.Line {
+  dashed?: boolean;
+  /** Stroke width in screen-space CSS px. Defaults to the canvas default. */
+  strokeWidth?: number;
+  /**
+   * Override the canvas color for this line's stroke and label pill. Falls
+   * back to the canvas's current color when absent.
+   */
+  color?: string;
+}
+/**
+ * A full-viewport axis-aligned line (infinite extent) at a given offset.
+ *
+ * `axis` indicates which axis the `offset` lives on:
+ * - `"x"` → vertical line at x=offset
+ * - `"y"` → horizontal line at y=offset
+ *
+ * Offset is in document space; the renderer projects it to screen.
+ */
+interface HUDRule {
+  axis: "x" | "y";
+  offset: number;
+}
+/**
+ * A rectangle in document space.
+ *
+ * Stroke uses the canvas color by default. Fill is opt-in.
+ */
+interface HUDRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** Whether to stroke the outline (default: true). */
+  stroke?: boolean;
+  /** Whether to fill the interior (default: false). */
+  fill?: boolean;
+  /** Opacity of the fill color, 0–1 (default: 1). Ignored when `fill` is falsy. */
+  fillOpacity?: number;
+  /** Draw the outline with a dash pattern. */
+  dashed?: boolean;
+  /** Stroke width in screen-space CSS px. Defaults to the canvas default. */
+  strokeWidth?: number;
+  /**
+   * Override the canvas color for this rect's stroke and fill. Falls back
+   * to the canvas's current color when absent.
+   */
+  color?: string;
+}
+/**
+ * A polyline (or closed polygon) in document space.
+ *
+ * Stroke uses the canvas color by default. Fill is opt-in.
+ */
+interface HUDPolyline {
+  points: cmath.Vector2[];
+  /** Whether to stroke the path (default: true). */
+  stroke?: boolean;
+  /** Whether to fill the interior (default: false). */
+  fill?: boolean;
+  /** Opacity of the fill color, 0–1 (default: 1). Ignored when `fill` is falsy. */
+  fillOpacity?: number;
+  /** Draw the stroke with a dash pattern. */
+  dashed?: boolean;
+  /**
+   * Override the canvas color for this polyline's stroke and fill. Falls
+   * back to the canvas's current color when absent.
+   */
+  color?: string;
+}
+/**
+ * A rectangle whose **size is fixed in screen-space** but whose **anchor lives
+ * in document space**. Used for handles and other chrome that must not scale
+ * with viewport zoom.
+ *
+ * The anchor `(x, y)` is the document-space point that maps to one corner (or
+ * center) of the resulting screen-space rect — controlled by `anchor`.
+ *
+ * Default anchor is `"center"` (the doc-space point becomes the rect's center).
+ */
+interface HUDScreenRect {
+  /** Document-space anchor point. */
+  x: number;
+  y: number;
+  /** Screen-space size in CSS px. */
+  width: number;
+  height: number;
+  /** Which point of the rect sits at (x, y). Default: "center". */
+  anchor?: "center" | "tl" | "tr" | "bl" | "br";
+  fill?: boolean;
+  stroke?: boolean;
+  /** Override the canvas color for fill. */
+  fillColor?: string;
+  /** Override the canvas color for stroke. */
+  strokeColor?: string;
+}
+/**
+ * A complete set of draw commands for one frame.
+ *
+ * The HUD clears the canvas and draws everything in this struct each frame.
+ * Callers build a `HUDDraw` from their domain data (snap result, measurement,
+ * guide state, etc.) and hand it to `HUDCanvas.draw()`.
+ */
+interface HUDDraw {
+  lines?: HUDLine[];
+  rules?: HUDRule[];
+  points?: cmath.Vector2[];
+  rects?: HUDRect[];
+  polylines?: HUDPolyline[];
+  /** Screen-space-sized rects anchored to document-space points (handles). */
+  screenRects?: HUDScreenRect[];
+}
+//#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;
+  constructor(canvas: HTMLCanvasElement, options?: HUDCanvasOptions);
+  setColor(color?: string): void;
+  setSize(w: number, h: number): void;
+  setTransform(transform: cmath.Transform): 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;
+  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/snap-guide.d.ts
+/**
+ * Convert a `guide.SnapGuide` (the output of `guide.plot()`) into a
+ * generic {@link HUDDraw} command list.
+ *
+ * Lines pass through directly (HUDLine extends cmath.ui.Line).
+ * Points pass through directly (both are cmath.Vector2).
+ * Rules are destructured from tuples to objects.
+ */
+declare function snapGuideToHUDDraw(sg: guide.SnapGuide | undefined): 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.
+ */
+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 event/cursor.d.ts
+/** 8 cardinal/diagonal resize directions. */
+type ResizeDirection = "n" | "ne" | "e" | "se" | "s" | "sw" | "w" | "nw";
+/** 4 corner positions for rotation handles. */
+type RotationCorner = "nw" | "ne" | "se" | "sw";
+/** Logical cursor icon names — the host maps these to CSS `cursor` values. */
+type CursorIcon = "default" | "pointer" | "move" | "crosshair" | "grab" | "grabbing" | "text" | {
+  kind: "resize";
+  direction: ResizeDirection;
+} | {
+  kind: "rotate";
+  corner: RotationCorner;
+};
+//#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;
+} | {
+  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; /** Bounding rect of the group at gesture start, in document-space. */
+  initial_rect: Rect; /** Anchor (pointer-down) in document-space. */
+  anchor_doc: cmath.Vector2; /** Current rect during the gesture, in document-space. */
+  current_rect: Rect;
+} | {
+  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;
+} | {
+  kind: "endpoint";
+  id: NodeId;
+  endpoint: "p1" | "p2"; /** Current endpoint position in document-space. */
+  pos_doc: cmath.Vector2;
+};
+//#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. */
+  rect: Rect;
+  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;
+} | {
+  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;
+} | {
+  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 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.
+ * - **`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: "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 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;
+}
+//#endregion
+//#region surface/surface.d.ts
+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;
+  /** 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;
+}
+/**
+ * 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;
+  private width;
+  private height;
+  constructor(canvas: HTMLCanvasElement, options: SurfaceOptions);
+  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;
+  setStyle(partial: Partial<HUDStyle>): 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;
+  modifiers(): Modifiers;
+}
+//#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 rect.
+ * - `rotate_handle` — one of 4 virtual rotation regions outside the group's
+ *   corners. Carries the group's initial rect for center math.
+ * - `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_rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+} | {
+  kind: "rotate_handle";
+  corner: RotationCorner;
+  ids: readonly NodeId[];
+  initial_rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+} | {
+  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[];
+};
+//#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;
+};
+/**
+ * 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;
+} /** 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;
+};
+/**
+ * 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).
+ * - **Cursor hover** is driven by the element's `cursor` field when the
+ *   pointer enters its hit region.
+ */
+interface OverlayElement {
+  action: OverlayAction;
+  hit: HitShape;
+  render?: RenderShape;
+  cursor?: CursorIcon;
+}
+//#endregion
+export { HUDPolyline as A, marqueeToHUDDraw as C, HUDCanvasOptions as D, HUDCanvas as E, HUDRule as M, HUDScreenRect as N, HUDDraw as O, lassoToHUDDraw as S, snapGuideToHUDDraw as T, Modifiers as _, RenderShape as a, SurfaceEvent as b, HUDStyle as c, Intent as d, IntentPhase as f, RotationCorner as g, ResizeDirection as h, OverlayElement as i, HUDRect as j, HUDLine as k, SelectionGroup as l, CursorIcon as m, MIN_CHROME_VISIBLE_SIZE as n, Surface as o, SurfaceGesture as p, MIN_HIT_SIZE as r, SurfaceOptions as s, HitShape as t, SelectionShape as u, NO_MODS as v, measurementToHUDDraw as w, SurfaceResponse as x, PointerButton as y };