@grida/svg-editor 1.0.0-alpha.3 → 1.0.0-alpha.4

package/README.md

@@ -142,7 +142,10 @@ export function FreeFormCanvas({ svg }: { svg: string }) {
   return (
     <SvgEditorProvider svg={svg}>
       <div style={{ position: "relative", width: "100%", height: "100vh" }}>
-        <SvgEditorCanvas onAttach={setHandle} style={{ width: "100%", height: "100%" }} />
+        <SvgEditorCanvas
+          onAttach={setHandle}
+          style={{ width: "100%", height: "100%" }}
+        />
         <div style={{ position: "absolute", bottom: 12, right: 12 }}>
           <button onClick={() => handle?.camera.fit("<root>")}>Fit</button>
           <button onClick={() => handle?.camera.reset()}>100%</button>
@@ -158,91 +161,18 @@ export function FreeFormCanvas({ svg }: { svg: string }) {
 
 The keynote case wants more than "fit on load" — it wants **"the slide is the world"**: no zooming out past fit, no panning when the slide already fills the viewport, and clamped panning when zoomed in so the slide always covers the viewport edge-to-edge.
 
-The package doesn't ship `camera.constraints` at v1 (see [Deferred for v1](#deferred-for-v1)). The recipe is **pure imperative JS** — no React. Camera lifecycle is owned by the DOM surface, not by React render cycles, so the policy lives next to the surface and React is just orchestration glue.
+This bundle ships as a one-import preset at the **`@grida/svg-editor/presets`** subpath. The preset composes the public primitives:
 
-The reusable primitive — `create_slide_constraint(camera)` — installs a `camera.subscribe(...)` that clamps zoom (≥ fit-zoom) and pan (slide always covers the viewport) on every change. `Camera.set_transform` is idempotent, so the subscribe→clamp→set loop converges in one round. Compose it with `editor.subscribe_with_selector(s => s.structure_version, ...)` for refit-on-load:
+1. `attach_dom_surface` with `fit: true` — slide visible on first frame.
+2. `camera.constraints = { type: 'cover', bounds: '<root>', padding }` — typed [camera constraint](#camera-constraints) that clamps zoom + pan.
+3. `editor.subscribe_with_selector(s => s.load_version, () => camera.fit('<root>'))` — refit only on fresh document loads, not on edits.
 
-```ts
-// Pure-JS policy. No React. Construct in onAttach, dispose on detach.
-import cmath from "@grida/cmath";
-import type { Camera, Rect, SvgEditor, Unsubscribe } from "@grida/svg-editor";
-import type { DomSurfaceHandle } from "@grida/svg-editor/dom";
-
-function create_slide_constraint(camera: Camera) {
-  let slide: Rect | null = null;
-  let margin = 0;
-  const enforce = () => {
-    if (!slide) return;
-    const t = camera.transform;
-    const vp = camera.viewport_size;
-    if (vp.width <= 0 || vp.height <= 0) return;
-    const min_zoom = Math.min(
-      (vp.width - 2 * margin) / slide.width,
-      (vp.height - 2 * margin) / slide.height
-    );
-    const s = Math.max(t[0][0], min_zoom);
-    const sw = s * slide.width, sh = s * slide.height;
-    const tx = sw > vp.width
-      ? cmath.clamp(t[0][2], vp.width - s * (slide.x + slide.width), -s * slide.x)
-      : (vp.width - sw) / 2 - s * slide.x;
-    const ty = sh > vp.height
-      ? cmath.clamp(t[1][2], vp.height - s * (slide.y + slide.height), -s * slide.y)
-      : (vp.height - sh) / 2 - s * slide.y;
-    camera.set_transform([[s, 0, tx], [0, s, ty]]);
-  };
-  const unsubscribe = camera.subscribe(enforce);
-  return {
-    set_slide(next: Rect | null) { slide = next; enforce(); },
-    set_margin(next: number) { margin = next; enforce(); },
-    dispose() { unsubscribe(); },
-  };
-}
-
-class KeynotePolicy {
-  private constraint = create_slide_constraint(this.handle.camera);
-  private unsub: Unsubscribe;
-  private margin: number;
-
-  constructor(
-    private editor: SvgEditor,
-    private handle: DomSurfaceHandle,
-    opts: { margin: number }
-  ) {
-    this.margin = opts.margin;
-    this.constraint.set_margin(this.margin);
-    this.refresh();
-    this.unsub = editor.subscribe_with_selector(
-      (s) => s.structure_version,
-      () => this.refresh()
-    );
-  }
-  set_margin(m: number) {
-    this.margin = m;
-    this.constraint.set_margin(m);
-    this.handle.camera.fit("<root>", { margin: m });
-  }
-  private refresh() {
-    const root = this.editor.tree().root;
-    const vb = this.editor.document.get_attr(root, "viewBox")?.split(/[\s,]+/).map(Number);
-    this.constraint.set_slide(
-      vb?.length === 4 && vb.every(Number.isFinite)
-        ? { x: vb[0], y: vb[1], width: vb[2], height: vb[3] }
-        : null
-    );
-    this.handle.camera.fit("<root>", { margin: this.margin });
-  }
-  dispose() { this.unsub(); this.constraint.dispose(); }
-}
-```
-
-React's role drops to: instantiate the policy in `onAttach`, hold it in a ref, dispose on unmount.
+The preset is opt-in by import: the main `@grida/svg-editor` entry never touches `presets/`, so hosts that don't want the bundle aren't paying for it.
 
 ```tsx
-import { useCallback, useEffect, useRef } from "react";
-import {
-  SvgEditorCanvas, SvgEditorProvider, useSvgEditor,
-} from "@grida/svg-editor/react";
-import type { DomSurfaceHandle } from "@grida/svg-editor/dom";
+import { useEffect, useRef, useState } from "react";
+import { SvgEditorProvider, useSvgEditor } from "@grida/svg-editor/react";
+import { keynote, type KeynoteSurfaceHandle } from "@grida/svg-editor/presets";
 
 export function KeynoteCanvas({ svg }: { svg: string }) {
   return (
@@ -254,24 +184,46 @@ export function KeynoteCanvas({ svg }: { svg: string }) {
 
 function KeynoteHost() {
   const editor = useSvgEditor();
-  const policy_ref = useRef<KeynotePolicy | null>(null);
-  const onAttach = useCallback((h: DomSurfaceHandle | null) => {
-    policy_ref.current?.dispose();
-    policy_ref.current = h ? new KeynotePolicy(editor, h, { margin: 80 }) : null;
+  const container_ref = useRef<HTMLDivElement | null>(null);
+  const [handle, setHandle] = useState<KeynoteSurfaceHandle | null>(null);
+
+  // Mount the preset on first render; dispose on unmount. The preset
+  // owns fit-on-attach, the cover constraint, and the load-version refit
+  // subscription — the host writes ~10 lines of React lifecycle, no math.
+  useEffect(() => {
+    const container = container_ref.current;
+    if (!container) return;
+    const h = keynote.attach(editor, { container, padding: 80 });
+    setHandle(h);
+    return () => {
+      setHandle(null);
+      h.detach();
+    };
   }, [editor]);
-  useEffect(() => () => policy_ref.current?.dispose(), []);
+
   return (
     <div style={{ padding: 24, background: "#1f2937", height: "100vh" }}>
-      <SvgEditorCanvas fit onAttach={onAttach} style={{
-        width: "100%", height: "100%",
-        background: "#fff", boxShadow: "0 10px 40px rgba(0,0,0,0.3)",
-      }}/>
+      <div
+        ref={container_ref}
+        style={{
+          width: "100%",
+          height: "100%",
+          background: "#fff",
+          boxShadow: "0 10px 40px rgba(0,0,0,0.3)",
+        }}
+      />
+      {/* Use `handle` for chrome — `useCameraSnapshot(handle, c => c.zoom, 1)`
+          for a zoom badge, `handle.set_padding(0)` for a Present-mode toggle, etc. */}
     </div>
   );
 }
 ```
 
-Both examples ship as live demos at `/canvas/svg` (free-form) and `/canvas/svg/keynote` (constrained) in the dogfood app. Their diff is the spec for what the SDK owes its users: same editor, same camera, same gestures — different host policies layered on top, and the policy itself is plain imperative JS that any framework could reuse.
+The handle is `KeynoteSurfaceHandle = DomSurfaceHandle & { set_padding(p: number): void }`. `set_padding` is preset-specific sugar for "I want a present-mode toggle that varies padding at runtime"; it mutates the live constraint and refits in one call.
+
+Both examples ship as live demos at `/canvas/svg` (free-form, no preset) and `/canvas/svg/keynote` (preset) in the dogfood app. Their diff is the spec for what the SDK owes its users: same editor, same camera, same gestures — the keynote demo opts into the preset; the free-form demo doesn't.
+
+> **Going deeper.** If you need to compose the building blocks differently — different constraint shape, conditional refit, host-managed bounds — read [`src/presets/keynote.ts`](https://github.com/gridaco/grida/blob/main/packages/grida-svg-editor/src/presets/keynote.ts) (≤ 70 lines of pure composition over public API) as the canonical reference.
 
 ## Install
 
@@ -316,8 +268,8 @@ import { attach_dom_surface } from "@grida/svg-editor/dom";
 
 const handle = attach_dom_surface(editor, {
   container,
-  gestures: true,   // default — install the bundled gesture set (see "Camera")
-  fit: false,       // default — start with identity camera (no auto-fit)
+  gestures: true, // default — install the bundled gesture set (see "Camera")
+  fit: false, // default — start with identity camera (no auto-fit)
 });
 
 handle.camera; // surface-scoped pan/zoom (see "Camera")
@@ -353,28 +305,50 @@ handle.camera.reset();           // identity
 handle.camera.subscribe(cb): Unsubscribe; // transient channel — no state.version bump
 ```
 
-`set_transform` is **idempotent by contract**: when the new transform is element-wise equal to the current, the call is a no-op (no notification fires). This is what makes host-side "subscribe → derive → set" loops (constraints, snap, sync) terminate in finite steps — the [keynote example](#keynote-like-canvas-fixed-viewbox-slide-with-bounded-camera) relies on it.
+`set_transform` is **idempotent by contract**: when the new transform is element-wise equal to the current, the call is a no-op (no notification fires). This is what makes constraints terminate in finite steps and what lets host-side "subscribe → derive → set" loops converge without recursion.
+
+Default behavior: **identity on attach**. Pass `fit: true` to `attach_dom_surface(...)` and the camera fits `"<root>"` on the first frame — Excalidraw's `initialData.scrollToContent: true`, but on the surface. Subsequent `editor.load()` calls do **not** re-fit; that's a host concern. Use `editor.state.load_version` (the "fresh document" signal, [see State](#observation--state)) as the trigger — it bumps once per `editor.load()` and is stable across edits:
 
-Default behavior: **identity on attach**. Pass `fit: true` to `attach_dom_surface(...)` and the camera fits `"<root>"` on the first frame — Excalidraw's `initialData.scrollToContent: true`, but on the surface. Subsequent `editor.load()` calls do **not** re-fit; that's a host concern (`editor.subscribe_with_selector(s => s.structure_version, () => handle.camera.fit("<root>"))` is the recipe).
+```ts
+editor.subscribe_with_selector(
+  (s) => s.load_version,
+  () => handle.camera.fit("<root>")
+);
+```
+
+#### Constraints
+
+```ts
+handle.camera.constraints = {
+  type: "cover", // bounds cover viewport (keynote / slide UX)
+  bounds: "<root>", // or an explicit Rect
+  padding: 80, // screen-pixel breathing room
+};
+handle.camera.constraints = null; // clear
+```
+
+A typed viewport clamp, evaluated synchronously inside every `set_transform` call. v1.1 ships one variant, `type: 'cover'`: bounds cover the viewport edge-to-edge — zoom lower-bounded at fit-with-padding, pan clamped so the user can't see past the bounds. CSS analogy: `object-fit: cover` applied to the bounds rect.
+
+The discriminator (`type`) is a tagged union for forward compatibility — future variants (`'contain'`, `'pan-region'`) will be addable without breaking existing call sites. The [keynote preset](#keynote-like-canvas-fixed-viewbox-slide-with-bounded-camera) is built on this primitive.
 
 #### Gestures
 
 `handle.gestures` is sibling to `editor.keymap` — a layer of installable bindings. The default set is bundled on attach:
 
-| `id`               | trigger                              | effect                       |
-| ------------------ | ------------------------------------ | ---------------------------- |
-| `wheel-pan-zoom`   | plain wheel                          | `camera.pan(delta)`          |
-| `wheel-pan-zoom`   | Ctrl/Cmd + wheel, native pinch       | `camera.zoom_at(...)` at cursor |
-| `space-drag-pan`   | Space-down + drag                    | hand-tool pan                |
-| `middle-mouse-pan` | middle-button drag                   | pan                          |
-| `keyboard-zoom`    | `Shift+0` / `Shift+1` / `Shift+2`    | reset / fit root / fit selection |
-| `keyboard-zoom`    | `Cmd/Ctrl + =` / `Cmd/Ctrl + -`      | zoom in / out                |
+| `id`               | trigger                           | effect                           |
+| ------------------ | --------------------------------- | -------------------------------- |
+| `wheel-pan-zoom`   | plain wheel                       | `camera.pan(delta)`              |
+| `wheel-pan-zoom`   | Ctrl/Cmd + wheel, native pinch    | `camera.zoom_at(...)` at cursor  |
+| `space-drag-pan`   | Space-down + drag                 | hand-tool pan                    |
+| `middle-mouse-pan` | middle-button drag                | pan                              |
+| `keyboard-zoom`    | `Shift+0` / `Shift+1` / `Shift+2` | reset / fit root / fit selection |
+| `keyboard-zoom`    | `Cmd/Ctrl + =` / `Cmd/Ctrl + -`   | zoom in / out                    |
 
 Swap as a unit (`attach_dom_surface(editor, { container, gestures: false })`) then call `handle.gestures.bind({ id, install: ctx => uninstall })` à la carte. **No per-gesture options bag** — if you disagree with a default, unbind it and bind your own. Same discipline as `editor.keymap`.
 
 #### `svg-boundary ≠ editor boundary`
 
-The SVG's intrinsic `width` / `height` / `viewBox` are *content*, not viewport. The camera frames space; the SVG sits in that space. A 1920×1080 attachment is fully serviced by `camera.fit("<root>")` + container CSS — there's no first-class "stage" concept (see [Deferred for v1](#deferred-for-v1)).
+The SVG's intrinsic `width` / `height` / `viewBox` are _content_, not viewport. The camera frames space; the SVG sits in that space. A 1920×1080 attachment is fully serviced by `camera.fit("<root>")` + container CSS for the unbounded case, or by `camera.constraints = { type: 'cover', bounds: '<root>', padding }` for the slide case. There is no first-class "stage" concept; the constraint is the layer where bounded-canvas UX is expressed.
 
 ### Lifecycle
 
@@ -407,6 +381,8 @@ editor.state: {
   readonly version: number;                  // bumps on every emit (selection, mutation, history)
   readonly structure_version: number;        // bumps only on tree-shape / display-label changes;
                                              // stable across pure attribute writes
+  readonly load_version: number;             // bumps once per editor.load(svg) call; starts at 0;
+                                             // the right "fresh document" signal — stable across edits
 };
 
 editor.subscribe(fn: (state: EditorState) => void): Unsubscribe;
@@ -997,6 +973,28 @@ The `@grida/keybinding` package provides the `Keybinding` type, `kb()` / `seq()`
 
 Anything that earns enough use to be a stable primitive graduates out of this section into the high-level API. Anything we add but later regret stays here under a deprecation marker until it can be removed.
 
+## Presets
+
+```ts
+import { keynote } from "@grida/svg-editor/presets";
+
+const handle = keynote.attach(editor, { container, padding: 80 });
+// later: handle.set_padding(0); // present-mode toggle
+//        handle.detach();
+```
+
+Presets are **opinionated bundles** that compose the public primitives (`attach_dom_surface`, `camera.constraints`, `load_version`, etc.) into one-import setups for common UX shapes. They live at the **`@grida/svg-editor/presets`** subpath — an explicit opt-in. The main `@grida/svg-editor` entry never references this subpath, so hosts that don't want a preset don't pay for it.
+
+**v1.1 ships one preset:**
+
+- **`keynote`** — slide-shaped canvas. Attaches the DOM surface with `fit: true`, installs `camera.constraints = { type: 'cover', bounds: '<root>', padding }`, subscribes to `editor.state.load_version` for refit-on-load. Returns a `KeynoteSurfaceHandle = DomSurfaceHandle & { set_padding(p): void }` — the `set_padding` method swaps the constraint padding at runtime (use for "Present mode" toggles).
+
+The preset's source ([`src/presets/keynote.ts`](https://github.com/gridaco/grida/blob/main/packages/grida-svg-editor/src/presets/keynote.ts)) is ≤ 70 lines of pure composition over the public package surface — no `_internal` reach, no private coupling. If you need a different shape, copy the file and modify.
+
+**Discipline.** Code in `src/presets/` is allowed to import only from `@grida/svg-editor` / `@grida/svg-editor/dom` / `@grida/svg-editor/react` and third-party packages — never from `src/core/`, `src/commands/`, `src/keymap/`, or `src/gestures/`. This means every preset is composable against what an external consumer has access to: if a preset works, the same composition works for any host.
+
+A second preset graduates when a second use case asks for one (`slidedeck`, `sticker`, `canvas`, …) — discovery-loop discipline.
+
 ## Deferred for v1
 
 What v1 explicitly doesn't ship. Each is documented elsewhere with the v1 workaround.
@@ -1010,9 +1008,9 @@ What v1 explicitly doesn't ship. Each is documented elsewhere with the v1 workar
 - **Non-DOM surfaces** (worker, React Native, headless test harness).
 - **Paint-server validity warnings** (dangling `url(#id)` references).
 - **Rotation gesture in the HUD.**
-- **Stage / bounded working area + `camera.constraints`.** *svg-boundary ≠ editor boundary*: the editor models an infinite canvas; the SVG's intrinsic `width` / `height` / `viewBox` are content, not viewport. Host code that wants Keynote-style bounded camera (lower-bounded zoom at fit; pan clamped so the slide always covers the viewport) writes ~25 lines of `subscribe + clamp + set_transform` against the public API — the recipe lives in the [keynote example above](#keynote-like-canvas-fixed-viewbox-slide-with-bounded-camera) and as a hook in the live demo at `/canvas/svg/keynote`. `Camera.set_transform` is intentionally idempotent so this loop terminates. A first-class `handle.camera.constraints = { bounds, padding, behavior }` (peer-validated via tldraw's `TLCameraConstraints`) is reserved for v2 — once we see a second use case, the recipe graduates.
 - **Persisted camera state.** Camera is surface-scoped and never enters `editor.state` / `editor.serialize()` / history. Hosts that want view bookmarks persist `handle.camera.transform` themselves.
 - **Gesture momentum / inertia / animated `fit`.** The `animate` shape isn't reserved in the type — it'll be added when delivered, not before.
+- **`CameraConstraints` variants beyond `'cover'`.** v1.1 ships `type: 'cover'` only (bounds cover viewport — slide / keynote UX). The discriminator is a tagged union so future variants land as additive arms: `type: 'contain'` (bounds always fully visible inside viewport — bounded artwork) and `type: 'pan-region'` (d3-zoom `translateExtent` style — pan clamped to a region with free zoom) are reserved names but not yet implemented. Peer-validated direction: tldraw's `TLCameraConstraints.behavior: 'inside' | 'outside'`, mapped to CSS-style `'cover'` / `'contain'` naming.
 
 ## Anti-goals
 
@@ -1030,7 +1028,7 @@ If a consumer needs any of the above, the right answer is "this is the wrong too
 
 ## Status
 
-`v1.0.0-alpha.3` — selection, translate, paint editing (solid + gradient), gradient defs, history, reorder, remove, set_text, keyboard shortcuts, **surface-scoped camera** (pan / zoom / fit with idempotent `set_transform`), **gestures layer** sibling to `editor.keymap` (wheel-pan-zoom, space-drag, middle-mouse-drag, keyboard zoom).
+`v1.0.0-alpha.4` — selection, translate, paint editing (solid + gradient), gradient defs, history, reorder, remove, set_text, keyboard shortcuts, **surface-scoped camera** (pan / zoom / fit with idempotent `set_transform`), **gestures layer** sibling to `editor.keymap` (wheel-pan-zoom, space-drag, middle-mouse-drag, keyboard zoom), **typed `camera.constraints`** (`'cover'` variant, peer-validated tagged union), **`editor.state.load_version`** (fresh-document signal distinct from `structure_version`), and the **`@grida/svg-editor/presets`** subpath shipping `keynote.attach` for slide-shaped SVGs.
 
 Round-trip fidelity (P1) is the design invariant; the v1 surface is deliberately minimal and the [Low-level API](#low-level-api) is the escape hatch when the high-level API doesn't yet cover what you need.
 

package/dist/chunk-CfYAbeIz.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };

package/dist/{dom-D-5D_3o0.mjs → dom-CmOu0HvI.mjs}

@@ -1,4 +1,4 @@
-import { a as capture_resize_baseline, c as is_resizable, i as apply_translate, l as is_text_input_focused, o as capture_translate_baseline, r as apply_resize, s as compute_resize_factors, t as parse_paint } from "./paint-BTKvRItP.mjs";
+import { a as capture_resize_baseline, c as is_resizable, i as apply_translate, l as is_text_input_focused, o as capture_translate_baseline, r as apply_resize, s as compute_resize_factors, t as parse_paint } from "./paint-Cfiw4g_J.mjs";
 import { createTextEditor } from "@grida/text-editor/dom";
 import { NO_MODS, Surface, measurementToHUDDraw } from "@grida/hud";
 import { measure } from "@grida/cmath/_measurement";
@@ -16,9 +16,26 @@ var Camera = class {
 		this.viewport_w = 0;
 		this.viewport_h = 0;
 		this.listeners = /* @__PURE__ */ new Set();
+		this._constraints = null;
 		this._transform = opts.initial ?? cmath.transform.identity;
 		this.resolve_bounds = opts.resolve_bounds;
 	}
+	/**
+	* 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() {
+		return this._constraints;
+	}
+	set constraints(c) {
+		this._constraints = c;
+		if (c) this.reenforce();
+	}
 	/** Underlying 2D affine. World→screen. */
 	get transform() {
 		return this._transform;
@@ -117,10 +134,15 @@ var Camera = class {
 	* 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) {
-		if (transform_equal(this._transform, t)) return;
-		this._transform = t;
+		const next = this.apply_constraints(t);
+		if (transform_equal(this._transform, next)) return;
+		this._transform = next;
 		this.notify();
 	}
 	/** Viewport size in screen pixels. Read by host code computing constraints. */
@@ -174,6 +196,10 @@ var Camera = class {
 		if (w === this.viewport_w && h === this.viewport_h) return;
 		this.viewport_w = w;
 		this.viewport_h = h;
+		if (this._constraints) {
+			const next = this.apply_constraints(this._transform);
+			if (!transform_equal(this._transform, next)) this._transform = next;
+		}
 		this.notify();
 	}
 	/** Convert a screen-space point to world-space. */
@@ -193,10 +219,71 @@ var Camera = class {
 			y: sy
 		};
 	}
+	/**
+	* 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.
+	*/
+	apply_constraints(t) {
+		if (!this._constraints) return t;
+		if (this.viewport_w <= 0 || this.viewport_h <= 0) return t;
+		switch (this._constraints.type) {
+			case "cover": return clamp_cover(t, this._constraints, this.viewport_w, this.viewport_h, this.resolve_bounds);
+		}
+	}
+	/**
+	* Re-clamp the stored transform against the current constraint. Called
+	* from the `constraints` setter; `_set_viewport_size` has its own
+	* notify-inclusive path.
+	*/
+	reenforce() {
+		if (!this._constraints) return;
+		const next = this.apply_constraints(this._transform);
+		if (transform_equal(this._transform, next)) return;
+		this._transform = next;
+		this.notify();
+	}
 	notify() {
 		for (const cb of this.listeners) cb();
 	}
 };
+/**
+* Clamp a transform under a `'cover'` constraint:
+* - Zoom lower-bounded at fit-with-padding (the slide always fills the
+*   viewport edge-to-edge).
+* - When at min-zoom the slide is locked centered (bounds smaller than
+*   viewport on the constrained axis is impossible above min_zoom; below
+*   is impossible because zoom is clamped up).
+* - When zoomed in, pan is clamped so the slide always covers the viewport
+*   (no black bars).
+*
+* Returns the input transform unchanged when bounds can't be resolved or
+* are degenerate.
+*/
+function clamp_cover(t, c, vp_w, vp_h, resolve) {
+	const bounds = typeof c.bounds === "string" ? resolve(c.bounds) : c.bounds;
+	if (!bounds || bounds.width <= 0 || bounds.height <= 0) return t;
+	const padding = c.padding ?? 0;
+	const eff_w = vp_w - 2 * padding;
+	const eff_h = vp_h - 2 * padding;
+	if (eff_w <= 0 || eff_h <= 0) return t;
+	const min_zoom = Math.min(eff_w / bounds.width, eff_h / bounds.height);
+	const s = Math.max(t[0][0], min_zoom);
+	const sw = s * bounds.width;
+	const sh = s * bounds.height;
+	const tx = sw > vp_w ? cmath.clamp(t[0][2], vp_w - s * (bounds.x + bounds.width), -s * bounds.x) : (vp_w - sw) / 2 - s * bounds.x;
+	const ty = sh > vp_h ? cmath.clamp(t[1][2], vp_h - s * (bounds.y + bounds.height), -s * bounds.y) : (vp_h - sh) / 2 - s * bounds.y;
+	return [[
+		s,
+		0,
+		tx
+	], [
+		0,
+		s,
+		ty
+	]];
+}
 function transform_equal(a, b) {
 	return a[0][0] === b[0][0] && a[0][1] === b[0][1] && a[0][2] === b[0][2] && a[1][0] === b[1][0] && a[1][1] === b[1][1] && a[1][2] === b[1][2];
 }

package/dist/dom-Cn-RtjRL.d.ts

@@ -0,0 +1,48 @@
+import { a as SurfaceHandle, d as Gestures, g as Camera, o as SvgEditor } from "./editor-D2l_CDr0.js";
+import cmath from "@grida/cmath";
+
+//#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;
+//#endregion
+export { DomSurfaceOptions as n, attach_dom_surface as r, DomSurfaceHandle as t };

package/dist/{dom-BlJZWpR_.js → dom-CoVZzFqy.js}

@@ -5,6 +5,15 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
 var __copyProps = (to, from, except, desc) => {
 	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
 		key = keys[i];
@@ -20,7 +29,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_paint = require("./paint-CVLZazOa.js");
+const require_paint = require("./paint-dDV-Trt9.js");
 let _grida_text_editor_dom = require("@grida/text-editor/dom");
 let _grida_hud = require("@grida/hud");
 let _grida_cmath__measurement = require("@grida/cmath/_measurement");
@@ -39,9 +48,26 @@ var Camera = class {
 		this.viewport_w = 0;
 		this.viewport_h = 0;
 		this.listeners = /* @__PURE__ */ new Set();
+		this._constraints = null;
 		this._transform = opts.initial ?? _grida_cmath.default.transform.identity;
 		this.resolve_bounds = opts.resolve_bounds;
 	}
+	/**
+	* 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() {
+		return this._constraints;
+	}
+	set constraints(c) {
+		this._constraints = c;
+		if (c) this.reenforce();
+	}
 	/** Underlying 2D affine. World→screen. */
 	get transform() {
 		return this._transform;
@@ -140,10 +166,15 @@ var Camera = class {
 	* 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) {
-		if (transform_equal(this._transform, t)) return;
-		this._transform = t;
+		const next = this.apply_constraints(t);
+		if (transform_equal(this._transform, next)) return;
+		this._transform = next;
 		this.notify();
 	}
 	/** Viewport size in screen pixels. Read by host code computing constraints. */
@@ -197,6 +228,10 @@ var Camera = class {
 		if (w === this.viewport_w && h === this.viewport_h) return;
 		this.viewport_w = w;
 		this.viewport_h = h;
+		if (this._constraints) {
+			const next = this.apply_constraints(this._transform);
+			if (!transform_equal(this._transform, next)) this._transform = next;
+		}
 		this.notify();
 	}
 	/** Convert a screen-space point to world-space. */
@@ -216,10 +251,71 @@ var Camera = class {
 			y: sy
 		};
 	}
+	/**
+	* 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.
+	*/
+	apply_constraints(t) {
+		if (!this._constraints) return t;
+		if (this.viewport_w <= 0 || this.viewport_h <= 0) return t;
+		switch (this._constraints.type) {
+			case "cover": return clamp_cover(t, this._constraints, this.viewport_w, this.viewport_h, this.resolve_bounds);
+		}
+	}
+	/**
+	* Re-clamp the stored transform against the current constraint. Called
+	* from the `constraints` setter; `_set_viewport_size` has its own
+	* notify-inclusive path.
+	*/
+	reenforce() {
+		if (!this._constraints) return;
+		const next = this.apply_constraints(this._transform);
+		if (transform_equal(this._transform, next)) return;
+		this._transform = next;
+		this.notify();
+	}
 	notify() {
 		for (const cb of this.listeners) cb();
 	}
 };
+/**
+* Clamp a transform under a `'cover'` constraint:
+* - Zoom lower-bounded at fit-with-padding (the slide always fills the
+*   viewport edge-to-edge).
+* - When at min-zoom the slide is locked centered (bounds smaller than
+*   viewport on the constrained axis is impossible above min_zoom; below
+*   is impossible because zoom is clamped up).
+* - When zoomed in, pan is clamped so the slide always covers the viewport
+*   (no black bars).
+*
+* Returns the input transform unchanged when bounds can't be resolved or
+* are degenerate.
+*/
+function clamp_cover(t, c, vp_w, vp_h, resolve) {
+	const bounds = typeof c.bounds === "string" ? resolve(c.bounds) : c.bounds;
+	if (!bounds || bounds.width <= 0 || bounds.height <= 0) return t;
+	const padding = c.padding ?? 0;
+	const eff_w = vp_w - 2 * padding;
+	const eff_h = vp_h - 2 * padding;
+	if (eff_w <= 0 || eff_h <= 0) return t;
+	const min_zoom = Math.min(eff_w / bounds.width, eff_h / bounds.height);
+	const s = Math.max(t[0][0], min_zoom);
+	const sw = s * bounds.width;
+	const sh = s * bounds.height;
+	const tx = sw > vp_w ? _grida_cmath.default.clamp(t[0][2], vp_w - s * (bounds.x + bounds.width), -s * bounds.x) : (vp_w - sw) / 2 - s * bounds.x;
+	const ty = sh > vp_h ? _grida_cmath.default.clamp(t[1][2], vp_h - s * (bounds.y + bounds.height), -s * bounds.y) : (vp_h - sh) / 2 - s * bounds.y;
+	return [[
+		s,
+		0,
+		tx
+	], [
+		0,
+		s,
+		ty
+	]];
+}
 function transform_equal(a, b) {
 	return a[0][0] === b[0][0] && a[0][1] === b[0][1] && a[0][2] === b[0][2] && a[1][0] === b[1][0] && a[1][1] === b[1][1] && a[1][2] === b[1][2];
 }
@@ -1556,6 +1652,12 @@ function rect_intersects(a, b) {
 	return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
 }
 //#endregion
+Object.defineProperty(exports, "__exportAll", {
+	enumerable: true,
+	get: function() {
+		return __exportAll;
+	}
+});
 Object.defineProperty(exports, "__toESM", {
 	enumerable: true,
 	get: function() {