@hachej/boring-ui-kit 0.1.111 → 0.2.0

package/dist/canvas-editor-native.js

@@ -0,0 +1,112 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { useEditor, useValue, GeoShapeGeoStyle, LANGUAGES } from '@tldraw/editor';
+import { Tldraw, iconTypes, DEFAULT_EMBED_DEFINITIONS } from 'tldraw';
+import { createMountedCanvasTools } from './canvas-mounted.js';
+import { CanvasProposals } from './canvas-proposals.js';
+const fontKeys = [
+    'tldraw_draw', 'tldraw_draw_italic', 'tldraw_draw_bold', 'tldraw_draw_italic_bold',
+    'tldraw_sans', 'tldraw_sans_italic', 'tldraw_sans_bold', 'tldraw_sans_italic_bold',
+    'tldraw_serif', 'tldraw_serif_italic', 'tldraw_serif_bold', 'tldraw_serif_italic_bold',
+    'tldraw_mono', 'tldraw_mono_italic', 'tldraw_mono_bold', 'tldraw_mono_italic_bold',
+];
+function assetSignature(assets) {
+    const requirements = [
+        ...fontKeys.map((key) => [`fonts.${key}`, assets?.fonts?.[key]]),
+        ...iconTypes.map((key) => [`icons.${key}`, assets?.icons?.[key]]),
+        ...LANGUAGES.map(({ locale }) => [`translations.${locale}`, assets?.translations?.[locale]]),
+        ...DEFAULT_EMBED_DEFINITIONS.map(({ type }) => [`embedIcons.${type}`, assets?.embedIcons?.[type]]),
+    ];
+    for (const [key, value] of requirements)
+        if (typeof value !== 'string' || !value.trim())
+            throw new TypeError(`Canvas asset URL is required: ${key}`);
+    return JSON.stringify(requirements);
+}
+export default function NativeCanvas({ controller, assetUrls, title = 'Canvas', className, height = 480, licenseKey, onMount, onMountedTools }) {
+    const state = useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    const [error, setError] = useState(null);
+    const [busy, setBusy] = useState(false);
+    const [nativeEditor, setNativeEditor] = useState(null);
+    const mounted = useRef(true);
+    const revokeTools = useRef(null);
+    useLayoutEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
+    const signature = useMemo(() => assetSignature(assetUrls), [assetUrls]);
+    const assets = useMemo(() => ({ fonts: { ...assetUrls.fonts }, icons: { ...assetUrls.icons }, translations: { ...assetUrls.translations }, embedIcons: { ...assetUrls.embedIcons } }), [signature]);
+    const outcome = state.save.kind === 'settled' ? state.save.result : undefined;
+    const pending = state.save.kind === 'pending';
+    const uncertain = outcome?.kind === 'unknown';
+    const conflict = outcome?.kind === 'conflict' || state.remote !== null;
+    const unavailable = state.readOnly || state.lifecycle === 'disposed';
+    const run = async (action) => {
+        if (!mounted.current || controller.getSnapshot().lifecycle === 'disposed')
+            return;
+        setBusy(true);
+        setError(null);
+        try {
+            const result = await action();
+            if (mounted.current && (result.kind === 'unavailable' || result.kind === 'denied' || result.kind === 'conflict' || result.kind === 'unknown'))
+                setError(result.reason);
+        }
+        catch (cause) {
+            if (mounted.current)
+                setError(cause instanceof Error ? cause.message : 'Canvas operation failed');
+        }
+        finally {
+            if (mounted.current)
+                setBusy(false);
+        }
+    };
+    const save = () => run(() => controller.flush(controller.actions.selection()));
+    const attach = (editor) => {
+        if (controller.getSnapshot().readOnly || controller.getSnapshot().lifecycle === 'disposed')
+            editor.updateInstanceState({ isReadonly: true });
+        editor.registerExternalAssetHandler('file', null);
+        editor.registerExternalAssetHandler('url', null);
+        for (const type of externalContentTypes)
+            editor.registerExternalContentHandler(type, null);
+        const cleanup = onMount?.(editor);
+        setNativeEditor(editor);
+        return () => { revokeTools.current?.(); setNativeEditor(current => current === editor ? null : current); cleanup?.(); };
+    };
+    return _jsxs("section", { className: className, "data-boring": "canvas-editor", "data-dirty": state.dirty || undefined, onKeyDownCapture: event => {
+            if ((event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 's') {
+                event.preventDefault();
+                if (!unavailable && !pending && !uncertain && !busy && !state.problem)
+                    void save();
+            }
+        }, children: [_jsxs("header", { children: [_jsx("strong", { children: title }), state.readOnly && _jsx("span", { children: "Read only" }), _jsx("span", { role: "status", children: state.lifecycle === 'disposed' ? 'Closed' : pending ? 'Saving' : uncertain ? 'Save unconfirmed' : conflict ? 'Changed elsewhere' : state.dirty ? 'Unsaved changes' : 'Saved' }), _jsx("button", { type: "button", disabled: unavailable || !state.dirty || pending || uncertain || busy || state.problem !== null, onClick: () => void save(), children: "Save" }), _jsx("button", { type: "button", disabled: state.lifecycle === 'disposed' || pending || uncertain || busy, onClick: () => void run(controller.actions.refresh), children: "Check saved version" })] }), uncertain && _jsxs("div", { role: "alert", children: ["Save acknowledgement was lost. Your current canvas is retained.", _jsx("button", { type: "button", disabled: busy, onClick: () => void run(controller.actions.reconcile), children: "Check save outcome" }), _jsx("button", { type: "button", disabled: busy || state.lifecycle === 'disposed', onClick: () => void run(controller.actions.abandon), children: "Keep draft and refresh" })] }), conflict && _jsxs("div", { role: "alert", children: ["The saved canvas changed. Your local edits have been kept.", _jsx("button", { type: "button", disabled: pending || uncertain || busy, onClick: () => void run(controller.actions.discardToRemote), children: "Discard local changes and reload" })] }), state.problem && _jsx("p", { role: "alert", children: state.problem }), (outcome?.kind === 'denied' || outcome?.kind === 'unavailable') && _jsx("p", { role: "alert", children: outcome.reason }), error && _jsx("p", { role: "alert", children: error }), _jsx(CanvasProposals, { controller: controller, state: state, editor: nativeEditor, busy: busy, run: run }), state.lifecycle === 'active' && _jsx("div", { "data-boring": "canvas-stage", style: { position: 'relative', height }, onClickCapture: event => { if (event.target instanceof Element && event.target.closest('a'))
+                    event.preventDefault(); }, onAuxClickCapture: event => { if (event.target instanceof Element && event.target.closest('a'))
+                    event.preventDefault(); }, children: _jsxs(Tldraw, { store: controller.store, hideUi: true, locale: "en", autoFocus: false, assetUrls: assets, ...(licenseKey === undefined ? {} : { licenseKey }), onMount: attach, children: [_jsx(CanvasTools, { controller: controller }), _jsx(MountedCommands, { controller: controller, revokeTools: revokeTools, ...(onMountedTools ? { onMountedTools } : {}) })] }) })] });
+}
+const externalContentTypes = ['text', 'files', 'file-replace', 'embed', 'svg-text', 'url', 'tldraw', 'excalidraw'];
+const choices = [
+    ['select', 'Select'], ['hand', 'Hand'], ['draw', 'Draw'], ['geo', 'Rectangle'], ['text', 'Text'],
+    ['arrow', 'Arrow'], ['line', 'Line'], ['note', 'Note'], ['frame', 'Frame'], ['highlight', 'Highlight'], ['eraser', 'Erase'],
+];
+function CanvasTools({ controller }) {
+    const editor = useEditor();
+    const state = useValue('canvas controls', () => ({ tool: editor.getCurrentToolId(), readOnly: controller.getSnapshot().readOnly || editor.getIsReadonly(), undo: editor.getCanUndo(), redo: editor.getCanRedo() }), [editor]);
+    const act = (action, changesDocument = true) => {
+        if (!editor.isDisposed && controller.getSnapshot().lifecycle === 'active'
+            && (!changesDocument || (!controller.getSnapshot().readOnly && !editor.getIsReadonly())))
+            action();
+    };
+    return _jsxs("div", { role: "toolbar", "aria-label": "Canvas tools", style: { position: 'absolute', top: 8, left: 8, zIndex: 300, display: 'flex', flexWrap: 'wrap', gap: 4 }, children: [choices.map(([id, label]) => _jsx("button", { type: "button", "aria-pressed": state.tool === id, disabled: state.readOnly && id !== 'hand' && id !== 'select', onClick: () => act(() => { if (id === 'geo')
+                    editor.setStyleForNextShapes(GeoShapeGeoStyle, 'rectangle'); editor.setCurrentTool(id); }, id !== 'hand' && id !== 'select'), children: label }, id)), _jsx("button", { type: "button", disabled: state.readOnly || !state.undo, onClick: () => act(() => { editor.undo(); }), children: "Undo" }), _jsx("button", { type: "button", disabled: state.readOnly || !state.redo, onClick: () => act(() => { editor.redo(); }), children: "Redo" }), _jsx("button", { type: "button", onClick: () => act(() => { editor.zoomToFit(); }, false), children: "Fit canvas" })] });
+}
+function MountedCommands({ controller, onMountedTools, revokeTools }) {
+    const editor = useEditor();
+    const binding = useMemo(() => createMountedCanvasTools({ controller, editor }), [controller, editor]);
+    useLayoutEffect(() => {
+        binding.activate();
+        revokeTools.current = binding.dispose;
+        return () => { binding.dispose(); if (revokeTools.current === binding.dispose)
+            revokeTools.current = null; };
+    }, [binding, revokeTools]);
+    useLayoutEffect(() => {
+        onMountedTools?.(binding.tools);
+        return () => { onMountedTools?.(null); };
+    }, [binding, onMountedTools]);
+    return null;
+}

package/dist/canvas-editor.d.ts

@@ -0,0 +1,6 @@
+export type { CanvasMountedSubject, CanvasMountedInspection, CanvasMountedTools } from './canvas-mounted.js';
+import type { CanvasEditorProps } from './canvas-editor-native.js';
+export type { CanvasAssetUrls, CanvasEditorProps, CanvasFontUrls } from './canvas-editor-native.js';
+/** Borrows one controller/store. The host supplies native CSS, fonts and any production license. */
+export declare function CanvasEditor(props: CanvasEditorProps): import("react").JSX.Element;
+//# sourceMappingURL=canvas-editor.d.ts.map

package/dist/canvas-editor.js

@@ -0,0 +1,13 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { lazy, Suspense, useState, useSyncExternalStore } from 'react';
+import { TextDraftControls } from './text-draft-controls.js';
+const NativeCanvas = lazy(() => import('./canvas-editor-native.js'));
+/** Borrows one controller/store. The host supplies native CSS, fonts and any production license. */
+export function CanvasEditor(props) {
+    const state = useSyncExternalStore(props.controller.subscribe, props.controller.getSnapshot, props.controller.getSnapshot);
+    const [mount, setMount] = useState({ controller: props.controller, sequence: 0 });
+    if (mount.controller !== props.controller)
+        setMount({ controller: props.controller, sequence: mount.sequence + 1 });
+    return _jsxs(_Fragment, { children: [_jsx(TextDraftControls, { recovery: state.recovery, actions: props.controller.actions, readOnly: state.readOnly, blocked: state.lifecycle !== 'active' || state.save.kind === 'pending' || (state.save.kind === 'settled' && state.save.result.kind === 'unknown') }, mount.sequence), _jsx(Suspense, { fallback: _jsx("p", { role: "status", children: "Loading canvas" }), children: _jsx(NativeCanvas, { ...props }, mount.sequence) })] });
+}

package/dist/canvas-mounted.d.ts

@@ -0,0 +1,41 @@
+import type { BoxLike, Editor, TLCamera, TLPageId, TLShape, TLShapeId } from '@tldraw/editor';
+import type { PresentationCommand, ViewerTarget } from './contracts.js';
+import type { CanvasController, CanvasProposalInput } from './canvas.js';
+import type { SaveSelection } from './resources.js';
+export type CanvasMountedSubject = SaveSelection['target']['subject'] & {
+    readonly mountId: string;
+    readonly pageId: TLPageId;
+};
+export interface CanvasMountedInspection {
+    readonly selection: SaveSelection;
+    readonly dirty: boolean;
+    readonly pageId: TLPageId;
+    readonly shapes: readonly TLShape[];
+    readonly selectedShapeIds: readonly TLShapeId[];
+    readonly camera: TLCamera;
+    readonly viewport: Readonly<BoxLike>;
+}
+export interface CanvasMountedTools {
+    readonly getTarget: () => ViewerTarget<CanvasMountedSubject> | null;
+    readonly inspect: PresentationCommand<{
+        readonly expiresAt: number;
+    }, CanvasMountedInspection, CanvasMountedSubject>;
+    readonly select: PresentationCommand<{
+        readonly expiresAt: number;
+        readonly shapeIds: readonly string[];
+    }, void, CanvasMountedSubject>;
+    readonly frame: PresentationCommand<{
+        readonly expiresAt: number;
+        readonly shapeIds: readonly string[];
+    }, void, CanvasMountedSubject>;
+    readonly propose: PresentationCommand<CanvasProposalInput, void, CanvasMountedSubject>;
+}
+export declare function createMountedCanvasTools({ controller, editor }: {
+    readonly controller: CanvasController;
+    readonly editor: Editor;
+}): {
+    tools: CanvasMountedTools;
+    activate: () => void;
+    dispose: () => void;
+};
+//# sourceMappingURL=canvas-mounted.d.ts.map

package/dist/canvas-mounted.js

@@ -0,0 +1,180 @@
+import { randomUUID } from '@hachej/boring-files/platform';
+import { freeze, sameBase } from './text-buffer.js';
+const expirySchema = { type: 'integer', minimum: Number.MIN_SAFE_INTEGER, maximum: Number.MAX_SAFE_INTEGER };
+function expiry(value) {
+    if (!value || typeof value !== 'object' || !('expiresAt' in value) || typeof value.expiresAt !== 'number' || !Number.isSafeInteger(value.expiresAt))
+        throw new TypeError('Command expiry is required');
+    return { expiresAt: value.expiresAt };
+}
+function shapesInput(value) {
+    const deadline = expiry(value);
+    if (!value || typeof value !== 'object' || !('shapeIds' in value) || !Array.isArray(value.shapeIds))
+        throw new TypeError('Shape IDs are required');
+    const shapeIds = [];
+    for (const id of value.shapeIds) {
+        if (typeof id !== 'string' || !id)
+            throw new TypeError('Shape IDs must be nonempty strings');
+        if (!shapeIds.includes(id))
+            shapeIds.push(id);
+    }
+    return { ...deadline, shapeIds };
+}
+const shapesSchema = { type: 'object', properties: { expiresAt: expirySchema, shapeIds: { type: 'array', items: { type: 'string', minLength: 1 } } }, required: ['expiresAt', 'shapeIds'] };
+function finiteBounds(box) {
+    return [box.x, box.y, box.w, box.h, box.x + box.w, box.y + box.h].every(Number.isFinite) && box.w >= 0 && box.h >= 0;
+}
+export function createMountedCanvasTools({ controller, editor }) {
+    const mountId = randomUUID();
+    let alive = false;
+    const available = () => alive && !editor.isDisposed && editor.store === controller.store
+        && editor.getContainer().isConnected && controller.getSnapshot().lifecycle === 'active' && !controller.getSnapshot().problem;
+    const viewportReady = () => {
+        const screen = editor.getContainer().getBoundingClientRect();
+        const viewport = editor.getViewportScreenBounds();
+        return [screen.x, screen.y, screen.width, screen.height].every(Number.isFinite) && screen.width > 0 && screen.height > 0
+            && finiteBounds(viewport) && Math.abs(viewport.x - screen.x) < 1e-6 && Math.abs(viewport.y - screen.y) < 1e-6
+            && Math.abs(viewport.w - screen.width) < 1e-6 && Math.abs(viewport.h - screen.height) < 1e-6;
+    };
+    const getTarget = () => {
+        if (!available())
+            return null;
+        const pageId = editor.getCurrentPageId();
+        let selected;
+        try {
+            selected = controller.actions.selection().target;
+        }
+        catch (error) {
+            if (!available())
+                return null;
+            throw error;
+        }
+        if (!available() || editor.getCurrentPageId() !== pageId)
+            return null;
+        return freeze({ ...selected, subject: { ...selected.subject, mountId, pageId } });
+    };
+    const check = (target, expiresAt, signal) => {
+        if (!available())
+            return { kind: 'unavailable', reason: 'Mounted canvas is unavailable' };
+        if (signal?.aborted)
+            return { kind: 'denied', reason: 'Command was cancelled' };
+        if (expiresAt <= Date.now())
+            return { kind: 'stale', reason: 'Command expired' };
+        const selected = getTarget();
+        if (!selected)
+            return { kind: 'unavailable', reason: 'Mounted canvas changed during capture' };
+        if (selected.instanceId !== target.instanceId || selected.epoch !== target.epoch
+            || selected.subject.mountId !== target.subject.mountId || selected.subject.pageId !== target.subject.pageId
+            || selected.subject.scopeId !== target.subject.scopeId || selected.subject.bufferVersion !== target.subject.bufferVersion
+            || !sameBase(selected.subject.base, target.subject.base))
+            return { kind: 'stale', reason: 'Mounted command target changed' };
+        if (!available())
+            return { kind: 'unavailable', reason: 'Mounted canvas is unavailable' };
+        if (signal?.aborted)
+            return { kind: 'denied', reason: 'Command was cancelled' };
+        if (expiresAt <= Date.now())
+            return { kind: 'stale', reason: 'Command expired' };
+        return null;
+    };
+    const operate = async (target, input, frame, signal) => {
+        const captured = structuredClone(target), parsed = shapesInput(input);
+        const refused = check(captured, parsed.expiresAt, signal);
+        if (refused)
+            return refused;
+        const shapes = editor.getCurrentPageShapes();
+        const ids = [];
+        for (const requested of parsed.shapeIds) {
+            const shape = shapes.find(shape => shape.id === requested);
+            if (!shape)
+                return { kind: 'denied', reason: 'Shape is not on the current page' };
+            ids.push(shape.id);
+        }
+        if (frame) {
+            if (!ids.length)
+                return { kind: 'denied', reason: 'Framing requires at least one shape' };
+            if (editor.getCameraOptions().isLocked)
+                return { kind: 'denied', reason: 'Canvas camera is locked' };
+            if (!viewportReady())
+                return { kind: 'unavailable', reason: 'Canvas viewport is unavailable or awaiting layout' };
+            let bounds;
+            for (const id of ids) {
+                const box = editor.getShapePageBounds(id);
+                if (!box || !finiteBounds(box))
+                    return { kind: 'unavailable', reason: 'Shape bounds are unavailable' };
+                if (!bounds)
+                    bounds = { x: box.x, y: box.y, w: box.w, h: box.h };
+                else {
+                    const x = Math.min(bounds.x, box.x), y = Math.min(bounds.y, box.y);
+                    bounds = { x, y, w: Math.max(bounds.x + bounds.w, box.x + box.w) - x, h: Math.max(bounds.y + bounds.h, box.y + box.h) - y };
+                }
+            }
+            if (!bounds || !finiteBounds(bounds))
+                return { kind: 'unavailable', reason: 'Shape bounds are unavailable' };
+            const before = check(captured, parsed.expiresAt, signal);
+            if (before)
+                return before;
+            editor.zoomToBounds(bounds, { immediate: true });
+            const after = check(captured, parsed.expiresAt, signal);
+            if (after)
+                return after;
+            if (!viewportReady())
+                return { kind: 'unavailable', reason: 'Canvas viewport changed during framing' };
+            const actual = editor.getViewportPageBounds();
+            if (!finiteBounds(actual) || actual.w <= 0 || actual.h <= 0 || actual.x > bounds.x + 1e-6 || actual.y > bounds.y + 1e-6
+                || actual.x + actual.w < bounds.x + bounds.w - 1e-6 || actual.y + actual.h < bounds.y + bounds.h - 1e-6)
+                return { kind: 'unavailable', reason: 'Camera constraints prevented framing' };
+        }
+        else {
+            const before = check(captured, parsed.expiresAt, signal);
+            if (before)
+                return before;
+            editor.setSelectedShapes(ids);
+            const after = check(captured, parsed.expiresAt, signal);
+            if (after)
+                return after;
+            const selected = editor.getSelectedShapeIds();
+            if (selected.length !== ids.length || !ids.every(id => selected.includes(id)))
+                return { kind: 'unavailable', reason: 'Shape selection was not applied' };
+        }
+        return { kind: 'applied', value: undefined };
+    };
+    const tools = {
+        getTarget,
+        inspect: {
+            name: 'inspect_mounted_canvas', input: { jsonSchema: { type: 'object', properties: { expiresAt: expirySchema }, required: ['expiresAt'] }, parse: expiry },
+            invoke: async (target, input, signal) => {
+                const captured = structuredClone(target), parsed = expiry(input), refused = check(captured, parsed.expiresAt, signal);
+                if (refused)
+                    return refused;
+                const selection = controller.actions.selection();
+                const viewport = editor.getViewportPageBounds();
+                const value = freeze(structuredClone({ selection, dirty: controller.getSnapshot().dirty, pageId: editor.getCurrentPageId(), shapes: editor.getCurrentPageShapes(),
+                    selectedShapeIds: editor.getSelectedShapeIds(), camera: editor.getCamera(), viewport: { x: viewport.x, y: viewport.y, w: viewport.w, h: viewport.h } }));
+                return check(captured, parsed.expiresAt, signal) ?? { kind: 'applied', value };
+            },
+        },
+        select: { name: 'select_mounted_canvas', input: { jsonSchema: shapesSchema, parse: shapesInput }, invoke: (target, input, signal) => operate(target, input, false, signal) },
+        frame: { name: 'frame_mounted_canvas', input: { jsonSchema: shapesSchema, parse: shapesInput }, invoke: (target, input, signal) => operate(target, input, true, signal) },
+        propose: {
+            name: 'propose_mounted_canvas_edits', input: controller.tools.propose.input,
+            invoke: async (target, input, signal) => {
+                const captured = structuredClone(target), parsed = controller.tools.propose.input.parse(input);
+                const refused = check(captured, parsed.expiresAt, signal);
+                if (refused)
+                    return refused;
+                if (controller.getSnapshot().readOnly || editor.getIsReadonly())
+                    return { kind: 'denied', reason: 'Canvas is read-only' };
+                const result = await controller.tools.propose.invoke(captured, parsed, signal);
+                if (result.kind === 'proposed') {
+                    const lateRefusal = check(captured, parsed.expiresAt, signal)
+                        ?? (editor.getIsReadonly() ? { kind: 'denied', reason: 'Canvas is read-only' } : null);
+                    if (lateRefusal) {
+                        controller.actions.reject(result.proposalId);
+                        return lateRefusal;
+                    }
+                }
+                return result.kind === 'proposed' ? { ...result, base: captured } : result;
+            },
+        },
+    };
+    return { tools, activate: () => { alive = true; }, dispose: () => { alive = false; } };
+}

package/dist/canvas-proposals.d.ts

@@ -0,0 +1,11 @@
+import type { Editor } from '@tldraw/editor';
+import type { CanvasController, CanvasState } from './canvas.js';
+import type { SaveResult } from './resources.js';
+export declare function CanvasProposals({ controller, state, editor, busy, run }: {
+    readonly controller: CanvasController;
+    readonly state: CanvasState;
+    readonly editor: Editor | null;
+    readonly busy: boolean;
+    readonly run: (action: () => Promise<SaveResult>) => Promise<void>;
+}): import("react").JSX.Element | null;
+//# sourceMappingURL=canvas-proposals.d.ts.map

package/dist/canvas-proposals.js

@@ -0,0 +1,45 @@
+'use client';
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { useValue } from '@tldraw/editor';
+import { sameBase } from './text-buffer.js';
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function changedFields(before, after, path = '') {
+    if (JSON.stringify(before) === JSON.stringify(after))
+        return [];
+    if ((object(before) || before === undefined) && (object(after) || after === undefined)) {
+        const left = object(before) ? before : {}, right = object(after) ? after : {};
+        const keys = [...new Set([...Object.keys(left), ...Object.keys(right)])].sort();
+        if (keys.length)
+            return keys.flatMap(key => changedFields(Object.hasOwn(left, key) ? left[key] : undefined, Object.hasOwn(right, key) ? right[key] : undefined, `${path}/${key.replaceAll('~', '~0').replaceAll('/', '~1')}`));
+    }
+    return [{ field: path || 'Record', before: before === undefined ? 'Absent' : JSON.stringify(before), after: after === undefined ? 'Absent' : JSON.stringify(after) }];
+}
+function ProposalChanges({ proposal }) {
+    const changes = useMemo(() => {
+        const before = new Map(Object.values(proposal.before.store).map(record => [String(record.id), record]));
+        const after = new Map(Object.values(proposal.after.store).map(record => [String(record.id), record]));
+        return [...new Set([...before.keys(), ...after.keys()])].flatMap(id => {
+            const fields = changedFields(before.get(id), after.get(id));
+            return fields.length ? [{ id, kind: !before.has(id) ? 'Added' : !after.has(id) ? 'Removed' : 'Changed', fields }] : [];
+        });
+    }, [proposal]);
+    return _jsxs("details", { children: [_jsxs("summary", { children: ["Review ", changes.length, " changed ", changes.length === 1 ? 'record' : 'records'] }), changes.map(change => _jsxs("div", { children: [_jsxs("h4", { children: [change.kind, ": ", change.id] }), _jsxs("table", { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "Field" }), _jsx("th", { scope: "col", children: "Before" }), _jsx("th", { scope: "col", children: "After" })] }) }), _jsx("tbody", { children: change.fields.map(row => _jsxs("tr", { children: [_jsx("th", { scope: "row", children: row.field }), _jsx("td", { children: _jsx("pre", { style: { whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }, children: row.before }) }), _jsx("td", { children: _jsx("pre", { style: { whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }, children: row.after }) })] }, row.field)) })] })] }, change.id))] });
+}
+export function CanvasProposals({ controller, state, editor, busy, run }) {
+    const nativeReadOnly = useValue('canvas proposal readonly', () => !editor || editor.isDisposed || editor.getIsReadonly(), [editor]);
+    const blocked = busy || nativeReadOnly || state.readOnly || state.lifecycle !== 'active' || state.problem !== null
+        || state.save.kind === 'pending' || (state.save.kind === 'settled' && state.save.result.kind === 'unknown');
+    if (!state.proposals.length)
+        return null;
+    return _jsx("aside", { "aria-label": "Canvas proposals", children: state.proposals.map(proposal => {
+            const stale = state.bufferVersion !== proposal.base.target.subject.bufferVersion || !sameBase(state.base, proposal.base.target.subject.base);
+            return _jsxs("article", { "data-boring": "canvas-proposal", children: [_jsx("h3", { children: proposal.summary || 'Canvas change proposal' }), _jsx(ProposalChanges, { proposal: proposal }), proposal.adopted ? _jsx("p", { children: "Applied locally. Publication status is shown above." }) : stale ? _jsx("p", { children: "Canvas changed since this proposal." }) : null, !proposal.adopted && _jsx("button", { type: "button", disabled: blocked || stale, onClick: () => {
+                            if (!editor || editor.isDisposed || editor.getIsReadonly())
+                                return;
+                            void run(() => controller.actions.accept(proposal.id));
+                        }, children: "Accept and save" }), _jsx("button", { type: "button", disabled: busy || state.lifecycle !== 'active', onClick: () => controller.actions.reject(proposal.id), children: "Dismiss" })] }, proposal.id);
+        }) });
+}

