@grida/hud 0.2.0 → 0.2.2

package/dist/index-Cp0X4SV7.d.ts

@@ -1,947 +0,0 @@
-import { i as RotationCorner, n as CursorRenderer, r as ResizeDirection, t as CursorIcon } from "./cursor-CIYvFshz.js";
-import cmath from "@grida/cmath";
-import { guide } from "@grida/cmath/_snap";
-import { Measurement } from "@grida/cmath/_measurement";
-
-//#region primitives/types.d.ts
-type HUDSemanticGroup = string;
-interface HUDSemantic {
-  /** Semantic owner of this primitive, used for group-level visibility policy. */
-  group?: HUDSemanticGroup;
-}
-/**
- * A line segment in document space, extending `cmath.ui.Line` with
- * an optional `dashed` style.
- */
-interface HUDLine extends cmath.ui.Line, HUDSemantic {
-  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;
-  /**
-   * Label rotation in radians (CCW) around the label pill's screen-space
-   * center. Defaults to `0`. Used to make the size meter pill rotate with
-   * a `SelectionShape.transformed` parent. Only affects the pill +
-   * text; the underlying line stroke is unaffected.
-   */
-  labelAngle?: number;
-}
-/**
- * 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 extends HUDSemantic {
-  axis: "x" | "y";
-  offset: number;
-  /**
-   * Override the canvas color for this rule's stroke. Falls back to
-   * the canvas's current color when absent.
-   */
-  color?: string;
-}
-/**
- * A single document-space point rendered as a small crosshair "X" on
- * the canvas. The size of the crosshair is fixed in CSS pixels; the
- * anchor (x, y) is in document space.
- *
- * Stroke uses the canvas color by default. Per-point override is opt-in.
- */
-interface HUDPoint extends HUDSemantic {
-  x: number;
-  y: number;
-  /**
-   * Override the canvas color for this point's crosshair stroke.
-   * Falls back to the canvas's current color when absent.
-   */
-  color?: string;
-}
-/**
- * A rectangle in document space.
- *
- * Stroke uses the canvas color by default. Fill is opt-in.
- */
-interface HUDRect extends HUDSemantic {
-  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 extends HUDSemantic {
-  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 extends HUDSemantic {
-  /** 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;
-  /**
-   * Rotation in radians (CCW) around the rect's screen-space center.
-   * Defaults to `0`. Used to make handle knobs / size badges rotate
-   * together with a `SelectionShape.transformed` parent. Hit-testing is
-   * unaffected — render and hit live on independent shapes per the
-   * package's render/hit-test split (see README).
-   */
-  angle?: number;
-}
-/**
- * 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?: HUDPoint[];
-  rects?: HUDRect[];
-  polylines?: HUDPolyline[];
-  /** Screen-space-sized rects anchored to document-space points (handles). */
-  screenRects?: HUDScreenRect[];
-}
-//#endregion
-//#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 (e.g. `@grida/svg-editor`, which applies the camera as a CSS
-   * transform on the `<svg>` 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/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;
-  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;
-  /**
-   * 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/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.
- */
-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/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;
-} | {
-  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;
-};
-//#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;
-} | {
-  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 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 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[];
-};
-//#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;
-} /** 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).
- *
- * 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;
-}
-//#endregion
-//#region surface/chrome.d.ts
-interface SurfaceChromeGroups {
-  hover?: HUDSemanticGroup;
-  selection?: HUDSemanticGroup;
-  selectionControls?: HUDSemanticGroup;
-  marquee?: HUDSemanticGroup;
-  transformPreview?: HUDSemanticGroup;
-}
-//#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;
-  /** 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 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;
-}
-/**
- * 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 colorOverride;
-  private width;
-  private height;
-  private cursor_renderer;
-  constructor(canvas: HTMLCanvasElement, options: SurfaceOptions);
-  /** 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;
-  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;
-  /**
-   * 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;
-}
-//#endregion
-export { HUDCanvas as A, HUDRect as B, SurfaceEvent as C, measurementToHUDDraw as D, marqueeToHUDDraw as E, PixelGridConfig as F, HUDScreenRect as H, drawPixelGrid as I, HUDDraw as L, DEFAULT_PIXEL_GRID_COLOR as M, DEFAULT_PIXEL_GRID_STEPS as N, snapGuideToHUDDraw as O, DrawPixelGridParams as P, HUDLine as R, PointerButton as S, lassoToHUDDraw as T, HUDSemantic as U, HUDRule as V, HUDSemanticGroup as W, SurfaceGesture as _, SurfaceVisibilityPolicy as a, Modifiers as b, MIN_CHROME_VISIBLE_SIZE as c, RenderShape as d, HUDStyle as f, Rect as g, SelectMode as h, SurfaceVisibilityContext as i, HUDCanvasOptions as j, filterHUDDrawByGroup as k, MIN_HIT_SIZE as l, IntentPhase as m, SurfaceOptions as n, SurfaceChromeGroups as o, Intent as p, SurfaceVisibility as r, HitShape as s, Surface as t, OverlayElement as u, SelectionGroup as v, SurfaceResponse as w, NO_MODS as x, SelectionShape as y, HUDPolyline as z };