@aethervtt/shard-audio-editor 0.0.0-stage → 0.2.1

package/dist/model.js

@@ -0,0 +1,560 @@
+import {
+  asEditorError,
+  clone,
+  editorError,
+  equal,
+  getAudioEditorSchema,
+  knownFields,
+  merge,
+  validateAudioDocument
+} from "./schema.js";
+export * from "./memory.js";
+export * from "./schema.js";
+export * from "./types.js";
+function segments(path) {
+  if (!path.startsWith("/") || path === "/")
+    throw editorError("invalid-document", "Use a JSON pointer to a document field.", path);
+  const parts = path.slice(1).split("/").map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"));
+  if (parts.some((part) => part === "__proto__" || part === "constructor" || part === "prototype"))
+    throw editorError("invalid-document", "Unsafe document field.", path);
+  return parts;
+}
+class AudioEditorSession {
+  documents;
+  assets;
+  preview;
+  current = {
+    dirty: false,
+    readOnly: false,
+    loading: false,
+    saving: false,
+    diagnostics: [],
+    canUndo: false,
+    canRedo: false,
+    historyEvicted: 0,
+    previewState: "idle"
+  };
+  baseline;
+  listeners = /* @__PURE__ */ new Set();
+  history = [];
+  future = [];
+  transaction;
+  limit;
+  byteLimit;
+  disposed = false;
+  generation = 0;
+  validationGeneration = 0;
+  validationAbort;
+  readAbort;
+  previewAbort;
+  unsubscribe;
+  unsubscribeAssets;
+  constructor(options) {
+    this.documents = options.documents;
+    this.assets = options.assets;
+    this.preview = options.preview;
+    this.limit = Math.max(1, options.historyLimit ?? 200);
+    this.byteLimit = Math.max(1, options.historyBytes ?? 16 * 1024 * 1024);
+    this.unsubscribe = this.documents.subscribe?.((ids) => {
+      if (this.disposed || this.current.saving) return;
+      if (this.current.document && ids.includes(this.current.document.id)) void this.remoteChanged();
+      else void this.refresh();
+    });
+    this.unsubscribeAssets = this.assets.subscribe?.(() => {
+      if (!this.disposed) void this.refresh();
+    });
+  }
+  get state() {
+    return {
+      ...this.current,
+      document: this.current.document && clone(this.current.document),
+      effective: this.current.effective && clone(this.current.effective),
+      conflict: this.current.conflict && clone(this.current.conflict),
+      diagnostics: [...this.current.diagnostics]
+    };
+  }
+  subscribe(listener) {
+    this.alive();
+    this.listeners.add(listener);
+    listener(this.state);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  alive() {
+    if (this.disposed) throw editorError("disposed", "This editor session has been disposed.");
+  }
+  editable() {
+    this.alive();
+    if (this.current.readOnly) throw editorError("read-only", "This document is read-only.");
+    if (!this.current.document) throw editorError("invalid-document", "Open a document first.");
+    return this.current.document;
+  }
+  emit() {
+    if (this.disposed) return;
+    this.current.canUndo = this.history.length > 0;
+    this.current.canRedo = this.future.length > 0;
+    this.current.dirty = !!this.current.document && (!this.baseline?.revision || !equal(this.current.document.value, this.baseline.value));
+    for (const listener of this.listeners) listener(this.state);
+  }
+  adopt(document) {
+    const schema = getAudioEditorSchema(document.type);
+    this.baseline = clone(document);
+    this.current = {
+      ...this.current,
+      document: clone(document),
+      schema,
+      effective: void 0,
+      conflict: void 0,
+      loading: false,
+      diagnostics: [],
+      historyEvicted: 0,
+      readOnly: !this.documents.commit || !schema || (document.schemaVersion ?? 1) > schema.version
+    };
+    this.history = [];
+    this.future = [];
+    this.transaction = void 0;
+  }
+  async open(id) {
+    this.alive();
+    if (this.current.saving) throw editorError("conflict", "Wait for the current save to finish.");
+    if (this.current.dirty && this.current.document?.id !== id)
+      throw editorError(
+        "conflict",
+        "Save or discard the current draft before opening another document."
+      );
+    if (this.current.dirty && this.current.document?.id === id) return;
+    this.readAbort?.abort();
+    const controller = new AbortController();
+    this.readAbort = controller;
+    const generation = ++this.generation;
+    this.current.loading = true;
+    this.emit();
+    try {
+      const document = await this.documents.read(id, controller.signal);
+      if (this.disposed || generation !== this.generation) return;
+      if (document.id !== id)
+        throw editorError("invalid-document", "The host returned a different document ID.");
+      this.adopt(document);
+      await this.refresh();
+    } catch (error) {
+      if (this.disposed || generation !== this.generation) return;
+      this.current.loading = false;
+      this.current.diagnostics = [asEditorError(error)];
+      this.emit();
+      throw error;
+    }
+  }
+  async create(document) {
+    this.alive();
+    if (this.current.dirty || this.current.saving)
+      throw editorError("conflict", "Save or discard the current draft first.");
+    if (!this.documents.commit)
+      throw editorError("read-only", "The host does not support creating documents.");
+    ++this.generation;
+    this.readAbort?.abort();
+    this.adopt({ ...document, revision: "" });
+    await this.refresh();
+  }
+  async createNew(type, name, id = crypto.randomUUID()) {
+    const schema = getAudioEditorSchema(type);
+    if (!schema) throw editorError("unsupported-schema", `Unknown audio schema ${type}.`);
+    await this.create({
+      id,
+      name,
+      type,
+      revision: "",
+      schemaVersion: schema.version,
+      value: schema.serialize(schema.defaults())
+    });
+  }
+  async duplicate(name, id = crypto.randomUUID()) {
+    await this.saveAs(id, name);
+  }
+  edit(edit) {
+    const doc = this.editable();
+    const parts = segments(edit.path);
+    const before = clone(doc.value);
+    const next = clone(doc.value);
+    const top = parts[0];
+    if (parts.length > 1 && next[top] === void 0 && this.current.effective?.[top] !== void 0)
+      next[top] = clone(this.current.effective[top]);
+    let parent = next;
+    for (let i = 0; i < parts.length - 1; i++) {
+      let key2 = parts[i];
+      if (Array.isArray(parent)) {
+        const index = key2 === "-" ? parent.length : Number(key2);
+        if (!Number.isInteger(index) || index < 0 || index > parent.length)
+          throw editorError("invalid-document", "Invalid array index.", edit.path);
+        key2 = String(index);
+      }
+      let child = parent[key2];
+      if (!child || typeof child !== "object") {
+        child = {};
+        parent[key2] = child;
+      }
+      parent = child;
+    }
+    const key = parts.at(-1);
+    if (Array.isArray(parent)) {
+      const index = key === "-" ? parent.length : Number(key);
+      if (!Number.isInteger(index) || index < 0 || index > parent.length)
+        throw editorError("invalid-document", "Invalid array index.", edit.path);
+      if (edit.remove) parent.splice(index, 1);
+      else if (edit.value !== void 0) parent[index] = clone(edit.value);
+    } else if (edit.remove) delete parent[key];
+    else if (edit.value !== void 0) parent[key] = clone(edit.value);
+    doc.value = next;
+    if (!this.transaction) this.record(before, doc.value);
+    this.current.effective = merge(this.current.effective ?? {}, doc.value);
+    this.emit();
+    void this.refresh();
+  }
+  replace(value) {
+    const doc = this.editable();
+    const before = clone(doc.value);
+    doc.value = clone(value);
+    if (!this.transaction) this.record(before, doc.value);
+    this.emit();
+    void this.refresh();
+  }
+  beginTransaction(_label) {
+    const doc = this.editable();
+    if (this.transaction)
+      throw editorError("conflict", "Finish the current edit transaction first.");
+    this.transaction = clone(doc.value);
+  }
+  endTransaction() {
+    const doc = this.editable();
+    if (!this.transaction) return;
+    this.record(this.transaction, doc.value);
+    this.transaction = void 0;
+    this.emit();
+  }
+  commitTransaction() {
+    this.endTransaction();
+  }
+  cancelTransaction() {
+    const doc = this.editable();
+    if (!this.transaction) return;
+    doc.value = this.transaction;
+    this.transaction = void 0;
+    this.emit();
+    void this.refresh();
+  }
+  record(before, after) {
+    if (equal(before, after)) return;
+    const entry = {
+      before: clone(before),
+      after: clone(after),
+      bytes: 2 * (JSON.stringify(before).length + JSON.stringify(after).length)
+    };
+    this.history.push(entry);
+    this.future = [];
+    let bytes = this.history.reduce((total, item) => total + item.bytes, 0);
+    while (this.history.length > this.limit || bytes > this.byteLimit) {
+      bytes -= this.history.shift().bytes;
+      this.current.historyEvicted++;
+    }
+  }
+  undo() {
+    const doc = this.editable();
+    if (this.transaction) this.cancelTransaction();
+    const entry = this.history.pop();
+    if (!entry) return;
+    this.future.push(entry);
+    doc.value = clone(entry.before);
+    this.emit();
+    void this.refresh();
+  }
+  redo() {
+    const doc = this.editable();
+    const entry = this.future.pop();
+    if (!entry) return;
+    this.history.push(entry);
+    doc.value = clone(entry.after);
+    this.emit();
+    void this.refresh();
+  }
+  async refresh() {
+    const document = this.current.document;
+    if (!document || this.disposed) {
+      this.emit();
+      return;
+    }
+    const sequence = ++this.validationGeneration;
+    this.validationAbort?.abort();
+    this.validationAbort = new AbortController();
+    const result = await validateAudioDocument(
+      clone(document),
+      this.documents,
+      this.assets,
+      this.validationAbort.signal
+    );
+    if (this.disposed || sequence !== this.validationGeneration || document.id !== this.current.document?.id)
+      return;
+    this.current.diagnostics = result.errors;
+    this.current.effective = result.effective?.value ?? clone(document.value);
+    this.emit();
+  }
+  async validate() {
+    this.alive();
+    await this.refresh();
+    return [...this.current.diagnostics];
+  }
+  async save() {
+    const doc = this.editable();
+    if (this.current.saving) throw editorError("conflict", "A save is already in progress.");
+    if (this.transaction) this.endTransaction();
+    if (!this.current.dirty) return clone(doc);
+    if (this.current.conflict)
+      throw editorError("conflict", "Resolve the external edit before saving.");
+    const snapshot = clone(doc);
+    this.current.saving = true;
+    this.emit();
+    try {
+      const result = await validateAudioDocument(snapshot, this.documents, this.assets);
+      if (result.errors.length) throw result.errors[0];
+      const saved = await this.documents.commit([
+        { document: snapshot, expectedRevision: this.baseline?.revision || null }
+      ]);
+      const confirmed = saved.find((item) => item.id === doc.id);
+      if (!confirmed?.revision)
+        throw editorError("invalid-document", "The host did not acknowledge the saved revision.");
+      if (this.disposed) return clone(confirmed);
+      this.baseline = clone(confirmed);
+      doc.revision = confirmed.revision;
+      doc.sourceText = confirmed.sourceText;
+      if (equal(doc.value, snapshot.value)) doc.value = clone(confirmed.value);
+      return clone(confirmed);
+    } catch (error) {
+      if (!this.disposed) this.current.diagnostics = [asEditorError(error)];
+      throw error;
+    } finally {
+      this.current.saving = false;
+      this.emit();
+    }
+  }
+  async saveAs(id, name) {
+    const current = this.editable();
+    if (this.current.saving) throw editorError("conflict", "Wait for the pending save.");
+    if (id === current.id)
+      throw editorError("conflict", "Save as needs a different host document ID.");
+    const document = { ...clone(current), id, name, revision: "" };
+    delete document.sourceText;
+    this.current.saving = true;
+    this.emit();
+    try {
+      const result = await validateAudioDocument(document, this.documents, this.assets);
+      if (result.errors.length) throw result.errors[0];
+      const saved = await this.documents.commit([{ document, expectedRevision: null }]);
+      this.alive();
+      const created = saved.find((item) => item.id === id);
+      if (!created?.revision)
+        throw editorError("invalid-document", "The host did not acknowledge the created document.");
+      const pending = equal(current.value, document.value) ? void 0 : clone(current.value);
+      this.adopt(created);
+      if (pending) this.current.document.value = pending;
+      await this.refresh();
+    } finally {
+      this.current.saving = false;
+      this.emit();
+    }
+  }
+  async reload() {
+    this.alive();
+    if (this.current.saving) throw editorError("conflict", "Wait for the pending save.");
+    const id = this.current.document?.id;
+    if (!id) return;
+    const doc = await this.documents.read(id);
+    this.alive();
+    if (this.current.document?.id !== id) return;
+    this.adopt(doc);
+    await this.refresh();
+  }
+  async remoteChanged() {
+    const id = this.current.document?.id;
+    if (!id) return;
+    try {
+      const remote = await this.documents.read(id);
+      if (this.disposed || this.current.document?.id !== id || remote.revision === this.baseline?.revision)
+        return;
+      if (this.current.dirty) this.current.conflict = clone(remote);
+      else this.adopt(remote);
+      await this.refresh();
+    } catch (error) {
+      if (!this.disposed) {
+        this.current.diagnostics = [asEditorError(error)];
+        this.emit();
+      }
+    }
+  }
+  /** Batch edits have an explicit adapter capability and one compare-and-swap boundary. */
+  async commitDocuments(changes) {
+    this.alive();
+    if (!this.documents.commit || changes.length > 1 && !this.documents.atomic)
+      throw editorError(
+        "unsupported-capability",
+        "The host cannot commit this atomic document batch."
+      );
+    const overlay = new Map(changes.map((change) => [change.document.id, change.document]));
+    const documents = {
+      ...this.documents,
+      read: async (id, signal) => clone(overlay.get(id) ?? await this.documents.read(id, signal))
+    };
+    for (const change of changes) {
+      const validation = await validateAudioDocument(change.document, documents, this.assets);
+      if (validation.errors.length) throw validation.errors[0];
+    }
+    return this.documents.commit(changes);
+  }
+  /** Explicit dependent IDs avoid renaming an unrelated parameter with the same display name. */
+  async renameParameter(from, to, dependentIds = []) {
+    const current = this.editable();
+    if (this.current.dirty || this.current.saving)
+      throw editorError("conflict", "Save the current draft before a parameter rename.");
+    if (!to || from === to)
+      throw editorError("invalid-document", "Choose a different nonempty parameter name.");
+    const global = current.type === "audio/AudioParameters";
+    if (dependentIds.length && !global)
+      throw editorError(
+        "invalid-document",
+        "Local parameter renames cannot change other documents."
+      );
+    const ids = [.../* @__PURE__ */ new Set([current.id, ...dependentIds])];
+    if (ids.length > 1 && !this.documents.atomic)
+      throw editorError(
+        "unsupported-capability",
+        "This host does not support atomic reference renames."
+      );
+    const changes = [];
+    for (const id of ids) {
+      const source = await this.documents.read(id);
+      const next = clone(source);
+      if (id !== current.id) {
+        const globals = next.value.globals;
+        if ((globals?.guid ?? globals?.path) !== current.id)
+          throw editorError(
+            "invalid-document",
+            `Document ${id} does not reference this parameter bank.`
+          );
+        const locals = next.value.parameters;
+        if (Array.isArray(locals) && locals.some(
+          (p) => typeof p === "object" && p !== null && !Array.isArray(p) && p.name === from
+        ))
+          throw editorError(
+            "conflict",
+            `Document ${id} shadows this global parameter with a local name.`
+          );
+      } else {
+        const definitions = next.value.parameters;
+        if (!Array.isArray(definitions))
+          throw editorError("invalid-document", "This document has no authored parameters.");
+        let found = false;
+        for (const entry of definitions) {
+          if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+          if (entry.name === to)
+            throw editorError("conflict", "That parameter name already exists.");
+          if (entry.name === from) {
+            entry.name = to;
+            found = true;
+          }
+        }
+        if (!found)
+          throw editorError(
+            "invalid-document",
+            "Parameter is inherited or does not exist; rename it in its defining document."
+          );
+      }
+      const update = (value, known) => {
+        if (Array.isArray(value) && Array.isArray(known)) {
+          value.forEach((item, index) => {
+            update(item, known[index] ?? null);
+          });
+          return;
+        }
+        if (!value || typeof value !== "object" || Array.isArray(value) || !known || typeof known !== "object")
+          return;
+        for (const key of Object.keys(known)) {
+          if ((key === "parameter" || key === "selectParameter") && value[key] === from)
+            value[key] = to;
+          else update(value[key], known[key]);
+        }
+      };
+      const schema = getAudioEditorSchema(next.type);
+      if (!schema)
+        throw editorError("unsupported-schema", `Unsupported document schema ${next.type}.`);
+      update(next.value, knownFields(schema.fields, next.value));
+      changes.push({ document: next, expectedRevision: source.revision });
+    }
+    await this.commitDocuments(changes);
+    await this.reload();
+  }
+  async play() {
+    this.alive();
+    if (!this.preview)
+      throw editorError("unsupported-capability", "This host does not provide audio preview.");
+    if (!this.current.document)
+      throw editorError("invalid-document", "Open a document to audition.");
+    const document = clone(this.current.document);
+    this.previewAbort?.abort();
+    const controller = new AbortController();
+    this.previewAbort = controller;
+    this.current.previewState = "preparing";
+    this.emit();
+    try {
+      const result = await this.preview.play(document, controller.signal);
+      if (!this.disposed && !controller.signal.aborted) {
+        this.current.previewState = "playing";
+        this.current.previewResult = result;
+        this.current.previewDocumentId = document.id;
+        this.emit();
+      }
+      return result;
+    } catch (error) {
+      if (!this.disposed && !controller.signal.aborted) {
+        this.current.previewState = "failed";
+        this.current.diagnostics = [asEditorError(error)];
+        this.emit();
+      }
+      throw error;
+    }
+  }
+  async stop() {
+    this.previewAbort?.abort();
+    await this.preview?.stop();
+    this.current.previewState = "idle";
+    this.current.previewResult = void 0;
+    this.current.previewDocumentId = void 0;
+    this.emit();
+  }
+  async dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    ++this.generation;
+    ++this.validationGeneration;
+    this.readAbort?.abort();
+    this.validationAbort?.abort();
+    this.previewAbort?.abort();
+    this.unsubscribe?.();
+    this.unsubscribeAssets?.();
+    this.listeners.clear();
+    this.history = [];
+    this.future = [];
+    this.transaction = void 0;
+    this.baseline = void 0;
+    this.current.document = void 0;
+    this.current.effective = void 0;
+    this.current.conflict = void 0;
+    this.current.previewResult = void 0;
+    this.current.previewDocumentId = void 0;
+    await this.preview?.dispose();
+  }
+}
+function createAudioEditorSession(options) {
+  return new AudioEditorSession(options);
+}
+export {
+  AudioEditorSession,
+  createAudioEditorSession
+};

