feat: dexie/persistence

TODO.txt

···
-=============================================================================
+================================================================================
+
 Author intent:
 - Build a Svelte-native editor core (TS) + renderer + UI.
 - Keep the "engine" framework-agnostic so Web + Tauri share it.
···
 - [ ] Task
 - (DoD) Definition of Done for the milestone
 - Files shown are ideas, not requirements
-==============================================================================
-1. Milestone A: Repo skeleton + dev loop                            *wb-A*
-==============================================================================
+
+================================================================================
+1. Milestone A: Repo skeleton + dev loop                                  *wb-A*
+================================================================================
 
 Goal: a monorepo that can run a blank canvas in web + desktop.
 
···
 - `pnpm dev:desktop` launches a Tauri window that shows the same canvas.
 - `pnpm test` runs at least 1 passing core test.
 
-==============================================================================
-2. Milestone B: Math + coordinate systems                            *wb-B*
-==============================================================================
-
-Goal: a correct, testable camera transform (world <-> screen).
-
-Core primitives (/packages/core/src/math.ts):
-[x] Define Vec2 { x, y } + helpers:
-    - add, sub, mulScalar, len, normalize, dot
-[x] Define Box2 { min: Vec2, max: Vec2 }:
-    - fromPoints, containsPoint, intersectsBox
-[x] Define Mat3 (2D affine) or equivalent:
-    - identity
-    - translate(tx, ty)
-    - scale(sx, sy)
-    - rotate(theta)
-    - multiply(a, b)
-    - transformPoint(m, p)
-
-Camera (/packages/core/src/camera.ts):
-[x] Define Camera { x, y, zoom } (world origin + scale)
-[x] Implement worldToScreen(camera, p)
-[x] Implement screenToWorld(camera, p)
-[x] Implement cameraPan(camera, deltaScreen) -> camera'
-[x] Implement cameraZoomAt(camera, factor, anchorScreenPoint) -> camera'
-
-Tests (/packages/core/tests/camera.test.ts):
-[x] worldToScreen(screenToWorld(p)) round-trip within epsilon
-[x] zoomAt keeps anchor point stable (screen position unchanged)
-[x] pan moves world under cursor as expected
+================================================================================
+2. Milestone B: Math + coordinate systems                                 *wb-B*
+================================================================================
 
-(DoD):
-- All math/camera functions are unit-tested and pass.
+Camera math, matrix utilities, and transforms are fully implemented and verified
+so world and screen coordinates map precisely.
 
-==============================================================================
-3. Milestone C: Document model (records)                              *wb-C*
-==============================================================================
+================================================================================
+3. Milestone C: Document model (records)                                  *wb-C*
+================================================================================
 
-Goal: define the minimal data model that can represent a drawing.
+Document/page/shape/binding records plus validation let the editor serialize and
+reason about drawings safely.
 
-Records & ID (/packages/core/src/model):
-[x] Implement createId(prefix) -> uuid (v4)
-[x] Define PageRecord { id, name, shapeIds: string[] }
-[x] Define ShapeRecord base:
-    - id, type, pageId
-    - x, y, rot
-    - props: object (type-specific)
+================================================================================
+4. Milestone D: Store + selectors (reactive core)                         *wb-D*
+================================================================================
 
-[x] Define shape types (minimal):
-    - rect: { w, h, fill, stroke, radius }
-    - ellipse: { w, h, fill, stroke }
-    - line: { a: Vec2, b: Vec2, stroke, width }
-    - arrow: { a: Vec2, b: Vec2, stroke, width }
-    - text: { text, fontSize, fontFamily, color, w? }
+The reactive store, invariants, and selectors supply deterministic state streams
+for both renderer and UI subscribers.
 
-[x] Define BindingRecord (for arrow endpoints):
-    - id, type: "arrow-end"
-    - fromShapeId (arrow id)
-    - toShapeId (target shape id)
-    - handle: "start" | "end"
-    - anchor: e.g. { kind: "center" } for v0
+================================================================================
+5. Milestone E: Canvas renderer (read-only)                               *wb-E*
+================================================================================
 
-Validation:
-[x] validateDoc(doc) -> { ok | errors[] }
+The renderer now draws the document via Canvas2D with camera transforms,
+DPI scaling, text sizing, and selection outlines.
 
-(DoD):
-- You can serialize a doc with a page + 1 shape to JSON and validate it.
+================================================================================
+6. Milestone F: Hit testing (picking)                                     *wb-F*
+================================================================================
 
-==============================================================================
-4. Milestone D: Store + selectors (reactive core)                      *wb-D*
-==============================================================================
+Geometry helpers compute bounds and intersections so hit testing can always
+return the topmost shape under the cursor.
 
-Goal: a fast, deterministic state container for the editor using RxJS
+================================================================================
+7. Milestone G: Input system (pointer + keyboard)                         *wb-G*
+================================================================================
 
-Store (/packages/core/src/reactivity.ts) - RxJS + SvelteKit (runes) friendly
+Pointer and keyboard adapters now normalize events, map them into actions, and
+feed the editor consistently across platforms.
 
-Core types:
-[x] Define EditorState:
-    - doc: { pages, shapes, bindings }
-    - ui: { currentPageId, selectionIds: string[], toolId: ToolId }
-    - camera: { x, y, zoom }
+================================================================================
+8. Milestone H: Tool state machine (foundation)                           *wb-H*
+================================================================================
 
-RxJS store (BehaviorSubject-backed):
-[x] Implement createEditorStore(initial: EditorState) that exposes:
-    - state$: Observable<EditorState>         (read stream)
-    - getState(): EditorState                (sync snapshot)
-    - setState(updater: (s) => s): void      (mutation API)
-    - subscribe(listener): () => void        (Svelte-compatible subscribe)
-    - select(selector, eq?): Observable<T>   (derived streams)
+Tool interfaces and the router manage lifecycle hooks so each tool is an
+explicit, testable state machine.
 
-    Notes:
-    - Use BehaviorSubject so new subscribers immediately get the current value.
-    - subscribe must return an unsubscribe function.
 
-Selectors (pure functions, no RxJS):
-[x] Implement selectors
-    - getCurrentPage(state)
-    - getShapesOnCurrentPage(state)
-    - getSelectedShapes(state)
+================================================================================
+9. Milestone I: Select/move tool (MVP interaction)                        *wb-I*
+================================================================================
 
-Invariants (pick "repair" and test it):
-[x] Implement enforceInvariants(state): EditorState (repair strategy):
-    - selectionIds := selectionIds filtered to existing shapes
-    - currentPageId must exist:
-        - if missing, set to first existing page
-        - if no pages exist, create a default page and set it
-[x] Ensure setState always runs enforceInvariants before publishing next state
+Selection logic handles hit selection, marquee, dragging, deletion, and escape
+so shapes can be moved reliably.
 
