@grida/hud 0.1.0 → 0.2.0

package/dist/{index-CBqCh-ZM.d.mts → index-Cp0X4SV7.d.ts}

@@ -1,13 +1,19 @@
-import { Measurement } from "@grida/cmath/_measurement";
+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 {
+interface HUDLine extends cmath.ui.Line, HUDSemantic {
   dashed?: boolean;
   /** Stroke width in screen-space CSS px. Defaults to the canvas default. */
   strokeWidth?: number;
@@ -16,6 +22,13 @@ interface HUDLine extends cmath.ui.Line {
    * 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.
@@ -26,16 +39,37 @@ interface HUDLine extends cmath.ui.Line {
  *
  * Offset is in document space; the renderer projects it to screen.
  */
-interface HUDRule {
+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 {
+interface HUDRect extends HUDSemantic {
   x: number;
   y: number;
   width: number;
@@ -61,7 +95,7 @@ interface HUDRect {
  *
  * Stroke uses the canvas color by default. Fill is opt-in.
  */
-interface HUDPolyline {
+interface HUDPolyline extends HUDSemantic {
   points: cmath.Vector2[];
   /** Whether to stroke the path (default: true). */
   stroke?: boolean;
@@ -87,7 +121,7 @@ interface HUDPolyline {
  *
  * Default anchor is `"center"` (the doc-space point becomes the rect's center).
  */
-interface HUDScreenRect {
+interface HUDScreenRect extends HUDSemantic {
   /** Document-space anchor point. */
   x: number;
   y: number;
@@ -102,6 +136,14 @@ interface HUDScreenRect {
   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.
@@ -113,13 +155,43 @@ interface HUDScreenRect {
 interface HUDDraw {
   lines?: HUDLine[];
   rules?: HUDRule[];
-  points?: cmath.Vector2[];
+  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;
@@ -143,10 +215,22 @@ declare class HUDCanvas {
   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).
@@ -172,16 +256,29 @@ declare class HUDCanvas {
   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.
  *
- * Lines pass through directly (HUDLine extends cmath.ui.Line).
- * Points pass through directly (both are cmath.Vector2).
- * Rules are destructured from tuples to objects.
+ * `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): HUDDraw | undefined;
+declare function snapGuideToHUDDraw(sg: guide.SnapGuide | undefined, color?: string): HUDDraw | undefined;
 //#endregion
 //#region primitives/measurement-guide.d.ts
 /**
@@ -281,19 +378,57 @@ interface SurfaceResponse {
   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;
+//#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: "rotate";
-  corner: RotationCorner;
+  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
 /**
@@ -333,10 +468,15 @@ type SurfaceGesture = {
 } | {
   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;
+  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[];
@@ -344,6 +484,14 @@ type SurfaceGesture = {
   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;
@@ -384,8 +532,20 @@ type Intent = {
 } | {
   kind: "resize"; /** Member ids of the group being resized (1 or more). */
   ids: NodeId[];
-  anchor: ResizeDirection; /** Target rect in document-space. */
+  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). */
@@ -424,48 +584,6 @@ type IntentHandler = (intent: Intent) => void;
  */
 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.
@@ -491,92 +609,6 @@ interface HUDStyle {
   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.
@@ -588,9 +620,12 @@ declare class Surface {
  *
  * - `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.
+ *   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 rect for center math.
+ *   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.
@@ -606,22 +641,12 @@ type OverlayAction = {
   kind: "resize_handle";
   direction: ResizeDirection;
   ids: readonly NodeId[];
-  initial_rect: {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-  };
+  initial_shape: SelectionShape;
 } | {
   kind: "rotate_handle";
   corner: RotationCorner;
   ids: readonly NodeId[];
-  initial_rect: {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-  };
+  initial_shape: SelectionShape;
 } | {
   kind: "endpoint_handle";
   endpoint: "p1" | "p2";
@@ -673,6 +698,23 @@ type HitShape =
 | {
   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
@@ -691,6 +733,12 @@ type RenderShape = /** Screen-space sized rect at doc anchor — e.g. resize kno
   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;
@@ -721,14 +769,179 @@ type RenderShape = /** Screen-space sized rect at doc anchor — e.g. resize kno
  *   `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.
+ *
+ * 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
-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 };
+//#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 };