package/dist/canvas-records.d.ts

@@ -0,0 +1,3 @@
+import type { TLStoreSchema, TLStoreSnapshot } from '@tldraw/tlschema';
+export declare function parseCanvasRecords(value: unknown, schema: TLStoreSchema): TLStoreSnapshot;
+//# sourceMappingURL=canvas-records.d.ts.map

package/dist/canvas-records.js

@@ -0,0 +1,39 @@
+const shapeTypes = new Set(['arrow', 'draw', 'frame', 'geo', 'group', 'highlight', 'line', 'note', 'text']);
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function allowed(record) {
+    if (record.typeName === 'asset')
+        throw new TypeError('Canvas assets require a separately qualified asset adapter');
+    if (record.typeName === 'shape' && !shapeTypes.has(record.type))
+        throw new TypeError('Unsupported canvas shape');
+    if (record.typeName === 'binding' && record.type !== 'arrow')
+        throw new TypeError('Unsupported canvas binding');
+    if (record.typeName === 'user' && record.imageUrl !== '')
+        throw new TypeError('Canvas author images require a separately qualified asset adapter');
+    if (!['document', 'page', 'shape', 'binding', 'user'].includes(record.typeName))
+        throw new TypeError('Only canvas document records may be published');
+}
+export function parseCanvasRecords(value, schema) {
+    if (!object(value) || Object.keys(value).some(key => key !== 'schema' && key !== 'store') || !object(value['schema']) || !object(value['store']))
+        throw new TypeError('Expected a canvas document snapshot');
+    const serialized = schema.serialize(), supplied = value['schema'], sequences = supplied['sequences'];
+    if (supplied['schemaVersion'] !== serialized.schemaVersion || !object(sequences)
+        || Object.keys(sequences).length !== Object.keys(serialized.sequences).length
+        || Object.entries(serialized.sequences).some(([key, version]) => sequences[key] !== version))
+        throw new TypeError('Canvas schema migration is not qualified');
+    const records = [];
+    for (const [id, item] of Object.entries(value['store'])) {
+        if (!object(item))
+            throw new TypeError('Invalid canvas record');
+        const type = Object.values(schema.types).find(candidate => candidate.typeName === item['typeName']);
+        if (!type || type.scope !== 'document')
+            throw new TypeError('Canvas snapshots cannot contain unknown or session records');
+        const record = type.validate(item);
+        if (record.id !== id)
+            throw new TypeError('Canvas record key and identity differ');
+        allowed(record);
+        records.push(record);
+    }
+    return structuredClone({ schema: serialized, store: Object.fromEntries(records.map(record => [record.id, record])) });
+}