-Tests
-[x] subscribe immediately receives current state upon subscription (BehaviorSubject behavior)
-[x] subscribe fires exactly once per setState call
-[x] invariants are enforced on any update (selection filtered, page fixed/created)
-
-(DoD):
-- Renderer can subscribe to state$ (or subscribe()) and redraw on any change.
-- SvelteKit can bridge to runes with $effect unsubscribe cleanup.
-
-==============================================================================
-5. Milestone E: Canvas renderer (read-only)                            *wb-E*
-==============================================================================
-
-Goal: draw the document from state, no interactivity yet.
-
-Renderer (/packages/renderer):
-[x] createRenderer(canvas, store) -> { dispose() }
-[x] Implement render loop strategy:
-    - requestAnimationFrame redraw on "dirty" flag
-    - mark dirty on store updates
-[x] Implement draw pipeline:
-    - clear canvas
-    - apply camera transform
-    - draw shapes (rect/ellipse/line/arrow/text)
-    - draw selection outline if selectionIds non-empty
-[x] Implement text measurement fallback:
-    - if text shape has w? else measureText and derive bounds
-[x] Implement pixel ratio handling:
-    - set canvas width/height by devicePixelRatio
-    - scale context accordingly
-
-(DoD):
-- With a hardcoded doc in the store, shapes appear at correct coordinates
-  and stay stable while resizing the browser window.
-
-==============================================================================
-6. Milestone F: Hit testing (picking)                                  *wb-F*
-==============================================================================
-
-Goal: determine what the cursor is over.
-
-Geometry (/packages/core/src/geom):
-[x] shapeBounds(shape) -> Box2
-[x] pointInRect(p, rectShape) -> bool
-[x] pointInEllipse(p, ellipseShape) -> bool
-[x] pointNearSegment(p, a, b, tolerance) -> bool
-[x] hitTestPoint(state, worldPoint) -> shapeId? (topmost wins)
-
-Layering:
-[x] Define draw order = page.shapeIds order
-[x] hitTest uses reverse order for topmost selection
-
-(DoD):
-- You can hover shapes and log the hit shape id (no selection yet).
-
-==============================================================================
-7. Milestone G: Input system (pointer + keyboard)                      *wb-G*
-==============================================================================
-
-Goal: normalize events into editor actions.
-
-Input adapter (/apps/web/src/lib/input):
-[x] Capture pointerdown/move/up
-[x] Convert screen coords -> world coords using camera
-[x] Track pointer state: isDown, startWorld, lastWorld, buttons
-
-Keyboard:
-[x] Capture keydown/keyup
-[x] Normalize modifiers (ctrl/cmd, shift, alt)
-
-Action bus (/packages/core/src/actions.ts):
-[x] Define Action union:
-    - PointerDown, PointerMove, PointerUp
-    - KeyDown, KeyUp
-    - Wheel (for zoom)
-[x] dispatch(action) -> store updates via tool state machine (next milestone)
-
-(DoD):
-- You can pan/zoom camera via wheel/drag with a temporary "camera tool"
-  (even before selection tool exists).
-
-==============================================================================
-8. Milestone H: Tool state machine (foundation)                        *wb-H*
-==============================================================================
-
-Goal: tools are explicit, testable state machines (RxJS based)
-
-Tools (/packages/core/src/tools):
-[x] Define ToolId: "select" | "rect" | "ellipse" | "line" | "arrow" | "text" | "pen"
-[x] Define Tool interface:
-    - id
-    - onEnter(state)
-    - onAction(state, action) -> newState
-    - onExit(state)
-
-Tool router:
-[x] routeAction(state, action) -> newState (delegates to active tool)
-
-(DoD):
-- A dummy tool can consume pointer events and update state deterministically.
-
-
-==============================================================================
-9. Milestone I: Select/move tool (MVP interaction)                     *wb-I*
-==============================================================================
-
-Goal: select shapes and drag them.
-
-Selection:
-[x] PointerDown:
-    - if hit shape: selection = [shapeId] (or add with shift)
-    - else selection = []
-[x] PointerMove while dragging selected:
-    - translate selected shapes by deltaWorld
-[x] PointerUp:
-    - end drag
-
-Marquee select (smallest slices):
-[x] Implement marquee start (on empty canvas pointerdown)
-[x] Render marquee rectangle overlay
-[x] On pointerup, select shapes whose bounds intersect marquee
-
-UX:
-[x] Escape clears selection
-[x] Delete removes selected shapes
-
-(DoD):
-- You can select and move shapes reliably.
-
-==============================================================================
-10. Milestone J: Create basic shapes via tools                         *wb-J*
-==============================================================================
-
-Goal: place shapes with dedicated tools.
-
-Rect tool (repeat pattern for others):
-[x] PointerDown on canvas:
-    - create a draft rect shape with w/h=0 at startWorld
-    - selection = [newId]
-[x] PointerMove:
-    - update w/h based on currentWorld - startWorld
-[x] PointerUp:
-    - if too small, delete it (click-cancel behavior)
-    - else finalize
-
-[x] Implement ellipse tool (same mechanics)
-[x] Implement line tool (a=startWorld, b=currentWorld)
-[x] Implement arrow tool (same as line but type="arrow")
-[x] Implement text tool:
-    - click to create text shape
-    - open in-place editor overlay (contenteditable) in Svelte
+================================================================================
+10. Milestone J: Create basic shapes via tools                            *wb-J*
+================================================================================
 
-(DoD):
-- You can draw rect/ellipse/line/arrow/text on the canvas.
+Rect, ellipse, line, arrow, and text tools now create shapes via click-drag
+interactions with proper finalize/cancel behavior.
 
 ================================================================================
 11. Milestone K: Bindings for arrows (v0)                                 *wb-K*
 ================================================================================
 
-Goal: arrow endpoints can "stick" to shapes.
-
-Binding creation:
-[x] On arrow finalize:
-    - hit test start/end points
-    - if point hits a target shape, create binding record for that handle
-
-Binding resolution:
-[x] resolveArrowEndpoints(state, arrowId) -> { a, b } in world coords
-    - if bound, compute endpoint at target shape bounds center (v0)
-    - else use arrow props a/b
-
-Live update:
-[x] When a target shape moves, bound arrow rerenders automatically
-    - no mutation required if resolve happens during render
-
-(DoD):
-- Arrows remain connected to moved shapes (center-to-center is fine for v0).
+Arrow endpoints bind to target shapes and stay attached by recalculating anchors
+whenever shapes move.
 
 ================================================================================
 12. Milestone L: History (undo/redo)                                      *wb-L*
 ================================================================================
 
-Goal: every user-visible change is undoable.
-
-History model (/packages/core/src/history):
-[x] Define Command:
-    - do(state) -> state
-    - undo(state) -> state
-[x] Wrap mutations as commands:
-    - CreateShapeCommand
-    - UpdateShapeCommand (with before/after snapshot)
-    - DeleteShapesCommand
-    - SetSelectionCommand
-    - SetCameraCommand
-[x] Implement stacks:
-    - undoStack, redoStack
-[x] Wire shortcuts:
-    - Ctrl/Cmd+Z undo
-    - Ctrl/Cmd+Shift+Z redo
-
-(DoD):
-- Undo/redo works for create/move/delete and camera changes.
-
-==============================================================================
-13. Milestone M: Persistence (web) via Dexie + History integration      *wb-M*
-==============================================================================
-
-Goal:
-- Persist boards to IndexedDB using Dexie (with schema versions + data upgrades).
-- Integrate with the (already implemented) history/command system so:
-  - do/undo/redo that changes the document is persisted
-  - non-document UI changes (selection/tool/camera, etc.) are NOT persisted
-
-Storage shape (v0 choice): Normalized tables
-- boards, pages, shapes, bindings + meta + migrations
-
-------------------------------------------------------------------------------
-M1. Dexie DB + schema v1
-------------------------------------------------------------------------------
-
-/apps/web/src/lib/db.ts
-[ ] Create a Dexie DB class `InkfiniteDB` extending Dexie.
-[ ] db.version(1).stores({
-      boards:      'id, name, createdAt, updatedAt',
-      pages:       '[boardId+id], boardId, updatedAt',
-      shapes:      '[boardId+id], boardId, type, updatedAt',
-      bindings:    '[boardId+id], boardId, type, updatedAt',
-      meta:        'key',
-      migrations:  'id, appliedAt'
-    })
-
-[ ] Implement schema upgrade hook(s):
-    - db.version(N).upgrade(tx => runMigrations(tx))
-
-(DoD):
-- DB opens; can insert + read a boards row.
-
-------------------------------------------------------------------------------
-M2. Repo API (what the editor uses)
-------------------------------------------------------------------------------
-
-/packages/core/src/persist/web.ts
-[ ] Define BoardMeta: { id, name, createdAt, updatedAt }.
-[ ] Implement DocRepo methods:
-    - listBoards(): Promise<BoardMeta[]>
-    - createBoard(name): Promise<boardId>
-    - renameBoard(boardId, name): Promise<void>
-    - deleteBoard(boardId): Promise<void>
-    - loadDoc(boardId): Promise<{ pages, shapes, bindings, order }>
-    - applyDocPatch(boardId, patch): Promise<void>
-
-Transactions:
-[ ] Ensure create/delete/applyDocPatch are atomic using db.transaction('rw', ...).
-
-Bulk writes:
-[ ] applyDocPatch uses bulkPut / bulkAdd when writing many shapes/pages/bindings.
-
-(DoD):
-- createBoard -> applyDocPatch -> loadDoc round-trips a simple doc.
-
-------------------------------------------------------------------------------
-M3. Migration system (schema + logical migrations)
-------------------------------------------------------------------------------
-
-Schema versions:
-[ ] When adding indexes/stores:
-    - bump db.version(N).stores(...)
-    - attach .upgrade(tx => ...) for data backfill/reshape
-
-Logical migrations:
-[ ] Create `runMigrations(tx)` called from Version.upgrade():
-    - reads applied ids from migrations table
-    - runs missing migrations in order
-    - writes (id, appliedAt) as each completes
+All document-affecting actions run through undoable commands with history stacks
+and keyboard shortcuts.
 
-Smallest initial migrations:
-[ ] MIG-0001: backfill boards.createdAt / updatedAt if missing
-[ ] MIG-0002: ensure every board has a default page row
+================================================================================
+13. Milestone M: Persistence (web) via Dexie + History integration        *wb-M*
+================================================================================
 
-(DoD):
-- Upgrading applies each logical migration exactly once.
+Document changes now persist to IndexedDB via Dexie with migrations, repo API,
+and history-driven syncing.
 
