@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/history/json-history-resource.ts

@@ -0,0 +1,165 @@
+import { HistoryOperationError, type HistoryService } from './history-service';
+import { sha256Hex } from './snapshot-store';
+import type { ResourceDescriptor, ResourceDriver, ResourceKind } from './types';
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export interface JsonHistoryResourceOptions<T> {
+  readonly history: HistoryService;
+  readonly kind: ResourceKind;
+  readonly scope: 'project' | 'session';
+  readonly location?: string;
+  readonly sessionId?: string;
+  readonly displayName?: string;
+  readonly capture: () => T;
+  readonly restore: (value: T) => void | Promise<void>;
+  /**
+   * The part of the captured state that constitutes this resource's CONFLICT
+   * IDENTITY — i.e. "has something else changed this resource since the
+   * transaction was recorded?". Defaults to the whole captured value.
+   *
+   * Override it when `capture()` deliberately includes state that is NOT part
+   * of the resource's persisted content and may change on its own. The ingest
+   * overlay resource is the motivating case: its snapshot carries a mirror of
+   * every live `Object3D`'s pose (needed as the RESTORE payload), but an
+   * ingested game is a RUNNING game that animates its own objects every frame.
+   * Hashing that live simulation state as identity made every ingest
+   * transaction fail preflight with `content-conflict` a frame after it was
+   * recorded — so undo silently did nothing (issue #81). The resource's real
+   * content is the overlay it serializes to disk, which only editor edits
+   * touch.
+   */
+  readonly conflictIdentity?: (value: T) => unknown;
+}
+
+/** Concrete JSON document/session resource backed by the project HistoryService. */
+export class JsonHistoryResource<T> {
+  readonly descriptor: ResourceDescriptor;
+  private revision = 0;
+  private readonly unregister: () => void;
+  private disposed = false;
+
+  constructor(private readonly options: JsonHistoryResourceOptions<T>) {
+    if (options.scope === 'project') {
+      if (!options.location) throw new Error('A project JSON history resource needs a location.');
+      this.descriptor = options.history.registry.registerProject(
+        options.kind,
+        options.location,
+        options.displayName,
+      );
+    } else {
+      if (!options.sessionId)
+        throw new Error('A session JSON history resource needs a session id.');
+      this.descriptor = options.history.registry.registerSession(
+        options.kind,
+        options.sessionId,
+        options.displayName ?? options.kind,
+      );
+    }
+
+    const driver: ResourceDriver = {
+      descriptor: this.descriptor,
+      capture: async () => {
+        const bytes = this.encode(options.capture());
+        return {
+          revision: this.revision,
+          contentType: 'application/json',
+          bytes,
+          sha256: await sha256Hex(bytes),
+        };
+      },
+      preflight: async (expected) => {
+        const bytes = this.encode(options.capture());
+        const actualSha256 = await sha256Hex(bytes);
+        // Fast path (and the behavior for every resource that does NOT narrow
+        // its identity): the full captured bytes still hash to what the
+        // transaction expects, so nothing has diverged.
+        if (actualSha256 === expected.sha256) return { ok: true };
+        // Otherwise the bytes differ — but that only counts as a CONFLICT if the
+        // part that identifies the resource differs. Compare the narrowed
+        // identity against the expected snapshot's own identity, decoded from
+        // the stored blob. (See `conflictIdentity` — an ingested game mutates
+        // the live-object mirror in its snapshot every frame on its own.)
+        if (options.conflictIdentity) {
+          const expectedValue = JSON.parse(
+            decoder.decode(options.history.snapshots.read(expected).bytes),
+          ) as T;
+          const expectedIdentity = JSON.stringify(options.conflictIdentity(expectedValue));
+          const actualIdentity = JSON.stringify(options.conflictIdentity(options.capture()));
+          if (expectedIdentity === actualIdentity) return { ok: true };
+        }
+        return {
+          ok: false,
+          reason: 'content-conflict',
+          actualRevision: this.revision,
+          actualSha256,
+        };
+      },
+      restore: async (snapshot) => {
+        const bytes = options.history.snapshots.read(snapshot).bytes;
+        await options.restore(JSON.parse(decoder.decode(bytes)) as T);
+        this.revision++;
+      },
+      estimateBytes: (snapshot) => snapshot.byteLength,
+    };
+    this.unregister = options.history.registerDriver(driver);
+  }
+
+  record(label: string, before: T, after: T): Promise<boolean> {
+    if (this.disposed) return Promise.reject(new Error('JSON history resource is disposed.'));
+    this.options.history.assertCanRecordAppliedChange();
+    this.revision++;
+    return this.options.history
+      .recordAppliedTransaction(
+        {
+          label,
+          resources: [this.descriptor.key],
+          scope: this.descriptor.scope,
+          ...(this.descriptor.sessionId ? { sessionId: this.descriptor.sessionId } : {}),
+        },
+        [
+          {
+            resource: this.descriptor.key,
+            beforeBytes: this.encode(before),
+            afterBytes: this.encode(after),
+            contentType: 'application/json',
+          },
+        ],
+      )
+      .catch(async (error: unknown) => {
+        try {
+          await this.options.restore(structuredClone(before));
+          this.revision++;
+        } catch (compensationError) {
+          throw this.options.history.blockForCompensationFailure(label, [this.descriptor.key], {
+            operationError: error,
+            compensationError,
+          });
+        }
+        if (!(error instanceof HistoryOperationError)) {
+          this.options.history.reportAppliedChangeFailure(label, [this.descriptor.key], error);
+        }
+        throw error;
+      });
+  }
+
+  /** Must be called immediately before a live or overlay mutation begins. */
+  assertCanMutate(): void {
+    if (this.disposed) throw new Error('JSON history resource is disposed.');
+    this.options.history.assertCanRecordAppliedChange();
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unregister();
+    if (this.descriptor.sessionId) {
+      this.options.history.expireSession(this.descriptor.sessionId);
+    }
+  }
+
+  private encode(value: T): Uint8Array {
+    return encoder.encode(JSON.stringify(value, null, 2));
+  }
+}

