@aethervtt/shard-platform 0.0.1 → 0.2.0

package/dist/audio-runtime.d.ts

@@ -0,0 +1,142 @@
+import type { AudioClipSource, AudioVoiceDesc, AudioVoiceParams } from './index.js';
+/** Optional, host-neutral extensions. Legacy AudioBackend implementations remain valid. */
+export interface AudioCapabilities {
+    scheduled: boolean;
+    automation: boolean;
+    mixer: boolean;
+    media: boolean;
+    meters: boolean;
+    offline: boolean;
+    sessions: boolean;
+}
+export interface AudioClock {
+    /** Seconds on the rendering clock, frozen while the context is suspended. */
+    now(): number;
+    /** Monotonic expiry clock, including suspension. Falls back to frame time in legacy hosts. */
+    wallNow?(): number;
+    /** Independent of rendering frames. Returns an idempotent unsubscribe. */
+    wake(callback: () => void, intervalSeconds: number): () => void;
+}
+export interface AudioPreparation {
+    readonly clip: AudioClipSource;
+    readonly decodedBytes: number;
+    readonly encodedBytes: number;
+    readonly sampleRate: number;
+    readonly samples: number;
+    readonly channels: number;
+    readonly released: boolean;
+    release(): void;
+}
+export interface AudioMemory {
+    /** Additional bounded finite-effect kernels, separate from decoded asset PCM. */
+    effectBytes: number;
+    encodedBytes: number;
+    decodedBytes: number;
+    budgetBytes: number;
+    loading: number;
+    pinned: number;
+    evictable: number;
+    voices: number;
+    nodes: number;
+    urls: number;
+}
+export type AudioPresentationState = 'preparing' | 'blocked' | 'scheduled' | 'rendering' | 'stopping' | 'ended' | 'failed';
+export interface AudioPresentation {
+    state: AudioPresentationState;
+    scheduledAt: number;
+    endedAt: number;
+    error: string | null;
+}
+export interface AudioScheduledVoice extends AudioVoiceDesc {
+    /** Absolute rendering-clock time. Omitted means immediate, preserving the old API. */
+    when?: number;
+    /** Duration in output seconds, not clip seconds. */
+    duration?: number;
+    lowpass?: number;
+    highpass?: number;
+}
+export type AudioAutomationProperty = 'gain' | 'envelope' | 'pitch' | 'lowpass' | 'highpass';
+export interface AudioAutomation {
+    property: AudioAutomationProperty;
+    at: number;
+    value: number;
+    duration: number;
+    curve?: 'linear' | 'exponential' | 'equal-power-in' | 'equal-power-out';
+}
+export interface AudioSessionOptions {
+    maxVoices?: number;
+    decodedBudgetBytes?: number;
+    maxDecodes?: number;
+    priority?: number;
+}
+export interface AudioEffectDesc {
+    id: string;
+    kind: 'lowpass' | 'highpass' | 'peaking' | 'compressor' | 'delay' | 'reverb';
+    frequency: number;
+    q: number;
+    gainDb: number;
+    threshold: number;
+    ratio: number;
+    attack: number;
+    release: number;
+    seconds: number;
+    feedback: number;
+    tailSeconds: number;
+    ir?: AudioClipSource;
+}
+export interface AudioSendDesc {
+    target: string;
+    gain: number;
+    pre: boolean;
+}
+export interface AudioBusDesc {
+    id: string;
+    parent: string;
+    gain: number;
+    userGain: number;
+    effects: readonly AudioEffectDesc[];
+    sends: readonly AudioSendDesc[];
+    return: boolean;
+}
+export interface AudioMixerGraph {
+    buses: readonly AudioBusDesc[];
+    maxNodes: number;
+}
+export interface AudioMeter {
+    available: boolean;
+    peak: number;
+    rms: number;
+    samples: number;
+    sampleRate: number;
+    at: number;
+}
+export interface AudioRuntimeExtension {
+    readonly capabilities: Readonly<AudioCapabilities>;
+    readonly clock: AudioClock;
+    readonly activeVoices: number;
+    setDecodedBudget(bytes: number): void;
+    /** Reserve a synchronous batch before starting any stem; release unused slots in finally. */
+    reserveVoices(count: number): () => void;
+    prepare(clip: AudioClipSource): Promise<AudioPreparation>;
+    /** Reclaims unpinned cache entries. Active voices retain their own pins. */
+    collect(): void;
+    memory(): AudioMemory;
+    play(desc: AudioScheduledVoice): number;
+    /** Waits until all requested source starts have been prepared and submitted, or rejects on failure. */
+    flush(): Promise<void>;
+    presentation(id: number): Readonly<AudioPresentation> | undefined;
+    /** In-place route/loop/spatial edits; false asks the caller to recreate at the current phase. */
+    reconfigure(id: number, desc: AudioVoiceDesc): boolean;
+    automate(id: number, command: AudioAutomation): void;
+    setVoiceSend(id: number, target: string, gain: number, rampSeconds: number): void;
+    /** Cancels a scheduled start; stops an already audible voice, with a truthful result. */
+    cancel(id: number): 'cancelled' | 'already-started' | 'ended';
+    configureMixer(graph: AudioMixerGraph): Promise<void>;
+    setMixerValue(bus: string, field: string, value: number, rampSeconds: number): void;
+    meter(bus: string): AudioMeter;
+    /** Headless clocks are explicitly advanced; live clocks ignore this. */
+    advance?(seconds: number): void;
+    update(id: number, params: AudioVoiceParams): void;
+}
+/** Shared host validation, also used by the headless scheduling model. */
+export declare function validateAudioAutomation(command: AudioAutomation): void;