-------------------------------------------------------------------------------
-M4. History integration (persist on do/undo/redo)
-------------------------------------------------------------------------------
-
-Goal:
-- Any history step that changes the document produces a persistence write.
-- Undo/redo produces persistence writes too.
-- UI-only commands do not touch IndexedDB.
-
-Step 1: Tag commands with persistence intent
-[ ] In your Command types (history layer), add a doc-impact tag:
-    - affectsDoc: boolean
-    - OR kind: 'doc' | 'ui' | 'camera'
-
-Rules (v0):
-- 'doc' commands persist
-- 'ui' and 'camera' do not persist
-
-Step 2: Provide a single hook point in history
-[ ] Add a history callback or event:
-    - onApplied({ kind, beforeState, afterState, commandId, op: 'do'|'undo'|'redo' })
-  This MUST fire after every do/undo/redo.
-
-Step 3: Compute a persistence patch (smallest practical approach)
-[ ] Implement `diffDoc(before.doc, after.doc) -> DocPatch` that outputs:
-    - upserts: pages[], shapes[], bindings[]
-    - deletes: pageIds[], shapeIds[], bindingIds[]
-    - order updates (page order, per-page shape order)
-
-  Note:
-  - Keep it minimal: only compare ids + updatedAt (or stable hash) initially.
-  - If this gets complicated, fall back to “persist full doc snapshot” v0 and
-    switch to patching later (but still behind applyDocPatch).
-
-Step 4: Persist after history events (with batching)
-[ ] Implement `createPersistenceSink(repo)` that exposes:
-    - enqueueDocPatch(boardId, patch): void
-    - flush(): Promise<void>
-
-[ ] Wire history -> sink:
-    - if event.kind === 'doc':
-        sink.enqueueDocPatch(boardId, diffDoc(before, after))
-    - else:
-        no-op
-
-[ ] Batch + flush policy:
-    - debounce 100–250ms
-    - force flush on:
-        - board switch
-        - page unload (best-effort)
-        - explicit Save action
-
-Step 5: Update updatedAt correctly
-[ ] On any persisted doc change, update:
-    - boards.updatedAt = now()
-    - updatedAt on modified rows (pages/shapes/bindings) if you store it
-
-(DoD):
-- Creating/moving/deleting shapes persists through refresh.
-- Undo and redo also persist through refresh.
-- Selection changes do NOT write to Dexie.
-
-------------------------------------------------------------------------------
-M5. Export / Import (backups + portability)
-------------------------------------------------------------------------------
-
-[ ] Export board:
-    - loadDoc(boardId) -> JSON (doc + meta)
-[ ] Import board:
-    - createBoard(name)
-    - applyDocPatch(full snapshot as upserts)
-
-(DoD):
-- Export -> Import recreates the same drawing.
-
-------------------------------------------------------------------------------
-Tests (vitest; use fake IndexedDB)
-------------------------------------------------------------------------------
-
-Dexie correctness:
-[ ] applyDocPatch uses a single transaction for multi-table writes
-[ ] deleteBoard deletes boards + related rows atomically
-
-History integration:
-[ ] doc command do => exactly 1 persistence flush (after debounce)
-[ ] undo => persists (document matches expected)
-[ ] redo => persists (document matches expected)
-[ ] ui-only command => 0 DB writes
-[ ] batching: 10 rapid doc commands => <= 2 writes (depending on debounce window)
-
-------------------------------------------------------------------------------
-Definition of Done
-------------------------------------------------------------------------------
-
-- Web: create board, draw, refresh -> content persists.
-- Undo/redo across refresh works.
-- Migration system exists and is exercised by at least one schema bump + upgrade.
-- Renderer redraws from in-memory state; persistence is driven by history events.
-
-==============================================================================
-14. Milestone N: Desktop packaging (Tauri)                             *wb-N*
-==============================================================================
+================================================================================
+14. Milestone N: Desktop packaging (Tauri)                                *wb-N*
+================================================================================
 
 Goal: same app works as a desktop app with filesystem access.
 
···
 (DoD):
 - Desktop app opens/saves JSON files on disk and reopens them correctly.
 
-==============================================================================
-15. Milestone O: Export (PNG/SVG)                                      *wb-O*
-==============================================================================
+================================================================================
+15. Milestone O: Export (PNG/SVG)                                         *wb-O*
+================================================================================
 
 Goal: export drawings as shareable artifacts.
 
···
 - One-click export works in both web and desktop.
 
 
-==============================================================================
-16. Milestone P: Performance + big docs (pragmatic)                    *wb-P*
-==============================================================================
+================================================================================
+16. Milestone P: Performance + big docs (pragmatic)                       *wb-P*
+================================================================================
 
 Goal: the editor stays responsive with many shapes.
 
···
 (DoD):
 - 10k simple shapes pans/zooms smoothly on a typical machine.
 
-==============================================================================
-17. Milestone Q: File Browser (web: Dexie inspector, desktop: FS)       *wb-Q*
-==============================================================================
+================================================================================
+17. Milestone Q: File Browser (web: Dexie inspector, desktop: FS)         *wb-Q*
+================================================================================
 
 Goal: A unified “Open board” experience:
 - Web: browse Dexie-backed boards + a useful persistence/migration inspector
 - Desktop: browse real directories/files (native file browser semantics)
 
-------------------------------------------------------------------------------
+--------------------------------------------------------------------------------
 Q1. Shared UX contracts
-------------------------------------------------------------------------------
+--------------------------------------------------------------------------------
 
 /packages/core/src/persist/DocRepo.ts:
 [ ] Define DocRepo interface (web + desktop):
···
 (DoD):
 - Svelte UI can render the browser purely from the ViewModel.
 
-------------------------------------------------------------------------------
+--------------------------------------------------------------------------------
 Q2. Web: Boards list + Dexie “Inspector” drawer
-------------------------------------------------------------------------------
+--------------------------------------------------------------------------------
 
 /apps/web/src/lib/filebrowser/FileBrowser.svelte:
 [ ] Boards panel:
···
 (DoD):
 - Web: you can browse boards, open one, and verify migrations + row counts.
 
-------------------------------------------------------------------------------
+--------------------------------------------------------------------------------
 Q3. Desktop: real directory + files (Tauri)
-------------------------------------------------------------------------------
+--------------------------------------------------------------------------------
 
 [ ] Add “Workspace folder” concept:
     - pick directory
···
 (DoD):
 - Desktop: pick a folder, browse files, open/save boards from disk.
 
-------------------------------------------------------------------------------
+--------------------------------------------------------------------------------
 Q4. Parity behaviors
-------------------------------------------------------------------------------
+--------------------------------------------------------------------------------
 
 [ ] Same shortcuts:
     - Ctrl/Cmd+O opens file browser
···
 (DoD):
 - Web and desktop feel like the same app, with storage differences made explicit.
 
-==============================================================================
-18. Milestone R: Quality polish (what makes it feel "real")            *wb-R*
-==============================================================================
+================================================================================
+18. Milestone R: Quality polish (what makes it feel "real")               *wb-R*
+================================================================================
 
 Goal: the UX crosses the "this is legit" threshold.
 
···
 (DoD):
 - A user can comfortably draw and edit without surprises.
 
-==============================================================================
-References (URLs)                                                   *wb-refs*
-==============================================================================
+================================================================================
+References (URLs)                                                      *wb-refs*
+================================================================================
 
 tldraw conceptual references (inspiration only):
 - https://tldraw.dev/docs/shapes

apps/web/package.json

···
     "test": "npm run test:unit -- --run",
     "format": "prettier --write ."
   },
-  "dependencies": { "inkfinite-core": "workspace:*", "inkfinite-renderer": "workspace:*" },
+  "dependencies": { "dexie": "^4.2.1", "inkfinite-core": "workspace:*", "inkfinite-renderer": "workspace:*" },
   "devDependencies": {
     "@eslint/compat": "^1.4.0",
     "@eslint/js": "^9.39.1",

apps/web/src/lib/canvas/Canvas.svelte

···
 <script lang="ts">
+	import HistoryViewer from '$lib/components/HistoryViewer.svelte';
+	import Toolbar from '$lib/components/Toolbar.svelte';
+	import { createInputAdapter, type InputAdapter } from '$lib/input';
 	import {
 		ArrowTool,
 		EllipseTool,
+		InkfiniteDB,
 		LineTool,
-		PageRecord,
 		RectTool,
 		SelectTool,
-		ShapeRecord,
 		Store,
 		TextTool,
+		createPersistenceSink,
 		createToolMap,
+		createWebDocRepo,
+		diffDoc,
 		routeAction,
 		switchTool,
 		type Action,
+		type LoadedDoc,
 		type ToolId,
 		type Viewport
 	} from 'inkfinite-core';
 	import { createRenderer, type Renderer } from 'inkfinite-renderer';
 	import { onDestroy, onMount } from 'svelte';
-	import HistoryViewer from '../components/HistoryViewer.svelte';
-	import Toolbar from '../components/Toolbar.svelte';
-	import { createInputAdapter, type InputAdapter } from '../input';
 
-	const store = new Store();
+	let repo: ReturnType<typeof createWebDocRepo> | null = null;
+	let sink: ReturnType<typeof createPersistenceSink> | null = null;
+	let activeBoardId: string | null = null;
 
-	store.setState((state) => {
-		const page = PageRecord.create('Page 1');
-		const rect1 = ShapeRecord.createRect(page.id, -200, -100, {
-			w: 150,
-			h: 100,
-			fill: '#ff6b6b',
-			stroke: '#c92a2a',
-			radius: 8
-		});
-		const rect2 = ShapeRecord.createRect(page.id, 50, -50, {
-			w: 120,
-			h: 80,
-			fill: '#4dabf7',
-			stroke: '#1971c2',
-			radius: 8
-		});
-		const ellipse = ShapeRecord.createEllipse(page.id, -100, 100, {
-			w: 100,
-			h: 100,
-			fill: '#51cf66',
-			stroke: '#2f9e44'
-		});
-
-		page.shapeIds.push(rect1.id, rect2.id, ellipse.id);
+	const store = new Store(undefined, {
+		onHistoryEvent: (event) => {
+			if (!activeBoardId || event.kind !== 'doc' || !sink) {
+				return;
+			}
+			const patch = diffDoc(event.beforeState.doc, event.afterState.doc);
+			sink.enqueueDocPatch(activeBoardId, patch);
+		}
+	});
 
-		return {
+	function applyLoadedDoc(doc: LoadedDoc) {
+		const firstPageId = doc.order.pageIds[0] ?? Object.keys(doc.pages)[0] ?? null;
+		store.setState((state) => ({
 			...state,
-			doc: {
-				...state.doc,
-				pages: { [page.id]: page },
-				shapes: { [rect1.id]: rect1, [rect2.id]: rect2, [ellipse.id]: ellipse }
-			},
-			ui: { ...state.ui, currentPageId: page.id }
-		};
-	});
+			doc: { pages: doc.pages, shapes: doc.shapes, bindings: doc.bindings },
+			ui: { ...state.ui, currentPageId: firstPageId }
+		}));
+	}
 
 	const selectTool = new SelectTool();
 	const rectTool = new RectTool();
···
 	let inputAdapter: InputAdapter | null = null;
 
 	onMount(() => {
-		renderer = createRenderer(canvas, store);
+		const db = new InkfiniteDB();
+		repo = createWebDocRepo(db);
+		sink = createPersistenceSink(repo, { debounceMs: 200 });
+		let disposed = false;
+
+		const hydrate = async () => {
+			const repoInstance = repo;
+			if (!repoInstance) {
+				return;
+			}
+			try {
+				const boards = await repoInstance.listBoards();
+				const id = boards[0]?.id ?? (await repoInstance.createBoard('My board'));
+				if (disposed) {
+					return;
+				}
+				activeBoardId = id;
+				const loaded = await repoInstance.loadDoc(id);
+				if (!disposed) {
+					applyLoadedDoc(loaded);
+				}
+			} catch (error) {
+				console.error('Failed to load board', error);
+			}
+		};
+
+		hydrate();
 
 		function getViewport(): Viewport {
 			const rect = canvas.getBoundingClientRect();
···
 			return store.getState().camera;
 		}
 
+		renderer = createRenderer(canvas, store);
 		inputAdapter = createInputAdapter({ canvas, getCamera, getViewport, onAction: handleAction });
+
+		function handleBeforeUnload() {
+			if (sink) {
+				void sink.flush();
+			}
+		}
+
+		window.addEventListener('beforeunload', handleBeforeUnload);
+
+		return () => {
+			disposed = true;
+			window.removeEventListener('beforeunload', handleBeforeUnload);
+		};
 	});
 
 	onDestroy(() => {
 		renderer?.dispose();
 		inputAdapter?.dispose();
+		if (sink) {
+			void sink.flush();
+		}
+		repo = null;
+		sink = null;
+		activeBoardId = null;
 	});
 </script>
 

apps/web/vite.config.ts

···
   plugins: [sveltekit(), devtoolsJson()],
   test: {
     ui: false,
+    watch: false,
     expect: { requireAssertions: true },
     projects: [{
       extends: "./vite.config.ts",

eslint.config.js

···
       }],
       "unicorn/prefer-ternary": "off",
       "unicorn/no-null": "off",
-      "unicorn/prevent-abbreviations": ["error", { "replacements": { "i": false, "props": false, "doc": false } }],
+      "unicorn/no-array-reverse": "off",
+      "unicorn/prevent-abbreviations": ["error", {
+        "replacements": { "i": false, "props": false, "doc": false, "db": false },
+      }],
     },
   }],
 );

