@artkit-ai/react 0.1.0 → 0.2.0

package/src/editor-session.ts

@@ -4,735 +4,257 @@ import {
   type ArtifactRegistry,
   applyOperations,
   type ChangeSummary,
-  type CommitResult,
-  deepEqual,
-  type EmitOptions,
   isArtifactError,
+  type LintIssue,
 } from '@artkit-ai/core';
 
-/** The editable part of an artifact: content plus the envelope fields operations can change. */
-export interface EnvelopeState {
-  content: unknown;
-  title: string;
-  themeId: string;
-  locale: string;
-}
+/**
+ * Local draft of one artifact (spec §11.6). The editor never talks to the server while the user edits: every batch is
+ * applied here, with the same pure engine as the server (`applyOperations`), and kept until the application saves.
+ * Saving is the application's decision: the editor emits the draft and the application persists it (or not).
+ */
 
-export interface SendRequest {
+export interface DraftSnapshot {
+  /** Version of the artifact the draft started from (the last one the application loaded or saved). */
   baseVersion: number;
-  operations: unknown[];
-  idempotencyKey: string;
-}
-
-export interface EditorSessionOptions {
-  registry: ArtifactRegistry;
-  /** Last confirmed version. */
+  /** The draft as the user sees it. */
   artifact: Artifact;
-  /** Commits a batch (usually `client.apply`). */
-  send(request: SendRequest): Promise<CommitResult>;
-  /** Loads the latest version, or a specific one, after a conflict or a rebased commit. */
-  load(version?: number): Promise<Artifact>;
-  /** Typing operations emitted within this window become one batch (default 600 ms). */
-  groupingWindowMs?: number;
-  /** Upper bound for one typing batch while the user keeps typing (default 5 s). */
-  maxGroupingMs?: number;
-  /** Undo entries kept (default 100). */
-  maxUndo?: number;
-  /** Locale of error messages produced locally. */
-  locale?: string;
-  createKey?(): string;
-  onCommitted?(result: CommitResult): void;
-}
-
-export type SessionStatus = 'idle' | 'editing' | 'saving' | 'conflict';
-
-export interface SessionConflict {
-  /**
-   * `server`: the server answered VERSION_CONFLICT; `rebase`: a newer version arrived and the pending
-   * operations no longer apply on it; `undo`/`redo`: the artifact changed after the edit being undone.
-   */
-  reason: 'server' | 'rebase' | 'undo' | 'redo';
-  /** What changed in the newer version, for the conflict diff. */
-  changes: ChangeSummary[];
-  /** The local operations that would be reapplied. */
+  /** Operations applied since `baseVersion`, in order. */
   operations: unknown[];
-  latest: Artifact;
-}
-
-export type SessionEvent =
-  | { type: 'saved'; version: number }
-  | { type: 'undone'; version: number }
-  | { type: 'redone'; version: number }
-  | { type: 'rebased'; version: number }
-  | { type: 'rejected'; error: ArtifactError }
-  | { type: 'rolled_back'; error: ArtifactError }
-  | { type: 'conflict'; reason: SessionConflict['reason'] }
-  | { type: 'conflict_resolved'; choice: ConflictChoice };
-
-export type ConflictChoice = 'keep-theirs' | 'reapply';
-
-export interface EditorSessionState {
-  confirmed: Artifact;
-  /** Optimistic state: confirmed version plus every unconfirmed local operation. */
-  view: EnvelopeState;
-  status: SessionStatus;
-  /** Local operations not confirmed yet (buffered, queued or in flight). */
+  /** True when the draft differs from the base. */
   dirty: boolean;
   canUndo: boolean;
   canRedo: boolean;
-  error?: ArtifactError;
-  conflict?: SessionConflict;
-  /** Set after a LOCKED rejection; editing stays disabled until then. */
-  lockedUntil?: string;
-  /** Last notable event, with a sequence number so hosts can announce each one once. */
-  event?: SessionEvent & { seq: number };
+  /** An edit is being applied. */
+  pending: boolean;
+  /** Last rejected batch, cleared by the next accepted one. */
+  error?: { code: string; message: string; issues: { path: string; message: string; hint?: string }[] };
+  /** Lint issues of the draft. */
+  lint: LintIssue[];
+  /** Changes of the last accepted batch. */
+  changes: ChangeSummary[];
 }
 
-interface UndoEntry {
-  /** Missing when the commit was rebased: loaded from `beforeVersion` on demand. */
-  before?: EnvelopeState;
-  beforeVersion: number;
-  after: EnvelopeState;
+export interface DraftSessionOptions {
+  registry: ArtifactRegistry;
+  artifact: Artifact;
+  /** Locale of the model-facing messages produced by the engine (pt-BR or en). */
+  locale?: string;
+  /** Times within which consecutive typing batches share one undo step. */
+  coalesceMs?: number;
+  /** Undo steps kept in memory. */
+  maxUndo?: number;
+  now?: () => number;
 }
 
-type Origin = 'edit' | 'undo' | 'redo' | 'reapply';
-
-type QueueItem =
-  | { type: 'ops'; ops: unknown[]; key: string; origin: Origin; entry?: UndoEntry }
-  | { type: 'undo' }
-  | { type: 'redo' };
-
-export function envelopeOf(
-  artifact: Pick<Artifact, 'content' | 'title' | 'themeId' | 'locale'>,
-): EnvelopeState {
-  return {
-    content: artifact.content,
-    title: artifact.title,
-    themeId: artifact.themeId,
-    locale: artifact.locale,
-  };
+interface Step {
+  artifact: Artifact;
+  operations: unknown[];
+  at: number;
+  typing: boolean;
 }
 
-function sameEnvelope(a: EnvelopeState, b: EnvelopeState): boolean {
-  return (
-    a.title === b.title && a.themeId === b.themeId && a.locale === b.locale && deepEqual(a.content, b.content)
-  );
+export interface EmitOptions {
+  /** Continuous gestures (typing, dragging) share one undo step; discrete changes always get their own. */
+  kind?: 'typing' | 'continuous' | 'discrete';
 }
 
-/**
- * Operations that turn `from` into `to`. Kinds do not provide inverse operations, so undo and redo send
- * `replace_content` with the snapshot (plus envelope operations); the commit still becomes a new version
- * (spec §8.5).
- */
-export function operationsBetween(from: EnvelopeState, to: EnvelopeState): unknown[] {
-  const ops: unknown[] = [];
-  if (!deepEqual(from.content, to.content))
-    ops.push({ op: 'replace_content', content: structuredClone(to.content) });
-  if (from.title !== to.title) ops.push({ op: 'set_title', title: to.title });
-  if (from.themeId !== to.themeId) ops.push({ op: 'set_theme', themeId: to.themeId });
-  if (from.locale !== to.locale) ops.push({ op: 'set_locale', locale: to.locale });
-  return ops;
-}
+type Listener = () => void;
 
-function toArtifactError(error: unknown): ArtifactError {
-  if (isArtifactError(error)) return error;
-  return new ArtifactError('INTERNAL_ERROR', 'Internal error while processing the request.', {
-    cause: error,
-  });
-}
+const DEFAULT_COALESCE_MS = 1000;
+const DEFAULT_MAX_UNDO = 200;
 
-function defaultKey(): string {
-  const cryptoApi = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
-  if (cryptoApi?.randomUUID) return cryptoApi.randomUUID();
-  return `ak-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
-}
-
-/**
- * Framework-free editing session behind `ArtifactEditor` (spec §13.6): batching of typing operations,
- * optimistic apply with the kind's own logic, rollback on rejection, local undo/redo over the user's own
- * batches, rebase of pending operations on newer versions, conflict resolution and lock handling.
- *
- * Batches are sent one at a time, each against the version the previous one produced.
- */
-export class EditorSession {
-  private readonly options: EditorSessionOptions;
-  private readonly windowMs: number;
-  private readonly maxGroupingMs: number;
+/** Draft of one artifact with local undo and redo. Batches are applied in order, one at a time. */
+export class DraftSession {
+  private readonly registry: ArtifactRegistry;
+  private readonly locale: string;
+  private readonly coalesceMs: number;
   private readonly maxUndo: number;
-  private confirmed: Artifact;
-  private view: EnvelopeState;
-  private buffer: unknown[] = [];
-  private bufferStartedAt = 0;
-  private timer: ReturnType<typeof setTimeout> | undefined;
-  private lockTimer: ReturnType<typeof setTimeout> | undefined;
-  private queue: QueueItem[] = [];
-  private inflight = false;
-  private undoStack: UndoEntry[] = [];
-  private redoStack: UndoEntry[] = [];
-  private error: ArtifactError | undefined;
-  private conflict: (SessionConflict & { origin: Origin; entry?: UndoEntry }) | undefined;
-  private lockedUntil: string | undefined;
-  private deferredRemote: Artifact | undefined;
-  private event: (SessionEvent & { seq: number }) | undefined;
-  private seq = 0;
+  private readonly now: () => number;
+  private base: Artifact;
+  private current: Step;
+  private undoStack: Step[] = [];
+  private redoStack: Step[] = [];
+  private queue: Promise<unknown> = Promise.resolve();
+  private pending = 0;
+  private error: DraftSnapshot['error'];
+  private lint: LintIssue[];
+  private changes: ChangeSummary[] = [];
+  private snapshot: DraftSnapshot;
+  private readonly listeners = new Set<Listener>();
   private disposed = false;
-  private readonly listeners = new Set<() => void>();
-  private idleWaiters: (() => void)[] = [];
-  private snapshot: EditorSessionState;
 
-  constructor(options: EditorSessionOptions) {
-    this.options = options;
-    this.windowMs = options.groupingWindowMs ?? 600;
-    this.maxGroupingMs = options.maxGroupingMs ?? 5000;
-    this.maxUndo = options.maxUndo ?? 100;
-    this.confirmed = options.artifact;
-    this.view = envelopeOf(options.artifact);
+  constructor(options: DraftSessionOptions) {
+    this.registry = options.registry;
+    this.locale = options.locale ?? 'en';
+    this.coalesceMs = options.coalesceMs ?? DEFAULT_COALESCE_MS;
+    this.maxUndo = options.maxUndo ?? DEFAULT_MAX_UNDO;
+    this.now = options.now ?? (() => Date.now());
+    this.base = options.artifact;
+    this.current = { artifact: options.artifact, operations: [], at: 0, typing: false };
+    this.lint = this.lintOf(options.artifact);
     this.snapshot = this.buildSnapshot();
   }
 
-  // -- subscription ---------------------------------------------------------------------------------
+  /** The current snapshot. Its identity changes only when the state changes. */
+  getSnapshot = (): DraftSnapshot => this.snapshot;
 
-  subscribe = (listener: () => void): (() => void) => {
+  subscribe = (listener: Listener): (() => void) => {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
   };
 
-  getSnapshot = (): EditorSessionState => this.snapshot;
-
-  /** Resolves once nothing is buffered, queued or in flight (or a conflict is waiting for the user). */
-  whenIdle(): Promise<void> {
-    if (this.isIdle()) return Promise.resolve();
-    return new Promise((resolve) => this.idleWaiters.push(resolve));
-  }
-
-  private isIdle(): boolean {
-    return (
-      this.buffer.length === 0 && !this.inflight && (this.queue.length === 0 || this.conflict !== undefined)
-    );
-  }
-
-  private buildSnapshot(): EditorSessionState {
-    const pendingEdits = this.queue.filter(
-      (item) => item.type === 'ops' && item.origin !== 'undo' && item.origin !== 'redo',
-    ).length;
-    const queuedUndo = this.queue.filter((item) => item.type === 'undo').length;
-    const queuedRedo = this.queue.filter((item) => item.type === 'redo').length;
-    const dirty = this.buffer.length > 0 || this.queue.length > 0 || this.inflight;
-    let status: SessionStatus = 'idle';
-    if (this.conflict) status = 'conflict';
-    else if (this.inflight || this.queue.length > 0) status = 'saving';
-    else if (this.buffer.length > 0) status = 'editing';
-    const blocked = this.conflict !== undefined || this.isLocked();
-    return {
-      confirmed: this.confirmed,
-      view: this.view,
-      status,
-      dirty,
-      canUndo:
-        !blocked && this.undoStack.length + pendingEdits + (this.buffer.length > 0 ? 1 : 0) > queuedUndo,
-      canRedo:
-        !blocked && this.buffer.length === 0 && pendingEdits === 0 && this.redoStack.length > queuedRedo,
-      ...(this.error ? { error: this.error } : {}),
-      ...(this.conflict
-        ? {
-            conflict: {
-              reason: this.conflict.reason,
-              changes: this.conflict.changes,
-              operations: this.conflict.operations,
-              latest: this.conflict.latest,
-            },
-          }
-        : {}),
-      ...(this.lockedUntil ? { lockedUntil: this.lockedUntil } : {}),
-      ...(this.event ? { event: this.event } : {}),
-    };
-  }
-
-  private notify(): void {
-    this.snapshot = this.buildSnapshot();
-    for (const listener of [...this.listeners]) listener();
-    if (this.isIdle() && this.idleWaiters.length > 0) {
-      const waiters = this.idleWaiters;
-      this.idleWaiters = [];
-      for (const resolve of waiters) resolve();
-    }
-  }
-
-  private announce(event: SessionEvent): void {
-    this.seq += 1;
-    this.event = { ...event, seq: this.seq };
-  }
-
-  private isLocked(): boolean {
-    return this.lockedUntil !== undefined && Date.parse(this.lockedUntil) > Date.now();
-  }
-
-  // -- local application -----------------------------------------------------------------------------
-
-  private applyLocal(state: EnvelopeState, ops: unknown[]): EnvelopeState {
-    const result = applyOperations(
-      this.options.registry,
-      { kind: this.confirmed.kind, ...state },
-      ops,
-      this.options.locale ? { locale: this.options.locale } : {},
-    );
-    return { content: result.content, title: result.title, themeId: result.themeId, locale: result.locale };
-  }
-
-  private pendingOperations(): unknown[] {
-    const ops: unknown[] = [];
-    for (const item of this.queue) if (item.type === 'ops') ops.push(...item.ops);
-    ops.push(...this.buffer);
-    return ops;
-  }
-
   /**
-   * Recomputes the optimistic view from the confirmed version. When the unconfirmed operations no
-   * longer apply, they move into a `rebase` conflict and the view falls back to the confirmed version.
+   * Applies a batch to the draft. Resolves to `true` when the batch was accepted. A rejected batch leaves the draft
+   * untouched and sets `snapshot.error`.
    */
-  private rebaseView(previous: Artifact): void {
-    let state = envelopeOf(this.confirmed);
-    try {
-      for (const item of this.queue) if (item.type === 'ops') state = this.applyLocal(state, item.ops);
-      if (this.buffer.length > 0) state = this.applyLocal(state, this.buffer);
-      this.view = state;
-    } catch {
-      const operations = this.pendingOperations();
-      this.clearTimer();
-      this.buffer = [];
-      // The in-flight batch (if any) is already at the server and settles on its own.
-      this.queue = this.inflight ? this.queue.slice(0, 1) : [];
-      this.view = envelopeOf(this.confirmed);
-      this.conflict = {
-        reason: 'rebase',
-        changes: this.changesBetween(previous, this.confirmed),
-        operations,
-        latest: this.confirmed,
-        origin: 'edit',
-      };
-      this.announce({ type: 'conflict', reason: 'rebase' });
-    }
+  apply(operations: unknown[], options: EmitOptions = {}): Promise<boolean> {
+    if (operations.length === 0) return Promise.resolve(true);
+    this.pending += 1;
+    this.publish();
+    const run = this.queue.then(async () => {
+      if (this.disposed) return false;
+      const typing = options.kind === 'typing' || options.kind === 'continuous';
+      try {
+        const result = await applyOperations(this.registry, this.current.artifact, operations, {
+          locale: this.locale,
+        });
+        const next: Artifact = {
+          ...this.current.artifact,
+          formatVersion: result.formatVersion,
+          title: result.title,
+          locale: result.locale,
+          themeId: result.themeId,
+          content: result.content,
+        };
+        const now = this.now();
+        const coalesce = typing && this.current.typing && now - this.current.at <= this.coalesceMs;
+        if (!coalesce) {
+          this.undoStack.push(this.current);
+          if (this.undoStack.length > this.maxUndo) this.undoStack.shift();
+        }
+        this.redoStack = [];
+        this.current = {
+          artifact: next,
+          operations: [...this.current.operations, ...operations],
+          at: now,
+          typing,
+        };
+        this.lint = result.lint;
+        this.changes = result.diff;
+        this.error = undefined;
+        return true;
+      } catch (error) {
+        this.error = errorOf(error);
+        return false;
+      }
+    });
+    this.queue = run.finally(() => {
+      this.pending -= 1;
+      this.publish();
+    });
+    return run.then((accepted) => {
+      this.publish();
+      return accepted;
+    });
   }
 
-  private changesBetween(before: EnvelopeState, after: EnvelopeState): ChangeSummary[] {
-    const changes: ChangeSummary[] = [];
-    if (before.title !== after.title)
-      changes.push({
-        type: 'changed',
-        target: 'envelope:title',
-        summary: `'${before.title}' → '${after.title}'`,
-      });
-    if (before.themeId !== after.themeId)
-      changes.push({
-        type: 'changed',
-        target: 'envelope:themeId',
-        summary: `${before.themeId} → ${after.themeId}`,
-      });
-    if (before.locale !== after.locale)
-      changes.push({
-        type: 'changed',
-        target: 'envelope:locale',
-        summary: `${before.locale} → ${after.locale}`,
-      });
-    try {
-      changes.push(...this.options.registry.get(this.confirmed.kind).diff(before.content, after.content));
-    } catch {
-      // A diff failure must not hide the conflict itself.
-    }
-    return changes;
+  /** Steps back one edit (local). Returns false when there is nothing to undo. */
+  undo(): boolean {
+    const previous = this.undoStack.pop();
+    if (!previous) return false;
+    this.redoStack.push(this.current);
+    this.restore(previous);
+    return true;
   }
 
-  // -- editing ---------------------------------------------------------------------------------------
+  /** Steps forward after an undo. Returns false when there is nothing to redo. */
+  redo(): boolean {
+    const next = this.redoStack.pop();
+    if (!next) return false;
+    this.undoStack.push(this.current);
+    this.restore(next);
+    return true;
+  }
 
   /**
-   * Called by the kind editor. Operations are applied optimistically right away; invalid ones are
-   * rejected locally (returns false) and never reach the server.
+   * Adopts an artifact loaded or saved by the application. A clean draft follows the new artifact. A draft that has
+   * changes keeps its content, and the base moves to the new version so the next save is a complete one.
    */
-  emit = (operations: unknown[], options: EmitOptions = {}): boolean => {
-    if (
-      this.disposed ||
-      this.conflict ||
-      this.isLocked() ||
-      !Array.isArray(operations) ||
-      operations.length === 0
-    )
-      return false;
-    try {
-      this.view = this.applyLocal(this.view, operations);
-    } catch (error) {
-      this.error = toArtifactError(error);
-      this.announce({ type: 'rejected', error: this.error });
-      this.notify();
-      return false;
-    }
-    this.error = undefined;
-    this.redoStack = [];
-    const maxOps = this.options.registry.batch.maxOperations;
-    if (options.kind === 'typing') {
-      if (this.buffer.length + operations.length > maxOps) this.flushBuffer();
-      if (this.buffer.length === 0) this.bufferStartedAt = Date.now();
-      this.buffer.push(...operations);
-      if (Date.now() - this.bufferStartedAt >= this.maxGroupingMs) this.flushBuffer();
-      else this.schedule();
-    } else {
-      // Discrete operations and the end of continuous gestures flush right away, after pending typing.
-      this.flushBuffer();
-      this.queue.push({ type: 'ops', ops: operations, key: this.key(), origin: 'edit' });
+  load(artifact: Artifact): void {
+    if (artifact.id !== this.base.id) throw new ArtifactError('INVALID_OPERATION', 'Load the same artifact.');
+    const clean = !this.buildSnapshot().dirty;
+    const sameContent = JSON.stringify(artifact.content) === JSON.stringify(this.current.artifact.content);
+    this.base = artifact;
+    if (clean || sameContent) {
+      this.current = { artifact, operations: [], at: 0, typing: false };
+      this.undoStack = [];
+      this.redoStack = [];
+      this.lint = this.lintOf(artifact);
+      this.changes = [];
     }
-    this.pump();
-    this.notify();
-    return true;
-  };
-
-  /** Sends buffered typing operations now (e.g. on blur or before navigation). */
-  flush(): void {
-    if (this.buffer.length === 0) return;
-    this.flushBuffer();
-    this.pump();
-    this.notify();
-  }
-
-  private key(): string {
-    return this.options.createKey?.() ?? defaultKey();
-  }
-
-  private schedule(): void {
-    this.clearTimer();
-    this.timer = setTimeout(() => {
-      this.timer = undefined;
-      this.flush();
-    }, this.windowMs);
-  }
-
-  private clearTimer(): void {
-    if (this.timer !== undefined) clearTimeout(this.timer);
-    this.timer = undefined;
+    this.publish();
   }
 
-  private flushBuffer(): void {
-    this.clearTimer();
-    if (this.buffer.length === 0) return;
-    this.queue.push({ type: 'ops', ops: this.buffer, key: this.key(), origin: 'edit' });
-    this.buffer = [];
+  /** Stops the session: later batches are ignored and listeners are dropped. */
+  dispose(): void {
+    this.disposed = true;
+    this.listeners.clear();
   }
 
-  undo = (): void => {
-    if (!this.snapshot.canUndo) return;
-    this.flushBuffer();
-    this.queue.push({ type: 'undo' });
-    this.pump();
-    this.notify();
-  };
-
-  redo = (): void => {
-    if (!this.snapshot.canRedo) return;
-    this.queue.push({ type: 'redo' });
-    this.pump();
-    this.notify();
-  };
-
-  dismissError = (): void => {
-    if (!this.error) return;
+  private restore(step: Step): void {
+    this.current = step;
+    this.lint = this.lintOf(step.artifact);
+    this.changes = [];
     this.error = undefined;
-    this.notify();
-  };
-
-  // -- sending ---------------------------------------------------------------------------------------
-
-  private pump(): void {
-    if (this.inflight || this.conflict) return;
-    const item = this.queue[0];
-    if (!item) return;
-    if (item.type === 'undo' || item.type === 'redo') {
-      this.resolveHistoryCommand(item.type);
-      return;
-    }
-    this.inflight = true;
-    const base = this.confirmed;
-    this.options
-      .send({ baseVersion: base.version, operations: item.ops, idempotencyKey: item.key })
-      .then(
-        (result) => this.onCommitted(item, base, result),
-        (error: unknown) => this.onRejected(item, base, error),
-      )
-      .finally(() => this.notify());
-  }
-
-  private resolveHistoryCommand(direction: 'undo' | 'redo'): void {
-    const stack = direction === 'undo' ? this.undoStack : this.redoStack;
-    const entry = stack.pop();
-    if (!entry) {
-      this.queue.shift();
-      this.pump();
-      return;
-    }
-    if (!entry.before) {
-      // Rebased commit: the version before it is only known by the server.
-      this.inflight = true;
-      this.options
-        .load(entry.beforeVersion)
-        .then(
-          (artifact) => {
-            entry.before = envelopeOf(artifact);
-            stack.push(entry);
-          },
-          (error: unknown) => {
-            this.queue.shift();
-            this.error = toArtifactError(error);
-            this.announce({ type: 'rolled_back', error: this.error });
-          },
-        )
-        .finally(() => {
-          this.inflight = false;
-          this.applyDeferred();
-          this.pump();
-          this.notify();
-        });
-      return;
-    }
-    const current = envelopeOf(this.confirmed);
-    const expected = direction === 'undo' ? entry.after : entry.before;
-    const target = direction === 'undo' ? entry.before : entry.after;
-    this.queue.shift();
-    if (!sameEnvelope(current, expected)) {
-      // Someone else changed the artifact after this edit: undoing blindly would discard their work.
-      this.conflict = {
-        reason: direction,
-        changes: this.changesBetween(expected, current),
-        operations: operationsBetween(current, target),
-        latest: this.confirmed,
-        origin: direction,
-        entry,
-      };
-      this.view = current;
-      this.announce({ type: 'conflict', reason: direction });
-      return;
-    }
-    const ops = operationsBetween(current, target);
-    if (ops.length === 0) {
-      (direction === 'undo' ? this.redoStack : this.undoStack).push(entry);
-      this.pump();
-      return;
-    }
-    this.queue.unshift({ type: 'ops', ops, key: this.key(), origin: direction, entry });
-    this.rebaseView(this.confirmed);
-    this.pump();
-  }
-
-  private onCommitted(item: Extract<QueueItem, { type: 'ops' }>, base: Artifact, result: CommitResult): void {
-    this.inflight = false;
-    this.queue.shift();
-    const previous = this.confirmed;
-    if (result.artifact.version > this.confirmed.version) this.confirmed = result.artifact;
-    const after = envelopeOf(result.artifact);
-    if (item.origin === 'undo' && item.entry) {
-      this.redoStack.push(item.entry);
-      this.announce({ type: 'undone', version: result.version });
-    } else if (item.origin === 'redo' && item.entry) {
-      this.pushUndo(item.entry);
-      this.announce({ type: 'redone', version: result.version });
-    } else {
-      this.pushUndo({
-        ...(result.rebased ? {} : { before: envelopeOf(base) }),
-        beforeVersion: result.version - 1,
-        after,
-      });
-      this.announce({ type: 'saved', version: result.version });
-    }
-    try {
-      this.options.onCommitted?.(result);
-    } catch {
-      // A failing host callback must not break the session.
-    }
-    if (!this.disposed) this.rebaseView(previous);
-    this.applyDeferred();
-    this.pump();
-  }
-
-  /** Incorporates a version that arrived while a request was in flight. */
-  private applyDeferred(): void {
-    const remote = this.deferredRemote;
-    this.deferredRemote = undefined;
-    if (remote && remote.version > this.confirmed.version) this.incorporate(remote);
+    this.publish();
   }
 
-  private pushUndo(entry: UndoEntry): void {
-    this.undoStack.push(entry);
-    if (this.undoStack.length > this.maxUndo) this.undoStack.splice(0, this.undoStack.length - this.maxUndo);
+  private lintOf(artifact: Artifact): LintIssue[] {
+    const adapter = this.registry.get(artifact.format, this.locale);
+    return adapter.lint(artifact.content as never, {
+      locale: artifact.locale,
+      theme: this.registry.theme(artifact.themeId, this.locale),
+    });
   }
 
-  private onRejected(
-    item: Extract<QueueItem, { type: 'ops' }>,
-    base: Artifact,
-    raw: unknown,
-  ): Promise<void> | void {
-    const error = toArtifactError(raw);
-    this.queue.shift();
-    if (error.code === 'VERSION_CONFLICT') {
-      const operations = [...item.ops, ...this.pendingOperations()];
-      this.clearTimer();
-      this.queue = [];
-      this.buffer = [];
-      const changes = Array.isArray(error.details.changesSinceBase)
-        ? (error.details.changesSinceBase as ChangeSummary[])
-        : undefined;
-      // Keep `inflight` set while loading so nothing else is sent against a stale base.
-      return this.options
-        .load()
-        .then(
-          (latest) => {
-            if (latest.version > this.confirmed.version) this.confirmed = latest;
-          },
-          () => undefined,
-        )
-        .then(() => {
-          this.inflight = false;
-          const remote = this.deferredRemote;
-          this.deferredRemote = undefined;
-          if (remote && remote.version > this.confirmed.version) this.confirmed = remote;
-          const reason = item.origin === 'undo' || item.origin === 'redo' ? item.origin : 'server';
-          this.conflict = {
-            reason,
-            changes: changes ?? this.changesBetween(base, this.confirmed),
-            operations: item.origin === 'undo' || item.origin === 'redo' ? item.ops : operations,
-            latest: this.confirmed,
-            origin: item.origin,
-            ...(item.entry ? { entry: item.entry } : {}),
-          };
-          this.view = envelopeOf(this.confirmed);
-          this.announce({ type: 'conflict', reason });
-        });
-    }
-    this.inflight = false;
-    // Any other rejection rolls back to the last confirmed version (spec §13.6).
-    this.clearTimer();
-    this.queue = [];
-    this.buffer = [];
-    if (item.entry) (item.origin === 'undo' ? this.undoStack : this.redoStack).push(item.entry);
-    if (error.code === 'LOCKED') this.setLocked(error);
-    this.error = error;
-    this.view = envelopeOf(this.confirmed);
-    this.announce({ type: 'rolled_back', error });
-    const remote = this.deferredRemote;
-    this.deferredRemote = undefined;
-    if (remote && remote.version > this.confirmed.version) {
-      this.confirmed = remote;
-      this.view = envelopeOf(remote);
-    }
+  private publish(): void {
+    this.snapshot = this.buildSnapshot();
+    for (const listener of this.listeners) listener();
   }
 
-  private setLocked(error: ArtifactError): void {
-    const expiresAt =
-      typeof error.details.expiresAt === 'string'
-        ? error.details.expiresAt
-        : new Date(Date.now() + 60_000).toISOString();
-    this.lockedUntil = expiresAt;
-    if (this.lockTimer !== undefined) clearTimeout(this.lockTimer);
-    const delay = Math.max(0, Date.parse(expiresAt) - Date.now());
-    this.lockTimer = setTimeout(() => {
-      this.lockTimer = undefined;
-      this.lockedUntil = undefined;
-      this.notify();
-    }, delay);
+  private buildSnapshot(): DraftSnapshot {
+    const dirty =
+      this.current.operations.length > 0 ||
+      JSON.stringify(this.current.artifact.content) !== JSON.stringify(this.base.content) ||
+      this.current.artifact.title !== this.base.title;
+    return {
+      baseVersion: this.base.version,
+      artifact: this.current.artifact,
+      operations: this.current.operations,
+      dirty,
+      canUndo: this.undoStack.length > 0,
+      canRedo: this.redoStack.length > 0,
+      pending: this.pending > 0,
+      ...(this.error ? { error: this.error } : {}),
+      lint: this.lint,
+      changes: this.changes,
+    };
   }
+}
 
-  // -- remote versions ---------------------------------------------------------------------------------
-
-  /**
-   * A version arrived from outside the session (refetch, agent commit, prop). Pending local operations
-   * are rebased on it; when they no longer apply, a `rebase` conflict asks the user what to keep.
-   */
-  receive = (artifact: Artifact): void => {
-    if (this.disposed || artifact.id !== this.confirmed.id) return;
-    if (artifact.version < this.confirmed.version) return;
-    if (artifact.version === this.confirmed.version) {
-      if (
-        artifact.status !== this.confirmed.status ||
-        artifact.meta.publishedVersion !== this.confirmed.meta.publishedVersion
-      ) {
-        this.confirmed = { ...this.confirmed, status: artifact.status, meta: artifact.meta };
-        this.notify();
-      }
-      return;
-    }
-    if (this.inflight) {
-      // Wait for the in-flight batch: applying it on top of a version that may already contain it
-      // would show its operations twice.
-      if (!this.deferredRemote || artifact.version > this.deferredRemote.version)
-        this.deferredRemote = artifact;
-      return;
-    }
-    this.incorporate(artifact);
-    this.notify();
-  };
-
-  private incorporate(artifact: Artifact): void {
-    const previous = this.confirmed;
-    this.confirmed = artifact;
-    if (this.conflict) {
-      this.conflict.latest = artifact;
-      this.view = envelopeOf(artifact);
-    } else {
-      this.rebaseView(previous);
-      if (!this.conflict) this.announce({ type: 'rebased', version: artifact.version });
-    }
+function errorOf(error: unknown): NonNullable<DraftSnapshot['error']> {
+  if (isArtifactError(error)) {
+    const payload = error.toPayload();
+    return {
+      code: payload.error.code,
+      message: payload.error.message,
+      issues: payload.error.issues ?? [],
+    };
   }
-
-  resolveConflict = (choice: ConflictChoice): void => {
-    const conflict = this.conflict;
-    if (!conflict) return;
-    this.conflict = undefined;
-    this.error = undefined;
-    this.view = envelopeOf(this.confirmed);
-    if (choice === 'reapply') {
-      if (conflict.origin === 'undo' || conflict.origin === 'redo') {
-        const entry = conflict.entry;
-        const target = entry ? (conflict.origin === 'undo' ? entry.before : entry.after) : undefined;
-        const ops = target ? operationsBetween(envelopeOf(this.confirmed), target) : [];
-        if (ops.length > 0) {
-          this.queue.unshift({
-            type: 'ops',
-            ops,
-            key: this.key(),
-            origin: conflict.origin,
-            ...(entry ? { entry } : {}),
-          });
-        }
-      } else {
-        try {
-          this.applyLocal(envelopeOf(this.confirmed), conflict.operations);
-          this.queue.unshift({ type: 'ops', ops: conflict.operations, key: this.key(), origin: 'reapply' });
-        } catch (error) {
-          this.error = toArtifactError(error);
-          this.announce({ type: 'rolled_back', error: this.error });
-          this.pump();
-          this.notify();
-          return;
-        }
-      }
-      this.rebaseView(this.confirmed);
-    }
-    this.announce({ type: 'conflict_resolved', choice });
-    this.pump();
-    this.notify();
+  return {
+    code: 'INTERNAL_ERROR',
+    message: error instanceof Error ? error.message : String(error),
+    issues: [],
   };
-
-  /**
-   * Stops timers and listeners. Buffered typing is still sent unless `discard` is set, so closing the
-   * editor right after typing does not lose the last keystrokes.
-   */
-  dispose(options: { discard?: boolean } = {}): void {
-    if (this.disposed) return;
-    if (options.discard) {
-      this.buffer = [];
-      this.queue = this.inflight ? this.queue.slice(0, 1) : [];
-    } else {
-      this.flushBuffer();
-      this.pump();
-    }
-    this.clearTimer();
-    if (this.lockTimer !== undefined) clearTimeout(this.lockTimer);
-    this.disposed = true;
-    this.listeners.clear();
-  }
 }