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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @aethervtt/shard-audio-editor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/dom.d.ts

@@ -0,0 +1,6 @@
+import { type AudioEditorMountOptions, type AudioEditorView } from './panels/common.js';
+export { drawAudioWaveform } from './drawing.js';
+export type { AudioEditorMountOptions, AudioEditorPanel, AudioEditorSceneSelection, AudioEditorView, } from './panels/common.js';
+export { audioEditorStyles } from './styles.js';
+/** Mount an owned, scoped view. The caller retains ownership of its session and host container. */
+export declare function mountAudioEditor(container: HTMLElement, options: AudioEditorMountOptions): AudioEditorView;

package/dist/dom.js

@@ -0,0 +1,11 @@
+import { mountPanel } from "./panels/common.js";
+import { drawAudioWaveform } from "./drawing.js";
+import { audioEditorStyles } from "./styles.js";
+function mountAudioEditor(container, options) {
+  return mountPanel(container, options);
+}
+export {
+  audioEditorStyles,
+  drawAudioWaveform,
+  mountAudioEditor
+};

package/dist/drawing.d.ts

@@ -0,0 +1,2 @@
+/** Draw a cached envelope. No decoding, timers or canvas ownership is hidden in the renderer. */
+export declare function drawAudioWaveform(context: CanvasRenderingContext2D, peaks: Float32Array, width: number, height: number, color: string): void;

package/dist/drawing.js

@@ -0,0 +1,12 @@
+function drawAudioWaveform(context, peaks, width, height, color) {
+  context.clearRect(0, 0, width, height);
+  context.fillStyle = color;
+  const scale = width / peaks.length;
+  for (let i = 0; i < peaks.length; i++) {
+    const amplitude = Math.min(1, Math.abs(peaks[i])) * height * 0.94;
+    context.fillRect(i * scale, (height - amplitude) / 2, Math.max(1, scale), amplitude);
+  }
+}
+export {
+  drawAudioWaveform
+};

package/dist/icons.d.ts

@@ -0,0 +1 @@
+export declare function audioIcon(document: Document, name: string): SVGSVGElement;

package/dist/icons.js