package/dist/audio-runtime.js

@@ -0,0 +1,16 @@
+import { ShardError } from "@aethervtt/shard-core";
+function validateAudioAutomation(command) {
+  if (!Number.isFinite(command.at) || command.at < 0 || !Number.isFinite(command.duration) || command.duration < 0 || !Number.isFinite(command.value) || command.value < 0 || (command.property === "pitch" || command.property === "lowpass") && command.value === 0)
+    throw new ShardError(
+      "audio/invalid-range",
+      "Automation requires finite nonnegative times and values, and positive pitch/cutoff",
+      { path: "/automation" }
+    );
+  if (command.property !== "gain" && command.property !== "envelope" && command.property !== "pitch" && command.property !== "lowpass" && command.property !== "highpass")
+    throw new ShardError("audio/invalid-range", "Unknown automation property", {
+      path: "/automation/property"
+    });
+}
+export {
+  validateAudioAutomation
+};

package/dist/index.d.ts

@@ -1,5 +1,8 @@
-import type { ShardError } from '@aethervtt/shard-core';
+import type { HeapStats, HotFunction, ShardError } from '@aethervtt/shard-core';
+import type { AudioRuntimeExtension, AudioSessionOptions } from './audio-runtime.js';
 import type { Workers } from './workers.js';
+export type * from './audio-runtime.js';
+export { validateAudioAutomation } from './audio-runtime.js';
 /**
  * Everything the engine needs from its host. The engine only talks to this interface;
  * hosts (browser, Tauri, headless) provide an implementation at startup.
@@ -17,6 +20,60 @@ export interface Platform {
      * first use. Absent on hosts without threads; `workersOf` falls back to running jobs inline.
      */
     readonly workers?: Workers;
+    /** The host's own performance instruments (long tasks, downloads), for 0062's metrics. */
+    readonly performance?: HostPerformance;
+}
+/**
+ * What the host itself can measure about a page or process (0062). Browsers report long tasks and
+ * resource timing; Node and Tauri report what they can, and leave out what they can't.
+ */
+export interface HostPerformance {
+    /** The user agent, or the runtime's name and version. */
+    readonly userAgent: string;
+    /**
+     * Main-thread tasks of 50 ms or more, as the host reports them: start (on the `clock`'s timeline)
+     * and duration, in ms. Returns an unsubscribe function. Absent where the host can't see them.
+     */
+    onLongTask?(listener: (startMs: number, durationMs: number) => void): () => void;
+    /** Bytes fetched so far (scripts, WASM, assets), over the wire and decoded. Absent without resource timing. */
+    downloads?(): HostDownloads;
+    /**
+     * The JS heap (0074): `v8.getHeapStatistics()` in Node; in a page,
+     * `performance.measureUserAgentSpecificMemory()` when isolated (at most every 5 s, so the last
+     * result), else `performance.memory` where it exists. Absent or undefined elsewhere.
+     */
+    heap?(): HeapStats | undefined;
+    /** Garbage collections (Node): start on `performance.now()`'s timeline, pause, and kind. */
+    onGc?(listener: (start: number, ms: number, kind: string) => void): () => void;
+    /**
+     * Starts sampling JavaScript (0074): `node:inspector`'s profiler in Node, the JS Self-Profiling
+     * API in pages served with `Document-Policy: js-profiling`. Undefined where it can't.
+     */
+    startSampler?(): Promise<HostSampler | undefined>;
+    /** Shows a span in the browser's own profiler (`performance.measure` with DevTools track data). */
+    measure?(name: string, track: string, start: number, ms: number): void;
+}
+/** A sampling profiler running for a capture's window. */
+export interface HostSampler {
+    stop(): Promise<HostSamples>;
+}
+export interface HostSamples {
+    /** The functions with the most self time. */
+    hottest: HotFunction[];
+    /** Stretches of the same top function on `performance.now()`'s timeline (browsers). */
+    samples?: {
+        name: string;
+        start: number;
+        ms: number;
+    }[];
+    /** The V8 `.cpuprofile` (Node). */
+    cpuprofile?: unknown;
+}
+export interface HostDownloads {
+    /** Bytes over the wire, headers included. Cached responses add nothing. */
+    transferred: number;
+    /** Bytes after decoding (decompression). */
+    decoded: number;
 }
 export * from './workers.js';
 export type MouseButton = 'left' | 'middle' | 'right' | 'back' | 'forward';