packages/core/package.json

···
   "devDependencies": {
     "@types/node": "^25.0.3",
     "@vitest/coverage-v8": "^4.0.16",
+    "fake-indexeddb": "^6.0.0",
     "bumpp": "^10.3.2",
     "tsdown": "^0.18.1",
     "typescript": "^5.9.3",

packages/core/src/history.ts

···
 import type { ShapeRecord } from "./model";
 import type { EditorState } from "./reactivity";
 
+export type CommandKind = "doc" | "ui" | "camera";
+
+export type HistoryOperation = "do" | "undo" | "redo";
+
+export type HistoryAppliedEvent = {
+  op: HistoryOperation;
+  commandId: number;
+  command: Command;
+  kind: CommandKind;
+  beforeState: EditorState;
+  afterState: EditorState;
+};
+
 /**
  * Command interface for undo/redo operations
  *
···
 export interface Command {
   /** Display name for this command (shown in history UI) */
   readonly name: string;
+  /** Command category, used for persistence decisions */
+  readonly kind: CommandKind;
 
   /**
    * Execute the command and return the new state
···
  */
 export class CreateShapeCommand implements Command {
   readonly name: string;
+  readonly kind = "doc" as const;
 
   constructor(private readonly shape: ShapeRecord, private readonly pageId: string) {
     this.name = `Create ${shape.type}`;
···
  */
 export class UpdateShapeCommand implements Command {
   readonly name: string;
+  readonly kind = "doc" as const;
 
   constructor(
     private readonly shapeId: string,
···
  */
 export class DeleteShapesCommand implements Command {
   readonly name: string;
+  readonly kind = "doc" as const;
 
   constructor(private readonly shapes: ShapeRecord[], private readonly pageId: string) {
     this.name = shapes.length === 1 ? `Delete ${shapes[0].type}` : `Delete ${shapes.length} shapes`;
···
  */
 export class SetSelectionCommand implements Command {
   readonly name = "Change selection";
+  readonly kind = "ui" as const;
 
   constructor(private readonly before: string[], private readonly after: string[]) {}
 
···
  */
 export class SetCameraCommand implements Command {
   readonly name = "Move camera";
+  readonly kind = "camera" as const;
 
   constructor(private readonly before: Camera, private readonly after: Camera) {}
 

packages/core/src/index.ts

···
 export * from "./history";
 export * from "./math";
 export * from "./model";
+export * from "./persistence/db";
+export * from "./persistence/web";
 export * from "./reactivity";
 export * from "./tools";

packages/core/src/persistence/db.ts

···
+import Dexie, { type Transaction } from "dexie";
+import { PageRecord as PageOps } from "../model";
+import type { BindingRow, BoardMeta, MetaRow, MigrationRow, PageRow, ShapeRow, Timestamp } from "./web";
+
+export const DB_NAME = "inkfinite";
+
+type Migration = { id: string; apply(tx: Transaction): Promise<void> };
+
+const PAGE_ORDER_META_PREFIX = "page-order:";
+const SHAPE_ORDER_META_PREFIX = "shape-order:";
+
+const pageOrderKey = (boardId: string) => `${PAGE_ORDER_META_PREFIX}${boardId}`;
+const shapeOrderKey = (boardId: string) => `${SHAPE_ORDER_META_PREFIX}${boardId}`;
+
+/**
+ * Dexie wrapper for Inkfinite persistence
+ */
+export class InkfiniteDB extends Dexie {
+  boards!: Dexie.Table<BoardMeta, string>;
+  pages!: Dexie.Table<PageRow, [string, string]>;
+  shapes!: Dexie.Table<ShapeRow, [string, string]>;
+  bindings!: Dexie.Table<BindingRow, [string, string]>;
+  meta!: Dexie.Table<MetaRow, string>;
+  migrations!: Dexie.Table<MigrationRow, string>;
+
+  constructor(name = DB_NAME) {
+    super(name);
+
+    this.version(1).stores({
+      boards: "id, name, createdAt, updatedAt",
+      pages: "[boardId+id], boardId, updatedAt",
+      shapes: "[boardId+id], boardId, type, updatedAt",
+      bindings: "[boardId+id], boardId, type, updatedAt",
+      meta: "key",
+      migrations: "id, appliedAt",
+    }).upgrade(async (tx) => {
+      await runMigrations(tx);
+    });
+  }
+}
+
+const MIGRATIONS: Migration[] = [{
+  id: "MIG-0001",
+  async apply(tx) {
+    const boards = tx.table<BoardMeta>("boards");
+    const rows = await boards.toArray();
+    const timestamp = Date.now();
+
+    for (const row of rows) {
+      const patch: Partial<BoardMeta> = {};
+      if (!row.createdAt) {
+        patch.createdAt = timestamp;
+      }
+      if (!row.updatedAt) {
+        patch.updatedAt = timestamp;
+      }
+
+      if (Object.keys(patch).length > 0) {
+        await boards.update(row.id, patch);
+      }
+    }
+  },
+}, {
+  id: "MIG-0002",
+  async apply(tx) {
+    const boards = tx.table<BoardMeta>("boards");
+    const pages = tx.table<PageRow>("pages");
+    const meta = tx.table<MetaRow>("meta");
+    const rows = await boards.toArray();
+    const timestamp = Date.now();
+
+    for (const row of rows) {
+      const pageCount = await pages.where("boardId").equals(row.id).count();
+      if (pageCount > 0) {
+        continue;
+      }
+
+      const defaultPage = PageOps.create("Page 1");
+      await pages.add({ ...defaultPage, boardId: row.id, updatedAt: timestamp });
+      await meta.put({ key: pageOrderKey(row.id), value: [defaultPage.id] });
+      await meta.put({ key: shapeOrderKey(row.id), value: { [defaultPage.id]: [...defaultPage.shapeIds] } });
+      await boards.update(row.id, { updatedAt: timestamp });
+    }
+  },
+}];
+
+/**
+ * Run pending logical migrations during schema upgrades
+ */
+export async function runMigrations(tx: Transaction): Promise<void> {
+  const migrations = tx.table<MigrationRow>("migrations");
+  const applied = await migrations.toArray();
+  const appliedIds = new Set(applied.map((row) => row.id));
+
+  for (const migration of MIGRATIONS) {
+    if (appliedIds.has(migration.id)) {
+      continue;
+    }
+
+    await migration.apply(tx);
+    await migrations.put({ id: migration.id, appliedAt: Date.now() as Timestamp });
+  }
+}

packages/core/src/persistence/web.ts

···
+/* eslint-disable unicorn/no-await-expression-member */
+import Dexie from "dexie";
+import {
+  type BindingRecord,
+  BindingRecord as BindingOps,
+  createId,
+  type Document,
+  type PageRecord,
+  PageRecord as PageOps,
+  type ShapeRecord,
+  ShapeRecord as ShapeOps,
+} from "../model";
+
+export type Timestamp = number;
+
+export type BoardMeta = { id: string; name: string; createdAt: Timestamp; updatedAt: Timestamp };
+
+export type PageRow = PageRecord & { boardId: string; updatedAt: Timestamp };
+
+export type ShapeRow = ShapeRecord & { boardId: string; updatedAt: Timestamp };
+
+export type BindingRow = BindingRecord & { boardId: string; updatedAt: Timestamp };
+
+export type MetaRow = { key: string; value: unknown };
+
+export type MigrationRow = { id: string; appliedAt: Timestamp };
+
+export type DocOrder = {
+  pageIds: string[];
+  /** Optional per-page shape order overrides */
+  shapeOrder?: Record<string, string[]>;
+};
+
+export type DocPatch = {
+  upserts?: { pages?: PageRecord[]; shapes?: ShapeRecord[]; bindings?: BindingRecord[] };
+  deletes?: { pageIds?: string[]; shapeIds?: string[]; bindingIds?: string[] };
+  order?: Partial<DocOrder>;
+};
+
+export type LoadedDoc = {
+  pages: Record<string, PageRecord>;
+  shapes: Record<string, ShapeRecord>;
+  bindings: Record<string, BindingRecord>;
+  order: DocOrder;
+};
+
+export type BoardExport = { board: BoardMeta; doc: Document; order: DocOrder };
+
+export type PersistenceSink = { enqueueDocPatch(boardId: string, patch: DocPatch): void; flush(): Promise<void> };
+
+export type PersistenceSinkOptions = { debounceMs?: number };
+
+export interface DocRepo {
+  listBoards(): Promise<BoardMeta[]>;
+  createBoard(name: string): Promise<string>;
+  renameBoard(boardId: string, name: string): Promise<void>;
+  deleteBoard(boardId: string): Promise<void>;
+  loadDoc(boardId: string): Promise<LoadedDoc>;
+  applyDocPatch(boardId: string, patch: DocPatch): Promise<void>;
+  exportBoard(boardId: string): Promise<BoardExport>;
+  importBoard(snapshot: BoardExport): Promise<string>;
+}
+
+export type WebRepoOptions = { now?: () => Timestamp };
+
+type DexieLike = Pick<Dexie, "table" | "transaction">;
+
+const DEFAULT_BOARD_NAME = "Untitled Board";
+
+const PAGE_ORDER_META_PREFIX = "page-order:";
+const SHAPE_ORDER_META_PREFIX = "shape-order:";
+
+const pageOrderKey = (boardId: string) => `${PAGE_ORDER_META_PREFIX}${boardId}`;
+const shapeOrderKey = (boardId: string) => `${SHAPE_ORDER_META_PREFIX}${boardId}`;
+
+/**
+ * Create a Dexie-backed DocRepo used by the web app.
+ */
+export function createWebDocRepo(database: DexieLike, options?: WebRepoOptions): DocRepo {
+  const now = () => options?.now?.() ?? Date.now();
+
+  const boards = () => database.table<BoardMeta>("boards");
+  const pages = () => database.table<PageRow>("pages");
+  const shapes = () => database.table<ShapeRow>("shapes");
+  const bindings = () => database.table<BindingRow>("bindings");
+  const meta = () => database.table<MetaRow>("meta");
+
+  async function listBoards(): Promise<BoardMeta[]> {
+    return boards().orderBy("updatedAt").reverse().toArray();
+  }
+
+  async function createBoard(name: string): Promise<string> {
+    const boardId = createId("board");
+    const timestamp = now();
+    const page = PageOps.create("Page 1");
+    const pageRow: PageRow = { ...page, boardId, updatedAt: timestamp };
+
+    await database.transaction("rw", boards(), pages(), meta(), async () => {
+      await boards().add({ id: boardId, name: name || DEFAULT_BOARD_NAME, createdAt: timestamp, updatedAt: timestamp });
+      await pages().add(pageRow);
+      await meta().put({ key: pageOrderKey(boardId), value: [page.id] });
+      await meta().put({ key: shapeOrderKey(boardId), value: { [page.id]: [...page.shapeIds] } });
+    });
+
+    return boardId;
+  }
+
+  async function renameBoard(boardId: string, name: string): Promise<void> {
+    await boards().update(boardId, { name, updatedAt: now() });
+  }
+
+  async function deleteBoard(boardId: string): Promise<void> {
+    await database.transaction("rw", [boards(), pages(), shapes(), bindings(), meta()], async () => {
+      const pageKeys = (await pages().where("boardId").equals(boardId).toArray()).map((row) =>
+        [row.boardId, row.id] as [string, string]
+      );
+      const shapeKeys = (await shapes().where("boardId").equals(boardId).toArray()).map((row) =>
+        [row.boardId, row.id] as [string, string]
+      );
+      const bindingKeys = (await bindings().where("boardId").equals(boardId).toArray()).map((row) =>
+        [row.boardId, row.id] as [string, string]
+      );
+
+      await boards().delete(boardId);
+      if (pageKeys.length > 0) await pages().bulkDelete(pageKeys);
+      if (shapeKeys.length > 0) await shapes().bulkDelete(shapeKeys);
+      if (bindingKeys.length > 0) await bindings().bulkDelete(bindingKeys);
+      await meta().delete(pageOrderKey(boardId));
+      await meta().delete(shapeOrderKey(boardId));
+    });
+  }
+
+  async function loadDoc(boardId: string): Promise<LoadedDoc> {
+    const pageRows = await pages().where("boardId").equals(boardId).toArray();
+    const [shapeRows, bindingRows, order] = await Promise.all([
+      shapes().where("boardId").equals(boardId).toArray(),
+      bindings().where("boardId").equals(boardId).toArray(),
+      loadOrder(boardId, pageRows),
+    ]);
+
+    const docPages: Record<string, PageRecord> = {};
+    for (const row of pageRows) {
+      docPages[row.id] = clonePageRow(row);
+    }
+
+    const docShapes: Record<string, ShapeRecord> = {};
+    for (const row of shapeRows) {
+      docShapes[row.id] = cloneShapeRow(row);
+    }
+
+    const docBindings: Record<string, BindingRecord> = {};
+    for (const row of bindingRows) {
+      docBindings[row.id] = cloneBindingRow(row);
+    }
+
+    return { pages: docPages, shapes: docShapes, bindings: docBindings, order };
+  }
+
+  async function loadOrder(boardId: string, fallbackPages: PageRow[]): Promise<DocOrder> {
+    const pageOrderRow = await meta().get(pageOrderKey(boardId));
+    const shapeOrderRow = await meta().get(shapeOrderKey(boardId));
+    const fallbackPageIds = fallbackPages.map((row) => row.id);
+    const fallbackShapeOrder = shapeOrderFromPageRows(fallbackPages);
+
+    return {
+      pageIds: (pageOrderRow?.value as string[] | undefined) ?? fallbackPageIds,
+      shapeOrder: (shapeOrderRow?.value as Record<string, string[]> | undefined) ?? fallbackShapeOrder,
+    };
+  }
+
+  async function applyDocPatch(boardId: string, patch: DocPatch): Promise<void> {
+    const timestamp = now();
+
+    await database.transaction("rw", [boards(), pages(), shapes(), bindings(), meta()], async () => {
+      const pageDeleteKeys = patch.deletes?.pageIds?.map((id) => [boardId, id] as [string, string]) ?? [];
+      const shapeDeleteKeys = patch.deletes?.shapeIds?.map((id) => [boardId, id] as [string, string]) ?? [];
+      const bindingDeleteKeys = patch.deletes?.bindingIds?.map((id) => [boardId, id] as [string, string]) ?? [];
+
+      if (pageDeleteKeys.length > 0) await pages().bulkDelete(pageDeleteKeys);
+      if (shapeDeleteKeys.length > 0) await shapes().bulkDelete(shapeDeleteKeys);
+      if (bindingDeleteKeys.length > 0) await bindings().bulkDelete(bindingDeleteKeys);
+
+      const upsertPages =
+        patch.upserts?.pages?.map((page) => ({ ...PageOps.clone(page), boardId, updatedAt: timestamp })) ?? [];
+      const upsertShapes =
+        patch.upserts?.shapes?.map((shape) => ({ ...ShapeOps.clone(shape), boardId, updatedAt: timestamp })) ?? [];
+      const upsertBindings =
+        patch.upserts?.bindings?.map((binding) => ({ ...BindingOps.clone(binding), boardId, updatedAt: timestamp }))
+          ?? [];
+
+      if (upsertPages.length > 0) await pages().bulkPut(upsertPages);
+      if (upsertShapes.length > 0) await shapes().bulkPut(upsertShapes);
+      if (upsertBindings.length > 0) await bindings().bulkPut(upsertBindings);
+
+      if (patch.order?.pageIds) {
+        await meta().put({ key: pageOrderKey(boardId), value: [...patch.order.pageIds] });
+      }
+
+      if (patch.order?.shapeOrder) {
+        await meta().put({ key: shapeOrderKey(boardId), value: patch.order.shapeOrder });
+      }
+
+      await boards().update(boardId, { updatedAt: timestamp });
+    });
+  }
+
+  async function exportBoard(boardId: string): Promise<BoardExport> {
+    const board = await boards().get(boardId);
+    if (!board) {
+      throw new Error(`Board ${boardId} not found`);
+    }
+
+    const { pages, shapes, bindings, order } = await loadDoc(boardId);
+    const doc: Document = { pages, shapes, bindings };
+    return { board, doc, order };
+  }
+
+  async function importBoard(snapshot: BoardExport): Promise<string> {
+    const boardId = snapshot.board.id ?? createId("board");
+    const timestamp = now();
+    const board: BoardMeta = {
+      id: boardId,
+      name: snapshot.board.name || DEFAULT_BOARD_NAME,
+      createdAt: snapshot.board.createdAt ?? timestamp,
+      updatedAt: timestamp,
+    };
+
+    await database.transaction("rw", [boards(), pages(), shapes(), bindings(), meta()], async () => {
+      await boards().put(board);
+
+      const pageRows = Object.values(snapshot.doc.pages).map((page) => ({
+        ...PageOps.clone(page),
+        boardId,
+        updatedAt: timestamp,
+      }));
+      const shapeRows = Object.values(snapshot.doc.shapes).map((shape) => ({
+        ...ShapeOps.clone(shape),
+        boardId,
+        updatedAt: timestamp,
+      }));
+      const bindingRows = Object.values(snapshot.doc.bindings).map((binding) => ({
+        ...BindingOps.clone(binding),
+        boardId,
+        updatedAt: timestamp,
+      }));
+
+      if (pageRows.length > 0) await pages().bulkPut(pageRows);
+      if (shapeRows.length > 0) await shapes().bulkPut(shapeRows);
+      if (bindingRows.length > 0) await bindings().bulkPut(bindingRows);
+
+      const order = snapshot.order ?? deriveDocOrderFromDocument(snapshot.doc);
+      await meta().put({ key: pageOrderKey(boardId), value: order.pageIds });
+      await meta().put({ key: shapeOrderKey(boardId), value: order.shapeOrder ?? {} });
+    });
+
+    return boardId;
+  }
+
+  return { listBoards, createBoard, renameBoard, deleteBoard, loadDoc, applyDocPatch, exportBoard, importBoard };
+}
+
+/**
+ * Compute a patch between two documents. Current implementation sends the full snapshot (upsert all rows).
+ */
+export function diffDoc(before: Document, after: Document): DocPatch {
+  const patch: DocPatch = {};
+
+  const deletedPages = difference(Object.keys(before.pages), Object.keys(after.pages));
+  const deletedShapes = difference(Object.keys(before.shapes), Object.keys(after.shapes));
+  const deletedBindings = difference(Object.keys(before.bindings), Object.keys(after.bindings));
+
+  if (deletedPages.length > 0 || deletedShapes.length > 0 || deletedBindings.length > 0) {
+    patch.deletes = {};
+    if (deletedPages.length > 0) patch.deletes.pageIds = deletedPages;
+    if (deletedShapes.length > 0) patch.deletes.shapeIds = deletedShapes;
+    if (deletedBindings.length > 0) patch.deletes.bindingIds = deletedBindings;
+  }
+
+  const pageUpserts = Object.values(after.pages).map((page) => PageOps.clone(page));
+  const shapeUpserts = Object.values(after.shapes).map((shape) => ShapeOps.clone(shape));
+  const bindingUpserts = Object.values(after.bindings).map((binding) => BindingOps.clone(binding));
+
+  if (pageUpserts.length > 0 || shapeUpserts.length > 0 || bindingUpserts.length > 0) {
+    patch.upserts = {};
+    if (pageUpserts.length > 0) patch.upserts.pages = pageUpserts;
+    if (shapeUpserts.length > 0) patch.upserts.shapes = shapeUpserts;
+    if (bindingUpserts.length > 0) patch.upserts.bindings = bindingUpserts;
+  }
+
+  patch.order = deriveDocOrderFromDocument(after);
+
+  return patch;
+}
+
+/**
+ * Batch doc patches and flush them with a debounce to cut down on Dexie writes.
+ */
+export function createPersistenceSink(repo: DocRepo, options?: PersistenceSinkOptions): PersistenceSink {
+  const debounceMs = options?.debounceMs ?? 200;
+  let pendingBoardId: string | null = null;
+  let pendingPatch: DocPatch | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let inflight: Promise<void> | null = null;
+
+  const scheduleFlush = () => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      timer = null;
+      void flush();
+    }, debounceMs);
+  };
+
+  const resetPending = () => {
+    pendingBoardId = null;
+    pendingPatch = null;
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+
+  async function flush(): Promise<void> {
+    if (inflight) {
+      await inflight;
+      return;
+    }
+
+    if (!pendingBoardId || !pendingPatch || isPatchEmpty(pendingPatch)) {
+      resetPending();
+      return;
+    }
+
+    const boardId = pendingBoardId;
+    const patch = pendingPatch;
+    resetPending();
+
+    inflight = repo.applyDocPatch(boardId, patch).finally(() => {
+      inflight = null;
+    });
+
+    await inflight;
+  }
+
+  function enqueueDocPatch(boardId: string, patch: DocPatch): void {
+    if (!boardId) {
+      throw new Error("boardId is required to persist edits");
+    }
+
+    if (pendingBoardId && pendingBoardId !== boardId) {
+      void flush();
+    }
+
+    pendingBoardId = boardId;
+    pendingPatch = clonePatch(patch);
+    if (!isPatchEmpty(pendingPatch)) {
+      scheduleFlush();
+    }
+  }
+
+  return { enqueueDocPatch, flush };
+}
+
+function clonePageRow(row: PageRow): PageRecord {
+  const { boardId: _boardId, updatedAt: _updatedAt, ...rest } = row;
+  return PageOps.clone(rest);
+}
+
+function cloneShapeRow(row: ShapeRow): ShapeRecord {
+  const { boardId: _boardId, updatedAt: _updatedAt, ...rest } = row;
+  return ShapeOps.clone(rest as ShapeRecord);
+}
+
+function cloneBindingRow(row: BindingRow): BindingRecord {
+  const { boardId: _boardId, updatedAt: _updatedAt, ...rest } = row;
+  return BindingOps.clone(rest);
+}
+
+function difference(before: string[], after: string[]): string[] {
+  const afterSet = new Set(after);
+  return before.filter((id) => !afterSet.has(id));
+}
+
+function deriveDocOrderFromDocument(doc: Document): DocOrder {
+  return { pageIds: Object.keys(doc.pages), shapeOrder: shapeOrderFromPagesRecords(doc.pages) };
+}
+
+function shapeOrderFromPagesRecords(pages: Record<string, PageRecord>): Record<string, string[]> {
+  return Object.fromEntries(Object.values(pages).map((page) => [page.id, [...page.shapeIds]]));
+}
+
+function shapeOrderFromPageRows(rows: PageRow[]): Record<string, string[]> {
+  return Object.fromEntries(rows.map((row) => [row.id, [...row.shapeIds]]));
+}
+
+function clonePatch(patch: DocPatch): DocPatch {
+  const cloned: DocPatch = {};
+
+  if (patch.upserts) {
+    cloned.upserts = {};
+    if (patch.upserts.pages) cloned.upserts.pages = patch.upserts.pages.map((page) => PageOps.clone(page));
+    if (patch.upserts.shapes) cloned.upserts.shapes = patch.upserts.shapes.map((shape) => ShapeOps.clone(shape));
+    if (patch.upserts.bindings) {
+      cloned.upserts.bindings = patch.upserts.bindings.map((binding) => BindingOps.clone(binding));
+    }
+    if (!cloned.upserts.pages && !cloned.upserts.shapes && !cloned.upserts.bindings) {
+      delete cloned.upserts;
+    }
+  }
+
+  if (patch.deletes) {
+    cloned.deletes = {};
+    if (patch.deletes.pageIds) cloned.deletes.pageIds = [...patch.deletes.pageIds];
+    if (patch.deletes.shapeIds) cloned.deletes.shapeIds = [...patch.deletes.shapeIds];
+    if (patch.deletes.bindingIds) cloned.deletes.bindingIds = [...patch.deletes.bindingIds];
+    if (!cloned.deletes.pageIds?.length && !cloned.deletes.shapeIds?.length && !cloned.deletes.bindingIds?.length) {
+      delete cloned.deletes;
+    }
+  }
+
+  if (patch.order) {
+    const pageIds = patch.order.pageIds ? [...patch.order.pageIds] : undefined;
+    const shapeOrder = cloneShapeOrderMap(patch.order.shapeOrder);
+    if (pageIds || shapeOrder) {
+      cloned.order = {};
+      if (pageIds) {
+        cloned.order.pageIds = pageIds;
+      }
+      if (shapeOrder) {
+        cloned.order.shapeOrder = shapeOrder;
+      }
+    }
+  }
+
+  return cloned;
+}
+
+function cloneShapeOrderMap(shapeOrder?: Record<string, string[]>): Record<string, string[]> | undefined {
+  if (!shapeOrder) {
+    return undefined;
+  }
+
+  return Object.fromEntries(Object.entries(shapeOrder).map(([pageId, shapeIds]) => [pageId, [...shapeIds]]));
+}
+
+function isPatchEmpty(patch: DocPatch): boolean {
+  const hasUpserts = Boolean(patch.upserts?.pages?.length)
+    || Boolean(patch.upserts?.shapes?.length)
+    || Boolean(patch.upserts?.bindings?.length);
+
+  const hasDeletes = Boolean(patch.deletes?.pageIds?.length)
+    || Boolean(patch.deletes?.shapeIds?.length)
+    || Boolean(patch.deletes?.bindingIds?.length);
+
+  const hasOrder = Boolean(patch.order?.pageIds?.length)
+    || Boolean(patch.order?.shapeOrder && Object.keys(patch.order.shapeOrder).length > 0);
+
+  return !(hasUpserts || hasDeletes || hasOrder);
+}

packages/core/src/reactivity.ts

···
 import { BehaviorSubject, type Subscription } from "rxjs";
 import type { Camera } from "./camera";
 import { Camera as CameraOps } from "./camera";
-import { type Command, History, type HistoryState } from "./history";
+import {
+  type Command,
+  History,
+  type HistoryAppliedEvent,
+  type HistoryEntry,
+  type HistoryOperation,
+  type HistoryState,
+} from "./history";
 import type { Document, PageRecord, ShapeRecord } from "./model";
 import { Document as DocumentOps } from "./model";
 
···
 
 export type StateUpdater = (state: EditorState) => EditorState;
 export type StateListener = (state: EditorState) => void;
+export type StoreOptions = { onHistoryEvent?: (event: HistoryAppliedEvent) => void };
 
 /**
  * Reactive store for editor state
···
 export class Store {
   private readonly state$: BehaviorSubject<EditorState>;
   private history: HistoryState;
+  private readonly historyListener?: (event: HistoryAppliedEvent) => void;
 
-  constructor(initialState?: EditorState) {
+  constructor(initialState?: EditorState, options?: StoreOptions) {
     this.state$ = new BehaviorSubject(initialState ?? EditorState.create());
     this.history = History.create();
+    this.historyListener = options?.onHistoryEvent;
   }
 
   /**
···
     this.history = newHistory;
     const repairedState = enforceInvariants(newState);
     this.state$.next(repairedState);
+    const entry = this.history.undoStack.at(-1);
+    if (entry) {
+      this.emitHistoryEvent("do", entry, currentState, repairedState);
+    }
   }
 
   /**
···
    */
   undo(): boolean {
     const currentState = this.state$.value;
+    const entry = this.history.undoStack.at(-1);
     const result = History.undo(this.history, currentState);
 
     if (!result) {
···
     this.history = newHistory;
     const repairedState = enforceInvariants(newState);
     this.state$.next(repairedState);
+    if (entry) {
+      this.emitHistoryEvent("undo", entry, currentState, repairedState);
+    }
     return true;
   }
 
···
    */
   redo(): boolean {
     const currentState = this.state$.value;
+    const entry = this.history.redoStack.at(-1);
     const result = History.redo(this.history, currentState);
 
     if (!result) {
···
     this.history = newHistory;
     const repairedState = enforceInvariants(newState);
     this.state$.next(repairedState);
+    if (entry) {
+      this.emitHistoryEvent("redo", entry, currentState, repairedState);
+    }
     return true;
   }
 
···
    */
   getObservable() {
     return this.state$.asObservable();
+  }
+
+  private emitHistoryEvent(
+    op: HistoryOperation,
+    entry: HistoryEntry,
+    beforeState: EditorState,
+    afterState: EditorState,
+  ): void {
+    if (!this.historyListener) {
+      return;
+    }
+
+    this.historyListener({
+      op,
+      commandId: entry.timestamp,
+      command: entry.command,
+      kind: entry.command.kind,
+      beforeState,
+      afterState,
+    });
   }
 }
 

packages/core/tests/persistence/web.test.ts

···
+import "fake-indexeddb/auto";
+import Dexie from "dexie";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { InkfiniteDB, runMigrations } from "../../src";
+import {
+  createPersistenceSink,
+  CreateShapeCommand,
+  createWebDocRepo,
+  diffDoc,
+  SetSelectionCommand,
+  Store,
+} from "../../src";
+import { Document as DocumentOps, PageRecord, ShapeRecord } from "../../src/model";
+
+const openDbs: Dexie[] = [];
+
+function createTestDb(name = `inkfinite-test-${Math.random().toString(36).slice(2)}`) {
+  const database = new InkfiniteDB(name);
+  openDbs.push(database);
+  return database;
+}
+
+afterEach(async () => {
+  await Promise.all(openDbs.map(async (database) => {
+    try {
+      await database.delete();
+    } catch {
+      /* No-op */
+    }
+  }));
+  openDbs.length = 0;
+  vi.useRealTimers();
+});
+
+describe("DocRepo (Dexie)", () => {
+  it("createBoard seeds default page + order and rename persists", async () => {
+    const db = createTestDb();
+    const repo = createWebDocRepo(db);
+    const boardId = await repo.createBoard("Seeded");
+    const loaded = await repo.loadDoc(boardId);
+
+    expect(Object.keys(loaded.pages)).toHaveLength(1);
+    expect(loaded.order.pageIds).toHaveLength(1);
+    expect(loaded.order.shapeOrder?.[loaded.order.pageIds[0]!]).toEqual([]);
+
+    await repo.renameBoard(boardId, "Renamed");
+    const boardRow = await db.table("boards").get(boardId);
+    expect(boardRow?.name).toBe("Renamed");
+  });
+
+  it("round-trips docs via applyDocPatch + loadDoc", async () => {
+    const database = createTestDb();
+    const repo = createWebDocRepo(database);
+    const boardId = await repo.createBoard("Round trip");
+
+    const page = PageRecord.create("Canvas");
+    const rect = ShapeRecord.createRect(page.id, 0, 0, { w: 100, h: 80, fill: "#000", stroke: "#fff", radius: 8 });
+    page.shapeIds.push(rect.id);
+
+    const doc = DocumentOps.create();
+    doc.pages[page.id] = page;
+    doc.shapes[rect.id] = rect;
+
+    await repo.applyDocPatch(boardId, diffDoc(DocumentOps.create(), doc));
+
+    const loaded = await repo.loadDoc(boardId);
+    expect(loaded.pages[page.id]).toEqual(page);
+    expect(loaded.shapes[rect.id]).toEqual(rect);
+    expect(loaded.order.pageIds).toContain(page.id);
+  });
+
+  it("applyDocPatch performs a single Dexie transaction", async () => {
+    const database = createTestDb();
+    const repo = createWebDocRepo(database);
+    const boardId = await repo.createBoard("Tx board");
+
+    const page = PageRecord.create("Tx Page");
+    const rect = ShapeRecord.createRect(page.id, 10, 10, { w: 50, h: 50, fill: "#ccc", stroke: "#111", radius: 4 });
+    page.shapeIds.push(rect.id);
+
+    const doc = DocumentOps.create();
+    doc.pages[page.id] = page;
+    doc.shapes[rect.id] = rect;
+
+    const transactionSpy = vi.spyOn(database, "transaction");
+    await repo.applyDocPatch(boardId, diffDoc(DocumentOps.create(), doc));
+    expect(transactionSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("deleteBoard removes rows across all tables", async () => {
+    const database = createTestDb();
+    const repo = createWebDocRepo(database);
+    const boardId = await repo.createBoard("Delete board");
+
+    const page = PageRecord.create("Delete Page");
+    const rect = ShapeRecord.createRect(page.id, 0, 0, { w: 40, h: 40, fill: "#f00", stroke: "#000", radius: 2 });
+    page.shapeIds.push(rect.id);
+
+    const doc = DocumentOps.create();
+    doc.pages[page.id] = page;
+    doc.shapes[rect.id] = rect;
+
+    await repo.applyDocPatch(boardId, diffDoc(DocumentOps.create(), doc));
+    await repo.deleteBoard(boardId);
+
+    expect(await database.table("boards").toArray()).toHaveLength(0);
+    expect(await database.table("pages").toArray()).toHaveLength(0);
+    expect(await database.table("shapes").toArray()).toHaveLength(0);
+    expect(await database.table("bindings").toArray()).toHaveLength(0);
+  });
+
+  it("exportBoard + importBoard round-trip doc + metadata", async () => {
+    const db = createTestDb();
+    const repo = createWebDocRepo(db);
+    const boardId = await repo.createBoard("Source");
+
+    const page = PageRecord.create("Canvas");
+    const rect = ShapeRecord.createRect(page.id, 5, 5, { w: 20, h: 10, fill: "#123", stroke: "#456", radius: 1 });
+    page.shapeIds.push(rect.id);
+
+    const doc = DocumentOps.create();
+    doc.pages[page.id] = page;
+    doc.shapes[rect.id] = rect;
+
+    await repo.applyDocPatch(boardId, diffDoc(DocumentOps.create(), doc));
+
+    const snapshot = await repo.exportBoard(boardId);
+    const importedId = await repo.importBoard({
+      ...snapshot,
+      board: { ...snapshot.board, id: "board:imported", name: "Imported" },
+    });
+
+    const imported = await repo.loadDoc(importedId);
+    expect(imported.pages).toEqual(snapshot.doc.pages);
+    expect(imported.shapes).toEqual(snapshot.doc.shapes);
+  });
+});
+
+describe("History persistence sink", () => {
+  let repo: ReturnType<typeof createWebDocRepo>;
+  let boardId: string;
+
+  beforeEach(async () => {
+    const database = createTestDb();
+    repo = createWebDocRepo(database);
+    boardId = await repo.createBoard("Persisted");
+  });
+
+  it("doc command triggers exactly one persistence flush", async () => {
+    const { store, sink, applySpy, pageId } = await createStoreWithSink(repo, boardId);
+
+    const rect = ShapeRecord.createRect(pageId, 0, 0, { w: 10, h: 10, fill: "#222", stroke: "#fff", radius: 0 });
+
+    store.executeCommand(new CreateShapeCommand(rect, pageId));
+    expect(applySpy).toHaveBeenCalledTimes(0);
+
+    await sink.flush();
+
+    expect(applySpy).toHaveBeenCalledTimes(1);
+    const loaded = await repo.loadDoc(boardId);
+    expect(loaded.shapes[rect.id]).toBeDefined();
+  });
+
+  it("undo and redo both persist document changes", async () => {
+    const { store, sink, applySpy, pageId } = await createStoreWithSink(repo, boardId);
+
+    const rect = ShapeRecord.createRect(pageId, 0, 0, { w: 25, h: 25, fill: "#0f0", stroke: "#090", radius: 0 });
+
+    store.executeCommand(new CreateShapeCommand(rect, pageId));
+    await sink.flush();
+    applySpy.mockClear();
+
+    store.undo();
+    await sink.flush();
+    expect(applySpy).toHaveBeenCalledTimes(1);
+    let loaded = await repo.loadDoc(boardId);
+    expect(loaded.shapes[rect.id]).toBeUndefined();
+
+    applySpy.mockClear();
+    store.redo();
+    await sink.flush();
+    expect(applySpy).toHaveBeenCalledTimes(1);
+    loaded = await repo.loadDoc(boardId);
+    expect(loaded.shapes[rect.id]).toBeDefined();
+  });
+
+  it("ui-only commands never hit persistence", async () => {
+    const { store, sink, applySpy, pageId } = await createStoreWithSink(repo, boardId);
+
+    const rect = ShapeRecord.createRect(pageId, 0, 0, { w: 15, h: 15, fill: "#aaa", stroke: "#bbb", radius: 0 });
+
+    store.executeCommand(new CreateShapeCommand(rect, pageId));
+    await sink.flush();
+    applySpy.mockClear();
+
+    store.executeCommand(new SetSelectionCommand([], [rect.id]));
+    await sink.flush();
+
+    expect(applySpy).toHaveBeenCalledTimes(0);
+  });
+
+  it("batches rapid doc commands into one flush", async () => {
+    const { store, sink, applySpy, pageId } = await createStoreWithSink(repo, boardId);
+
+    for (let i = 0; i < 10; i++) {
+      const rect = ShapeRecord.createRect(pageId, i * 5, 0, { w: 5, h: 5, fill: "#444", stroke: "#111", radius: 0 });
+      store.executeCommand(new CreateShapeCommand(rect, pageId));
+    }
+
+    await sink.flush();
+
+    expect(applySpy).toHaveBeenCalledTimes(1);
+    const loaded = await repo.loadDoc(boardId);
+    expect(Object.keys(loaded.shapes).length).toBeGreaterThanOrEqual(10);
+  });
+});
+
+describe("runMigrations", () => {
+  it("backfills timestamps and default page/order", async () => {
+    const db = new Dexie(`migrations-test-${Math.random().toString(36).slice(2)}`);
+    db.version(1).stores({
+      boards: "id, name, createdAt, updatedAt",
+      pages: "[boardId+id], boardId, updatedAt",
+      shapes: "[boardId+id], boardId, type, updatedAt",
+      bindings: "[boardId+id], boardId, type, updatedAt",
+      meta: "key",
+      migrations: "id, appliedAt",
+    });
+    openDbs.push(db);
+    await db.open();
+    await db.table("boards").add({ id: "board:legacy", name: "Legacy Board" });
+
+    await db.transaction("rw", db.tables, async (tx) => {
+      await runMigrations(tx);
+    });
+
+    const board = await db.table("boards").get("board:legacy");
+    expect(board?.createdAt).toBeTypeOf("number");
+    expect(board?.updatedAt).toBeTypeOf("number");
+
+    const pages = await db.table("pages").where("boardId").equals("board:legacy").toArray();
+    expect(pages).toHaveLength(1);
+
+    const pageOrder = await db.table("meta").get(`page-order:board:legacy`);
+    expect(pageOrder?.value).toEqual([pages[0]!.id]);
+
+    const shapeOrder = await db.table("meta").get(`shape-order:board:legacy`);
+    expect(shapeOrder?.value).toEqual({ [pages[0]!.id]: [] });
+
+    const migrations = await db.table("migrations").toArray();
+    expect(migrations.map((row) => row.id)).toContain("MIG-0001");
+    expect(migrations.map((row) => row.id)).toContain("MIG-0002");
+  });
+
+  it("does not re-apply already applied migrations", async () => {
+    const db = new Dexie(`migrations-repeat-${Math.random().toString(36).slice(2)}`);
+    db.version(1).stores({
+      boards: "id, name, createdAt, updatedAt",
+      pages: "[boardId+id], boardId, updatedAt",
+      shapes: "[boardId+id], boardId, type, updatedAt",
+      bindings: "[boardId+id], boardId, type, updatedAt",
+      meta: "key",
+      migrations: "id, appliedAt",
+    });
+    openDbs.push(db);
+    await db.open();
+    await db.table("boards").add({ id: "board:legacy-two", name: "Legacy", createdAt: 1, updatedAt: 1 });
+
+    await db.transaction("rw", db.tables, async (tx) => {
+      await runMigrations(tx);
+    });
+
+    const migrationsAfterFirstRun = await db.table("migrations").toArray();
+
+    await db.table("pages").clear();
+    await db.table("meta").clear();
+
+    await db.transaction("rw", db.tables, async (tx) => {
+      await runMigrations(tx);
+    });
+
+    const migrationsAfterSecondRun = await db.table("migrations").toArray();
+    expect(migrationsAfterSecondRun).toHaveLength(migrationsAfterFirstRun.length);
+  });
+});
+
+async function createStoreWithSink(repo: ReturnType<typeof createWebDocRepo>, boardId: string) {
+  const sink = createPersistenceSink(repo, { debounceMs: 10 });
+  const applySpy = vi.spyOn(repo, "applyDocPatch");
+  const store = new Store(undefined, {
+    onHistoryEvent: (event) => {
+      if (event.kind !== "doc") {
+        return;
+      }
+      const patch = diffDoc(event.beforeState.doc, event.afterState.doc);
+      sink.enqueueDocPatch(boardId, patch);
+    },
+  });
+
+  const pageId = await hydrateStoreFromRepo(store, repo, boardId);
+  return { store, sink, applySpy, pageId };
+}
+
+async function hydrateStoreFromRepo(store: Store, repo: ReturnType<typeof createWebDocRepo>, boardId: string) {
+  const loaded = await repo.loadDoc(boardId);
+  const firstPageId = loaded.order.pageIds[0] ?? Object.keys(loaded.pages)[0];
+
+  store.setState((state) => ({
+    ...state,
+    doc: { pages: loaded.pages, shapes: loaded.shapes, bindings: loaded.bindings },
+    ui: { ...state.ui, currentPageId: firstPageId ?? null },
+  }));
+
+  return firstPageId!;
+}

packages/core/vitest.config.ts

···
 export default defineConfig({
   test: {
     ui: false,
+    watch: false,
     coverage: {
       provider: "v8",
       reporter: ["text", "html", "json"],

packages/renderer/vitest.config.ts

···
 import { defineConfig } from "vitest/config";
 
-export default defineConfig({ test: { environment: "jsdom", globals: true, ui: false } });
+export default defineConfig({ test: { environment: "jsdom", globals: true, ui: false, watch: false } });

pnpm-lock.yaml

···
 
   apps/web:
     dependencies:
+      dexie:
+        specifier: ^4.2.1
+        version: 4.2.1
       inkfinite-core:
         specifier: workspace:*
         version: link:../../packages/core
···
       bumpp:
         specifier: ^10.3.2
         version: 10.3.2(magicast@0.5.1)
+      fake-indexeddb:
+        specifier: ^6.0.0
+        version: 6.2.5
       tsdown:
         specifier: ^0.18.1
         version: 0.18.1(typescript@5.9.3)
···
 
   exsolve@1.0.8:
     resolution: {integrity: sha512-LmDxfWXwcTArk8fUEnOfSZpHOJ6zOMUJKOtFLFqJLoKJetuQG874Uc7/Kki7zFLzYybmZhp1M7+98pfMqeX8yA==}
+
+  fake-indexeddb@6.2.5:
+    resolution: {integrity: sha512-CGnyrvbhPlWYMngksqrSSUT1BAVP49dZocrHuK0SvtR0D5TMs5wP0o3j7jexDJW01KSadjBp1M/71o/KR3nD1w==}
+    engines: {node: '>=18'}
 
   fast-deep-equal@3.1.3:
     resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
···
   expect-type@1.3.0: {}
 
   exsolve@1.0.8: {}
+
+  fake-indexeddb@6.2.5: {}
 
   fast-deep-equal@3.1.3: {}