package/dist/panels/common.d.ts

@@ -0,0 +1,33 @@
+import { type ComponentDef, type JsonObject, type JsonValue } from '@aethervtt/shard-core';
+import type { AudioEditorSession } from '../model.js';
+export type AudioEditorPanel = 'library' | 'event' | 'mixer' | 'music' | 'parameters' | 'diagnostics';
+export interface AudioEditorMountOptions {
+    session: AudioEditorSession;
+    theme?: 'dark' | 'light';
+    layout?: 'full' | 'compact';
+    /** A host-served copy of audioEditorStyles, for CSPs forbidding inline style elements. */
+    stylesheetUrl?: string;
+    strings?: Readonly<Record<string, string>>;
+    scene?: AudioEditorSceneSelection;
+}
+/** Optional scene component selection. The host owns its history and persistence. */
+export interface AudioEditorSceneSelection {
+    schema: ComponentDef;
+    value: JsonObject;
+    readOnly?: boolean;
+    edit(change: {
+        path: string;
+        value?: JsonValue;
+        remove?: boolean;
+    }): void;
+}
+export interface AudioEditorView {
+    readonly element: HTMLElement;
+    readonly root: ShadowRoot;
+    setTheme(theme: 'dark' | 'light'): void;
+    /** Rerender after the host updates its optional scene selection. */
+    refresh(): void;
+    dispose(): void;
+}
+/** All panels share this command-driven renderer; mount never starts audio. */
+export declare function mountPanel(container: HTMLElement, options: AudioEditorMountOptions, fixedPanel?: AudioEditorPanel): AudioEditorView;