@@ -39,10 +96,35 @@ export type RawInputEvent = {
     y: number;
     dx: number;
     dy: number;
-} | {
+}
+/**
+ * Wheel movement in pixels (line and page deltas already converted). `x`/`y` (CSS pixels, from
+ * the element's top left) and `modifiers` come from sources that know them; a ctrl wheel is a
+ * trackpad pinch.
+ */
+ | {
     type: 'wheel';
     dx: number;
     dy: number;
+    x?: number;
+    y?: number;
+    modifiers?: number;
+}
+/**
+ * One pointer (0060): mouse, pen or touch, in CSS pixels from the element's top left. Gestures
+ * read these; `mouse-*` and `touch` events still feed the device resources and action maps.
+ */
+ | {
+    type: 'pointer';
+    id: number;
+    phase: PointerPhase;
+    pointer: PointerKind;
+    /** The button that went down (`down`/`up`), or the one held since (`move`). */
+    button: MouseButton;
+    x: number;
+    y: number;
+    /** `MODIFIERS` bits held: shift, ctrl, alt, meta. */
+    modifiers: number;
 } | {
     type: 'touch';
     id: number;
@@ -69,10 +151,44 @@ export type RawInputEvent = {
     type: 'text';
     text: string;
 };
+export type PointerPhase = 'down' | 'move' | 'up' | 'cancel';
+export type PointerKind = 'mouse' | 'pen' | 'touch';
+/** Bits of a pointer or wheel event's `modifiers`. */
+export declare const MODIFIERS: {
+    readonly shift: 1;
+    readonly ctrl: 2;
+    readonly alt: 4;
+    readonly meta: 8;
+};
+/**
+ * What the scene takes from the pointer while a control is enabled (0060). A source stops the
+ * host's default handling (`preventDefault`) only for what's listed here and for claimed pointers;
+ * everything else passes through to the page.
+ */
+export interface PointerPolicy {
+    /** Mouse buttons enabled controls drag with: presses with them, and the context menu for 'right'. */
+    buttons: readonly MouseButton[];
+    /** Wheel events zoom a control. */
+    wheel: boolean;
+    /** Touches drive a control: the element gets `touch-action: none`. */
+    touch: boolean;
+}
 /** Where raw input comes from: DOM listeners in a browser or webview, nothing when headless. */
 export interface InputSource {
     /** Appends events since the last drain (and polls devices like gamepads). */
     drain(out: RawInputEvent[]): void;
+    /**
+     * Calls `listener` whenever an event arrives, so an on-demand app wakes to drain it (0052).
+     * Returns an unsubscribe function. Polled devices (gamepads) don't call it.
+     */
+    onInput?(listener: () => void): () => void;
+    /**
+     * A consumer took this pointer's gesture (0060): its later events are the scene's
+     * (`preventDefault`), and it keeps reporting outside the element (pointer capture) until it ends.
+     */
+    claimPointer?(id: number): void;
+    /** What enabled controls take; see `PointerPolicy`. Called when it changes. */
+    setPointerPolicy?(policy: PointerPolicy): void;
     dispose(): void;
 }
 export type FileChangeKind = 'create' | 'modify' | 'remove';
@@ -81,10 +197,18 @@ export interface FileChangeEvent {
     readonly path: string;
 }
 export interface PlatformFileSystem {
+    /** A media/fetch URL for an existing host file; absent when the host cannot expose one. */
+    resolveUrl?(path: string): string | undefined;
     /** False on hosts that can only read (for example a static web build). */
     readonly writable: boolean;
     readText(path: string): Promise<string>;
     readBytes(path: string): Promise<Uint8Array>;
+    /**
+     * `length` bytes from `offset` (fewer at the end of the file): one ranged read, so a terrain
+     * page comes out of a pack of hundreds without reading the rest (0071). Absent on hosts that
+     * can't; callers read the whole file then.
+     */
+    readRange?(path: string, offset: number, length: number): Promise<Uint8Array>;
     writeText(path: string, data: string): Promise<void>;
     writeBytes(path: string, data: Uint8Array): Promise<void>;
     exists(path: string): Promise<boolean>;
@@ -139,6 +263,10 @@ export interface AudioClipSource {
     readonly id: string;
     /** The file as imported (WAV, Ogg, MP3, FLAC). A new array means new contents. */
     readonly bytes: Uint8Array;
+    /** Resolved immutable imported-artifact URL for lazy media playback. Bytes may be empty. */
+    readonly url?: string;
+    readonly channels?: number;
+    readonly sampleRate?: number;
     /** `wav`, `vorbis`, `opus`, `mp3`, or `flac`. */
     readonly codec: string;
     /** Seconds. */
@@ -173,6 +301,11 @@ export interface AudioVoiceParams {
     z: number;
 }
 export interface AudioVoiceDesc extends AudioVoiceParams {
+    /** Additive post-spatial sends; routes must be declared by the source bus mixer sends. */
+    readonly sends?: readonly {
+        target: string;
+        gain: number;
+    }[];
     readonly clip: AudioClipSource;
     /** Bus name; the backend mixes it at the gain last given to `setBus`. */
     readonly bus: string;
@@ -188,12 +321,21 @@ export type AudioContextState = 'running' | 'suspended' | 'closed' | 'headless';
  * voices; a backend only makes the sound (or, headless, records it).
  */
 export interface AudioBackend {
+    /** Advanced features are opt-in; unsupported operations must not silently degrade. */
+    readonly runtime?: AudioRuntimeExtension;
+    /** An independent session under a shared host context/cache. */
+    createSession?(options?: AudioSessionOptions): AudioBackend;
     /** `web`, `headless`, ... */
     readonly kind: string;
     /** Browsers keep the context suspended until a user gesture; voices wait until then. */
     readonly state: AudioContextState;
     /** Returns an id for `update` and `stop`. */
     play(voice: AudioVoiceDesc): number;
+    /**
+     * Gets a clip ready to play (a browser decodes it), so its first play starts on time instead of
+     * starting late into the clip. Optional: backends with nothing to prepare leave it out.
+     */
+    preload?(clip: AudioClipSource): void;
     update(voice: number, params: AudioVoiceParams): void;
     /** Stops a voice, fading out over `fade` seconds (default: at once). */
     stop(voice: number, fade?: number): void;

package/dist/index.js

@@ -1,4 +1,6 @@
+import { validateAudioAutomation } from "./audio-runtime.js";
 export * from "./workers.js";
+const MODIFIERS = { shift: 1, ctrl: 2, alt: 4, meta: 8 };
 function createMemoryStorage() {
   const data = /* @__PURE__ */ new Map();
   return {
@@ -12,5 +14,7 @@ function createMemoryStorage() {
   };
 }
 export {
-  createMemoryStorage
+  MODIFIERS,
+  createMemoryStorage,
+  validateAudioAutomation
 };

package/dist/workers.d.ts

@@ -4,6 +4,19 @@ export interface WorkerRunOptions {
     readonly transfer?: readonly ArrayBuffer[];
     /** `high` jobs start before every queued `normal` one. Default `normal`. */
     readonly priority?: 'high' | 'normal';
+    /** What the profiler calls the job: its span is `worker/<kind>` (0074). Default: `fn`. */
+    readonly kind?: string;
+}
+/**
+ * One finished job as the worker timed it (0074), on the calling thread's `performance.now()`
+ * timeline: the two contexts' `timeOrigin`s are subtracted, so it lines up with main-thread spans.
+ */
+export interface WorkerJobTiming {
+    kind: string;
+    /** The pool's thread that ran it, from 0. */
+    worker: number;
+    start: number;
+    ms: number;
 }
 /**
  * A pool of background threads that run functions exported by ES modules. Results never depend on
@@ -23,6 +36,11 @@ export interface Workers {
     run<T>(module: string, fn: string, args: readonly unknown[], options?: WorkerRunOptions): Promise<T>;
     /** Stops every worker. Jobs still running or queued reject. */
     dispose(): void;
+    /**
+     * Calls `listener` with every finished job's timing, measured inside the worker and carried back
+     * with its result, so it costs no extra messages. Returns an unsubscribe function.
+     */
+    observe?(listener: (timing: WorkerJobTiming) => void): () => void;
 }
 /** What a host gives the pool for one worker thread. */
 export interface WorkerThread {

package/dist/workers.js

@@ -1,17 +1,36 @@
 import { ShardError } from "@aethervtt/shard-core";
+const clock = globalThis;
+function timeOrigin() {
+  return clock.performance?.timeOrigin ?? 0;
+}
+function now() {
+  return clock.performance ? clock.performance.now() : Date.now();
+}
 function createWorkerPool(options) {
   const slots = [];
   const high = [];
   const normal = [];
+  const observers = /* @__PURE__ */ new Set();
   let nextId = 1;
   let disposed = false;
   const start = (slot) => {
+    const index = slots.indexOf(slot);
     const events = {
       message: (message) => {
         const reply = message;
         const job = slot.job;
         if (!job || job.id !== reply.id) return;
         slot.job = void 0;
+        const time = reply.time;
+        if (time && observers.size > 0) {
+          const timing = {
+            kind: job.kind,
+            worker: index,
+            start: time[0] - timeOrigin(),
+            ms: time[1]
+          };
+          for (const listener of observers) listener(timing);
+        }
         if (reply.ok) job.resolve(reply.result);
         else job.reject(toError(reply.error));
         pump();
@@ -70,6 +89,7 @@ function createWorkerPool(options) {
         id: nextId++,
         module,
         fn,
+        kind: opts.kind ?? fn,
         args,
         transfer: opts.transfer ?? [],
         resolve,
@@ -78,8 +98,13 @@ function createWorkerPool(options) {
       (opts.priority === "high" ? high : normal).push(job);
       pump();
     }),
+    observe: (listener) => {
+      observers.add(listener);
+      return () => observers.delete(listener);
+    },
     dispose: () => {
       disposed = true;
+      observers.clear();
       const stopped = new ShardError("platform/workers-disposed", "The worker pool was disposed");
       for (const job of [...high.splice(0), ...normal.splice(0)]) job.reject(stopped);
       for (const slot of slots) {
@@ -99,10 +124,15 @@ function toError(e) {
 }
 function createInlineWorkers() {
   const modules = /* @__PURE__ */ new Map();
+  const observers = /* @__PURE__ */ new Set();
   let disposed = false;
   return {
     size: 0,
-    run: async (module, fn, args) => {
+    observe: (listener) => {
+      observers.add(listener);
+      return () => observers.delete(listener);
+    },
+    run: async (module, fn, args, options = {}) => {
       if (disposed)
         throw new ShardError("platform/workers-disposed", "The worker pool was disposed");
       let mod = modules.get(module);
@@ -119,7 +149,13 @@ function createInlineWorkers() {
           hint: "Worker functions are named exports of the module passed to run()."
         });
       }
-      return await f(...args);
+      const start = now();
+      const result = await f(...args);
+      if (observers.size > 0) {
+        const timing = { kind: options.kind ?? fn, worker: 0, start, ms: now() - start };
+        for (const listener of observers) listener(timing);
+      }
+      return result;
     },
     dispose: () => {
       disposed = true;
@@ -160,8 +196,10 @@ const handle = async (msg, post) => {
     if (typeof f !== 'function') {
       throw Object.assign(new Error('"' + module + '" has no export "' + fn + '"'), { code: 'platform/worker-no-export' })
     }
+    const t0 = performance.now()
     const result = await f(...args)
-    post({ id, ok: true, result }, transfers(result))
+    const time = [performance.timeOrigin + t0, performance.now() - t0]
+    post({ id, ok: true, result, time }, transfers(result))
   } catch (e) {
     post({ id, ok: false, error: { code: e && e.code, message: String((e && e.message) || e), hint: e && e.hint, path: e && e.path } }, [])
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aethervtt/shard-platform",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -16,7 +16,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@aethervtt/shard-core": "0.0.1"
+    "@aethervtt/shard-core": "0.2.0"
   },
   "repository": {
     "type": "git",
@@ -28,6 +28,6 @@
     "provenance": true
   },
   "shard": {
-    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+    "buildSha": "32c22a3944ed23f5d1baa90bf7cc9fae724f5fd8"
   }
 }