@@ -0,0 +1,29 @@
+const paths = {
+  library: "M3 5h6l2 2h10v12H3z M3 9h18",
+  event: "M3 12h3l2-7 4 14 3-10 2 3h4",
+  mixer: "M5 3v7m0 4v7m7-18v13m0 4v1m7-18v3m0 4v11 M2 10h6v4H2z M9 16h6v4H9z M16 6h6v4h-6z",
+  music: "M9 18V5l11-2v13 M9 8l11-2 M9 18c0 4-7 4-7 1s7-4 7-1 M20 16c0 4-7 4-7 1s7-4 7-1",
+  parameters: "M3 7h7m4 0h7M3 17h3m4 0h11 M10 4v6m4-6v6M6 14v6m4-6v6",
+  diagnostics: "M3 3v18h18 M7 15l4-5 4 3 5-8",
+  undo: "M9 5 4 10l5 5 M4 10h10a6 6 0 0 1 0 12",
+  redo: "m15 5 5 5-5 5 M20 10H10a6 6 0 0 0 0 12",
+  save: "M5 3h12l4 4v14H3V3z M7 3v6h10V3 M7 21v-8h10v8",
+  play: "m8 4 12 8-12 8z",
+  stop: "M6 6h12v12H6z",
+  clip: "M3 10v4m4-8v12m5-15v18m5-15v12m4-8v4",
+  snapshot: "M4 5h16v14H4z M8 9h8m-8 4h5"
+};
+function audioIcon(document, name) {
+  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  svg.setAttribute("viewBox", "0 0 24 24");
+  svg.setAttribute("aria-hidden", "true");
+  svg.setAttribute("focusable", "false");
+  svg.classList.add("icon");
+  const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
+  path.setAttribute("d", paths[name] ?? paths.event);
+  svg.append(path);
+  return svg;
+}
+export {
+  audioIcon
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './methods.js';
+export * from './model.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./methods.js";
+export * from "./model.js";

package/dist/memory.d.ts

@@ -0,0 +1,13 @@
+import type { AudioAssetCatalog, AudioAssetContent, AudioAssetEntry, AudioDocument, AudioDocumentStore } from './types.js';
+/** Reference adapter for static hosts. No filesystem, fetch fallback or ambient browser storage. */
+export declare function createMemoryAudioHost(options?: {
+    scope?: string;
+    documents?: readonly AudioDocument[];
+    assets?: readonly (AudioAssetEntry & {
+        content: AudioAssetContent;
+    })[];
+    readOnly?: boolean;
+}): {
+    documents: AudioDocumentStore;
+    assets: AudioAssetCatalog;
+};

package/dist/memory.js

@@ -0,0 +1,93 @@
+import { clone, editorError } from "./schema.js";
+function createMemoryAudioHost(options = {}) {
+  const scope = options.scope ?? "memory";
+  const records = new Map(options.documents?.map((doc) => [doc.id, clone(doc)]));
+  const clips = new Map(options.assets?.map((asset) => [asset.id, asset]));
+  const listeners = /* @__PURE__ */ new Set();
+  const revisionScope = crypto.randomUUID();
+  let revision = 0;
+  const documents = {
+    scope,
+    atomic: true,
+    async read(id, signal) {
+      signal?.throwIfAborted();
+      const doc = records.get(id);
+      if (!doc) throw editorError("asset-unavailable", `Document ${id} is unavailable.`);
+      return clone(doc);
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    ...options.readOnly ? {} : {
+      async commit(changes, signal) {
+        signal?.throwIfAborted();
+        const ids = /* @__PURE__ */ new Set();
+        for (const change of changes) {
+          if (ids.has(change.document.id))
+            throw editorError("conflict", "A batch repeats the same document.");
+          ids.add(change.document.id);
+          const current = records.get(change.document.id);
+          if ((current?.revision ?? null) !== change.expectedRevision)
+            throw editorError(
+              "conflict",
+              `Document ${change.document.id} changed since it was opened.`
+            );
+        }
+        const saved = changes.map((change) => ({
+          ...clone(change.document),
+          revision: `memory:${revisionScope}:${++revision}`
+        }));
+        for (const doc of saved) records.set(doc.id, doc);
+        for (const listener of listeners) listener([...ids]);
+        return clone(saved);
+      }
+    }
+  };
+  const assets = {
+    scope,
+    async list(query) {
+      query.signal?.throwIfAborted();
+      const all = [...records.values()].map(({ id, name, type, revision: revision2 }) => ({
+        id,
+        name,
+        type,
+        revision: revision2
+      }));
+      for (const { content: _, ...entry } of clips.values()) all.push(entry);
+      const filtered = all.filter(
+        (entry) => (!query.type || entry.type === query.type) && (!query.search || entry.name.toLowerCase().includes(query.search.toLowerCase()))
+      );
+      const offset = Math.max(0, Number(query.cursor) || 0);
+      const limit = Math.max(1, Math.min(100, query.limit ?? 50));
+      return {
+        items: clone(filtered.slice(offset, offset + limit)),
+        total: filtered.length,
+        nextCursor: offset + limit < filtered.length ? String(offset + limit) : void 0
+      };
+    },
+    async get(id, signal) {
+      signal?.throwIfAborted();
+      const clip = clips.get(id);
+      if (clip) {
+        const { content: _, ...entry } = clip;
+        return clone(entry);
+      }
+      const doc = await documents.read(id, signal);
+      return { id: doc.id, name: doc.name, type: doc.type, revision: doc.revision };
+    },
+    async resolve(id, signal) {
+      signal?.throwIfAborted();
+      const entry = clips.get(id);
+      if (!entry) throw editorError("asset-unavailable", `Audio asset ${id} is unavailable.`);
+      return { ...entry.content, bytes: entry.content.bytes?.slice() };
+    },
+    subscribe: documents.subscribe
+  };
+  return { documents, assets };
+}
+export {
+  createMemoryAudioHost
+};

package/dist/methods.d.ts

@@ -0,0 +1,4 @@
+import type { AppMethod } from '@aethervtt/shard-runtime';
+import type { AudioEditorSession } from './model.js';
+/** Explicit registration only. The host grants protocol access to this editor session. */
+export declare function audioEditorMethods(session: AudioEditorSession): AppMethod[];

package/dist/methods.js

@@ -0,0 +1,79 @@
+import { defineSchema, t } from "@aethervtt/shard-core";
+function audioEditorMethods(session) {
+  const empty = defineSchema("audio-editor/Empty", {});
+  return [
+    {
+      name: "audio.editor.describe",
+      description: "Inspect audio document revision, draft and diagnostics.",
+      params: empty,
+      handler: () => {
+        const { schema, diagnostics, ...state } = session.state;
+        return {
+          ...state,
+          schema: schema?.jsonSchema(),
+          diagnostics: diagnostics.map((e) => ({
+            code: e.code,
+            message: e.message,
+            path: e.path,
+            hint: e.hint
+          }))
+        };
+      }
+    },
+    {
+      name: "audio.editor.edit",
+      description: "Edit one schema-backed audio document field.",
+      params: defineSchema("audio-editor/Edit", {
+        path: t.string({ required: true }),
+        value: t.json(),
+        remove: t.bool()
+      }),
+      handler: (_, p) => {
+        session.edit({
+          path: p.path,
+          value: p.value,
+          remove: p.remove
+        });
+        return { updated: true };
+      }
+    },
+    {
+      name: "audio.editor.validate",
+      description: "Validate the draft against the runtime schema and host asset catalog.",
+      params: empty,
+      handler: async () => (await session.validate()).map((e) => ({
+        code: e.code,
+        message: e.message,
+        path: e.path,
+        hint: e.hint
+      }))
+    },
+    {
+      name: "audio.editor.undo",
+      description: "Undo one authored document transaction.",
+      params: empty,
+      handler: () => {
+        session.undo();
+        return { updated: true };
+      }
+    },
+    {
+      name: "audio.editor.redo",
+      description: "Redo one authored document transaction.",
+      params: empty,
+      handler: () => {
+        session.redo();
+        return { updated: true };
+      }
+    },
+    {
+      name: "audio.editor.commit",
+      description: "Validate and save the draft through the host revision boundary.",
+      params: empty,
+      handler: () => session.save()
+    }
+  ];
+}
+export {
+  audioEditorMethods
+};

package/dist/model.d.ts

@@ -0,0 +1,61 @@
+import type { JsonObject, ShardError } from '@aethervtt/shard-core';
+import type { AudioDocument, AudioDocumentChange, AudioEditorEdit, AudioEditorOptions, AudioEditorState } from './types.js';
+export * from './memory.js';
+export * from './schema.js';
+export * from './types.js';
+/** Editor work is event-driven; allocating history and view snapshots does not enter engine frames. */
+export declare class AudioEditorSession {
+    readonly documents: AudioEditorOptions['documents'];
+    readonly assets: AudioEditorOptions['assets'];
+    readonly preview: AudioEditorOptions['preview'];
+    private current;
+    private baseline?;
+    private listeners;
+    private history;
+    private future;
+    private transaction?;
+    private readonly limit;
+    private readonly byteLimit;
+    private disposed;
+    private generation;
+    private validationGeneration;
+    private validationAbort?;
+    private readAbort?;
+    private previewAbort?;
+    private unsubscribe?;
+    private unsubscribeAssets?;
+    constructor(options: AudioEditorOptions);
+    get state(): AudioEditorState;
+    subscribe(listener: (state: AudioEditorState) => void): () => void;
+    private alive;
+    private editable;
+    private emit;
+    private adopt;
+    open(id: string): Promise<void>;
+    create(document: AudioDocument): Promise<void>;
+    createNew(type: string, name: string, id?: `${string}-${string}-${string}-${string}-${string}`): Promise<void>;
+    duplicate(name: string, id?: `${string}-${string}-${string}-${string}-${string}`): Promise<void>;
+    edit(edit: AudioEditorEdit): void;
+    replace(value: JsonObject): void;
+    beginTransaction(_label?: string): void;
+    endTransaction(): void;
+    commitTransaction(): void;
+    cancelTransaction(): void;
+    private record;
+    undo(): void;
+    redo(): void;
+    private refresh;
+    validate(): Promise<ShardError[]>;
+    save(): Promise<AudioDocument | undefined>;
+    saveAs(id: string, name: string): Promise<void>;
+    reload(): Promise<void>;
+    private remoteChanged;
+    /** Batch edits have an explicit adapter capability and one compare-and-swap boundary. */
+    commitDocuments(changes: readonly AudioDocumentChange[]): Promise<AudioDocument[]>;
+    /** Explicit dependent IDs avoid renaming an unrelated parameter with the same display name. */
+    renameParameter(from: string, to: string, dependentIds?: readonly string[]): Promise<void>;
+    play(): Promise<unknown>;
+    stop(): Promise<void>;
+    dispose(): Promise<void>;
+}
+export declare function createAudioEditorSession(options: AudioEditorOptions): AudioEditorSession;