@grida/svg-editor 1.0.0-alpha.13 → 1.0.0-alpha.15

package/README.md

@@ -51,7 +51,15 @@ Internally, the editor wraps the parsed SVG in a **typed element IR**: a per-nod
 
 The IR is a **typed view, not alternative storage**. The parsed AST remains the in-memory store; file bytes remain the source of truth; the parse-side source-position trivia store carries whitespace, attribute order, and unknown-namespace content. The IR is rebuilt from the AST on every load and discarded on `dispose`. P1 round-trip stands.
 
-This is consistent with the "Not a private IR" anti-goal below — that anti-goal rejects alternative on-disk format and bytes-projected-from-IR storage, neither of which this is. Design: `docs/wg/feat-svg-editor/element-ir.md`. Migration sketch: `docs/wg/feat-svg-editor/element-ir-migration.md`.
+This is consistent with the "Not a private IR" anti-goal below — that anti-goal rejects alternative on-disk format and bytes-projected-from-IR storage, neither of which this is. Design: [`docs/wg/feat-svg-editor/element-ir.md`](https://grida.co/docs/wg/feat-svg-editor/element-ir). The phased migration sketch lands with the implementation slice.
+
+### Defined terms
+
+The editor's design docs use capitalised terms with precise meanings. The one most often referenced in everyday review:
+
+- **[Policy Class](https://grida.co/docs/wg/feat-svg-editor/glossary/policy-class)** — the minimal partition of editable elements such that every editing intent admits the same set of legal solutions within a class. `<circle>` and `<ellipse>` are different Policy Classes because their resize solution spaces fork differently, even though both are conics. The unit at which a host's policy decision (refuse / native / promote / via-transform) maps onto. When a design discussion asks "should X and Y be treated the same?" — apply the Policy Class fork test, not authoring intuition.
+
+Full glossary: [`docs/wg/feat-svg-editor/glossary/`](https://github.com/gridaco/grida/tree/main/docs/wg/feat-svg-editor/glossary/).
 
 ## Principles
 
@@ -163,13 +171,34 @@ const editor = createSvgEditor({
 });
 ```
 
-`createSvgEditor` is the only constructor. The returned `SvgEditor` is the only object consumers ever hold.
+`createSvgEditor` is the only **editor** constructor. The returned `SvgEditor` is the only editor instance consumers ever hold. A small set of Layer-A geometry primitives (see [Geometry primitives](#geometry-primitives) below) is also exported for callers that need canonical SVG geometry without mounting an editor — those are not editor instances and have no lifecycle.
 
 The editor core is **headless**. It parses the SVG, owns the document IR, accepts commands, and emits state — but it does not import, reference, or call into `window`, `document`, `HTMLElement`, or any DOM type. To render or take input, the host attaches a `Surface` (next section).
 
+### Geometry primitives
+
+A small set of Layer-A primitives is exported for callers that want canonical SVG geometry without mounting an editor. These are not part of the editor lifecycle, do not subscribe, and do not produce diffs against an `SvgDocument` — they are pure value classes over the bytes you hand them.
+
+#### `PathModel`
+
+Models a single SVG path's vector network for callers that want path geometry without an editor. Construct from a `d` string, observe vertex/segment shape, compute a bbox, serialize back to `d`. No editor, no document, no DOM.
+
+```ts
+import { PathModel } from "@grida/svg-editor";
+
+const m = PathModel.fromSvgPathD("M 10 10 L 100 10 L 100 100 Z");
+m.vertexCount(); // 3
+m.segmentCount(); // 3
+m.snapshot(); // { vertices, segments } — POJO
+m.bbox(); // { x, y, width, height }
+m.toSvgPathD(); // canonical d
+```
+
+`@experimental` — the externally-stable contract for v0 is construction (`fromSvgPathD`) plus `snapshot()` / `bbox()` / `vertexCount()` / `segmentCount()` / `toSvgPathD()`. Mutation methods on the class exist for the editor's internal use and are not part of the documented public surface.
+
 ### Surface
 
-A `Surface` is the host-provided rendering and input boundary. The editor pushes paint instructions and HUD descriptors to the surface; the surface pushes normalized input events back. Non-DOM hosts (React Native, worker-side renderer, headless test harness) implement the `Surface` interface themselves. The shipped `domSurface` is the reference implementation used by the React layer.
+A `Surface` is the host-provided rendering and input boundary. The shipped `domSurface` is the reference implementation used by the React layer; non-DOM hosts (React Native, worker-side renderer, headless test harness) would implement the same interface — though only one implementation exists today (P6: public only after dogfooding).
 
 ```ts
 import { attach_dom_surface } from "@grida/svg-editor/dom";
@@ -179,29 +208,32 @@ const handle = attach_dom_surface(editor, { container });
 handle.detach();
 ```
 
-The contract (full surface contract documented separately — out of scope for this README):
+The v0 contract is pure lifecycle:
 
 ```ts
 interface Surface {
-  // editor → surface: paint the document + HUD overlay
-  paint(snapshot: SurfacePaintSnapshot): void;
-
-  // surface → editor: hit-test on screen pixel
-  hit_test(x: number, y: number): NodeId | null;
-
-  // surface → editor: subscribe to normalized input
-  on_input(listener: (event: SurfaceInputEvent) => void): Unsubscribe;
-
+  /** Teardown: detach listeners, drop retained refs. Called from
+   *  `editor.detach()` and `editor.dispose()`. */
   dispose(): void;
 }
 ```
 
+What's deliberately **not** part of the contract yet:
+
+- **Paint push.** There is no `paint(snapshot)` channel. The surface re-serializes the document by subscribing to the editor and writing to its own rendering target.
+- **Normalized input events.** Input routing is surface-private — the DOM surface attaches pointer/keyboard listeners on its own container and reaches the editor through the in-package `_internal` channel.
+- **Hit-testing.** Picking is surface-private: the DOM surface owns its own pointer → node-id resolver against its rendered scene. World-space geometry queries (`bounds_of`, `node_at_point` for non-pointer callers) route through `editor.geometry` instead. A cross-surface `hit_test` contract is deferred until a second surface needs one — its shape (screen vs. world units, z-order tie-breaks, hit-record vs. id) isn't pinned.
+
+Each will become a public seam when a second surface implementation arrives and pins its shape. Until then, exporting `paint(snapshot: unknown)` / `on_input(event: unknown)` / `hit_test(x, y)` would be contracts a foreign implementer cannot honestly satisfy (P6 — public only after dogfooding).
+
 Geometry (world-space bboxes, screen ↔ local projection) is exposed via `editor.geometry`, not the `Surface` itself — the DOM surface registers a `MemoizedGeometryProvider` with the editor on attach so headless callers can query bounds without going through the surface.
 
 `@grida/svg-editor/dom` exports `attach_dom_surface(editor, { container, ... })` as the default DOM implementation, plus the surface-scoped types (`Camera`, `Gestures`, `SnapOptions`, `MemoizedGeometryProvider`, `DomComputedResolver`) that callers writing alternative surfaces or advanced integrations may need. It mounts the SVG into the container, wires pointer / keyboard listeners scoped to that container, and uses native `getBBox` / `getScreenCTM` for geometry. It is the only place in this package that imports DOM types.
 
 The container is **exclusively owned** by the surface. Render toolbars, layer lists, inspectors, and any other interactive chrome as **siblings** of the container, not children. Children of the container interfere with pointer routing (capture redirects, hit-test ordering) and produce silent click breakage. The shipped `SvgEditorCanvas` React component enforces this by creating its own internal div; hosts using `domSurface` / `keynote.attach` directly are responsible for the same discipline. In development, the surface emits a `console.warn` at attach time when the container is non-empty.
 
+**Attention gate.** The DOM surface installs document- and window-level keydown listeners (so a user with focus on a side-panel button can still hit editor shortcuts while the pointer is on the canvas). Those listeners are gated by an internal attention predicate: a key is claimed (and `preventDefault()`-ed) only when **focus is inside the container's subtree OR the pointer is over the container**. Body-focus alone — the natural state when the surface is embedded as a block in a longer document — is not attended, so the editor stays out of the way of page-level shortcuts (Space / arrows to scroll, Cmd+= to zoom, etc.). Passive observation listeners (modifier mirrors, blur resets) are not gated — they don't call `preventDefault()` and need to stay live across focus boundaries.
+
 ### Lifecycle
 
 ```ts
@@ -217,9 +249,32 @@ editor.dispose(): void; // permanent teardown
 ```ts
 editor.load(svg: string): void; // replace the document (e.g. file-on-disk changed)
 editor.serialize(): string; // emit clean SVG — guaranteed round-trip per P1
+editor.serialize_node(id: NodeId): string; // emit ONE element's subtree — a fragment, see below
 editor.reset(): void; // back to last load() input, clears history
 ```
 
+`serialize_node(id)` exports the markup of a single element — the bridge from
+"what the user selected" (a `NodeId`) to "the SVG for that element," e.g. to
+hand a downstream consumer (an AI agent) the selected subtree without
+re-serializing the whole document. It reuses `serialize()`'s trivia-preserving
+rules (attribute order, quotes, whitespace, comments — emitted as authored).
+
+It is deliberately **weaker** than `serialize()`, and the two must not be
+conflated: `serialize()` emits the whole document and carries the P1
+round-trip guarantee; `serialize_node()` emits a **fragment** and does not.
+Namespace declarations that live on an ancestor (`xmlns:xlink` and friends,
+normally on the root `<svg>`) are **not** inlined into the fragment — a node
+using `xlink:href` serializes without `xmlns:xlink`. The fragment is the
+element's markup as authored, not a standalone parseable document. Throws on
+an unknown id or a non-element node (selections are always elements).
+
+> A stable reference to a node that survives a `load()` — and survives an
+> external rewrite of the file — is a separate, unsolved problem (`NodeId`
+> regenerates on each parse). Positional child-index paths address only the
+> deterministic-re-parse case, not structural edits; durable node identity is
+> under design — see
+> [durable node identity](https://grida.co/docs/wg/feat-svg-editor/durable-node-identity).
+
 ### Observation — state
 
 ```ts
@@ -498,18 +553,23 @@ editor.tree(): {
 
 Returns a shallow snapshot. Cheap to call after a `version` bump.
 
-### Modes
+### Modes and tools
+
+"What does a click do" is governed by **two orthogonal axes**, both editor-internal — consumers observe them and flip them via commands, but cannot define new values for either.
 
-Modes are the editor's internal state machine for "what does a click do." Consumers observe `state.mode`, flip it via commands, but cannot define new modes.
+- **`Mode`** — what the editor is _doing_. Two values: `select` (normal interaction — pick / marquee / drag) and `edit-content` (inline text edit, or vector content edit on a path).
+- **`Tool`** — what pointer-down _means_ within the current mode. `cursor` (the default — select / marquee / drag), `insert` (a tag — pointer-down draws a new element of that tag, drag-to-size), `insert-text` (click-only — places a single-line `<text>` and enters content-edit immediately; `<text>` has no intrinsic size so it doesn't drag-to-size), and the content-edit-only `lasso` / `bend` (valid only while `mode === "edit-content"` on a path).
 
 ```ts
-editor.modes: ReadonlyArray<Mode>; // discoverable, frozen after construction
-// e.g. ["select", "insert-rect", "insert-ellipse", "insert-line", "insert-text", "edit-content"]
+editor.modes: ReadonlyArray<Mode>; // discoverable, frozen after construction — ["select", "edit-content"]
+editor.state.mode: Mode;
+editor.state.tool: Tool;
 
 editor.commands.set_mode(mode: Mode): void;
+editor.set_tool(tool: Tool): void; // also dispatchable as the `tool.set` command (keymap V/R/O/L/T)
 ```
 
-When a mode-driven gesture completes (rect drawn, text inserted), the editor returns to `select` automatically. Modifier keys can override this (Shift to stay in insert mode); that behavior is bundled, not customizable.
+When a tool-driven gesture completes (a shape is drawn, a text element placed), the tool reverts to `cursor` automatically. Modifier keys can override this (e.g. hold to stay in the insert tool); that behavior is bundled, not customizable.
 
 ### Commands
 
@@ -558,9 +618,11 @@ editor.commands.{
   group(): void;                      // wrap selection in a new <g>
   remove(): void;
 
-  // insertion
-  insert(tag: InsertableTag, attrs?: Readonly<Record<string, string>>): NodeId;
-  insert_preview(tag: InsertableTag, initial?: Readonly<Record<string, string>>): InsertPreviewSession;
+  // insertion — `tag` is an open string (so paste / RPC can create any element,
+  // e.g. "path"); only the closed `InsertableTag` set gets a pointer-driven
+  // draw gesture and default paint.
+  insert(tag: string, attrs?: Readonly<Record<string, string>>): NodeId;
+  insert_preview(tag: string, initial?: Readonly<Record<string, string>>): InsertPreviewSession;
 
   // content
   set_text(value: string): void;
@@ -654,25 +716,25 @@ These are not internals to be replaced — they're documented sugar over `useEdi
 ```tsx
 import {
   // state slices (one-line wrappers over useEditorState)
-  useSelection,        // → readonly NodeId[]
-  useTool,             // → Tool
-  useMode,             // → Mode
-  useCanUndo,          // → boolean
-  useCanRedo,          // → boolean
+  useSelection, // → readonly NodeId[]
+  useTool, // → Tool
+  useMode, // → Mode
+  useCanUndo, // → boolean
+  useCanRedo, // → boolean
 
   // lifecycle-aware preview sessions — unmount = discard (never commit)
-  usePaintPreview,     // (channel) → PaintPreviewSession
-  usePropertyPreview,  // (name) → PreviewSession
+  usePaintPreview, // (channel) → PaintPreviewSession
+  usePropertyPreview, // (name) → PreviewSession
 
   // bound imperative actions, stable identity across renders
-  useEditorLoad,       // → (svg: string) => void
-  useEditorSerialize,  // → () => string
+  useEditorLoad, // → (svg: string) => void
+  useEditorSerialize, // → () => string
 
   // RAII hover override (clears on unmount if this hook set the override)
-  useHoverOverride,    // → (id: NodeId | null) => void
+  useHoverOverride, // → (id: NodeId | null) => void
 
   // camera bridge (subscribe to a slice of handle.camera without bumping state.version)
-  useCameraSnapshot,   // (handle, selector, fallback) → T
+  useCameraSnapshot, // (handle, selector, fallback) → T
 } from "@grida/svg-editor/react";
 ```
 
@@ -701,25 +763,27 @@ Everything else is consumer-built against the editor's API. The two patterns:
 
 ```tsx
 function Toolbar() {
-  const mode = useEditorState((s) => s.mode);
-  const cmd = useCommands();
+  // Insertion is the `Tool` axis, not `Mode` — `Mode` is only
+  // "select" / "edit-content". Flip tools via `editor.set_tool(...)`.
+  const tool = useEditorState((s) => s.tool);
+  const editor = useSvgEditor();
   return (
     <>
       <ToolButton
-        active={mode === "select"}
-        onClick={() => cmd.set_mode("select")}
+        active={tool.type === "cursor"}
+        onClick={() => editor.set_tool({ type: "cursor" })}
       >
         ↖
       </ToolButton>
       <ToolButton
-        active={mode === "insert-rect"}
-        onClick={() => cmd.set_mode("insert-rect")}
+        active={tool.type === "insert" && tool.tag === "rect"}
+        onClick={() => editor.set_tool({ type: "insert", tag: "rect" })}
       >
         ▭
       </ToolButton>
       <ToolButton
-        active={mode === "insert-text"}
-        onClick={() => cmd.set_mode("insert-text")}
+        active={tool.type === "insert-text"}
+        onClick={() => editor.set_tool({ type: "insert-text" })}
       >
         T
       </ToolButton>
@@ -821,9 +885,14 @@ If a consumer needs any of the above, the right answer is "this is the wrong too
 
 ## Status
 
-- `v0.0.0` — selection only, no mutation.
+- `v0.x` — selection, transform, insert (rect / ellipse / line), inline text
+  edit, and the click-to-place text tool. Experimental.
+
+The shape of the API, the mental model, the file-format guarantees, and the scope are all unsettled. Nothing here is stable — public types still in flux include the `Tool` union (a planned axis split, see `TODO.md` F2). Do not depend on it from production code.
+
+## Contributing
 
-The shape of the API, the mental model, the file-format guarantees, and the scope are all unsettled. Nothing here is stable. Do not depend on it from production code.
+- [`TODO.md`](./TODO.md) — open questions and deferred work, grouped by area.
 
 ## License
 

package/dist/dom-CK6GlgFF.d.mts

@@ -0,0 +1,114 @@
+import { c as SvgEditor, p as Gestures, s as SurfaceHandle, w as Camera } from "./editor-Dl7c0q5A.mjs";
+import cmath from "@grida/cmath";
+import { guide } from "@grida/cmath/_snap";
+
+//#region src/core/snap/options.d.ts
+type SnapOptions = {
+  /** When false, snap behavior and snap-guide rendering are both off. */enabled: boolean;
+  /** Snap threshold in HUD canvas pixels (container CSS px in svg-editor;
+   *  whatever space the consumer feeds in). Constant across zoom because
+   *  the input rects are already in screen-equivalent units. */
+  threshold_px: number;
+};
+declare const DEFAULT_SNAP_OPTIONS: SnapOptions;
+//#endregion
+//#region src/dom.d.ts
+type DomSurfaceOptions = {
+  /** Mount the SVG inside this container. */container: HTMLElement;
+  /**
+   * Install the default gesture set (wheel-pan/zoom, space-drag, middle-mouse,
+   * keyboard zoom). Default `true`. Pass `false` to start blank and bind à la
+   * carte via `handle.gestures.bind(...)`.
+   */
+  gestures?: boolean;
+  /**
+   * Auto-fit the document into the viewport on initial attach. Default
+   * `false`. Mirrors Excalidraw's `initialData.scrollToContent`.
+   * Subsequent `editor.load()` calls do NOT re-fit — call
+   * `handle.camera.fit("<root>")` yourself if you want that behavior.
+   */
+  fit?: boolean;
+  /**
+   * Initial camera transform. Default `cmath.transform.identity`. Ignored
+   * when `fit: true`.
+   */
+  initial_camera?: cmath.Transform;
+};
+/**
+ * Surface handle for the DOM surface. Extends the editor's core
+ * `SurfaceHandle` with the viewport-scoped concerns: pan/zoom (`camera`)
+ * and pointer/wheel/keyboard gesture bindings (`gestures`).
+ *
+ * Camera + gestures are **surface-scoped**: detaching the surface drops
+ * both. They never appear on the headless `SvgEditor`.
+ */
+type DomSurfaceHandle = SurfaceHandle & {
+  camera: Camera;
+  gestures: Gestures;
+};
+/**
+ * Attach a DOM surface to a headless editor. Returns a `DomSurfaceHandle`
+ * whose `detach()` is the inverse — DOM cleared, listeners removed,
+ * gestures uninstalled.
+ *
+ * Usage is one-shot per container: the surface owns the container's children
+ * for its lifetime, and `detach()` restores it to empty.
+ */
+declare function attach_dom_surface(editor: SvgEditor, options: DomSurfaceOptions): DomSurfaceHandle;
+/**
+ * Affine projection of a point through a 2×3 CTM, then offset by a
+ * container origin (in page CSS-px). Mirrors how `line_endpoints_in_container`
+ * and `shape_of` (transformed branch) bridge from local SVG coords to the
+ * HUD's container-CSS-px space (HUD keeps its own transform at identity;
+ * the SVG carries the camera as a CSS transform, which getScreenCTM
+ * folds in).
+ *
+ * Exported for headless test coverage — pure function, no DOM types.
+ */
+declare function project_point_through_ctm(px: number, py: number, ctm: {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  e: number;
+  f: number;
+}, container_offset: readonly [number, number]): [number, number];
+/**
+ * Inverse of the CTM's linear part applied to a delta vector. Drops
+ * translation. Used to convert a HUD-reported container-space drag delta
+ * back to the path's local coord space for `PathModel.translateVertices`.
+ *
+ * Throws on a degenerate (det = 0) matrix — the caller is expected to
+ * have a non-singular CTM for any visible element.
+ */
+declare function project_delta_inverse_ctm(dx: number, dy: number, ctm: {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+}): [number, number];
+/**
+ * Inverse-project a doc-space rect through a CTM + container offset back
+ * into the element's local frame. The output is the AABB of the four
+ * inverse-projected corners — when the CTM has a rotation component the
+ * AABB is an approximation, but it matches what the user visually
+ * expects from a screen-aligned marquee drag.
+ *
+ * Returns `null` when the CTM's linear part is singular (degenerate
+ * camera) — the caller should skip any test that needs the local rect.
+ */
+declare function inverse_project_rect(rect: {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}, ctm: {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  e: number;
+  f: number;
+}, offset: readonly [number, number]): cmath.Rectangle | null;
+//#endregion
+export { project_delta_inverse_ctm as a, SnapOptions as c, inverse_project_rect as i, DomSurfaceOptions as n, project_point_through_ctm as o, attach_dom_surface as r, DEFAULT_SNAP_OPTIONS as s, DomSurfaceHandle as t };

package/dist/dom-CsKXTaNw.d.ts

@@ -0,0 +1,112 @@
+import { c as SvgEditor, p as Gestures, s as SurfaceHandle, w as Camera } from "./editor-BKoo9SPL.js";
+import cmath from "@grida/cmath";
+//#region src/core/snap/options.d.ts
+type SnapOptions = {
+  /** When false, snap behavior and snap-guide rendering are both off. */enabled: boolean;
+  /** Snap threshold in HUD canvas pixels (container CSS px in svg-editor;
+   *  whatever space the consumer feeds in). Constant across zoom because
+   *  the input rects are already in screen-equivalent units. */
+  threshold_px: number;
+};
+declare const DEFAULT_SNAP_OPTIONS: SnapOptions;
+//#endregion
+//#region src/dom.d.ts
+type DomSurfaceOptions = {
+  /** Mount the SVG inside this container. */container: HTMLElement;
+  /**
+   * Install the default gesture set (wheel-pan/zoom, space-drag, middle-mouse,
+   * keyboard zoom). Default `true`. Pass `false` to start blank and bind à la
+   * carte via `handle.gestures.bind(...)`.
+   */
+  gestures?: boolean;
+  /**
+   * Auto-fit the document into the viewport on initial attach. Default
+   * `false`. Mirrors Excalidraw's `initialData.scrollToContent`.
+   * Subsequent `editor.load()` calls do NOT re-fit — call
+   * `handle.camera.fit("<root>")` yourself if you want that behavior.
+   */
+  fit?: boolean;
+  /**
+   * Initial camera transform. Default `cmath.transform.identity`. Ignored
+   * when `fit: true`.
+   */
+  initial_camera?: cmath.Transform;
+};
+/**
+ * Surface handle for the DOM surface. Extends the editor's core
+ * `SurfaceHandle` with the viewport-scoped concerns: pan/zoom (`camera`)
+ * and pointer/wheel/keyboard gesture bindings (`gestures`).
+ *
+ * Camera + gestures are **surface-scoped**: detaching the surface drops
+ * both. They never appear on the headless `SvgEditor`.
+ */
+type DomSurfaceHandle = SurfaceHandle & {
+  camera: Camera;
+  gestures: Gestures;
+};
+/**
+ * Attach a DOM surface to a headless editor. Returns a `DomSurfaceHandle`
+ * whose `detach()` is the inverse — DOM cleared, listeners removed,
+ * gestures uninstalled.
+ *
+ * Usage is one-shot per container: the surface owns the container's children
+ * for its lifetime, and `detach()` restores it to empty.
+ */
+declare function attach_dom_surface(editor: SvgEditor, options: DomSurfaceOptions): DomSurfaceHandle;
+/**
+ * Affine projection of a point through a 2×3 CTM, then offset by a
+ * container origin (in page CSS-px). Mirrors how `line_endpoints_in_container`
+ * and `shape_of` (transformed branch) bridge from local SVG coords to the
+ * HUD's container-CSS-px space (HUD keeps its own transform at identity;
+ * the SVG carries the camera as a CSS transform, which getScreenCTM
+ * folds in).
+ *
+ * Exported for headless test coverage — pure function, no DOM types.
+ */
+declare function project_point_through_ctm(px: number, py: number, ctm: {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  e: number;
+  f: number;
+}, container_offset: readonly [number, number]): [number, number];
+/**
+ * Inverse of the CTM's linear part applied to a delta vector. Drops
+ * translation. Used to convert a HUD-reported container-space drag delta
+ * back to the path's local coord space for `PathModel.translateVertices`.
+ *
+ * Throws on a degenerate (det = 0) matrix — the caller is expected to
+ * have a non-singular CTM for any visible element.
+ */
+declare function project_delta_inverse_ctm(dx: number, dy: number, ctm: {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+}): [number, number];
+/**
+ * Inverse-project a doc-space rect through a CTM + container offset back
+ * into the element's local frame. The output is the AABB of the four
+ * inverse-projected corners — when the CTM has a rotation component the
+ * AABB is an approximation, but it matches what the user visually
+ * expects from a screen-aligned marquee drag.
+ *
+ * Returns `null` when the CTM's linear part is singular (degenerate
+ * camera) — the caller should skip any test that needs the local rect.
+ */
+declare function inverse_project_rect(rect: {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}, ctm: {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  e: number;
+  f: number;
+}, offset: readonly [number, number]): cmath.Rectangle | null;
+//#endregion
+export { project_delta_inverse_ctm as a, SnapOptions as c, inverse_project_rect as i, DomSurfaceOptions as n, project_point_through_ctm as o, attach_dom_surface as r, DEFAULT_SNAP_OPTIONS as s, DomSurfaceHandle as t };