@fieldnotes/svelte 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Irakli Iremashvili
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,216 @@
-# Temporary Holding Version
+# @fieldnotes/svelte
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Svelte bindings for the [Field Notes](https://github.com/IrakliDevelop/fieldnotes) infinite canvas SDK. Embed Svelte components directly onto an infinite, pannable, zoomable canvas.
+
+## Install
+
+```bash
+npm install @fieldnotes/core @fieldnotes/svelte
+```
+
+Requires Svelte 5 (`svelte >=5 <6`, runes) and `@fieldnotes/core >=0.96.0`. The package ships
+`.svelte` sources, so your bundler compiles them with your Svelte version (Vite with
+`@sveltejs/vite-plugin-svelte`, or SvelteKit).
+
+## Quick Start
+
+Full runnable example: `examples/svelte` — `pnpm --filter fieldnotes-svelte-example dev`
+
+The canvas needs a container with a defined size — it fills whatever it's given. With no `tools`
+prop and no tools registered in `onready`, it registers the default tool bundle
+(`createDefaultTools()`: hand, select, pencil, eraser, arrow, note, text, shape) with `select`
+active, so a persisting board is one component:
+
+```svelte
+<script lang="ts">
+  import { FieldNotesCanvas } from '@fieldnotes/svelte';
+  import type { CanvasState } from '@fieldnotes/core';
+
+  const saved = localStorage.getItem('board') ?? undefined;
+  const save = (state: CanvasState) => localStorage.setItem('board', JSON.stringify(state));
+</script>
+
+<div style="width: 100vw; height: 100vh">
+  <FieldNotesCanvas initialData={saved} onchange={save} style="width: 100%; height: 100%" />
+</div>
+```
+
+`initialData` takes a saved state object or JSON string. `onchange` receives `viewport.exportState()`,
+trailing-debounced by `changeDebounceMs` (default 250); a pending call is flushed on unmount, and
+the initial load is not reported as a change.
+
+For your own toolbar, pass an explicit tool array and control the active tool with `tool` and
+`ontoolchange`. Keep `tools` a module constant or `$state.raw([...])`, never a deep `$state` proxy:
+
+```svelte
+<script module lang="ts">
+  import { HandTool, SelectTool, PencilTool, EraserTool, NoteTool, ShapeTool } from '@fieldnotes/core';
+
+  const TOOLS = [
+    new HandTool(),
+    new SelectTool(),
+    new PencilTool(),
+    new EraserTool(),
+    new NoteTool(),
+    new ShapeTool(),
+  ];
+</script>
+
+<script lang="ts">
+  import { FieldNotesCanvas } from '@fieldnotes/svelte';
+  import Toolbar from './Toolbar.svelte';
+
+  let tool = $state('select');
+  const setTool = (name: string) => (tool = name);
+</script>
+
+<FieldNotesCanvas tools={TOOLS} {tool} ontoolchange={setTool} style="width: 100vw; height: 100vh">
+  <Toolbar {tool} onselect={setTool} />
+</FieldNotesCanvas>
+```
+
+## Props
+
+Not all props are reactive — the canvas is stateful. Changing a mount-only prop after mount has no effect:
+
+| Prop                            | Reactivity                                                                   |
+| ------------------------------- | ---------------------------------------------------------------------------- |
+| `options`                       | Mount-only — the canvas is stateful; construct with the right options        |
+| `tools`                         | Array: reactive, append-only. Omitted or `'default'`: mount-only (see below) |
+| `initialData`                   | Mount-only — loaded once before `onready`                                    |
+| `onchange` / `changeDebounceMs` | Reactive — the latest callback is used without resubscribing                 |
+| `tool` / `ontoolchange`         | Reactive (controlled)                                                        |
+| `defaultTool`                   | Mount-only (uncontrolled initial tool); ignored when `tool` is set           |
+| `snapToGrid` (deprecated)       | Reactive compatibility prop; prefer a domain constraint service              |
+| `class` / `style` / `children`  | Reactive; `class` and `style` apply to the root `<div>`                      |
+
+`tools` as an array registers each tool once (tools cannot be unregistered). `tools="default"`
+registers `createDefaultTools()` at mount, before `onready` (so you can customise them there).
+Omitted registers the same bundle after `onready` only when neither `options.tools` is set nor any
+tool was registered by then, then activates `tool`, `defaultTool` or `select`; hosts that register
+tools in `onready` get no defaults. `tools={[]}` registers nothing.
+
+`tool` is a plain prop, not `$bindable`: a core tool switch (keyboard or API) never reverts or
+overwrites it. Update your state from `ontoolchange`, as in the example above.
+
+- **`onready(viewport)`** fires once after the `Viewport` is created, tools are registered and
+  `initialData` is loaded. If it throws, the viewport is destroyed and the error is rethrown.
+- **`onchange(state)`** — see Quick Start. If the flush on unmount throws, the viewport is still
+  destroyed and the error is passed to `reportError`.
+- **`ontoolchange(name)`** fires whenever the active tool changes (keyboard, API, or the `tool` prop).
+
+`children` render only once the viewport exists, so components inside can call `useViewport()` and
+the helpers during init.
+
+## Embedding Svelte Components
+
+The headline feature — render any Svelte subtree as a canvas element that pans, zooms, and
+resizes with the canvas:
+
+```svelte
+<FieldNotesCanvas style="width: 100vw; height: 100vh">
+  <CanvasElement position={{ x: 100, y: 200 }} size={{ w: 300, h: 200 }}>
+    <MyCard />
+  </CanvasElement>
+  <CanvasElement position={{ x: 500, y: 100 }}>
+    <button onclick={clicked}>Interactive button on the canvas</button>
+  </CanvasElement>
+</FieldNotesCanvas>
+```
+
+Embedded components use a **two-mode interaction model**: by default they can be selected, dragged, and resized. **Double-click** to enter interact mode (clicks, inputs, forms work). **Escape** or click outside to exit.
+
+`position` is required; `size` is optional — omit it to let the element size to its content. Both
+props are reactive and compared by value: new objects with equal coordinates do not touch the
+store. The children keep their component context (`useViewport()` works inside), and keyed
+reorders of `CanvasElement`s leave their content on the canvas.
+
+`<CanvasElement>` is **host-owned**: Svelte is the source of truth for its element. Its store mutations carry `origin: 'host'`, so mounting, moving, resizing and unmounting never create undo steps and are never sent to a sync relay (the DOM subtree exists only in this document). The element is **transient**: `exportState()` / `exportJSON()` omit it, so a saved canvas never contains a ghost of a Svelte embed. After a store `clear` (a user's clear-canvas gesture or a remote one) or a `loadState()` the component re-registers itself, so the embed survives. To persist an embed across reloads, use the viewport's `registerHtmlRenderer` with an `htmlType` and serializable `data` instead.
+
+## Minimap
+
+```svelte
+<Minimap class="minimap" width={200} height={140} />
+```
+
+A collapsible thumbnail navigator. Props: `width` (default `200`), `height` (default `140`),
+`defaultCollapsed` (uncontrolled, default `false`), `background`, `viewportStroke`, and `class` /
+`style` for positioning, which is yours. While collapsed no controller exists: zero listeners,
+zero rendering. Works inside `<FieldNotesCanvas>` or under `setViewportContext(viewport)`.
+
+## Helpers
+
+Each helper has the same name as its `@fieldnotes/react` hook and returns Svelte stores. Call it
+during component init (the top level of `<script>`) inside `<FieldNotesCanvas>` or under
+`setViewportContext`; a getter `useToolOptions` name is tracked with `$effect.pre`, which only
+works there. Stores subscribe to the viewport while they have subscribers, so `$store` in the
+template is all you need. Single values are `Readable`s; tuples hold a store and a setter; result
+objects are a `Readable` of the state that also carries the action functions (`$history.canUndo`,
+`history.undo()`).
+
+| Helper                            | Returns                                                                                                                                                                            |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useViewport()`                   | The `Viewport`; throws outside a canvas                                                                                                                                            |
+| `setViewportContext(viewport)`    | Provides a host-created viewport to descendants (call during init)                                                                                                                 |
+| `useCamera()`                     | `Readable<{ x, y, zoom }>`                                                                                                                                                         |
+| `useElements(type?)`              | `Readable<CanvasElement[]>`, all or one type; `type` is fixed at init                                                                                                              |
+| `useElements(selector, isEqual?)` | `Readable<R>`; updates only when the selected value changes (default: one-level shallow compare)                                                                                   |
+| `useSelection()`                  | `Readable<string[]>`, a stable array that changes only with the selection                                                                                                          |
+| `useSelectionStyle()`             | `[style, applyStyle]` — `style` is `Readable<ElementStyle \| null>`; `applyStyle(patch)` is one undo step                                                                          |
+| `useSelectionStyleDetails()`      | `[details, applyStyle]` — per-field applicability, mixed state and common style                                                                                                    |
+| `useSelectionOps()`               | `$ops`: `selectedIds`, `selectedCount`, `canGroup`, `canUngroup`, `canAlign`, `canDistribute`, `isLocked`; `ops.group`, `ungroup`, `toggleLock`, `align`, `distribute`             |
+| `useHistory()`                    | `$history`: `canUndo`, `canRedo`; `history.undo`, `redo`                                                                                                                           |
+| `useLayers()`                     | `$layers`: `layers`, `activeLayerId`; `layers.createLayer`, `removeLayer`, `renameLayer`, `reorderLayer`, `setVisible`, `setLocked`, `setOpacity`, `setActiveLayer`, `moveElement` |
+| `useActiveTool()`                 | `[name, setTool]`; `$name` is `''` with no active tool                                                                                                                             |
+| `useToolOptions(name)`            | `[options, setOptions]`; `$options` is `null` for an unknown tool or one without options. A getter `() => name` is tracked                                                         |
+| `useElementRects(match)`          | `Readable<readonly ElementRect[]>`; ignores camera motion. `match` is fixed at init                                                                                                |
+
+```svelte
+<script lang="ts">
+  import { useElements, useHistory } from '@fieldnotes/svelte';
+  import type { CanvasElement } from '@fieldnotes/core';
+
+  // A selector updates only when its result changes; plain useElements() updates on every mutation.
+  const count = useElements((els: CanvasElement[]) => els.length);
+  const notes = useElements('note');
+  const history = useHistory();
+</script>
+
+<p>{$count} elements, {$notes.length} notes</p>
+<button onclick={history.undo} disabled={!$history.canUndo}>Undo</button>
+<button onclick={history.redo} disabled={!$history.canRedo}>Redo</button>
+```
+
+Selectors returning nested fresh objects need a custom `isEqual`, as in React.
+
+## Escape Hatch
+
+`useViewport()` returns the raw `Viewport` for anything the helpers do not cover. Outside the
+canvas, keep the instance `onready` hands you in `$state.raw` (never deep `$state`); it is
+destroyed when the canvas unmounts. See the [core README](../core/README.md) for the full
+`Viewport` API.
+
+## Server-Side Rendering
+
+Importing the package and server-rendering a page that contains `<FieldNotesCanvas>`
+(`svelte/server` `render`, SvelteKit SSR) does not throw: the server renders an empty container
+and the canvas mounts on the client. `children`, `onready` and the helpers run only on the client.
+
+## Lifecycle
+
+The viewport is created in `onMount` and destroyed exactly once when the component is destroyed.
+Svelte tears down the children first — `CanvasElement`s remove their elements and helper stores
+unsubscribe while the viewport is still alive — and then the canvas flushes a pending `onchange`
+and destroys the viewport. `@fieldnotes/react` and `@fieldnotes/vue` destroy the viewport before
+their children unmount.
+
+## Versioning
+
+`@fieldnotes/core` and `@fieldnotes/svelte` are versioned independently. The package's
+`peerDependencies` declare the compatible core range (`>=0.96.0 <1.0.0`). Pre-1.0, minor versions
+may contain breaking changes; if a core minor ever breaks the wrapper, a coordinated release raises
+the lower bound.
+
+## License
+
+MIT

package/dist/CanvasElement.svelte

@@ -0,0 +1,122 @@
+<script module lang="ts">
+  import type { Snippet } from 'svelte';
+
+  /** Props for {@link CanvasElement}. */
+  export interface CanvasElementProps {
+    /** Canvas-space position of the element's top-left corner. */
+    position: { x: number; y: number };
+    /** Optional fixed size; omit to let the element size to its content. */
+    size?: { w: number; h: number };
+    children: Snippet;
+  }
+
+  /**
+   * Marks every store mutation this component makes as host-owned: external origin, so it
+   * neither creates an undo step nor is re-broadcast to the sync hub.
+   */
+  const HOST_ORIGIN = 'host';
+</script>
+
+<!--
+  @component
+  Renders its children as an HTML element embedded in the canvas coordinate space.
+  The element is host-owned and transient: it is driven entirely by props, never appears
+  in exported state, and never records an undo step.
+  Must be used inside a `<FieldNotesCanvas>`.
+-->
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { useViewport } from './context.js';
+
+  const { position, size, children }: CanvasElementProps = $props();
+  const viewport = useViewport();
+
+  // Derived per value, so new props with equal geometry do not update the store.
+  const x = $derived(position.x);
+  const y = $derived(position.y);
+  const w = $derived(size?.w);
+  const h = $derived(size?.h);
+  const geometry = () => ({
+    position: { x, y },
+    size: w === undefined || h === undefined ? undefined : { w, h },
+  });
+
+  let container: HTMLDivElement;
+  let elementId: string | null = null;
+
+  onMount(() => {
+    const register = () => {
+      // Append to domLayer immediately so the children are queryable in the document
+      // before the viewport render loop fires via requestAnimationFrame.
+      viewport.domLayer.appendChild(container);
+      const { position: current, size: currentSize } = geometry();
+      return viewport.addHtmlElement(container, current, currentSize, {
+        transient: true,
+        origin: HOST_ORIGIN,
+      });
+    };
+
+    elementId = register();
+
+    // A store clear detaches every canvas-owned DOM node and forgets the content registered
+    // for it, so this component has to hand its container back afterwards. The decision is
+    // deferred to a microtask because a remote clear is followed — synchronously, by the sync
+    // client — by re-adding the transient elements: reading the store inside the event would
+    // always report this element gone and add a duplicate.
+    const handleStoreReplacement = () => {
+      const clearedId = elementId;
+      if (clearedId === null) return;
+      queueMicrotask(() => {
+        if (elementId !== clearedId) return;
+        if (viewport.store.getById(clearedId)?.type === 'html') {
+          // Survived the clear (the sync client re-adds transient elements after a remote
+          // clear): restore the container as that element's content instead of adding a second.
+          viewport.updateHtmlElement(clearedId, container);
+        } else {
+          elementId = register();
+        }
+        viewport.requestRender();
+      });
+    };
+    // `clear` covers a clear-canvas gesture and a remote clear. A wholesale state replacement
+    // (`loadState`/`loadJSON`) runs inside `suspendNotifications`, so the store coalesces its
+    // events into a single `batch` instead: the same recovery applies.
+    const unsubscribeClear = viewport.store.on('clear', handleStoreReplacement);
+    const unsubscribeBatch = viewport.store.on('batch', handleStoreReplacement);
+
+    return () => {
+      unsubscribeClear();
+      unsubscribeBatch();
+      if (elementId) {
+        viewport.store.remove(elementId, { origin: HOST_ORIGIN });
+        viewport.requestRender();
+        elementId = null;
+      }
+      // Removing the element usually detaches the container; never leave it orphaned in the layer.
+      if (container.parentNode === viewport.domLayer) container.remove();
+    };
+  });
+
+  let registered = false;
+  $effect(() => {
+    const next = geometry();
+    // The first run sees the geometry onMount just registered.
+    if (!registered) {
+      registered = true;
+      return;
+    }
+    if (!elementId) return;
+    const { position: nextPosition, size: nextSize } = next;
+    viewport.store.update(
+      elementId,
+      { position: nextPosition, ...(nextSize ? { size: nextSize } : {}) },
+      { origin: HOST_ORIGIN },
+    );
+    viewport.requestRender();
+  });
+</script>
+
+<!-- Only the inner div moves into the canvas: Svelte moves its own root on keyed reorders. -->
+<div style="display: contents">
+  <div bind:this={container} style="width: 100%; height: 100%">{@render children()}</div>
+</div>

package/dist/CanvasElement.svelte.d.ts

@@ -0,0 +1,25 @@
+import type { Snippet } from 'svelte';
+/** Props for {@link CanvasElement}. */
+export interface CanvasElementProps {
+    /** Canvas-space position of the element's top-left corner. */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** Optional fixed size; omit to let the element size to its content. */
+    size?: {
+        w: number;
+        h: number;
+    };
+    children: Snippet;
+}
+/**
+ * Renders its children as an HTML element embedded in the canvas coordinate space.
+ * The element is host-owned and transient: it is driven entirely by props, never appears
+ * in exported state, and never records an undo step.
+ * Must be used inside a `<FieldNotesCanvas>`.
+ */
+declare const CanvasElement: import("svelte").Component<CanvasElementProps, {}, "">;
+type CanvasElement = ReturnType<typeof CanvasElement>;
+export default CanvasElement;
+//# sourceMappingURL=CanvasElement.svelte.d.ts.map

package/dist/CanvasElement.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CanvasElement.svelte.d.ts","sourceRoot":"","sources":["../src/CanvasElement.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,wEAAwE;IACxE,IAAI,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAkHH;;;;;GAKG;AACH,QAAA,MAAM,aAAa,wDAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,CAAC"}

package/dist/FieldNotesCanvas.svelte

@@ -0,0 +1,161 @@
+<script module lang="ts">
+  import type { Snippet } from 'svelte';
+  import type { ViewportOptions, Tool, CanvasState, ImportableCanvasState } from '@fieldnotes/core';
+  import { Viewport, createDefaultTools } from '@fieldnotes/core';
+
+  export interface FieldNotesCanvasProps {
+    /** Constructor-only: changes after mount are ignored (the canvas is stateful). */
+    options?: ViewportOptions;
+    /**
+     * `'default'` (mount-only): `createDefaultTools()` registered before `onready`, `select` active.
+     * Omitted: the same bundle after `onready`, only if no tools are registered by then.
+     * An array is reactive (append-only): tools present here are registered; removal is not
+     * supported, and `[]` registers nothing.
+     */
+    tools?: Tool[] | 'default';
+    /** Mount-only: a saved state (object or JSON string) loaded before `onready`. */
+    initialData?: ImportableCanvasState | string;
+    /** Debounce window for `onchange` in milliseconds (default 250). */
+    changeDebounceMs?: number;
+    /** Uncontrolled initial tool. Ignored when `tool` is set. */
+    defaultTool?: string;
+    /** Controlled active tool. Pair with `ontoolchange`. */
+    tool?: string;
+    /**
+     * Reactive compatibility toggle for the core snap flag.
+     * @deprecated Grid snapping is domain behavior. Configure it through the
+     * VTT grid/constraint service instead.
+     */
+    snapToGrid?: boolean;
+    /** Called once the viewport exists; a throw destroys the viewport and is rethrown. */
+    onready?: (viewport: Viewport) => void;
+    /** Trailing-debounced with the exported state after any change; flushed on unmount. */
+    onchange?: (state: CanvasState) => void;
+    /** Fires whenever the active tool changes (keyboard, API, or `tool` prop). */
+    ontoolchange?: (name: string) => void;
+    class?: string;
+    style?: string;
+    /** Rendered inside the canvas once the viewport exists; `useViewport()` works there. */
+    children?: Snippet;
+  }
+</script>
+
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import ViewportProvider from './ViewportProvider.svelte';
+
+  const {
+    options,
+    tools,
+    initialData,
+    changeDebounceMs = 250,
+    defaultTool,
+    tool,
+    snapToGrid,
+    onready,
+    onchange,
+    ontoolchange,
+    class: className,
+    style,
+    children,
+  }: FieldNotesCanvasProps = $props();
+
+  let root: HTMLDivElement;
+  let viewport = $state.raw<Viewport | null>(null);
+
+  // Props are read inside callbacks, so the debounce and handlers always see the latest values.
+  onMount(() => {
+    const vp = new Viewport(root, options);
+
+    const activate = (fallback?: string) => {
+      const name = tool ?? defaultTool ?? fallback;
+      if (name) vp.setTool(name);
+    };
+    // An explicit `options.tools` is the host's choice; core registers it and activates select.
+    const deferDefaults = tools === undefined && options?.tools === undefined;
+    for (const t of tools === 'default' ? createDefaultTools() : (tools ?? [])) {
+      vp.toolManager.register(t);
+    }
+    if (!deferDefaults) activate(tools === 'default' ? 'select' : undefined);
+
+    try {
+      if (typeof initialData === 'string') vp.loadJSON(initialData);
+      else if (initialData) vp.loadState(initialData);
+    } catch (error) {
+      vp.destroy();
+      throw error;
+    }
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const emitChange = () => {
+      timer = undefined;
+      onchange?.(vp.exportState());
+    };
+    // Subscribed after initialData so the initial load is not reported as a change.
+    const unsubscribe = vp.onStateChange(() => {
+      clearTimeout(timer);
+      timer = setTimeout(emitChange, changeDebounceMs);
+    });
+
+    try {
+      onready?.(vp);
+
+      // Hosts that register their own tools in onready keep exactly those.
+      if (deferDefaults) {
+        const registerDefaults = vp.toolManager.toolNames.length === 0;
+        if (registerDefaults) {
+          for (const t of createDefaultTools()) vp.toolManager.register(t);
+        }
+        activate(registerDefaults ? 'select' : undefined);
+      }
+    } catch (error) {
+      clearTimeout(timer);
+      unsubscribe();
+      vp.destroy();
+      throw error;
+    }
+
+    const unsubscribeTool = vp.toolManager.onChange((name) => ontoolchange?.(name));
+    viewport = vp;
+
+    return () => {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+        try {
+          emitChange();
+        } catch (error) {
+          // A failing host save must not leak the viewport or throw out of unmount.
+          if (typeof reportError === 'function') reportError(error);
+          else console.error('[fieldnotes] onChange failed during unmount', error);
+        }
+      }
+      unsubscribeTool();
+      unsubscribe();
+      vp.destroy();
+      viewport = null;
+    };
+  });
+
+  $effect(() => {
+    if (!viewport || tool === undefined) return;
+    if (viewport.toolManager.activeTool?.name !== tool) viewport.setTool(tool);
+  });
+
+  $effect(() => {
+    if (!viewport || snapToGrid === undefined) return;
+    viewport.setSnapToGrid(snapToGrid);
+  });
+
+  $effect(() => {
+    if (!viewport || !Array.isArray(tools)) return;
+    for (const t of tools) {
+      if (!viewport.toolManager.getTool(t.name)) viewport.toolManager.register(t);
+    }
+  });
+</script>
+
+<div bind:this={root} class={className} {style}>
+  {#if viewport}
+    <ViewportProvider {viewport}>{@render children?.()}</ViewportProvider>
+  {/if}
+</div>

package/dist/FieldNotesCanvas.svelte.d.ts

@@ -0,0 +1,42 @@
+import type { Snippet } from 'svelte';
+import type { ViewportOptions, Tool, CanvasState, ImportableCanvasState } from '@fieldnotes/core';
+import { Viewport } from '@fieldnotes/core';
+export interface FieldNotesCanvasProps {
+    /** Constructor-only: changes after mount are ignored (the canvas is stateful). */
+    options?: ViewportOptions;
+    /**
+     * `'default'` (mount-only): `createDefaultTools()` registered before `onready`, `select` active.
+     * Omitted: the same bundle after `onready`, only if no tools are registered by then.
+     * An array is reactive (append-only): tools present here are registered; removal is not
+     * supported, and `[]` registers nothing.
+     */
+    tools?: Tool[] | 'default';
+    /** Mount-only: a saved state (object or JSON string) loaded before `onready`. */
+    initialData?: ImportableCanvasState | string;
+    /** Debounce window for `onchange` in milliseconds (default 250). */
+    changeDebounceMs?: number;
+    /** Uncontrolled initial tool. Ignored when `tool` is set. */
+    defaultTool?: string;
+    /** Controlled active tool. Pair with `ontoolchange`. */
+    tool?: string;
+    /**
+     * Reactive compatibility toggle for the core snap flag.
+     * @deprecated Grid snapping is domain behavior. Configure it through the
+     * VTT grid/constraint service instead.
+     */
+    snapToGrid?: boolean;
+    /** Called once the viewport exists; a throw destroys the viewport and is rethrown. */
+    onready?: (viewport: Viewport) => void;
+    /** Trailing-debounced with the exported state after any change; flushed on unmount. */
+    onchange?: (state: CanvasState) => void;
+    /** Fires whenever the active tool changes (keyboard, API, or `tool` prop). */
+    ontoolchange?: (name: string) => void;
+    class?: string;
+    style?: string;
+    /** Rendered inside the canvas once the viewport exists; `useViewport()` works there. */
+    children?: Snippet;
+}
+declare const FieldNotesCanvas: import("svelte").Component<FieldNotesCanvasProps, {}, "">;
+type FieldNotesCanvas = ReturnType<typeof FieldNotesCanvas>;
+export default FieldNotesCanvas;
+//# sourceMappingURL=FieldNotesCanvas.svelte.d.ts.map

package/dist/FieldNotesCanvas.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldNotesCanvas.svelte.d.ts","sourceRoot":"","sources":["../src/FieldNotesCanvas.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAClG,OAAO,EAAE,QAAQ,EAAsB,MAAM,kBAAkB,CAAC;AAEhE,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC;IAC3B,iFAAiF;IACjF,WAAW,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC;IAC7C,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,sFAAsF;IACtF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;IACvC,uFAAuF;IACvF,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACxC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAkIH,QAAA,MAAM,gBAAgB,2DAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}