package/src/history/persistence-coordinator.ts

@@ -0,0 +1,35 @@
+import type { ResourceKey } from './types';
+
+/** Serializes every in-process writer that touches the same authored resource. */
+export class PersistenceCoordinator {
+  private readonly tails = new Map<ResourceKey, Promise<void>>();
+
+  run<T>(resource: ResourceKey, operation: () => Promise<T>): Promise<T> {
+    return this.runMany([resource], operation);
+  }
+
+  async runMany<T>(resources: readonly ResourceKey[], operation: () => Promise<T>): Promise<T> {
+    const keys = [...new Set(resources)].sort();
+    if (keys.length === 0) return operation();
+
+    const previous = keys.map((key) => this.tails.get(key) ?? Promise.resolve());
+    const acquired = Promise.all(previous).then(() => undefined);
+    let release!: () => void;
+    const held = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const reservation = acquired.then(() => held);
+    for (const key of keys) this.tails.set(key, reservation);
+
+    await acquired;
+    try {
+      return await operation();
+    } finally {
+      release();
+      for (const key of keys) {
+        if (this.tails.get(key) !== reservation) continue;
+        this.tails.delete(key);
+      }
+    }
+  }
+}

package/src/history/project-file-history.ts

@@ -0,0 +1,266 @@
+import { getStorageBackend } from '../storage';
+import type { HistoryService } from './history-service';
+import { normalizeProjectPath } from './resource-registry';
+import { sha256Hex } from './snapshot-store';
+import type {
+  ResourceDescriptor,
+  ResourceDriver,
+  ResourceKey,
+  ResourceKind,
+  ResourceSnapshot,
+} from './types';
+
+const ABSENT = 0;
+const PRESENT = 1;
+
+function encodeFile(exists: boolean, bytes: Uint8Array = new Uint8Array()): Uint8Array {
+  const encoded = new Uint8Array(bytes.byteLength + 1);
+  encoded[0] = exists ? PRESENT : ABSENT;
+  if (exists) encoded.set(bytes, 1);
+  return encoded;
+}
+
+function decodeFile(encoded: Uint8Array): { exists: boolean; bytes: Uint8Array } {
+  const marker = encoded[0];
+  if (marker !== ABSENT && marker !== PRESENT) throw new Error('Invalid project-file snapshot.');
+  return { exists: marker === PRESENT, bytes: encoded.slice(1) };
+}
+
+async function captureFile(
+  backend: HistoryFileBackend,
+  path: string,
+  revision: number,
+  contentType: string,
+): Promise<ResourceSnapshot> {
+  const exists = await backend.exists(path);
+  const bytes = encodeFile(exists, exists ? await backend.readBytes(path) : undefined);
+  return { revision, contentType, bytes, sha256: await sha256Hex(bytes) };
+}
+
+interface ManagedFile {
+  descriptor: ResourceDescriptor;
+  revision: number;
+  contentType: string;
+  listeners: Set<() => void>;
+}
+
+export interface ProjectFileMutation {
+  readonly path: string;
+  readonly data: string | Uint8Array | null;
+  readonly kind?: ResourceKind;
+  readonly contentType?: string;
+}
+
+/** Exact-byte, existence-aware history for project files reached through StorageBackend. */
+export class ProjectFileHistory {
+  private readonly files = new Map<string, ManagedFile>();
+  private readonly listeners = new Set<(path: string) => void>();
+
+  constructor(
+    private readonly history: HistoryService,
+    private readonly backend: HistoryFileBackend,
+  ) {}
+
+  write(
+    path: string,
+    data: string | Uint8Array,
+    options: { label: string; kind?: ResourceKind; contentType?: string },
+  ): Promise<boolean> {
+    const normalized = normalizeProjectPath(path);
+    const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : Uint8Array.from(data);
+    const file = this.file(
+      normalized,
+      options.kind ?? 'project-file',
+      options.contentType ?? (typeof data === 'string' ? 'text/plain' : 'application/octet-stream'),
+    );
+    return this.history.transaction(
+      { label: options.label, resources: [file.descriptor.key], scope: 'project' },
+      async (tx) => {
+        await tx.write(file.descriptor.key, encodeFile(true, bytes), file.contentType);
+        return true;
+      },
+    );
+  }
+
+  writeWithResources(
+    path: string,
+    data: string | Uint8Array,
+    options: { label: string; kind?: ResourceKind; contentType?: string },
+    additional: readonly {
+      resource: ResourceKey;
+      bytes: Uint8Array;
+      contentType: string;
+    }[],
+  ): Promise<boolean> {
+    const normalized = normalizeProjectPath(path);
+    const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : Uint8Array.from(data);
+    const file = this.file(
+      normalized,
+      options.kind ?? 'project-file',
+      options.contentType ?? (typeof data === 'string' ? 'text/plain' : 'application/octet-stream'),
+    );
+    return this.history.transaction(
+      {
+        label: options.label,
+        resources: [file.descriptor.key, ...additional.map((change) => change.resource)],
+        scope: 'project',
+      },
+      async (tx) => {
+        await tx.write(file.descriptor.key, encodeFile(true, bytes), file.contentType);
+        for (const change of additional) {
+          await tx.write(change.resource, change.bytes, change.contentType);
+        }
+        return true;
+      },
+    );
+  }
+
+  remove(
+    path: string,
+    options: { label: string; kind?: ResourceKind; contentType?: string },
+  ): Promise<boolean> {
+    const normalized = normalizeProjectPath(path);
+    const file = this.file(
+      normalized,
+      options.kind ?? 'project-file',
+      options.contentType ?? 'application/octet-stream',
+    );
+    return this.history.transaction(
+      { label: options.label, resources: [file.descriptor.key], scope: 'project' },
+      async (tx) => {
+        await tx.write(file.descriptor.key, encodeFile(false), file.contentType);
+        return true;
+      },
+    );
+  }
+
+  /** Apply a logical multi-file operation as one failure-atomic undo step. */
+  mutate(changes: readonly ProjectFileMutation[], options: { label: string }): Promise<boolean> {
+    const staged = changes.map((change) => {
+      const path = normalizeProjectPath(change.path);
+      const contentType = change.contentType ?? 'application/octet-stream';
+      return {
+        change,
+        file: this.file(path, change.kind ?? 'project-file', contentType),
+        contentType,
+      };
+    });
+    const uniqueResources = new Set(staged.map(({ file }) => file.descriptor.key));
+    if (uniqueResources.size !== staged.length) {
+      throw new Error('A project-file mutation cannot write the same path twice.');
+    }
+    return this.history.transaction(
+      { label: options.label, resources: [...uniqueResources], scope: 'project' },
+      async (tx) => {
+        for (const { change, file, contentType } of staged) {
+          const bytes =
+            change.data === null
+              ? encodeFile(false)
+              : encodeFile(
+                  true,
+                  typeof change.data === 'string'
+                    ? new TextEncoder().encode(change.data)
+                    : Uint8Array.from(change.data),
+                );
+          await tx.write(file.descriptor.key, bytes, contentType);
+        }
+        return true;
+      },
+    );
+  }
+
+  subscribe(path: string, listener: () => void): () => void {
+    const normalized = normalizeProjectPath(path);
+    const file = this.files.get(normalized);
+    if (!file) throw new Error(`Project file "${normalized}" is not registered with history.`);
+    file.listeners.add(listener);
+    return () => file.listeners.delete(listener);
+  }
+
+  subscribeAll(listener: (path: string) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private file(path: string, kind: ResourceKind, contentType: string): ManagedFile {
+    const existing = this.files.get(path);
+    if (existing) {
+      if (existing.descriptor.kind !== kind) {
+        throw new Error(
+          `Project file "${path}" is already registered as ${existing.descriptor.kind}.`,
+        );
+      }
+      existing.contentType = contentType;
+      return existing;
+    }
+    const descriptor = this.history.registry.registerProject(kind, path);
+    const file: ManagedFile = {
+      descriptor,
+      revision: 0,
+      contentType,
+      listeners: new Set(),
+    };
+    const driver: ResourceDriver = {
+      descriptor,
+      capture: () => captureFile(this.backend, path, file.revision, file.contentType),
+      preflight: async (expected) => {
+        const current = await captureFile(this.backend, path, file.revision, file.contentType);
+        return current.sha256 === expected.sha256
+          ? { ok: true }
+          : {
+              ok: false,
+              reason: 'content-conflict',
+              actualRevision: file.revision,
+              actualSha256: current.sha256,
+            };
+      },
+      restore: async (snapshot) => {
+        const decoded = decodeFile(this.history.snapshots.read(snapshot).bytes);
+        if (decoded.exists) await this.backend.write(path, decoded.bytes);
+        else await this.backend.remove(path);
+        file.revision++;
+        for (const listener of file.listeners) listener();
+        for (const listener of this.listeners) listener(path);
+      },
+      estimateBytes: (snapshot) => snapshot.byteLength,
+    };
+    this.history.registerDriver(driver);
+    this.files.set(path, file);
+    return file;
+  }
+}
+
+export interface HistoryFileBackend {
+  readonly id: string;
+  readBytes(path: string): Promise<Uint8Array>;
+  write(path: string, data: string | Uint8Array): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  remove(path: string): Promise<void>;
+}
+
+const managers = new WeakMap<
+  HistoryService,
+  Map<string, { backend: HistoryFileBackend; manager: ProjectFileHistory }>
+>();
+
+export function getProjectFileHistory(
+  history: HistoryService,
+  backend: HistoryFileBackend = getStorageBackend(),
+  namespace = 'public',
+): ProjectFileHistory {
+  let byNamespace = managers.get(history);
+  if (!byNamespace) {
+    byNamespace = new Map();
+    managers.set(history, byNamespace);
+  }
+  const existing = byNamespace.get(namespace);
+  if (existing) {
+    if (existing.backend !== backend) {
+      throw new Error('The project storage backend changed without creating a new editor session.');
+    }
+    return existing.manager;
+  }
+  const manager = new ProjectFileHistory(history, backend);
+  byNamespace.set(namespace, { backend, manager });
+  return manager;
+}

package/src/history/project-root-history-backends.ts

@@ -0,0 +1,53 @@
+import { getEditorMode } from '../editor-mode';
+import { getStorageBackend } from '../storage';
+import type { HistoryFileBackend } from './project-file-history';
+
+class ScopedHttpHistoryBackend implements HistoryFileBackend {
+  constructor(
+    readonly id: string,
+    private readonly endpoint: string,
+  ) {}
+
+  async readBytes(path: string): Promise<Uint8Array> {
+    const response = await fetch(`${this.endpoint}?${new URLSearchParams({ path })}`);
+    if (!response.ok) throw new Error(`${this.id}.readBytes '${path}': HTTP ${response.status}`);
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  async write(path: string, data: string | Uint8Array): Promise<void> {
+    const content = typeof data === 'string' ? data : new TextDecoder().decode(data);
+    const response = await fetch(this.endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ path, content }),
+    });
+    if (!response.ok) throw new Error(`${this.id}.write '${path}': HTTP ${response.status}`);
+  }
+
+  async exists(path: string): Promise<boolean> {
+    const response = await fetch(`${this.endpoint}?${new URLSearchParams({ path })}`);
+    if (response.status === 404) return false;
+    if (!response.ok) throw new Error(`${this.id}.exists '${path}': HTTP ${response.status}`);
+    return true;
+  }
+
+  async remove(path: string): Promise<void> {
+    const response = await fetch(this.endpoint, {
+      method: 'DELETE',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ path }),
+    });
+    if (!response.ok) throw new Error(`${this.id}.remove '${path}': HTTP ${response.status}`);
+  }
+}
+
+const dataHttp = new ScopedHttpHistoryBackend('project-data-http', '/__editor/data-file');
+const manifestHttp = new ScopedHttpHistoryBackend('project-manifest-http', '/__editor/manifest');
+
+export function getDataHistoryBackend(): HistoryFileBackend {
+  return getEditorMode() === 'browser' ? getStorageBackend() : dataHttp;
+}
+
+export function getManifestHistoryBackend(): HistoryFileBackend {
+  return getEditorMode() === 'browser' ? getStorageBackend() : manifestHttp;
+}