@volter/editor-core 0.5.57

package/src/history/resource-registry.ts

@@ -0,0 +1,209 @@
+import type { ResourceDescriptor, ResourceKey, ResourceKind } from './types';
+
+export type ResourceIdFactory = () => string;
+
+function defaultIdFactory(): string {
+  return crypto.randomUUID();
+}
+
+function resourceKey(id: string): ResourceKey {
+  return `resource:${id}` as ResourceKey;
+}
+
+function basename(path: string): string {
+  return path.slice(path.lastIndexOf('/') + 1);
+}
+
+/** Normalize a StorageBackend path without importing Node path APIs into the browser. */
+export function normalizeProjectPath(input: string): string {
+  if (input.includes('\0')) throw new Error('Resource path cannot contain a NUL byte.');
+  const slashed = input.replaceAll('\\', '/');
+  if (slashed.startsWith('/') || /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(slashed)) {
+    throw new Error(`Resource path must be project-relative: "${input}".`);
+  }
+
+  const output: string[] = [];
+  for (const segment of slashed.split('/')) {
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') {
+      if (output.length === 0) {
+        throw new Error(`Resource path escapes the project root: "${input}".`);
+      }
+      output.pop();
+      continue;
+    }
+    output.push(segment);
+  }
+  if (output.length === 0) throw new Error('Resource path cannot be empty.');
+  return output.join('/');
+}
+
+function sessionSegment(input: string, label: string): string {
+  const value = input.trim();
+  if (
+    !value ||
+    value === '.' ||
+    value === '..' ||
+    value.includes('/') ||
+    value.includes('\\') ||
+    value.includes('\0')
+  ) {
+    throw new Error(`${label} must be one non-empty path segment.`);
+  }
+  return value;
+}
+
+/** Project-session registry: stable keys are independent from mutable file locations. */
+export class ResourceRegistry {
+  private readonly descriptors = new Map<ResourceKey, ResourceDescriptor>();
+  private readonly keyByLocation = new Map<string, ResourceKey>();
+  private readonly inactive = new Set<ResourceKey>();
+
+  constructor(private readonly makeId: ResourceIdFactory = defaultIdFactory) {}
+
+  registerProject(kind: ResourceKind, path: string, displayName?: string): ResourceDescriptor {
+    const normalized = normalizeProjectPath(path);
+    const location = `project://${normalized}`;
+    const existing = this.existingAt(location, kind);
+    if (existing) return existing;
+    return this.add({
+      key: resourceKey(this.makeId()),
+      kind,
+      scope: 'project',
+      displayName: displayName ?? basename(normalized),
+      location,
+      sessionId: null,
+    });
+  }
+
+  registerDraft(kind: ResourceKind, displayName: string): ResourceDescriptor {
+    const id = this.makeId();
+    return this.add({
+      key: resourceKey(id),
+      kind,
+      scope: 'project',
+      displayName,
+      location: `draft://${id}`,
+      sessionId: null,
+    });
+  }
+
+  registerSession(
+    kind: ResourceKind,
+    sessionId: string,
+    resourceId: string,
+    displayName?: string,
+  ): ResourceDescriptor {
+    const normalizedSession = sessionSegment(sessionId, 'Session id');
+    const normalizedResource = normalizeProjectPath(resourceId);
+    const location = `session://${normalizedSession}/${normalizedResource}`;
+    const existing = this.existingAt(location, kind);
+    if (existing) return existing;
+    return this.add({
+      key: resourceKey(this.makeId()),
+      kind,
+      scope: 'session',
+      displayName: displayName ?? basename(normalizedResource),
+      location,
+      sessionId: normalizedSession,
+    });
+  }
+
+  /** Promote a draft or move a project file without changing history identity. */
+  setProjectLocation(key: ResourceKey, path: string, displayName?: string): ResourceDescriptor {
+    const current = this.requireActive(key);
+    if (current.scope !== 'project')
+      throw new Error('A session resource cannot become a project file.');
+    const normalized = normalizeProjectPath(path);
+    const location = `project://${normalized}`;
+    const collision = this.keyByLocation.get(location);
+    if (collision && collision !== key) {
+      throw new Error(`Another resource is already registered at "${location}".`);
+    }
+    if (current.location) this.keyByLocation.delete(current.location);
+    const next: ResourceDescriptor = {
+      ...current,
+      displayName: displayName ?? basename(normalized),
+      location,
+    };
+    this.descriptors.set(key, next);
+    this.keyByLocation.set(location, key);
+    return next;
+  }
+
+  get(key: ResourceKey): ResourceDescriptor | null {
+    return this.descriptors.get(key) ?? null;
+  }
+
+  getByLocation(location: string): ResourceDescriptor | null {
+    const key = this.keyByLocation.get(location);
+    return key ? (this.descriptors.get(key) ?? null) : null;
+  }
+
+  isActive(key: ResourceKey): boolean {
+    return this.descriptors.has(key) && !this.inactive.has(key);
+  }
+
+  /** Keep descriptors for history display, but make their drivers unavailable. */
+  expireSession(sessionId: string): ResourceKey[] {
+    const expired: ResourceKey[] = [];
+    for (const descriptor of this.descriptors.values()) {
+      if (descriptor.sessionId !== sessionId || this.inactive.has(descriptor.key)) continue;
+      this.inactive.add(descriptor.key);
+      expired.push(descriptor.key);
+    }
+    return expired;
+  }
+
+  expireResources(resources: Iterable<ResourceKey>): ResourceKey[] {
+    const expired: ResourceKey[] = [];
+    for (const key of resources) {
+      const descriptor = this.descriptors.get(key);
+      if (!descriptor || this.inactive.has(key)) continue;
+      this.inactive.add(key);
+      if (descriptor.location && this.keyByLocation.get(descriptor.location) === key) {
+        this.keyByLocation.delete(descriptor.location);
+      }
+      expired.push(key);
+    }
+    return expired;
+  }
+
+  clear(): void {
+    this.descriptors.clear();
+    this.keyByLocation.clear();
+    this.inactive.clear();
+  }
+
+  private add(descriptor: ResourceDescriptor): ResourceDescriptor {
+    if (this.descriptors.has(descriptor.key)) {
+      throw new Error(`Duplicate resource key "${descriptor.key}".`);
+    }
+    if (descriptor.location && this.keyByLocation.has(descriptor.location)) {
+      throw new Error(`Duplicate resource location "${descriptor.location}".`);
+    }
+    this.descriptors.set(descriptor.key, descriptor);
+    if (descriptor.location) this.keyByLocation.set(descriptor.location, descriptor.key);
+    return descriptor;
+  }
+
+  private existingAt(location: string, kind: ResourceKind): ResourceDescriptor | null {
+    const key = this.keyByLocation.get(location);
+    if (!key) return null;
+    const descriptor = this.descriptors.get(key)!;
+    if (descriptor.kind !== kind) {
+      throw new Error(
+        `Resource "${location}" is already registered as ${descriptor.kind}, not ${kind}.`,
+      );
+    }
+    if (this.inactive.has(key)) throw new Error(`Resource "${location}" has expired.`);
+    return descriptor;
+  }
+
+  private requireActive(key: ResourceKey): ResourceDescriptor {
+    const descriptor = this.descriptors.get(key);
+    if (!descriptor) throw new Error(`Unknown resource key "${key}".`);
+    if (this.inactive.has(key)) throw new Error(`Resource "${key}" has expired.`);
+    return descriptor;
+  }
+}

