Add renderer-independent canvas model, transactions and view sessions
This commit is contained in:
@@ -0,0 +1,268 @@
|
||||
import type { Applied, Availability, Capability, Change, Command, Commit, CoreSnapshot, Document, ElementRecord, Geometry, HistoryEntry, HistoryState, Id, OperationIntent, Origin, Registry, Result, Snapshot } from './types.ts';
|
||||
import { applyChanges, commonCanvas, createDocument, invert, targetElement, validateDocument } from './document.ts';
|
||||
import { clone, equal, fault, freeze, readMap, reject } from './values.ts';
|
||||
|
||||
export type EditorOptions<Runtime = undefined> = {
|
||||
registry: Registry; document: Document; createId?: () => Id; historyLimit?: number;
|
||||
policy?: (command: Command, document: Document) => Availability;
|
||||
traversalPolicy?: (entry: HistoryEntry, direction: 'undo' | 'redo') => Availability;
|
||||
onListenerError?: (error: unknown) => void;
|
||||
allowRawChanges?: boolean;
|
||||
recovery?: CoreSnapshot & { readonly rootRevision: number };
|
||||
runtime?: Runtime;
|
||||
/** Installed by the engine. Pure preparation: an error rejects the entire commit. */
|
||||
reduceRuntime?: (previous: Runtime, next: CoreSnapshot, commit: Commit) => Runtime;
|
||||
};
|
||||
export type Transaction = { dispatch(command: Command): Availability; getDocument(): Document };
|
||||
export type Editor = ReturnType<typeof createEditor>;
|
||||
const isThenable = (value: unknown) => !!value && (typeof value === 'object' || typeof value === 'function') && typeof (value as { then?: unknown }).then === 'function';
|
||||
|
||||
export function createEditor<Runtime = undefined>(options: EditorOptions<Runtime>) {
|
||||
const source = options.recovery?.document ?? options.document;
|
||||
const document = createDocument(source.projectId, [...source.canvases.values()], [...source.elements.values()], source.tombstones);
|
||||
validateDocument(document, options.registry);
|
||||
let state: Snapshot<Runtime> = Object.freeze({ revision: options.recovery?.revision ?? 0, rootRevision: options.recovery?.rootRevision ?? 0, document, history: options.recovery?.history ?? Object.freeze({ undo: Object.freeze([]), redo: Object.freeze([]), entries: readMap(new Map<Id, HistoryEntry>()) }), operations: options.recovery?.operations ?? readMap(new Map<Id, OperationIntent>()), runtime: options.runtime as Runtime });
|
||||
let entered = false, disposed = false, sequence = 0;
|
||||
for (const intent of state.operations.values()) sequence = Math.max(sequence, intent.sequence);
|
||||
const listeners = new Set<(commit: Commit, snapshot: Snapshot<Runtime>) => void>();
|
||||
const createId = options.createId || (() => globalThis.crypto.randomUUID());
|
||||
const limit = options.historyLimit ?? 100;
|
||||
if (!Number.isSafeInteger(limit) || limit < 1) throw fault('invalid_history_limit');
|
||||
|
||||
function plan(document: Document, command: Command): { document: Document; changes: readonly Change[] } {
|
||||
const permission = options.policy?.(command, document);
|
||||
if (permission && !permission.enabled) throw fault(permission.code, permission.targets);
|
||||
let changes: readonly Change[];
|
||||
if (command.type === 'canvas.create') {
|
||||
if (document.canvases.has(command.canvas.id)) throw fault('duplicate_identity', [command.canvas.id]);
|
||||
changes = [{ kind: 'canvas', id: command.canvas.id, before: null, after: command.canvas }];
|
||||
} else if (command.type === 'canvas.reparent') {
|
||||
const canvas = document.canvases.get(command.canvasId);
|
||||
if (!canvas) throw fault('canvas_not_loaded', [command.canvasId]);
|
||||
changes = equal(canvas.parent, command.parent) ? [] : [{ kind: 'canvas', id: canvas.id, before: canvas, after: { ...canvas, parent: command.parent } }];
|
||||
} else if (command.type === 'element.create') {
|
||||
const element = command.element;
|
||||
if (document.elements.has(element.id) || document.tombstones.has(element.id)) throw fault('duplicate_identity', [element.id]);
|
||||
if (options.registry.resolve(element) !== 'known') throw fault('unsupported_component', [element.id]);
|
||||
changes = [{ kind: 'element', id: element.id, before: null, after: element }];
|
||||
} else if (command.type === 'changes.apply') {
|
||||
if (!options.allowRawChanges) throw fault('raw_changes_not_allowed');
|
||||
changes = command.changes;
|
||||
} else {
|
||||
let element = targetElement(document, command.target);
|
||||
if (options.registry.resolve(element) !== 'known') throw fault('unsupported_component', [element.id]);
|
||||
if (command.type === 'element.remove') {
|
||||
changes = [{ kind: 'element', id: element.id, before: element, after: null }];
|
||||
for (const edge of document.elements.values()) if (edge.structure === 'connection' && (edge.source.elementId === element.id || edge.target.elementId === element.id)) changes = [...changes, { kind: 'element', id: edge.id, before: edge, after: null }];
|
||||
} else if (command.type === 'element.move') {
|
||||
if (!options.registry.supports(element, 'geometry.move')) throw fault('unsupported_capability', [element.id]);
|
||||
changes = [{ kind: 'field', target: command.target, field: 'ownerCanvasId', before: element.ownerCanvasId, after: command.canvasId }];
|
||||
if (command.geometry && element.structure === 'node') changes = [...changes, { kind: 'field', target: command.target, field: 'geometry', before: element.geometry, after: command.geometry }];
|
||||
for (const canvas of document.canvases.values()) if (canvas.parent?.entryElementId === element.id) changes = [...changes, { kind: 'canvas', id: canvas.id, before: canvas, after: { ...canvas, parent: { ...canvas.parent, canvasId: command.canvasId } } }];
|
||||
const moved = applyChanges(document, changes);
|
||||
for (const edge of moved.elements.values()) if (edge.structure === 'connection') {
|
||||
const source = moved.elements.get(edge.source.elementId), target = moved.elements.get(edge.target.elementId);
|
||||
if (!source || !target) throw fault('invalid_endpoint', [edge.id]);
|
||||
const owner = commonCanvas(moved, source.ownerCanvasId, target.ownerCanvasId);
|
||||
if (owner !== edge.ownerCanvasId) changes = [...changes, { kind: 'field', target: { id: edge.id, incarnation: edge.incarnation }, field: 'ownerCanvasId', before: edge.ownerCanvasId, after: owner }];
|
||||
}
|
||||
} else {
|
||||
const output: Change[] = [];
|
||||
const run = (capability: Capability, patch: unknown) => {
|
||||
const handler = options.registry.handlers.get(element.componentId)?.get(capability);
|
||||
if (!handler) throw fault('unsupported_capability', [element.id, capability]);
|
||||
const generated = handler({ element, input: freeze({ patch: clone(patch) }) });
|
||||
// A handler is scoped to this target; it cannot write another object or domain.
|
||||
for (const change of generated) if (change.target.id !== element.id || change.target.incarnation !== element.incarnation || (capability === 'content.edit' ? !change.field.startsWith('data.') : change.field !== 'geometry')) throw fault('invalid_handler_change', [element.id]);
|
||||
output.push(...generated);
|
||||
element = targetElement(applyChanges(document, output), command.target);
|
||||
};
|
||||
if (command.type === 'element.data') run('content.edit', command.patch);
|
||||
else {
|
||||
if (element.structure !== 'node' || Object.keys(command.patch).some(key => !['x', 'y', 'width', 'height', 'rotation'].includes(key))) throw fault('invalid_geometry_patch', [element.id]);
|
||||
const parts: [Capability, Partial<Geometry>][] = [
|
||||
['geometry.move', Object.fromEntries(Object.entries(command.patch).filter(([key]) => key === 'x' || key === 'y'))],
|
||||
['geometry.resize', Object.fromEntries(Object.entries(command.patch).filter(([key]) => key === 'width' || key === 'height'))],
|
||||
['geometry.rotate', Object.fromEntries(Object.entries(command.patch).filter(([key]) => key === 'rotation'))],
|
||||
];
|
||||
for (const [capability, patch] of parts) if (Object.keys(patch).length) run(capability, patch);
|
||||
}
|
||||
changes = output;
|
||||
}
|
||||
}
|
||||
const next = applyChanges(document, changes);
|
||||
return { document: next, changes: freeze(clone(changes)) };
|
||||
}
|
||||
|
||||
function assertOpen() {
|
||||
if (disposed) throw fault('editor_disposed');
|
||||
if (entered) throw fault('reentrant_dispatch');
|
||||
}
|
||||
function emit(commit: Commit) {
|
||||
for (const listener of [...listeners]) try { listener(commit, state); } catch (error) { try { options.onListenerError?.(error); } catch { /* Observers cannot roll back a committed state. */ } }
|
||||
}
|
||||
function uniqueId(used: Set<Id>): Id {
|
||||
const id = createId();
|
||||
if (!id || used.has(id) || state.operations.has(id) || state.history.entries.has(id)) throw fault('duplicate_operation_id');
|
||||
used.add(id); return id;
|
||||
}
|
||||
function publish(document: Document, changes: readonly Change[], origin: Origin, history: HistoryState, historyEntryId?: Id): Applied {
|
||||
const used = new Set<Id>();
|
||||
for (const id of history.entries.keys()) used.add(id);
|
||||
// Canonical remote/ACK/replay updates must never feed back into the outbox.
|
||||
const outbound = !['remote', 'ack', 'replay'].includes(origin);
|
||||
const operationIds = Object.freeze(outbound ? [uniqueId(used)] : []);
|
||||
const operations = new Map(state.operations);
|
||||
if (outbound) {
|
||||
const canvasIds = new Set<Id>();
|
||||
for (const change of changes) {
|
||||
if (change.kind === 'canvas') {
|
||||
canvasIds.add(change.id);
|
||||
if (change.before?.parent) canvasIds.add(change.before.parent.canvasId);
|
||||
if (change.after?.parent) canvasIds.add(change.after.parent.canvasId);
|
||||
} else if (change.kind === 'element') {
|
||||
if (change.before) canvasIds.add(change.before.ownerCanvasId);
|
||||
if (change.after) canvasIds.add(change.after.ownerCanvasId);
|
||||
} else {
|
||||
const before = state.document.elements.get(change.target.id), after = document.elements.get(change.target.id);
|
||||
if (before) canvasIds.add(before.ownerCanvasId);
|
||||
if (after) canvasIds.add(after.ownerCanvasId);
|
||||
if (change.field === 'ownerCanvasId') { canvasIds.add(change.before as Id); canvasIds.add(change.after as Id); }
|
||||
}
|
||||
}
|
||||
const intent: OperationIntent = freeze({ id: operationIds[0], operationType: 'document.change', operationSchemaVersion: 1, sequence: sequence + 1, origin, canvasIds: [...canvasIds].sort(), changes, dependencies: [] });
|
||||
operations.set(intent.id, intent);
|
||||
}
|
||||
if (historyEntryId) {
|
||||
const entries = new Map(history.entries), entry = entries.get(historyEntryId)!;
|
||||
entries.set(entry.id, freeze({ ...entry, operationIds: [...entry.operationIds, ...operationIds] }));
|
||||
history = Object.freeze({ ...history, entries: readMap(entries) });
|
||||
}
|
||||
const next: CoreSnapshot = Object.freeze({ revision: state.revision + 1, document, history, operations: readMap(operations) });
|
||||
const commit = freeze({ revision: next.revision, origin, changes, operationIds });
|
||||
const runtime = options.reduceRuntime ? options.reduceRuntime(state.runtime, next, commit) : state.runtime;
|
||||
if (isThenable(runtime)) throw fault('async_transaction');
|
||||
state = Object.freeze({ ...next, rootRevision: state.rootRevision + 1, runtime });
|
||||
if (outbound) sequence++;
|
||||
emit(commit);
|
||||
return Object.freeze({ status: 'applied', revision: state.revision, operationIds, ...(historyEntryId ? { historyEntryId } : {}) });
|
||||
}
|
||||
|
||||
function transaction(callback: (transaction: Transaction) => unknown, settings: { label?: string; groupId?: Id; history?: boolean; origin?: Origin } = {}): Result {
|
||||
try { assertOpen(); } catch (error) { return reject(error); }
|
||||
entered = true;
|
||||
let active = true, document = state.document, failed: unknown;
|
||||
const changes: Change[] = [];
|
||||
const tx: Transaction = Object.freeze({
|
||||
dispatch(command: Command): Availability {
|
||||
if (!active) throw fault('transaction_closed');
|
||||
if (failed) return { enabled: false, ...reject(failed) };
|
||||
try {
|
||||
const result = plan(document, command); document = result.document; changes.push(...result.changes);
|
||||
return { enabled: true };
|
||||
} catch (error) { failed = error; const result = reject(error); return { enabled: false, code: result.code, targets: result.targets }; }
|
||||
},
|
||||
getDocument() { if (!active) throw fault('transaction_closed'); return document; },
|
||||
});
|
||||
try {
|
||||
const result = callback(tx);
|
||||
active = false;
|
||||
if (isThenable(result)) { Promise.resolve(result).catch(() => {}); throw fault('async_transaction'); }
|
||||
if (failed) throw failed;
|
||||
validateDocument(document, options.registry);
|
||||
if (!changes.length || documentsEqual(document, state.document)) return Object.freeze({ status: 'applied', revision: state.revision, operationIds: Object.freeze([]) });
|
||||
let history = state.history, historyEntryId: Id | undefined;
|
||||
if (settings.history !== false && (!settings.origin || settings.origin === 'user')) {
|
||||
const entries = new Map(history.entries), undo = [...history.undo];
|
||||
for (const id of history.redo) entries.delete(id);
|
||||
const prior = undo.length ? entries.get(undo[undo.length - 1]) : undefined;
|
||||
if (settings.groupId && prior?.groupId === settings.groupId) {
|
||||
historyEntryId = prior.id;
|
||||
entries.set(prior.id, freeze({ ...prior, changes: [...prior.changes, ...changes] }));
|
||||
} else {
|
||||
historyEntryId = uniqueId(new Set());
|
||||
entries.set(historyEntryId, freeze({ id: historyEntryId, label: settings.label || 'Edit', changes: [...changes], operationIds: [], ...(settings.groupId ? { groupId: settings.groupId } : {}) }));
|
||||
undo.push(historyEntryId);
|
||||
}
|
||||
while (undo.length > limit) entries.delete(undo.shift()!);
|
||||
history = Object.freeze({ undo: Object.freeze(undo), redo: Object.freeze([]), entries: readMap(entries) });
|
||||
}
|
||||
return publish(document, freeze([...changes]), settings.origin || 'user', history, historyEntryId);
|
||||
} catch (error) { active = false; return reject(error); }
|
||||
finally { entered = false; }
|
||||
}
|
||||
function dispatch(command: Command, settings?: Parameters<typeof transaction>[1]): Result {
|
||||
return transaction(tx => { tx.dispatch(command); }, settings);
|
||||
}
|
||||
function can(command: Command): Availability {
|
||||
try { if (disposed) throw fault('editor_disposed'); const result = plan(state.document, command); validateDocument(result.document, options.registry); return { enabled: true }; }
|
||||
catch (error) { const result = reject(error); return { enabled: false, code: result.code, targets: result.targets }; }
|
||||
}
|
||||
function traverse(direction: 'undo' | 'redo'): Result {
|
||||
try { assertOpen(); } catch (error) { return reject(error); }
|
||||
entered = true;
|
||||
try {
|
||||
const source = state.history[direction], id = source[source.length - 1];
|
||||
if (!id) throw fault('history_empty');
|
||||
const entry = state.history.entries.get(id)!;
|
||||
const allowed = options.traversalPolicy?.(entry, direction);
|
||||
if (allowed && !allowed.enabled) throw fault(allowed.code, allowed.targets);
|
||||
let changes = direction === 'undo' ? invert(entry.changes) : entry.changes;
|
||||
const generations = new Map<Id, number>();
|
||||
changes = changes.map(change => {
|
||||
if (change.kind === 'element' && !change.before && change.after) {
|
||||
const dead = state.document.tombstones.get(change.id);
|
||||
if (dead !== undefined && change.after.incarnation <= dead) { generations.set(change.id, dead + 1); return freeze({ ...change, after: { ...change.after, incarnation: dead + 1 } }); }
|
||||
}
|
||||
return change;
|
||||
}).map(change => change.kind === 'field' && generations.has(change.target.id) ? freeze({ ...change, target: { ...change.target, incarnation: generations.get(change.target.id)! } }) : change);
|
||||
const document = applyChanges(state.document, changes);
|
||||
validateDocument(document, options.registry);
|
||||
const entries = new Map(state.history.entries);
|
||||
entries.set(id, freeze({ ...entry, changes: direction === 'undo' ? invert(changes) : changes }));
|
||||
const history: HistoryState = Object.freeze({ undo: Object.freeze(direction === 'undo' ? state.history.undo.slice(0, -1) : [...state.history.undo, id]), redo: Object.freeze(direction === 'redo' ? state.history.redo.slice(0, -1) : [...state.history.redo, id]), entries: readMap(entries) });
|
||||
return publish(document, changes, direction, history, id);
|
||||
} catch (error) { return reject(error); }
|
||||
finally { entered = false; }
|
||||
}
|
||||
return Object.freeze({ getSnapshot: () => state, registry: options.registry, dispatch, transaction, can,
|
||||
subscribe(listener: (commit: Commit, snapshot: Snapshot<Runtime>) => void) { if (disposed) throw fault('editor_disposed'); listeners.add(listener); return () => { listeners.delete(listener); }; },
|
||||
/** Engine-only metadata commit, sharing the document/history publication boundary. */
|
||||
updateRuntime(reduce: (runtime: Runtime) => Runtime, expectedRootRevision = state.rootRevision): Result {
|
||||
try { assertOpen(); } catch (error) { return reject(error); }
|
||||
entered = true;
|
||||
try {
|
||||
if (expectedRootRevision !== state.rootRevision) throw fault('stale_plan');
|
||||
const runtime = reduce(state.runtime);
|
||||
if (isThenable(runtime)) throw fault('async_transaction');
|
||||
if (runtime !== state.runtime) {
|
||||
state = Object.freeze({ ...state, rootRevision: state.rootRevision + 1, runtime });
|
||||
emit(freeze({ revision: state.revision, origin: 'ack', changes: [], operationIds: [] }));
|
||||
}
|
||||
return Object.freeze({ status: 'applied', revision: state.revision, operationIds: Object.freeze([]) });
|
||||
} catch (error) { return reject(error); }
|
||||
finally { entered = false; }
|
||||
},
|
||||
/** Engine-only canonical proposal: validation and runtime state publish as one root. */
|
||||
reconcile(document: Document, runtime: Runtime, expectedRootRevision: number): Result {
|
||||
try { assertOpen(); } catch (error) { return reject(error); }
|
||||
entered = true;
|
||||
try {
|
||||
if (expectedRootRevision !== state.rootRevision) throw fault('stale_plan');
|
||||
if (document.projectId !== state.document.projectId) throw fault('project_mismatch');
|
||||
const next = createDocument(document.projectId, [...document.canvases.values()], [...document.elements.values()], document.tombstones);
|
||||
validateDocument(next, options.registry);
|
||||
const changed = !documentsEqual(next, state.document);
|
||||
state = Object.freeze({ ...state, document: changed ? next : state.document, runtime, revision: state.revision + Number(changed), rootRevision: state.rootRevision + 1 });
|
||||
emit(freeze({ revision: state.revision, origin: 'ack', changes: [], operationIds: [] }));
|
||||
return Object.freeze({ status: 'applied', revision: state.revision, operationIds: Object.freeze([]) });
|
||||
} catch (error) { return reject(error); }
|
||||
finally { entered = false; }
|
||||
},
|
||||
history: Object.freeze({ undo: () => traverse('undo'), redo: () => traverse('redo'), canUndo: () => !!state.history.undo.length, canRedo: () => !!state.history.redo.length }),
|
||||
dispose() { disposed = true; listeners.clear(); },
|
||||
});
|
||||
}
|
||||
function documentsEqual(a: Document, b: Document): boolean {
|
||||
return equal([...a.canvases], [...b.canvases]) && equal([...a.elements], [...b.elements]) && equal([...a.tombstones], [...b.tombstones]);
|
||||
}
|
||||
Reference in New Issue
Block a user