package/dist/canvas.d.ts

@@ -0,0 +1,92 @@
+import type { TLStore, TLStoreSnapshot } from '@tldraw/editor';
+import type { ResourceAccess, ResourceClient, ResourceLocator, ResourceSnapshot } from '@hachej/boring-files';
+import type { CanvasEdit } from './canvas-document.js';
+import type { PresentationCommand, PresentationResult } from './contracts.js';
+import type { SaveResult, SaveSelection } from './resources.js';
+import { type TextBufferState } from './text-buffer.js';
+import type { TextDraftOptions } from './text-draft-types.js';
+export { canvasMediaType } from './canvas-document.js';
+export type CanvasSource = {
+    readonly kind: 'saved';
+    readonly snapshot: ResourceSnapshot;
+} | {
+    readonly kind: 'new';
+    readonly target: ResourceLocator;
+};
+export interface CanvasOptions {
+    readonly drafts?: TextDraftOptions;
+    /** Borrow one editor's store; the host owns its lifetime and native schema. */
+    readonly store: TLStore;
+    readonly source: CanvasSource;
+    readonly client: ResourceClient;
+    readonly identity: Pick<ResourceAccess, 'scopeId' | 'principalId' | 'initiatorId'>;
+    readonly instanceId: string;
+    readonly epoch: string;
+    readonly readOnly?: boolean;
+    readonly onListenerError?: (error: unknown) => void;
+}
+export interface CanvasProposal {
+    readonly id: string;
+    readonly base: SaveSelection;
+    readonly before: TLStoreSnapshot;
+    readonly after: TLStoreSnapshot;
+    readonly edits: readonly CanvasEdit[];
+    readonly summary: string;
+    readonly adopted: boolean;
+}
+type CanvasSubject = SaveSelection['target']['subject'];
+export interface CanvasInspection {
+    readonly selection: SaveSelection;
+    readonly document: TLStoreSnapshot;
+    readonly dirty: boolean;
+}
+export interface CanvasProposalInput {
+    readonly expiresAt: number;
+    readonly edits: readonly CanvasEdit[];
+    readonly summary: string;
+}
+export interface CanvasTools {
+    readonly inspect: PresentationCommand<{
+        readonly expiresAt: number;
+    }, CanvasInspection, CanvasSubject>;
+    readonly propose: PresentationCommand<CanvasProposalInput, void, CanvasSubject>;
+}
+export type CanvasState = Omit<TextBufferState, 'text'> & {
+    readonly document: TLStoreSnapshot;
+    readonly problem: string | null;
+    readonly proposals: readonly CanvasProposal[];
+};
+/** Revision-checked document publication over a borrowed native tldraw store. */
+export declare function createCanvasController(options: CanvasOptions): {
+    store: TLStore;
+    getSnapshot: () => CanvasState;
+    subscribe: (listener: () => void) => (() => void);
+    actions: {
+        selection: () => SaveSelection;
+        refresh: () => Promise<import("@hachej/boring-files").ReadResult>;
+        discardToRemote: () => Promise<import("@hachej/boring-files").ReadResult>;
+        reconcile: () => Promise<SaveResult>;
+        abandon: () => Promise<import("@hachej/boring-files").ReadResult>;
+        checkDrafts: () => Promise<import("./text-draft-types.js").TextDraftDiscovery>;
+        checkpointDraft: () => Promise<import("./text-draft-types.js").TextDraftCheckpointResult>;
+        restoreDraft: (choice: import("./text-draft-types.js").TextDraftChoiceSelection) => Promise<{
+            readonly kind: "restored";
+            readonly selection: SaveSelection;
+        } | import("./text-draft-types.js").TextDraftChoiceFailure>;
+        discardDraft: (choice: import("./text-draft-types.js").TextDraftChoiceSelection) => Promise<{
+            readonly kind: "discarded";
+        } | import("./text-draft-types.js").TextDraftChoiceFailure>;
+        propose: (base: SaveSelection, edits: readonly CanvasEdit[], summary?: string) => PresentationResult<void, {
+            readonly scopeId: string;
+            readonly base: import("@hachej/boring-files").ResourceExpectation;
+            readonly bufferVersion: number;
+        }>;
+        accept: (proposalId: string) => Promise<SaveResult>;
+        reject: (proposalId: string) => void;
+    };
+    tools: Readonly<CanvasTools>;
+    flush: (selection: SaveSelection, signal?: AbortSignal) => Promise<SaveResult>;
+    dispose: () => void;
+};
+export type CanvasController = ReturnType<typeof createCanvasController>;
+//# sourceMappingURL=canvas.d.ts.map