@thomasfosterau/components 0.0.0 → 0.2.0

package/dist/canvas/VectorCanvas.svelte

@@ -0,0 +1,320 @@
+<!-- @component
+A pan-and-zoom SVG surface over a `VectorDocument`, with each element drawn by a renderer snippet the application supplies.
+-->
+<!--
+  VectorCanvas — a pan-and-zoom SVG surface over a {@link VectorDocument}, with
+  the elements drawn by a renderer the application supplies.
+
+  It owns the viewport and the pointer plumbing; it owns nothing about what the
+  elements MEAN. Selection, creation and dragging are the application's, reached
+  through `oninteract` — which is why a floor-plan editor and a planting plan
+  can share this without either one's vocabulary leaking into it.
+
+  ## ARIA contract
+
+  The `<svg>` is `role="application"` named by `label` (default "Vector editing
+  canvas"). `application` is the honest role for a surface that interprets its
+  own input — it tells a screen reader to pass keys through rather than to read
+  the SVG as a picture — and it is a promise that the surface HANDLES those
+  keys, which § Keys keeps.
+
+  ## Keys
+
+  When `interactive`, the `<svg>` is one Tab stop, and every keydown and keyup
+  on it goes to `onkey` FIRST. What a key means to the elements is the
+  application's, for the same reason a pointer gesture is. Only a key the
+  application left alone (did not `preventDefault`), and not a Ctrl, Alt or
+  Meta chord, falls through to the two bindings this component owns, because
+  it owns the viewport:
+
+  | Key                     | Does                                         |
+  | ----------------------- | -------------------------------------------- |
+  | Arrow keys (`pan` tool) | pan by 40 screen pixels; Shift for 160       |
+  | `+` / `=`, `-`          | zoom in / out about the centre of the view   |
+
+  The application says which of its elements is focused through
+  `activedescendant` (an element id inside the surface), so DOM focus stays on
+  the `<svg>` and the arrow keys never scroll the page out from under the
+  reader.
+
+  ## Two decisions worth stating
+
+  - The document prop is `doc`, not `document`: a prop called `document` shadows
+    the global inside a component that also reaches for the DOM, which is a bug
+    waiting for the next line of code.
+  - The viewport is REPORTED through `onviewportchange` rather than mutated
+    through `$bindable`, so the document stays the caller's to own and an undo
+    stack has something to undo.
+
+  Pointer events rather than mouse events: one code path covers mouse, touch and
+  pen, and `setPointerCapture` keeps a drag alive past the edge of the canvas.
+
+  Hand-rolled rather than built on a bits-ui primitive because there is no
+  primitive for this: bits-ui owns focus, keyboard and ARIA relationships
+  between named widgets, and a pan/zoom surface is none of those — it is raw
+  pointer geometry.
+-->
+<script lang="ts" generics="T extends CanvasElement">import { panBy, screenToCanvas, snapToGrid, sortByZIndex, zoomAbout } from "./utils.js";
+let { doc, selected = new Set(), tool = "select", width = 800, height = 600, element, interactive = true, label = "Vector editing canvas", activedescendant = "", describedby = "", overlay, onkey, onfocuschange, onviewportchange, oninteract, class: className, ...rest } = $props();
+// Scoped to this instance: two canvases on one page would otherwise share a
+// `<pattern id>`, and the second would paint the first's grid.
+const uid = $props.id();
+const gridPatternId = `vector-canvas-grid-${uid}`;
+let surface = $state();
+/** -1 is "no pointer down"; the id is what `setPointerCapture` released. */
+let dragging = $state(-1);
+let panning = $state(false);
+/**
+* The pointer's last SCREEN position, so a pan is the difference between two
+* positions we recorded. `MouseEvent.movementX` would say the same thing in
+* one property, but its value is scaled by the device pixel ratio in some
+* browsers and zeroed after a coalesced move in others — a pan that drifts
+* on one machine and not another is not worth the line it saves.
+*/
+let lastScreen = $state({
+	x: 0,
+	y: 0
+});
+/**
+* Chromium's own double-click interval and its slop, in milliseconds and CSS
+* pixels.
+*/
+const MULTI_PRESS_MS = 500;
+const MULTI_PRESS_SLOP = 4;
+/** The run of rapid presses at one spot: 1, then 2, then 3… */
+let pressCount = 0;
+let lastPress = {
+	time: 0,
+	x: 0,
+	y: 0
+};
+/**
+* The press count, counted HERE rather than read off `event.detail`.
+*
+* `MouseEvent.detail` carries the click count; `PointerEvent.detail` is 0,
+* always, in every browser — and a component that listens on pointer events
+* to cover mouse, touch and pen alike therefore never sees it. That is easy
+* to miss, because a synthetic `pointerdown` dispatched by a test carries
+* whatever `detail` the test puts on it: the check reads as working and does
+* nothing at all in a browser. Counting it here also makes a double-TAP
+* count, which `detail` would not have done on any input.
+*/
+const countPress = (event) => {
+	const rapid = event.timeStamp - lastPress.time < MULTI_PRESS_MS && Math.abs(event.clientX - lastPress.x) <= MULTI_PRESS_SLOP && Math.abs(event.clientY - lastPress.y) <= MULTI_PRESS_SLOP;
+	pressCount = rapid ? pressCount + 1 : 1;
+	lastPress = {
+		time: event.timeStamp,
+		x: event.clientX,
+		y: event.clientY
+	};
+	return pressCount;
+};
+const ordered = $derived(sortByZIndex(doc.elements));
+const at = (event) => {
+	if (surface === undefined) return {
+		x: 0,
+		y: 0
+	};
+	const box = surface.getBoundingClientRect();
+	const point = screenToCanvas({
+		x: event.clientX - box.left,
+		y: event.clientY - box.top
+	}, doc.viewport);
+	return doc.grid.snap ? snapToGrid(point, doc.grid.size) : point;
+};
+const down = (event) => {
+	if (!interactive) return;
+	// Capture on the surface so a drag that leaves the element keeps reporting.
+	// Guarded rather than called bare: a test DOM (and an old browser) can
+	// have the element without the method, and a TypeError here would take
+	// the whole gesture with it.
+	if (typeof surface?.setPointerCapture === "function") surface.setPointerCapture(event.pointerId);
+	dragging = event.pointerId;
+	panning = tool === "pan";
+	lastScreen = {
+		x: event.clientX,
+		y: event.clientY
+	};
+	const detail = countPress(event);
+	if (!panning) oninteract?.({
+		phase: "down",
+		tool,
+		point: at(event),
+		detail,
+		native: event
+	});
+};
+const move = (event) => {
+	if (!interactive || dragging !== event.pointerId) return;
+	if (panning) {
+		onviewportchange?.(panBy(doc.viewport, event.clientX - lastScreen.x, event.clientY - lastScreen.y));
+		lastScreen = {
+			x: event.clientX,
+			y: event.clientY
+		};
+	} else oninteract?.({
+		phase: "move",
+		tool,
+		point: at(event),
+		detail: 1,
+		native: event
+	});
+};
+const up = (event) => {
+	if (!interactive || dragging !== event.pointerId) return;
+	if (typeof surface?.releasePointerCapture === "function") {
+		surface.releasePointerCapture(event.pointerId);
+	}
+	if (!panning) oninteract?.({
+		phase: "up",
+		tool,
+		point: at(event),
+		detail: 1,
+		native: event
+	});
+	dragging = -1;
+	panning = false;
+};
+const wheel = (event) => {
+	if (!interactive || surface === undefined) return;
+	event.preventDefault();
+	const box = surface.getBoundingClientRect();
+	const pointer = {
+		x: event.clientX - box.left,
+		y: event.clientY - box.top
+	};
+	onviewportchange?.(zoomAbout(doc.viewport, pointer, event.deltaY > 0 ? .9 : 1.1));
+};
+/** Screen pixels one arrow press pans by with the `pan` tool; Shift multiplies it. */
+const PAN_STEP = 40;
+const COARSE_PAN = 4;
+/** Which way the view moves for each arrow: right reveals more of the right. */
+const PAN_DIRECTIONS = new Map([
+	["ArrowLeft", {
+		x: 1,
+		y: 0
+	}],
+	["ArrowRight", {
+		x: -1,
+		y: 0
+	}],
+	["ArrowUp", {
+		x: 0,
+		y: 1
+	}],
+	["ArrowDown", {
+		x: 0,
+		y: -1
+	}]
+]);
+/** The zoom factor per key; `=` is `+` without the Shift. */
+const ZOOM_KEYS = new Map([
+	["+", 1.1],
+	["=", 1.1],
+	["-", .9]
+]);
+/** The view's own keys, for whatever the application did not claim. */
+const viewKey = (event) => {
+	const factor = ZOOM_KEYS.get(event.key);
+	if (factor !== undefined) {
+		onviewportchange?.(zoomAbout(doc.viewport, {
+			x: width / 2,
+			y: height / 2
+		}, factor));
+		return true;
+	}
+	const direction = PAN_DIRECTIONS.get(event.key);
+	if (tool !== "pan" || direction === undefined) return false;
+	const step = PAN_STEP * (event.shiftKey ? COARSE_PAN : 1);
+	onviewportchange?.(panBy(doc.viewport, direction.x * step, direction.y * step));
+	return true;
+};
+const key = (event) => {
+	if (!interactive) return;
+	onkey?.(event);
+	if (event.type !== "keydown" || event.defaultPrevented) return;
+	if (event.ctrlKey || event.metaKey || event.altKey) return;
+	if (viewKey(event)) event.preventDefault();
+};
+</script>
+
+<div
+  class={['bg-base-100 relative overflow-hidden select-none', className]}
+  style:width="{width}px"
+  style:height="{height}px"
+  style:touch-action="none"
+>
+  <!-- Svelte's a11y table files `application` under the non-interactive roles;
+       ARIA defines it as the role that takes focus and handles its own keys,
+       which is exactly what the tabindex and the key handlers are for. -->
+  <!-- svelte-ignore a11y_no_noninteractive_tabindex, a11y_no_noninteractive_element_interactions -->
+  <svg
+    {...rest}
+    bind:this={surface}
+    {width}
+    {height}
+    role="application"
+    aria-label={label}
+    aria-activedescendant={activedescendant === '' ? undefined : activedescendant}
+    aria-describedby={describedby === '' ? undefined : describedby}
+    tabindex={interactive ? 0 : undefined}
+    class="focus-visible:outline-primary cursor-crosshair focus:outline-none focus-visible:outline-2 focus-visible:-outline-offset-2"
+    onkeydown={key}
+    onkeyup={key}
+    onfocus={() => onfocuschange?.(true)}
+    onblur={() => onfocuschange?.(false)}
+    onpointerdown={down}
+    onpointermove={move}
+    onpointerup={up}
+    onpointercancel={up}
+    onwheel={wheel}
+  >
+    <defs>
+      <pattern
+        id={gridPatternId}
+        width={doc.grid.size}
+        height={doc.grid.size}
+        patternUnits="userSpaceOnUse"
+      >
+        <path
+          d="M {doc.grid.size} 0 L 0 0 0 {doc.grid.size}"
+          fill="none"
+          stroke={doc.grid.color}
+          stroke-width="0.5"
+        />
+      </pattern>
+    </defs>
+
+    <g
+      transform="translate({doc.viewport.offsetX},{doc.viewport.offsetY}) scale({doc.viewport.zoom})"
+    >
+      {#if doc.grid.visible}
+        <!-- Sized to swamp any reachable pan rather than tracked to the
+             viewport: a rect that has to be recomputed on every pan is a
+             reactive dependency for a decoration. -->
+        <rect x={-10000} y={-10000} width={20000} height={20000} fill="url(#{gridPatternId})" />
+      {/if}
+
+      {#each ordered as node (node.id)}
+        <g opacity={node.visible === false ? 0 : node.opacity}>
+          {#if element}
+            {@render element(node, selected.has(node.id))}
+          {:else}
+            <!-- The fallback is a marker, not a drawing: an application that
+                 has not supplied a renderer should SEE that it has not. -->
+            <circle
+              cx={node.position.x}
+              cy={node.position.y}
+              r="5"
+              fill={node.fillColor}
+              stroke={selected.has(node.id) ? 'currentColor' : node.strokeColor}
+              stroke-width={node.strokeWidth}
+            />
+          {/if}
+        </g>
+      {/each}
+
+      {@render overlay?.()}
+    </g>
+  </svg>
+</div>

package/dist/canvas/VectorCanvas.svelte.d.ts

@@ -0,0 +1,105 @@
+import type { Snippet } from 'svelte';
+import type { SVGAttributes } from 'svelte/elements';
+import type { CanvasElement, Point, VectorDocument, Viewport } from './types.ts';
+declare function $$render<T extends CanvasElement>(): {
+    props: Omit<SVGAttributes<SVGSVGElement>, "class" | "onfocus" | "onblur" | "onkeydown" | "onkeyup" | "height" | "width"> & {
+        /** The document to draw: its elements, viewport and grid. */
+        doc: VectorDocument<T>;
+        /**
+         * Which elements the application considers selected.
+         * @defaultValue an empty set
+         */
+        selected?: ReadonlySet<string> | undefined;
+        /**
+         * The application's active tool; `pan` is the one this component handles.
+         * @defaultValue `'select'`
+         */
+        tool?: string | undefined;
+        /**
+         * Viewport size in CSS pixels.
+         * @defaultValue `800`
+         */
+        width?: number | undefined;
+        /**
+         * Viewport height in CSS pixels.
+         * @defaultValue `600`
+         */
+        height?: number | undefined;
+        /** Draws one element, told whether it is selected. */
+        element?: Snippet<[T, boolean]> | undefined;
+        /**
+         * Whether pointer input is accepted at all.
+         * @defaultValue `true`
+         */
+        interactive?: boolean | undefined;
+        /**
+         * Names the surface for assistive tech.
+         * @defaultValue `'Vector editing canvas'`
+         */
+        label?: string | undefined;
+        /**
+         * The id of the element that has keyboard focus inside the surface, for
+         * `aria-activedescendant`; `''` for none.
+         * @defaultValue `''`
+         */
+        activedescendant?: string | undefined;
+        /**
+         * The id of an element describing the surface's keys, for
+         * `aria-describedby`; `''` for none.
+         * @defaultValue `''`
+         */
+        describedby?: string | undefined;
+        /** Drawn above every element, in canvas coordinates: a cursor, a guide. */
+        overlay?: Snippet<[]> | undefined;
+        /** Every keydown and keyup on the surface, before its own keys; `preventDefault` claims the key. */
+        onkey?: ((event: KeyboardEvent) => void) | undefined;
+        /** Whether the surface has keyboard focus, each time that changes. */
+        onfocuschange?: ((focused: boolean) => void) | undefined;
+        /**
+         * The viewport after a pan or a zoom.
+         *
+         * `| undefined` on every callback here and below is the `$props()` seam
+         * under `exactOptionalPropertyTypes`: a caller holding an optional handler
+         * spreads it straight through, and `{...maybe}` hands over an explicit
+         * `undefined` that a bare `?:` would refuse.
+         */
+        onviewportchange?: ((viewport: Viewport) => void) | undefined;
+        /** A pointer gesture, in canvas coordinates, snapped when the grid says so. */
+        oninteract?: ((event: {
+            readonly phase: "down" | "move" | "up";
+            readonly tool: string;
+            readonly point: Point;
+            /**
+             * How many presses this one is in a run of rapid presses at the same
+             * spot: 1 for a single press, 2 for the second of a double-press.
+             * Always 1 on `move` and `up`.
+             */
+            readonly detail: number;
+            readonly native: PointerEvent;
+        }) => void) | undefined;
+        /** Merged onto the sized box that clips the surface, caller's last. */
+        class?: string | undefined;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends CanvasElement> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends CanvasElement>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends CanvasElement>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/** A pan-and-zoom SVG surface over a `VectorDocument`, with each element drawn by a renderer snippet the application supplies. */
+declare const VectorCanvas: $$IsomorphicComponent;
+type VectorCanvas<T extends CanvasElement> = InstanceType<typeof VectorCanvas<T>>;
+export default VectorCanvas;

package/dist/canvas/history.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Undo and redo over a {@link VectorDocument}, as pure functions on the
+ * {@link Transform} and {@link HistoryEntry} types `./types.ts` already
+ * declares.
+ *
+ * Those two types were written for exactly this; `Transform`'s own comment is
+ * the specification — "carrying the previous elements alongside the new ones is
+ * what makes a transform invertible — undo is the same structure read
+ * backwards, rather than a second code path". This module takes it at its word,
+ * so there is no second structure to keep in step with the first.
+ *
+ * **Transforms, not snapshots.** A history of whole documents is bounded by the
+ * size of the PLAN; a history of transforms is bounded by the size of the
+ * EDITS. A plan with four hundred elements would otherwise cost four hundred
+ * elements per keystroke.
+ *
+ * @module @thomasfosterau/components/canvas/history
+ */
+import type { CanvasElement, HistoryEntry, Transform, VectorDocument } from './types.ts';
+/**
+ * How many steps back an editing session can walk.
+ *
+ * Capped rather than unbounded: a plan editor is a long-lived page, and an
+ * unbounded stack is a leak that only shows up in the session that matters. A
+ * hundred is well past what a reader walks back by hand.
+ */
+export declare const HISTORY_LIMIT = 100;
+/** The undo and redo stacks; the caller owns them, as it owns the document. */
+export interface History<T extends CanvasElement = CanvasElement> {
+    /** Oldest first; the last entry is the one `undo` takes back. */
+    readonly past: readonly HistoryEntry<T>[];
+    /** Nearest first; the first entry is the one `redo` puts back. */
+    readonly future: readonly HistoryEntry<T>[];
+}
+/** A session with nothing to undo. */
+export declare const emptyHistory: <T extends CanvasElement>() => History<T>;
+/**
+ * A transform's meaning, for every one of the four `type`s:
+ * **every id in `elementIds` ends as its entry in `elements`, or absent when
+ * `elements` has none for it.**
+ *
+ * `add`, `update` and `delete` are the narrow cases of that one rule (absent
+ * before, present both, present before) and `batch` is the mixed one. Naming
+ * them separately is for the reader and for a history entry's `description`;
+ * the arithmetic below does not branch on `type` at all, which is why a
+ * mixed `batch` cannot be the case somebody forgot to handle.
+ *
+ * `previousElements` is not read here — it is what {@link invertTransform}
+ * needs, and reading it would make applying a transform depend on the document
+ * it was recorded against still being the current one.
+ *
+ * A re-added element is APPENDED rather than restored to its old index. Paint
+ * order is `zIndex`'s job (`sortByZIndex`), so the array's order carries no
+ * meaning to preserve.
+ */
+export declare const applyTransform: <T extends CanvasElement>(doc: VectorDocument<T>, transform: Transform<T>) => VectorDocument<T>;
+/**
+ * The transform that undoes this one: the two element lists swapped, and
+ * `add` and `delete` exchanged so a history entry still reads as what it did.
+ *
+ * Both lists are written as arrays even when the original omitted one, so the
+ * result is a transform whose own inverse is the original — `invert(invert(t))`
+ * differs from `t` only in carrying `[]` where `t` carried nothing.
+ */
+export declare const invertTransform: <T extends CanvasElement>(transform: Transform<T>) => Transform<T>;
+/**
+ * The history with one edit pushed on.
+ *
+ * Recording CLEARS the redo stack, which is the standard rule and the only
+ * honest one: once the document has diverged, the futures recorded against the
+ * old one describe a document that no longer exists.
+ *
+ * `timestamp` is a parameter rather than a `Date.now()` call inside, so this
+ * stays a pure function a test can pin.
+ */
+export declare const recordEdit: <T extends CanvasElement>(history: History<T>, transform: Transform<T>, description?: string, timestamp?: number) => History<T>;
+/**
+ * The transform from one set of elements to another, both keyed by id.
+ *
+ * This is how a component that has just changed a document reports WHAT it
+ * changed without keeping a parallel log: snapshot the elements a gesture is
+ * about when it starts, read them again when it ends, and the difference is the
+ * history entry. A gesture that touched one element costs one element, however
+ * many pointer moves it took.
+ *
+ * The `type` is named from the two sets — absent before is an `add`, absent
+ * after a `delete`, a mix a `batch` — so an entry's `type` still reads as what
+ * the reader did even though {@link applyTransform} does not branch on it.
+ */
+export declare const diffTransform: <T extends CanvasElement>(before: readonly T[], after: readonly T[]) => Transform<T>;
+/** A document and the history that goes with it, after a step in either direction. */
+export interface HistoryStep<T extends CanvasElement = CanvasElement> {
+    readonly doc: VectorDocument<T>;
+    readonly history: History<T>;
+}
+/**
+ * The document one step back, or nothing when there is nothing to undo.
+ *
+ * None-or-one rather than a nullable result, for `boundingBox`'s reason: the
+ * caller writes `const [step] = undo(...)` and the empty case needs no
+ * sentinel to remember to check.
+ */
+export declare const undo: <T extends CanvasElement>(doc: VectorDocument<T>, history: History<T>) => readonly HistoryStep<T>[];
+/** The document one step forward, or nothing when there is nothing to redo. */
+export declare const redo: <T extends CanvasElement>(doc: VectorDocument<T>, history: History<T>) => readonly HistoryStep<T>[];

package/dist/canvas/history.js

@@ -0,0 +1,147 @@
+/**
+ * Undo and redo over a {@link VectorDocument}, as pure functions on the
+ * {@link Transform} and {@link HistoryEntry} types `./types.ts` already
+ * declares.
+ *
+ * Those two types were written for exactly this; `Transform`'s own comment is
+ * the specification — "carrying the previous elements alongside the new ones is
+ * what makes a transform invertible — undo is the same structure read
+ * backwards, rather than a second code path". This module takes it at its word,
+ * so there is no second structure to keep in step with the first.
+ *
+ * **Transforms, not snapshots.** A history of whole documents is bounded by the
+ * size of the PLAN; a history of transforms is bounded by the size of the
+ * EDITS. A plan with four hundred elements would otherwise cost four hundred
+ * elements per keystroke.
+ *
+ * @module @thomasfosterau/components/canvas/history
+ */
+/**
+ * How many steps back an editing session can walk.
+ *
+ * Capped rather than unbounded: a plan editor is a long-lived page, and an
+ * unbounded stack is a leak that only shows up in the session that matters. A
+ * hundred is well past what a reader walks back by hand.
+ */
+export const HISTORY_LIMIT = 100;
+/** A session with nothing to undo. */
+export const emptyHistory = () => ({ past: [], future: [] });
+/**
+ * A transform's meaning, for every one of the four `type`s:
+ * **every id in `elementIds` ends as its entry in `elements`, or absent when
+ * `elements` has none for it.**
+ *
+ * `add`, `update` and `delete` are the narrow cases of that one rule (absent
+ * before, present both, present before) and `batch` is the mixed one. Naming
+ * them separately is for the reader and for a history entry's `description`;
+ * the arithmetic below does not branch on `type` at all, which is why a
+ * mixed `batch` cannot be the case somebody forgot to handle.
+ *
+ * `previousElements` is not read here — it is what {@link invertTransform}
+ * needs, and reading it would make applying a transform depend on the document
+ * it was recorded against still being the current one.
+ *
+ * A re-added element is APPENDED rather than restored to its old index. Paint
+ * order is `zIndex`'s job (`sortByZIndex`), so the array's order carries no
+ * meaning to preserve.
+ */
+export const applyTransform = (doc, transform) => {
+    const touched = new Set(transform.elementIds);
+    const next = new Map((transform.elements ?? []).map((element) => [element.id, element]));
+    const present = new Set(doc.elements.map((element) => element.id));
+    const kept = doc.elements.flatMap((element) => {
+        if (!touched.has(element.id))
+            return [element];
+        const replacement = next.get(element.id);
+        return replacement === undefined ? [] : [replacement];
+    });
+    const added = (transform.elements ?? []).filter((element) => !present.has(element.id));
+    return { ...doc, elements: [...kept, ...added] };
+};
+/**
+ * The transform that undoes this one: the two element lists swapped, and
+ * `add` and `delete` exchanged so a history entry still reads as what it did.
+ *
+ * Both lists are written as arrays even when the original omitted one, so the
+ * result is a transform whose own inverse is the original — `invert(invert(t))`
+ * differs from `t` only in carrying `[]` where `t` carried nothing.
+ */
+export const invertTransform = (transform) => ({
+    type: transform.type === 'add' ? 'delete' : transform.type === 'delete' ? 'add' : transform.type,
+    elementIds: transform.elementIds,
+    elements: transform.previousElements ?? [],
+    previousElements: transform.elements ?? [],
+});
+/**
+ * The history with one edit pushed on.
+ *
+ * Recording CLEARS the redo stack, which is the standard rule and the only
+ * honest one: once the document has diverged, the futures recorded against the
+ * old one describe a document that no longer exists.
+ *
+ * `timestamp` is a parameter rather than a `Date.now()` call inside, so this
+ * stays a pure function a test can pin.
+ */
+export const recordEdit = (history, transform, description = '', timestamp = Date.now()) => {
+    const entry = {
+        transform,
+        timestamp,
+        ...(description === '' ? {} : { description }),
+    };
+    const past = [...history.past, entry];
+    return { past: past.slice(Math.max(0, past.length - HISTORY_LIMIT)), future: [] };
+};
+/**
+ * The transform from one set of elements to another, both keyed by id.
+ *
+ * This is how a component that has just changed a document reports WHAT it
+ * changed without keeping a parallel log: snapshot the elements a gesture is
+ * about when it starts, read them again when it ends, and the difference is the
+ * history entry. A gesture that touched one element costs one element, however
+ * many pointer moves it took.
+ *
+ * The `type` is named from the two sets — absent before is an `add`, absent
+ * after a `delete`, a mix a `batch` — so an entry's `type` still reads as what
+ * the reader did even though {@link applyTransform} does not branch on it.
+ */
+export const diffTransform = (before, after) => {
+    const gone = before.some((element) => !after.some((other) => other.id === element.id));
+    const fresh = after.some((element) => !before.some((other) => other.id === element.id));
+    const ids = [...new Set([...before, ...after].map((element) => element.id))];
+    return {
+        type: gone && fresh ? 'batch' : gone ? 'delete' : fresh ? 'add' : 'update',
+        elementIds: ids,
+        elements: after,
+        previousElements: before,
+    };
+};
+/**
+ * The document one step back, or nothing when there is nothing to undo.
+ *
+ * None-or-one rather than a nullable result, for `boundingBox`'s reason: the
+ * caller writes `const [step] = undo(...)` and the empty case needs no
+ * sentinel to remember to check.
+ */
+export const undo = (doc, history) => {
+    const entry = history.past.at(-1);
+    if (entry === undefined)
+        return [];
+    return [
+        {
+            doc: applyTransform(doc, invertTransform(entry.transform)),
+            history: { past: history.past.slice(0, -1), future: [entry, ...history.future] },
+        },
+    ];
+};
+/** The document one step forward, or nothing when there is nothing to redo. */
+export const redo = (doc, history) => {
+    const [entry, ...rest] = history.future;
+    if (entry === undefined)
+        return [];
+    return [
+        {
+            doc: applyTransform(doc, entry.transform),
+            history: { past: [...history.past, entry], future: rest },
+        },
+    ];
+};