package/src/history/snapshot-store.ts

@@ -0,0 +1,103 @@
+import { sha256Hex } from '../bytes-codec';
+import type { ResourceSnapshot, SnapshotRef } from './types';
+
+interface BlobRecord {
+  readonly bytes: Uint8Array;
+  references: number;
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.byteLength !== b.byteLength) return false;
+  for (let i = 0; i < a.byteLength; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+/** In-memory, content-addressed snapshot blobs for one open project session. */
+export class SnapshotStore {
+  private readonly blobs = new Map<string, BlobRecord>();
+  private retainedBytes = 0;
+
+  async put(snapshot: Omit<ResourceSnapshot, 'sha256'>): Promise<SnapshotRef> {
+    if (!Number.isSafeInteger(snapshot.revision) || snapshot.revision < 0) {
+      throw new Error('Snapshot revision must be a non-negative safe integer.');
+    }
+    const bytes = Uint8Array.from(snapshot.bytes);
+    const sha256 = await sha256Hex(bytes);
+    const existing = this.blobs.get(sha256);
+    if (existing) {
+      // A real SHA-256 collision is fantastically unlikely, but silently aliasing
+      // different authored bytes would make undo corrupt data.
+      if (!bytesEqual(existing.bytes, bytes)) throw new Error(`SHA-256 collision for ${sha256}.`);
+      existing.references++;
+    } else {
+      this.blobs.set(sha256, { bytes, references: 1 });
+      this.retainedBytes += bytes.byteLength;
+    }
+    return {
+      revision: snapshot.revision,
+      contentType: snapshot.contentType,
+      sha256,
+      blobKey: sha256,
+      byteLength: bytes.byteLength,
+    };
+  }
+
+  retain(ref: SnapshotRef): void {
+    const blob = this.requireBlob(ref);
+    blob.references++;
+  }
+
+  release(ref: SnapshotRef): void {
+    const blob = this.requireBlob(ref);
+    blob.references--;
+    if (blob.references === 0) {
+      this.blobs.delete(ref.blobKey);
+      this.retainedBytes -= blob.bytes.byteLength;
+    }
+  }
+
+  read(ref: SnapshotRef): ResourceSnapshot {
+    const blob = this.requireBlob(ref);
+    return {
+      revision: ref.revision,
+      contentType: ref.contentType,
+      bytes: Uint8Array.from(blob.bytes),
+      sha256: ref.sha256,
+    };
+  }
+
+  has(ref: SnapshotRef): boolean {
+    const blob = this.blobs.get(ref.blobKey);
+    return !!blob && blob.bytes.byteLength === ref.byteLength;
+  }
+
+  get uniqueBlobCount(): number {
+    return this.blobs.size;
+  }
+
+  get uniqueByteLength(): number {
+    return this.retainedBytes;
+  }
+
+  get referenceCount(): number {
+    let count = 0;
+    for (const blob of this.blobs.values()) count += blob.references;
+    return count;
+  }
+
+  clear(): void {
+    this.blobs.clear();
+    this.retainedBytes = 0;
+  }
+
+  private requireBlob(ref: SnapshotRef): BlobRecord {
+    const blob = this.blobs.get(ref.blobKey);
+    if (!blob) throw new Error(`Snapshot blob "${ref.blobKey}" is not retained.`);
+    if (ref.sha256 !== ref.blobKey || blob.bytes.byteLength !== ref.byteLength) {
+      throw new Error(`Snapshot reference "${ref.blobKey}" does not match its retained blob.`);
+    }
+    return blob;
+  }
+}