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

package/README.md

@@ -123,6 +123,108 @@ A few scenarios this is designed to handle well.
 >
 > The editor freezes the animation at `t=0` for editing, applies the position change to the static `cx` attribute, and preserves the `<animate>` block verbatim. The inspector shows a clear "animated property" badge so the user understands what they're editing.
 
+### Free-form canvas (Figma-style infinite canvas)
+
+Identity camera, default gestures, no auto-fit. Pan with the wheel, Cmd+wheel to zoom at cursor, space-drag for hand-tool, `Shift+1` to fit, `Shift+0` to reset.
+
+```tsx
+import {
+  SvgEditorCanvas,
+  SvgEditorProvider,
+  useCameraSnapshot,
+} from "@grida/svg-editor/react";
+import type { DomSurfaceHandle } from "@grida/svg-editor/dom";
+import { useState } from "react";
+
+export function FreeFormCanvas({ svg }: { svg: string }) {
+  const [handle, setHandle] = useState<DomSurfaceHandle | null>(null);
+  const zoom = useCameraSnapshot(handle, (c) => c.zoom, 1);
+  return (
+    <SvgEditorProvider svg={svg}>
+      <div style={{ position: "relative", width: "100%", height: "100vh" }}>
+        <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>
+          <span>{Math.round(zoom * 100)}%</span>
+        </div>
+      </div>
+    </SvgEditorProvider>
+  );
+}
+```
+
+### Keynote-like canvas (fixed-viewBox slide with bounded camera)
+
+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.
+
+This bundle ships as a one-import preset at the **`@grida/svg-editor/presets`** subpath. The preset composes the public primitives:
+
+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.
+
+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 { 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 (
+    <SvgEditorProvider svg={svg}>
+      <KeynoteHost />
+    </SvgEditorProvider>
+  );
+}
+
+function KeynoteHost() {
+  const editor = useSvgEditor();
+  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]);
+
+  return (
+    <div style={{ padding: 24, background: "#1f2937", height: "100vh" }}>
+      <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>
+  );
+}
+```
+
+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
 
 ```sh
@@ -164,13 +266,90 @@ A surface is the editor's attachment seam — it mounts the SVG into a host envi
 ```ts
 import { attach_dom_surface } from "@grida/svg-editor/dom";
 
-const handle = attach_dom_surface(editor, { container });
-// later:
+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)
+});
+
+handle.camera; // surface-scoped pan/zoom (see "Camera")
+handle.gestures; // surface-scoped wheel/pointer/keyboard layer
 handle.detach();
 ```
 
 `@grida/svg-editor/dom` is the only place in this package that imports DOM types. The internal `Surface` type exists for tests and future work; it is not a documented extension point at v1.
 
+### Camera
+
+The camera is a **surface-scoped** pan/zoom: it lives on `handle.camera`, never on `editor.state`. View state and document state are disjoint — pan/zoom doesn't bump `state.version`, doesn't serialize, and isn't undoable. A second `attach_dom_surface(...)` gets its own camera.
+
+```ts
+handle.camera.center;            // world-space point at viewport center (Vec2)
+handle.camera.zoom;              // uniform scale; 1 = 100 %
+handle.camera.bounds;            // world Rect visible in the viewport
+handle.camera.viewport_size;     // { width, height } in screen px
+handle.camera.transform;         // underlying cmath.Transform (advanced read)
+
+handle.camera.pan({ x, y });     // translate by a screen-space delta
+handle.camera.zoom_at(factor, origin_screen);  // pinch / wheel-at-cursor
+handle.camera.set_center({ x, y });
+handle.camera.set_zoom(z, pivot_screen?);
+handle.camera.set_transform(t);  // idempotent — no notify when t === current
+
+handle.camera.fit("<root>");     // fit the document into the viewport
+handle.camera.fit("<selection>"); // fit current selection
+handle.camera.fit(nodeId);
+handle.camera.fit(rect, { margin: 64 });
+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 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:
+
+```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                    |
+
+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 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
 
 ```ts
@@ -202,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;
@@ -597,16 +778,18 @@ import {
   useSvgEditor,
   useEditorState,
   useCommands,
+  useCameraSnapshot,
 } from "@grida/svg-editor/react";
 ```
 
 That's the whole public surface.
 
 - `SvgEditorProvider` — owns the headless editor, puts it in context.
-- `SvgEditorCanvas` — the only UI component we ship; internally calls `attach_dom_surface(editor, { container: div })` on mount and `detach()` on unmount.
+- `SvgEditorCanvas` — the only UI component we ship; internally calls `attach_dom_surface(editor, { container: div, gestures, fit, initial_camera })` on mount and `detach()` on unmount. Pass `onAttach={setHandle}` to receive the `DomSurfaceHandle` (for `handle.camera` / `handle.gestures`).
 - `useSvgEditor()` — returns the editor instance from context.
-- `useEditorState(selector, equals?)` — subscribes to a slice of `editor.state` and re-renders on change. The subscription primitive.
+- `useEditorState(selector, equals?)` — subscribes to a slice of `editor.state` and re-renders on change.
 - `useCommands()` — sugar for `useSvgEditor().commands`.
+- `useCameraSnapshot(handle, selector, fallback)` — sibling to `useEditorState`, for the camera channel. Returns the selected value and re-renders on camera mutation; uses `fallback` while `handle` is null. The recipe lives in the package because both demos wrote it identically (see `/canvas/svg` and `/canvas/svg/keynote`).
 
 Top-level wiring:
 
@@ -790,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.
@@ -803,6 +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.**
+- **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
 
@@ -820,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.1` — selection, translate, paint editing (solid + gradient), gradient defs, history, reorder, remove, set_text, keyboard shortcuts.
+`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 };