@grida/svg-editor 1.0.0-alpha.1 → 1.0.0-alpha.11

package/dist/editor-Bd4-VCEJ.d.ts

@@ -0,0 +1,1139 @@
+import cmath from "@grida/cmath";
+import { AnyNode } from "@grida/svg/parser";
+import * as _$_grida_history0 from "@grida/history";
+import { SelectMode } from "@grida/hud";
+import { Keybinding, Platform } from "@grida/keybinding";
+
+//#region src/types.d.ts
+/**
+ * Stable identifier for a node in the editor's document model.
+ *
+ * Independent of any backing representation. Generated when the document is
+ * parsed.
+ */
+type NodeId = string;
+type Vec2 = {
+  x: number;
+  y: number;
+};
+type Rect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+type Mode = "select" | "edit-content";
+/**
+ * SVG element tags supported by the insertion subsystem. Closed set; adding
+ * a new insertable tag requires a PR.
+ *
+ * `text` is deliberately out of v1: `<text>` has no intrinsic size and any
+ * usable text-insert UX must immediately mount the inline content-editor on
+ * the new node rather than dropping a placeholder. Reserved for a future PR.
+ */
+type InsertableTag = "rect" | "ellipse" | "line";
+/**
+ * Active tool — orthogonal to `Mode`. `Mode` is what the editor is doing
+ * (interacting normally vs. inline text edit); `Tool` is what pointer-down
+ * does while in `select` mode.
+ *
+ *  - `cursor` (default): pointer-down selects / starts marquee / drags
+ *    selection (existing HUD-driven behavior).
+ *  - `insert`: pointer-down opens an insertion-preview gesture for the
+ *    given tag. Click-no-drag inserts a default-sized node; drag sizes
+ *    the new node. Tool reverts to `cursor` after commit.
+ */
+type Tool = {
+  type: "cursor";
+} | {
+  type: "insert";
+  tag: InsertableTag;
+};
+declare const TOOL_CURSOR: Tool;
+type Provenance = {
+  /** CSS cascade origin (css-cascade-5 §6.2). */origin: "author" | "user_agent"; /** Editor metadata — where in the file the winning declaration lives. */
+  carrier: "presentation_attribute" | "inline_style" | "stylesheet" | "inherited" | "defaulted";
+};
+type InvalidComputedValue = {
+  error: "invalid_at_computed_value_time";
+  reason: string;
+};
+type PropertyValue<T = string | number> = {
+  declared: string | null;
+  computed: T | InvalidComputedValue | null;
+  provenance: Provenance;
+};
+type Color = {
+  kind: "rgb";
+  value: string;
+} | {
+  kind: "current_color";
+};
+type PaintFallback = {
+  kind: "none";
+} | {
+  kind: "color";
+  value: Color;
+};
+type Paint = {
+  kind: "none";
+} | {
+  kind: "color";
+  value: Color;
+} | {
+  kind: "ref";
+  id: string;
+  fallback?: PaintFallback;
+} | {
+  kind: "context_fill";
+} | {
+  kind: "context_stroke";
+};
+type PaintValue = {
+  declared: string | null;
+  computed: Paint | InvalidComputedValue | null;
+  provenance: Provenance;
+};
+type GradientStop = {
+  offset: number;
+  color: string;
+  opacity?: number;
+};
+type LinearGradientDefinition = {
+  kind: "linear";
+  stops: GradientStop[];
+  x1?: number;
+  y1?: number;
+  x2?: number;
+  y2?: number;
+  gradient_units?: "user_space_on_use" | "object_bounding_box";
+  spread_method?: "pad" | "reflect" | "repeat";
+};
+type RadialGradientDefinition = {
+  kind: "radial";
+  stops: GradientStop[];
+  cx?: number;
+  cy?: number;
+  r?: number;
+  fx?: number;
+  fy?: number;
+  gradient_units?: "user_space_on_use" | "object_bounding_box";
+  spread_method?: "pad" | "reflect" | "repeat";
+};
+type GradientDefinition = LinearGradientDefinition | RadialGradientDefinition;
+type GradientEntry = {
+  id: string;
+  definition: GradientDefinition;
+  ref_count: number;
+};
+type EditorStyle = {
+  chrome_color: string;
+  handle_size: number;
+  handle_fill: string;
+  handle_stroke: string;
+  endpoint_dot_radius: number;
+  selection_outline_width: number;
+  /**
+   * Color for measurement guides (distance lines + numeric pills). Distinct
+   * from `chrome_color` so the user can tell at a glance whether something
+   * is selection chrome or a measurement readout.
+   */
+  measurement_color: string; /** `W × H` pill under each selected node, in `chrome_color`. */
+  show_size_meter: boolean;
+  /** Snap to neighbor edges, centers, and equidistant spacing during
+   *  translate. Both behavior and guides are off when `false`. */
+  snap_enabled: boolean;
+  /** Snap activation distance in HUD container pixels. Touch UIs may
+   *  prefer larger (~10–12); precision UIs smaller (~3–4). */
+  snap_threshold_px: number;
+  /** Hit-test tolerance in screen CSS pixels. The picker selects a node
+   *  whose rendered geometry is within this many pixels of the pointer,
+   *  making thin elements (1-px lines, hairline strokes) selectable
+   *  without pixel-perfect aiming. Tolerance is screen-space, not
+   *  world-space — the band stays the same width on screen regardless
+   *  of zoom. `0` disables fat-hit and falls back to elementFromPoint
+   *  exact-pixel selection. */
+  hit_tolerance_px: number;
+  /** Snap-to-pixel-grid quantization for translate. When `true`, every
+   *  translate (drag, nudge, RPC) snaps the agent-union origin to integer
+   *  multiples of `pixel_grid_size` as the final pipeline stage — composes
+   *  on top of snap-to-geometry, which still emits guides as usual. Default
+   *  `false` for SVG-fidelity: SVG paths are unitless and frequently
+   *  fractional; forcing integers would corrupt authored geometry.
+   *
+   *  Naming: this is the *action* flag (snap to the pixel grid). The
+   *  "pixel grid" itself — a visual integer-pixel overlay — is a separate
+   *  feature (see `@grida/canvas-pixelgrid`) and is unrelated. */
+  snap_to_pixel_grid: boolean;
+  /** Quantum size in HUD container pixels (`1` = integer grid). Ignored
+   *  when `snap_to_pixel_grid` is false. */
+  pixel_grid_size: number;
+  /** Show the visual pixel-grid overlay on the HUD. Independent of
+   *  `snap_to_pixel_grid` — this is the *display* flag, that one is the
+   *  *action* flag. The grid is zoom-gated; it only paints at high zoom
+   *  (see `@grida/hud` `setPixelGrid` for the threshold). Default `true`. */
+  pixel_grid: boolean;
+  /** Shift-drag snap step for rotation, in radians. Default π/12 (15°).
+   *  When `null` or `<= 0`, shift-rotate is free (no quantization). */
+  angle_snap_step_radians: number | null;
+};
+declare const DEFAULT_STYLE: EditorStyle;
+type ClipboardProvider = {
+  read(): Promise<string | null>;
+  write(text: string): Promise<void>;
+};
+type FontResolver = {
+  resolve(family: string): Promise<{
+    available: boolean;
+    metrics?: {
+      ascent: number;
+      descent: number;
+      unitsPerEm: number;
+    };
+  }>;
+};
+type FileIOProvider = {
+  openSvg(): Promise<string | null>;
+  saveSvg(svg: string, suggestedName?: string): Promise<void>;
+};
+type Providers = {
+  clipboard?: ClipboardProvider;
+  fonts?: FontResolver;
+  file_io?: FileIOProvider;
+};
+type EditorState = {
+  readonly selection: ReadonlyArray<NodeId>;
+  readonly scope: NodeId | null;
+  readonly mode: Mode;
+  /**
+   * Active tool — orthogonal to `mode`. Default `{ type: "cursor" }`. While
+   * in `select` mode + `insert` tool, pointer-down on the surface starts
+   * an insertion gesture for the configured tag instead of selection.
+   * Switched via `editor.set_tool(...)` or the bundled `tool.set` keymap
+   * (V/R/O/L). Bumps `state.version` only.
+   */
+  readonly tool: Tool;
+  readonly dirty: boolean;
+  readonly can_undo: boolean;
+  readonly can_redo: boolean;
+  /**
+   * Bumps on every editor emission. Use this when you need to react to
+   * any change — selection, history, mutation. NOT a good cache key for
+   * tree-shape views because it fires on attribute writes too (e.g. x/y
+   * during a drag).
+   */
+  readonly version: number;
+  /**
+   * Bumps only when the document's tree shape or display-label-affecting
+   * data changes — node added/removed/reordered, text content, or the
+   * `id` attribute. Stable across pure presentation-attribute writes.
+   *
+   * The right cache key for hierarchy / layers panels: snapshot once per
+   * `structure_version` so a drag doesn't invalidate the tree view.
+   */
+  readonly structure_version: number;
+  /**
+   * Bumps when any change occurs that could shift a node's world-space
+   * bounds — geometry-affecting attribute writes (x, y, d, transform,
+   * font-size, …), text content, or structure (insert/remove). Stable
+   * across pure presentation writes (fill, stroke-color, opacity).
+   *
+   * Cache key for `GeometryProvider` — bounds caches snapshot on this
+   * so a fill-color change doesn't invalidate them.
+   */
+  readonly geometry_version: number;
+  /**
+   * Bumps once per `editor.load(svg)` call. Distinct from
+   * `structure_version` (which bumps on edits too). Starts at 0; the
+   * constructor's initial SVG does NOT count as a load. Use this when
+   * you want to react to "a new document was loaded" — e.g. refit
+   * camera to the new root, reset host-side UI state, clear per-file
+   * scratch — without firing on text edits, reorders, or deletes.
+   *
+   * Monotonic, never resets.
+   */
+  readonly load_version: number;
+};
+type Unsubscribe = () => void;
+type ReorderDirection = "bring_forward" | "send_backward" | "bring_to_front" | "send_to_back";
+type PreviewSession = {
+  update(value: string): void;
+  commit(): void;
+  discard(): void;
+};
+type PaintPreviewSession = {
+  update(paint: Paint): void;
+  commit(): void;
+  discard(): void;
+};
+/**
+ * Preview-bracketed insertion gesture. Returned by
+ * `editor.commands.insert_preview(...)`. The pending node is created and
+ * inserted immediately (so the HUD selection chrome renders); per-frame
+ * geometry writes call `update(attrs)`; `commit()` collapses the gesture
+ * into a single undo step; `discard()` rolls back as if the gesture never
+ * happened.
+ */
+type InsertPreviewSession = {
+  /** The live node, addressable during drag. */readonly id: NodeId;
+  update(attrs: Readonly<Record<string, string>>): void;
+  commit(): void;
+  discard(): void;
+};
+//#endregion
+//#region src/core/camera.d.ts
+/**
+ * Returns world-space bounds for the given target, or `null` when
+ * unresolvable (e.g. empty selection, unknown node id). Implemented by the
+ * surface — the camera itself has no view into the document.
+ *
+ * Only string targets are passed to the resolver — `Rect` targets are
+ * handled by the camera as identity (the rect IS its own bounds).
+ */
+type BoundsResolver = (target: "<root>" | "<selection>" | NodeId) => Rect | null;
+type CameraOptions = {
+  resolve_bounds: BoundsResolver;
+  initial?: cmath.Transform;
+};
+/**
+ * Camera viewport constraint. Discriminated union with `type` so future
+ * variants (`'contain'`, `'pan-region'`) can be added without breaking
+ * existing call sites — each future variant has its own payload shape.
+ *
+ * v1.1 ships only `'cover'`. CSS analogy: `object-fit: cover` — the
+ * bounds rect covers the viewport edge-to-edge. Zoom is lower-bounded
+ * at fit-with-padding; pan is clamped so the bounds always covers the
+ * viewport. Use for slide / page / kiosk UX where the user should
+ * never see past the artwork.
+ */
+type CameraConstraints = {
+  /** Bounds cover viewport (viewport ⊆ bounds). Keynote / slide UX. */type: "cover"; /** World-space rect, or `"<root>"` to resolve via BoundsResolver. */
+  bounds: Rect | "<root>"; /** Screen-pixel breathing room between bounds and viewport edge. */
+  padding?: number;
+  /**
+   * Screen-pixel scroll slack past the bounds edge when zoomed in past fit.
+   * Applies only on axes where the bounds strictly exceed the viewport
+   * (`sw > vp_w` / `sh > vp_h`); the centered branch is unchanged, so a
+   * fitted axis stays locked at center. Hard clamp — no elasticity, no
+   * bounce-back. Default 0 (strict cover behavior). Negative values are
+   * clamped to 0. Values approaching or exceeding the bounds extent are
+   * permitted but produce visually degenerate behavior; the constraint
+   * makes no attempt to cap.
+   */
+  pan_overshoot?: number;
+};
+/**
+ * Surface-scoped pan/zoom state.
+ *
+ * The public shape leads with the peer convention (`center` / `zoom` /
+ * `bounds`) and keeps the matrix as an advanced read. Methods mirror
+ * Figma/Penpot where they overlap.
+ */
+declare class Camera {
+  private _transform;
+  private viewport_w;
+  private viewport_h;
+  private listeners;
+  private resolve_bounds;
+  private _constraints;
+  constructor(opts: CameraOptions);
+  /**
+   * Current viewport constraint, or `null` for free pan/zoom. Set with
+   * `camera.constraints = { type: 'cover', bounds: '<root>', padding: 80 }`
+   * to clamp zoom + pan; assign `null` to clear.
+   *
+   * Constraints are applied synchronously inside `set_transform` (and
+   * `_set_viewport_size`), so every public mutation respects them
+   * automatically — the host never needs to subscribe-and-clamp itself.
+   */
+  get constraints(): CameraConstraints | null;
+  set constraints(c: CameraConstraints | null);
+  /** Underlying 2D affine. World→screen. */
+  get transform(): cmath.Transform;
+  /** Uniform scale factor. 1 = 100 %. */
+  get zoom(): number;
+  /** World-space point currently at viewport center. */
+  get center(): Vec2;
+  /** World-space rectangle visible in the viewport. */
+  get bounds(): Rect;
+  /** Translate the camera by a screen-space delta. */
+  pan(delta_screen: Vec2): void;
+  /**
+   * Multiply zoom by `factor` keeping `origin_screen` fixed in world space.
+   * Used by wheel-zoom-at-cursor and pinch-zoom.
+   */
+  zoom_at(factor: number, origin_screen: Vec2): void;
+  /** Pan so `c` lands at the viewport center. Zoom unchanged. */
+  set_center(c: Vec2): void;
+  /** Set zoom directly; pivot defaults to viewport center. */
+  set_zoom(z: number, pivot_screen?: Vec2): void;
+  /**
+   * Replace the entire transform.
+   *
+   * Idempotent: when the new transform is element-wise equal to the current
+   * one, this is a no-op (no notification fires). This is the seam that
+   * makes external constraint loops (e.g. "subscribe → compute clamped →
+   * set_transform") terminate: the clamp re-emits the same transform on
+   * the second pass, set_transform short-circuits, no recursion.
+   *
+   * When `camera.constraints` is non-null, the input transform is clamped
+   * synchronously before being stored — every public mutation respects the
+   * constraint automatically.
+   */
+  set_transform(t: cmath.Transform): void;
+  /** Viewport size in screen pixels. Read by host code computing constraints. */
+  get viewport_size(): {
+    width: number;
+    height: number;
+  };
+  /**
+   * Fit a target into the viewport.
+   *
+   * - `"<root>"` — the document root's content bounds (host-resolved).
+   * - `"<selection>"` — current editor.state.selection's union bounds.
+   * - `NodeId` — that node's content bounds.
+   * - `Rect` — an explicit world-space rectangle.
+   *
+   * No-ops if the target resolves to `null` (e.g. empty selection) or if
+   * the viewport size is 0 (no container).
+   */
+  fit(target: "<root>" | "<selection>" | NodeId | Rect, opts?: {
+    margin?: number;
+  }): void;
+  /** Snap back to identity. */
+  reset(): void;
+  /**
+   * Subscribe to camera changes. Fires on every mutation. Cheap channel —
+   * does NOT bump `editor.state.version`. Same pattern as
+   * `editor.subscribe_surface_hover`.
+   */
+  subscribe(cb: () => void): Unsubscribe;
+  /** @internal Surface drives this on container resize. */
+  _set_viewport_size(w: number, h: number): void;
+  /** Convert a screen-space point to world-space. */
+  screen_to_world(p: Vec2): Vec2;
+  /** Convert a world-space point to screen-space. */
+  world_to_screen(p: Vec2): Vec2;
+  /**
+   * Apply the current constraint (if any) to a candidate transform.
+   * Pure: returns the clamped result, never mutates state. Returns the
+   * input unchanged when constraints are null / bounds are unresolvable /
+   * viewport is 0.
+   */
+  private apply_constraints;
+  /**
+   * Re-clamp the stored transform against the current constraint. Called
+   * from the `constraints` setter; `_set_viewport_size` has its own
+   * notify-inclusive path.
+   */
+  private reenforce;
+  private notify;
+}
+//#endregion
+//#region src/core/align.d.ts
+type AlignDirection = "left" | "right" | "top" | "bottom" | "horizontal_centers" | "vertical_centers";
+//#endregion
+//#region src/core/document.d.ts
+interface DocumentEvents {
+  /** Fires after any structural mutation. */
+  on_change(fn: () => void): () => void;
+}
+declare class SvgDocument implements DocumentEvents {
+  private nodes;
+  private prolog;
+  private epilog;
+  /** Snapshot of the input string, used for `reset()`. */
+  private source;
+  /** Original parse result, for `reset()`. */
+  private original;
+  readonly root: NodeId;
+  private listeners;
+  /**
+   * Counter that bumps ONLY when something the hierarchy view cares about
+   * changes — tree topology (`insert`/`remove`), text-node content
+   * (`set_text`), or the `id` attribute (which feeds display labels). Pure
+   * presentation-attribute writes (x, y, fill, …) do NOT bump it.
+   *
+   * Why a separate counter: consumers like the layers panel cache snapshots
+   * keyed on this. During a drag, x/y writes fire `emit()` repeatedly but
+   * `structure_version` stays stable, so the panel's snapshot reference
+   * stays the same and React skips the re-render of the whole tree.
+   */
+  private _structure_version;
+  /** Bumps on writes that can shift world-space bounds (`GEOMETRY_ATTRS`,
+   *  `set_text`, `insert`, `remove`). Cache key for `GeometryProvider`;
+   *  see docs/wg/feat-svg-editor/geometry.md. */
+  private _geometry_version;
+  constructor(svg: string);
+  static parse(svg: string): SvgDocument;
+  /** Reload from the original parse, discarding all edits. */
+  reset_to_original(): void;
+  /** Replace document with new svg source (clears edits + history-owned state). */
+  load(svg: string): void;
+  on_change(fn: () => void): () => void;
+  /** See `_structure_version` for what this counter signals. */
+  get structure_version(): number;
+  /** See `_geometry_version` for what this counter signals. */
+  get geometry_version(): number;
+  private emit;
+  /** Notify subscribers — for callers that mutate directly via setAttr/etc. */
+  notify(): void;
+  get(id: NodeId): AnyNode | null;
+  is_element(id: NodeId): boolean;
+  parent_of(id: NodeId): NodeId | null;
+  children_of(id: NodeId): readonly NodeId[];
+  /** Element children only — text/comment/cdata filtered out. */
+  element_children_of(id: NodeId): readonly NodeId[];
+  next_sibling_of(id: NodeId): NodeId | null;
+  next_element_sibling_of(id: NodeId): NodeId | null;
+  tag_of(id: NodeId): string;
+  contains(ancestor: NodeId, descendant: NodeId): boolean;
+  /**
+   * Filter a selection down to its **subtree roots** — drop any id whose
+   * ancestor is also in the input set.
+   *
+   * Mirrors `pruneNestedNodes` in the main canvas editor's query module
+   * ([editor/grida-canvas/query/index.ts:138](../../../../editor/grida-canvas/query/index.ts)) and shares its UX motivation:
+   * when a parent and a descendant are both selected, only the parent
+   * should drive multi-node mutations — otherwise the descendant
+   * accumulates the transform twice (once via the parent's `transform`,
+   * once via its own attribute write). Required for `commands.remove`
+   * (avoids re-attaching detached descendants on undo) and any multi-
+   * member translate path (avoids 2× drift for the Bar-chart marquee
+   * case).
+   *
+   * Order: preserves the input order for retained ids. Duplicates in
+   * the input are not deduplicated — callers are responsible (the
+   * editor's `commands.select` already dedupes).
+   *
+   * Performance: `O(n × depth)`. Builds a `Set` over the input once,
+   * then walks each id's ancestor chain at most once. The main editor's
+   * version is `O(n² × depth)` (per-pair `isAncestor`) — fine at typical
+   * selection sizes (a few dozen), worth winning here for free since
+   * `parent_of` is `O(1)` on our parent-map.
+   */
+  prune_nested_nodes(ids: ReadonlyArray<NodeId>): NodeId[];
+  all_nodes(): readonly NodeId[];
+  all_elements(): readonly NodeId[];
+  find_by_tag(ancestor: NodeId, tag: string): readonly NodeId[];
+  /** Read attribute by local name, optionally namespace-filtered. */
+  get_attr(id: NodeId, name: string, ns?: string | null): string | null;
+  /**
+   * Set / remove an attribute. If the attribute exists, it is mutated in place
+   * (preserving source position). If it doesn't, it's appended.
+   */
+  set_attr(id: NodeId, name: string, value: string | null, ns?: string | null): void;
+  attributes_of(id: NodeId): {
+    name: string;
+    ns: string | null;
+    value: string;
+  }[];
+  get_style(id: NodeId, property: string): string | null;
+  set_style(id: NodeId, property: string, value: string | null): void;
+  get_all_styles(id: NodeId): Array<{
+    property: string;
+    value: string;
+  }>;
+  /**
+   * Whether `id` can be opened in the flat-string text editor.
+   *
+   * v1 contract: the editor only operates on a *single flat text run*. That
+   * means the target must be a `<text>` or `<tspan>` whose direct children
+   * are all text nodes (or it has no children). A `<text>` containing a
+   * `<tspan>` is *not* honestly editable — `text_of` would drop the tspan
+   * content from the editor's view, and a flat-text write would leave the
+   * tspan dangling. Tspan-as-target is fine and well-defined when it's a
+   * leaf; only the host decides whether to route double-click to a tspan
+   * or its parent text.
+   */
+  is_text_edit_target(id: NodeId): boolean;
+  text_of(id: NodeId): string;
+  /** Replace all direct text children with a single text node carrying `value`. */
+  set_text(id: NodeId, value: string): void;
+  insert(id: NodeId, parent: NodeId, before: NodeId | null): void;
+  remove(id: NodeId): void;
+  /** Create a new element node and register it (not yet inserted). */
+  create_element(local: string, opts?: {
+    prefix?: string | null;
+    ns?: string | null;
+  }): NodeId;
+  serialize(): string;
+  private emit_node;
+  private emit_attr;
+}
+//#endregion
+//#region src/core/defs.d.ts
+interface GradientsApi {
+  list(): ReadonlyArray<GradientEntry>;
+  get(id: string): GradientEntry | null;
+  upsert(definition: GradientDefinition, opts?: {
+    id?: string;
+  }): string;
+  remove(id: string): void;
+  subscribe(fn: (entries: ReadonlyArray<GradientEntry>) => void): Unsubscribe;
+}
+type Defs = {
+  gradients: GradientsApi;
+};
+//#endregion
+//#region src/commands/registry.d.ts
+/**
+ * Command registry.
+ *
+ * A passive id-keyed registry of handlers. Built so that:
+ *
+ *  - keybindings (in `src/keymap`) can address commands by stable id;
+ *  - new commands can be added in ONE place (`src/commands/defaults.ts`)
+ *    without growing the public surface of the editor;
+ *  - "one key, many meanings" can be expressed via chain semantics: a
+ *    handler returns `true` if it consumed, `false`/`void` otherwise,
+ *    and the dispatcher tries the next candidate in the chain.
+ *
+ * Handlers are plain closures — they capture whatever editor reference
+ * they need. The registry itself stays unaware of the editor's type,
+ * which avoids a circular type dependency between editor and registry.
+ */
+/** Stable, dotted id for a command, e.g. `"history.undo"`. */
+type CommandId = string;
+/**
+ * A command handler.
+ *
+ * Return `true` if the handler consumed the invocation. Return `false`
+ * or `undefined` to signal "did not apply" — the dispatcher will try
+ * the next candidate registered for the same key.
+ *
+ * Handlers are closures: they capture their editor reference. No
+ * editor parameter is passed — keep handlers self-contained.
+ */
+type CommandHandler = (args?: unknown) => boolean | void;
+declare class CommandRegistry {
+  private readonly map;
+  /**
+   * Register a command. Returns an unregister function. Re-registering
+   * the same id replaces the previous handler (last writer wins).
+   */
+  register(id: CommandId, handler: CommandHandler): () => void;
+  /**
+   * Invoke a command by id. Returns `true` if the handler consumed,
+   * `false` otherwise (including unknown ids and handlers that returned
+   * `false`/`undefined`).
+   */
+  invoke(id: CommandId, args?: unknown): boolean;
+  has(id: CommandId): boolean;
+  /** All registered ids, for debugging / introspection. */
+  ids(): readonly CommandId[];
+}
+//#endregion
+//#region src/keymap/keymap.d.ts
+type KeymapBinding = {
+  /** Declarative key combination. Build with `kb()` / `c()` / `seq()`. */keybinding: Keybinding; /** Command id to invoke on match. */
+  command: CommandId; /** Forwarded as the `args` parameter to the command handler. */
+  args?: unknown; /** Higher priorities run first in the chain. Default 0. */
+  priority?: number;
+  /**
+   * Reserved for V2; not honored by the V1 dispatcher. When added, this
+   * will be evaluated before the handler runs; if false, the binding is
+   * skipped without invoking the handler.
+   */
+  when?: (ctx: unknown) => boolean;
+};
+declare class Keymap {
+  private readonly commands;
+  private readonly platformGetter;
+  /**
+   * Bindings bucketed by canonical chunk-key hash, computed per
+   * `@grida/keybinding`'s `chunkKey`. Each list is the chain for that
+   * key, sorted in dispatch order (priority desc, then registration
+   * order).
+   */
+  private readonly buckets;
+  /** Insert order, so ties on priority are deterministic. */
+  private seq;
+  constructor(commands: CommandRegistry, platformGetter?: () => Platform);
+  /**
+   * Bind a key combination to a command. Returns an unbind function.
+   * The same `Keybinding` can be bound to multiple commands — they will
+   * all be tried in chain order on dispatch.
+   */
+  bind(binding: KeymapBinding): () => void;
+  /**
+   * Remove bindings matching the spec. If both filters are passed, only
+   * bindings that match BOTH are removed.
+   */
+  unbind(spec: {
+    keybinding?: Keybinding;
+    command?: CommandId;
+  }): void;
+  /** All registered bindings, for introspection. Order is not guaranteed. */
+  bindings(): readonly KeymapBinding[];
+  /**
+   * Does the keymap have a binding that matches this event's chord —
+   * regardless of whether any handler would consume it? Hosts use this
+   * to decide whether to swallow the platform's default action (e.g.
+   * `event.preventDefault()` in the browser), so that an advertised
+   * shortcut like `Cmd+G` doesn't fall through to the browser's find
+   * bar even when the binding's handler rejects.
+   *
+   * Pure read; runs no handlers, no side effects. Honors the same
+   * text-input-focused guard `dispatch` uses, so a typing user's
+   * keystroke isn't "claimed" by an unrelated unmodified key.
+   */
+  claims(event: KeyboardEvent): boolean;
+  /**
+   * Match the event against bound chunks, then run candidates in chain
+   * order. Returns `true` on the first handler that consumes; returns
+   * `false` if nothing matched or all matches fell through.
+   *
+   * `dispatch` is browser-agnostic: it does NOT call `preventDefault()`
+   * or touch the event in any way. The host decides what to do with the
+   * platform default — typically `if (keymap.claims(e)) e.preventDefault()`,
+   * which prevents the platform default for advertised shortcuts even
+   * when the chain rejects. See README → `editor.keymap`.
+   */
+  dispatch(event: KeyboardEvent): boolean;
+  /**
+   * Compute the set of canonical hashes a `Keybinding` lights up. A
+   * binding with aliases (multiple sequences) contributes one hash per
+   * single-chunk alias; multi-chunk sequences (chords) are skipped in
+   * V1.
+   */
+  private chunkKeysFor;
+  private has_safe_mod;
+}
+//#endregion
+//#region src/core/geometry.d.ts
+/**
+ * Read-only access to world-space node bounds and hit-tests.
+ *
+ * Implementations should be cheap to call: snap (the main consumer)
+ * will query dozens of nodes per pointermove. The driver wraps SVG
+ * `getBBox` + `getCTM`; the memoizer caches per-`NodeId` to survive
+ * the surface re-rendering the SVG tree every editor tick.
+ */
+interface GeometryProvider {
+  /**
+   * World-space bounding rect for a single node, or `null` when the
+   * node has no rendered geometry (orphan, detached, unsupported tag).
+   */
+  bounds_of(id: NodeId): Rect | null;
+  /**
+   * Bulk read. Missing nodes are simply absent from the result map.
+   * Drivers should be free to batch / parallelize internally.
+   */
+  bounds_of_many(ids: ReadonlyArray<NodeId>): Map<NodeId, Rect>;
+  /**
+   * Ids of nodes whose world-space bounds intersect `rect`. Order is
+   * implementation-defined.
+   */
+  nodes_in_rect(rect: Rect): NodeId[];
+  /**
+   * Topmost node id at world-space point `p`, or `null` when no node
+   * is hit. "Topmost" is defined by the renderer's z-order.
+   */
+  node_at_point(p: Vec2): NodeId | null;
+}
+type GeometrySignals = {
+  /** Fires when tree shape changes (insert/remove/reorder). */subscribe_structure: (cb: () => void) => Unsubscribe; /** Fires when any bounds-affecting change occurs. */
+  subscribe_geometry: (cb: () => void) => Unsubscribe;
+};
+/**
+ * Caches `bounds_of` results keyed on `NodeId`; full-clears on either
+ * `structure_version` or `geometry_version` bump. See docs/wg/feat-svg-editor/geometry.md for
+ * why the cache is load-bearing under the surface's per-tick re-render.
+ */
+declare class MemoizedGeometryProvider implements GeometryProvider {
+  private readonly driver;
+  private readonly unsubscribers;
+  private cache;
+  constructor(driver: GeometryProvider, signals: GeometrySignals);
+  bounds_of(id: NodeId): Rect | null;
+  bounds_of_many(ids: ReadonlyArray<NodeId>): Map<NodeId, Rect>;
+  /**
+   * Pass-through. These are less hot than `bounds_of` (called once per
+   * gesture frame at most) and their result is sensitive to current
+   * viewport state, so caching them would be a footgun.
+   */
+  nodes_in_rect(rect: Rect): NodeId[];
+  node_at_point(p: Vec2): NodeId | null;
+  /** Unsubscribe from both signals. Call on surface detach. */
+  dispose(): void;
+}
+//#endregion
+//#region src/gestures/gestures.d.ts
+/** Stable identifier for a gesture binding. Used by `unbind({ id })`. */
+type GestureId = string;
+/**
+ * Context passed to every installer. Exposes the seams a gesture needs:
+ * the container element to listen on, the camera to mutate, and the
+ * editor for keymap dispatch / state reads.
+ *
+ * Surface authors construct this once at attach; bindings receive it on
+ * every `install(...)` call.
+ */
+type GestureContext = {
+  /** Container element listeners attach to. */container: HTMLElement; /** SVG element being framed by the camera. Useful for hit-testing. */
+  svg_root: () => SVGSVGElement | null; /** HUD canvas overlay; sits on top of the SVG. */
+  hud_canvas: HTMLCanvasElement; /** Camera the binding mutates. */
+  camera: Camera; /** Editor for keymap dispatch / state reads. */
+  editor: SvgEditor; /** Handle for advanced bindings (e.g. wanting `camera.fit("<selection>")`). */
+  handle: SurfaceHandle;
+};
+type GestureBinding = {
+  /** Stable id used by `unbind` / `bindings()`. */id: GestureId;
+  /**
+   * Wire DOM listeners (or any side-effect) needed for this gesture.
+   * Returns the uninstaller — called on `unbind` or surface detach.
+   */
+  install(ctx: GestureContext): () => void;
+};
+/**
+ * Sibling to `Keymap`. Owns a list of installed gesture bindings; each
+ * binding's `install(ctx)` is called eagerly when bound and uninstalled
+ * on `unbind` or surface detach.
+ */
+declare class Gestures {
+  private readonly ctx;
+  private entries;
+  constructor(ctx: GestureContext);
+  /**
+   * Install a gesture binding. Returns an unbind function.
+   * Re-binding the same `id` does NOT replace — both will be active.
+   * Use `unbind({ id })` first if you want a clean swap.
+   */
+  bind(binding: GestureBinding): () => void;
+  /**
+   * Remove bindings matching the spec. With `{ id }`, all bindings with
+   * that id are uninstalled. With no spec, this is a no-op (use
+   * `dispose()` to nuke everything).
+   */
+  unbind(spec: {
+    id?: GestureId;
+  }): void;
+  /** All currently installed bindings. Order is registration order. */
+  bindings(): readonly GestureBinding[];
+  /** @internal Uninstall every binding. Surface calls on detach. */
+  _dispose(): void;
+}
+//#endregion
+//#region src/core/editor.d.ts
+/** Resolved paint from the DOM-attached cascade. `resolved_paint` mirrors the
+ *  shape of `PaintValue.computed` so consumers can treat it uniformly with
+ *  the headless cascade. */
+type DomComputedPaint = {
+  computed: string;
+  resolved_paint: Paint | InvalidComputedValue | null;
+};
+/** Contract the DOM surface implements to delegate cascade resolution to
+ *  `getComputedStyle()`. Registered via `editor._internal.set_computed_resolver`
+ *  on attach. */
+type DomComputedResolver = {
+  computed_property(id: NodeId, name: string): string | null;
+  computed_paint(id: NodeId, channel: "fill" | "stroke"): DomComputedPaint | null;
+};
+type CreateSvgEditorOptions = {
+  svg: string;
+  providers?: Providers;
+  style?: Partial<EditorStyle>;
+};
+type SvgEditor = ReturnType<typeof createSvgEditor>;
+type Surface = {
+  paint(snapshot: unknown): void;
+  hit_test(x: number, y: number): NodeId | null;
+  on_input(listener: (event: unknown) => void): Unsubscribe;
+  dispose(): void;
+};
+type SurfaceHandle = {
+  detach(): void;
+};
+type Commands = {
+  select(target: NodeId | ReadonlyArray<NodeId>, opts?: {
+    mode?: SelectMode;
+  }): void;
+  deselect(): void;
+  /**
+   * Replace the selection with every element-child of the current scope
+   * (or `doc.root` when no scope is entered). Returns `false` when the
+   * scope has no element children — letting the keymap chain fall through
+   * unchanged.
+   */
+  select_all(): boolean;
+  /**
+   * Rotate the selection to the next or previous sibling within the
+   * current single-selection's parent. Wraps at both ends. With an empty
+   * or multi-selection, falls back to selecting the first / last child of
+   * the current scope (so Tab from "nothing selected" picks something).
+   * Returns `false` when no candidate exists (empty scope).
+   */
+  select_sibling(direction: "next" | "prev"): boolean;
+  enter_scope(group: NodeId): void;
+  exit_scope(): void;
+  set_mode(mode: Mode): void;
+  set_property(name: string, value: string | null): void;
+  preview_property(name: string): PreviewSession;
+  set_paint(channel: "fill" | "stroke", paint: Paint): void;
+  preview_paint(channel: "fill" | "stroke"): PaintPreviewSession;
+  set_paint_from_gradient(channel: "fill" | "stroke", definition: GradientDefinition, opts?: {
+    reuse_existing?: boolean;
+  }): {
+    gradient_id: string;
+  };
+  translate(delta: {
+    dx: number;
+    dy: number;
+  }): void;
+  nudge(delta: {
+    dx: number;
+    dy: number;
+  }): void;
+  /**
+   * Map the selection's current union-bbox to `target` as a single atomic
+   * step. Maps width/height/x/y simultaneously — each member scales
+   * around the union NW anchor, then the result is translated so the
+   * union NW lands at `target.{x, y}`. Per-tag constraints (circle
+   * uniform, text edge no-op) execute inside `apply_resize` for each
+   * member.
+   *
+   * The default selection is `state.selection`. Pass `opts.ids` to
+   * override. Members whose tag is not resizable
+   * (e.g. `<g>`) are skipped silently; the gesture is a no-op when no
+   * resizable member remains. Returns `true` when a history step was
+   * pushed.
+   */
+  resize_to(target: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }, opts?: {
+    ids?: ReadonlyArray<NodeId>;
+  }): boolean;
+  /**
+   * Rotate the selection by `angle` radians around the union-bbox center
+   * (or `opts.pivot` if provided). One atomic history step. Returns
+   * `false` and a no-op when any member's transform isn't rotatable (see
+   * `is_rotatable` — refuses non-trivial transforms, `<text rotate>`,
+   * CSS-property transforms, animated transforms).
+   *
+   * Pivot defaults to bbox-center of the live selection via the attached
+   * surface's `geometry_provider`. With no surface attached, the function
+   * uses local-attribute bbox approximations (less precise for transformed
+   * ancestors, but correct for flat docs).
+   */
+  rotate(angle: number, opts?: {
+    ids?: ReadonlyArray<NodeId>;
+    pivot?: {
+      x: number;
+      y: number;
+    };
+  }): boolean;
+  /**
+   * Set the absolute rotation of each member to `angle` radians. Computes
+   * the per-member delta from each baseline's current rotation. Pivot
+   * defaults to union-bbox center. Same refusal semantics as `rotate`.
+   * One atomic history step.
+   */
+  rotate_to(angle: number, opts?: {
+    ids?: ReadonlyArray<NodeId>;
+    pivot?: {
+      x: number;
+      y: number;
+    };
+  }): boolean;
+  /**
+   * Collapse each selected member's `transform=` to a single `matrix(...)`
+   * token, baking accumulated translates / rotates / scales / skews into
+   * the equivalent affine. After flatten, the element's transform list
+   * classifies as `mixed` from the parser's view — but `rotate` will then
+   * refuse it. The point isn't to enable further rotation; it's to give
+   * the user an explicit pre-rotation reset path so accumulated trig
+   * drift has a recovery option.
+   *
+   * Returns `false` when nothing was changed (selection empty or every
+   * member already has no transform / a single matrix).
+   */
+  flatten_transform(opts?: {
+    ids?: ReadonlyArray<NodeId>;
+  }): boolean;
+  /**
+   * Translate each member so its bbox aligns with the requested edge or
+   * center of the selection's union bbox. Single atomic history step.
+   * Refuses (returns `false`) when fewer than two members have a world-
+   * bbox available — alignment with a single reference is undefined here
+   * (target-to-canvas / target-to-parent semantics are not yet designed).
+   */
+  align(direction: AlignDirection, opts?: {
+    ids?: ReadonlyArray<NodeId>;
+  }): boolean;
+  reorder(direction: ReorderDirection): void;
+  remove(): void;
+  /**
+   * Wrap the current selection in a new plain `<g>`. Returns `true` if
+   * the wrap was performed (a history step was pushed and the new group
+   * is the active selection); `false` if the policy in `GROUPING.md`
+   * rejected the call.
+   */
+  group(): boolean;
+  /**
+   * Atomic one-shot insertion. Creates a new element of the given SVG
+   * tag with the supplied attributes (merged on top of the package's
+   * default paint attrs for `rect` / `ellipse` / `line`), inserts it at
+   * the given parent (default: root), and selects it. One undo step.
+   * Returns the new node id.
+   *
+   * Use this for paste, programmatic creation, and any non-pointer
+   * insertion path. The DOM surface's drag-to-size gesture uses
+   * `insert_preview` instead so it can bracket per-frame attr writes.
+   */
+  insert(tag: string, attrs: Readonly<Record<string, string>>, opts?: {
+    parent?: NodeId;
+    index?: number;
+    select?: boolean;
+  }): NodeId;
+  /**
+   * Preview-bracketed insertion for drag-to-size gestures. Creates and
+   * inserts the node immediately (so HUD selection chrome renders);
+   * per-frame `update(attrs)` writes geometry; `commit()` collapses the
+   * gesture into one undo step; `discard()` rolls back as if the gesture
+   * never happened.
+   */
+  insert_preview(tag: string, initial: Readonly<Record<string, string>>, opts?: {
+    parent?: NodeId;
+    index?: number;
+  }): InsertPreviewSession;
+  set_text(value: string): void;
+  load_svg(svg: string): void;
+  serialize_svg(): string;
+  undo(): void;
+  redo(): void;
+  /**
+   * Register a command handler under a stable id. Returns an unregister
+   * function. Re-registering the same id replaces the previous handler.
+   *
+   * Handlers return `true` if they consumed the invocation; `false` or
+   * `undefined` signal "did not apply" — the keymap dispatcher will try
+   * the next candidate in the chain.
+   */
+  register(id: CommandId, handler: CommandHandler): () => void;
+  /**
+   * Invoke a registered command by id. Returns `true` if a handler
+   * consumed the invocation, `false` otherwise (including unknown ids).
+   */
+  invoke(id: CommandId, args?: unknown): boolean; /** Whether an id has a registered handler. */
+  has(id: CommandId): boolean;
+};
+declare function createSvgEditor(opts: CreateSvgEditorOptions): {
+  /**
+   * Low-level IR handle. Mutating directly bypasses history; prefer
+   * `editor.commands` for app code.
+   */
+  document: SvgDocument;
+  readonly state: EditorState;
+  subscribe: (fn: (state: EditorState) => void) => Unsubscribe;
+  subscribe_with_selector: <T>(selector: (s: EditorState) => T, fn: (value: T, prev: T) => void, equals?: (a: T, b: T) => boolean) => Unsubscribe;
+  node_properties: (id: NodeId, names: ReadonlyArray<string>) => {
+    readonly [name: string]: PropertyValue;
+  };
+  node_paint: (id: NodeId, channel: "fill" | "stroke") => PaintValue;
+  dom_computed_property: (id: NodeId, name: string) => string | null;
+  dom_computed_paint: (id: NodeId, channel: "fill" | "stroke") => DomComputedPaint | null;
+  /**
+   * Enter content-edit mode on a `<text>` node. Returns `false` (no-op)
+   * when no DOM surface is attached.
+   */
+  enter_content_edit: (target?: NodeId) => boolean;
+  defs: Defs;
+  commands: Commands;
+  /**
+   * Human-readable label for hierarchy panels. SVG has no native "name";
+   * this is the package's single source of truth so panels don't reinvent
+   * the rule.
+   *
+   * Rule:
+   *   - `<text>` → text content, whitespace-collapsed and truncated at
+   *     ~40 chars (falls back to `"text"` for empty content).
+   *   - Otherwise → tag name, suffixed with `#id` when the `id` attribute
+   *     is present (e.g. `"rect #sun"`).
+   *
+   * `opts.tagLabel` lets callers substitute a friendlier or localized
+   * term for the raw tag (e.g. `"rect"` → `"Rectangle"`). Only invoked
+   * on the non-text branch.
+   */
+  display_label(id: NodeId, opts?: {
+    tagLabel?: (tag: string) => string;
+  }): string;
+  tree(): {
+    root: NodeId;
+    nodes: ReadonlyMap<NodeId, {
+      id: NodeId;
+      tag: string;
+      name?: string;
+      parent: NodeId | null;
+      children: ReadonlyArray<NodeId>;
+    }>;
+  };
+  /**
+   * The effective hover from the attached HUD surface — what's under the
+   * pointer, OR whatever `set_surface_hover_override` last pushed. Used
+   * by out-of-canvas UI (layers panel, breadcrumbs) to mirror the canvas
+   * highlight. Returns `null` when nothing is hovered.
+   */
+  surface_hover(): NodeId | null;
+  /**
+   * Push a hover override into the HUD surface — e.g. when the user
+   * hovers a row in a layers panel. The HUD will render the override's
+   * outline and (when applicable) drive measurement to that node.
+   * Pass `null` to clear and let the pointer pick take over again.
+   */
+  set_surface_hover_override(id: NodeId | null): void;
+  /**
+   * Subscribe to changes in the effective surface hover. Fires when the
+   * HUD reports a new pointer pick AND when an override is set/cleared.
+   * Cheap channel — does NOT bump `state.version`.
+   */
+  subscribe_surface_hover(cb: () => void): () => void;
+  /**
+   * Subscribe to bounds-affecting changes. Fires when any document
+   * mutation advances `state.geometry_version` — drag, resize, text
+   * edit, structural insert/remove. Skips presentation-only writes
+   * (fill, opacity, stroke-color).
+   */
+  subscribe_geometry(cb: () => void): () => void;
+  /**
+   * World-space geometry queries. Non-null when a DOM surface is
+   * attached; null otherwise (queries need a renderer to read bbox
+   * from). Read-only — never mutates document state.
+   */
+  readonly geometry: GeometryProvider | null;
+  modes: readonly Mode[]; /** Switch the active tool. No history entry; bumps `state.version`. */
+  set_tool: (next: Tool) => void;
+  readonly style: Readonly<EditorStyle>;
+  set_style: (partial: Partial<EditorStyle>) => void;
+  load: (svg: string) => void;
+  serialize: () => string;
+  reset: () => void;
+  attach: (surface: Surface) => SurfaceHandle;
+  detach: () => void;
+  dispose: () => void;
+  providers: Providers;
+  _internal: {
+    doc: SvgDocument;
+    history: {
+      preview: (label: string) => _$_grida_history0.Preview;
+    };
+    emit: () => void;
+    /** Fires after a drag-commit (via orchestrator), `commands.nudge`, or
+     *  `commands.translate`. The nudge-dwell watcher subscribes here. */
+    subscribe_translate_commit(cb: () => void): () => void; /** Drag-commit publisher; nudge/translate commands publish directly. */
+    notify_translate_commit: () => void;
+    set_content_edit_driver(fn: ((target: NodeId) => boolean) | null): void;
+    /** Fires the driver immediately with the current override so the
+     *  surface can sync state on attach. */
+    set_surface_hover_override_driver(fn: ((id: NodeId | null) => void) | null): void;
+    push_surface_hover(id: NodeId | null): void;
+    set_computed_resolver(fn: DomComputedResolver | null): void; /** Surface registers its geometry provider on attach; clears on detach. */
+    set_geometry(p: GeometryProvider | null): void;
+  };
+  keymap: Keymap;
+};
+//#endregion
+export { GradientEntry as A, PaintPreviewSession as B, Color as C, FileIOProvider as D, EditorStyle as E, LinearGradientDefinition as F, Providers as G, PreviewSession as H, Mode as I, ReorderDirection as J, RadialGradientDefinition as K, NodeId as L, InsertPreviewSession as M, InsertableTag as N, FontResolver as O, InvalidComputedValue as P, Vec2 as Q, Paint as R, ClipboardProvider as S, EditorState as T, PropertyValue as U, PaintValue as V, Provenance as W, Tool as X, TOOL_CURSOR as Y, Unsubscribe as Z, AlignDirection as _, SelectMode as a, CameraConstraints as b, SvgEditor as c, GestureContext as d, GestureId as f, MemoizedGeometryProvider as g, GeometrySignals as h, DomComputedResolver as i, GradientStop as j, GradientDefinition as k, createSvgEditor as l, GeometryProvider as m, CreateSvgEditorOptions as n, Surface as o, Gestures as p, Rect as q, DomComputedPaint as r, SurfaceHandle as s, Commands as t, GestureBinding as u, BoundsResolver as v, DEFAULT_STYLE as w, CameraOptions as x, Camera as y, PaintFallback as z };