@motionscript/browser 0.1.0 → 0.1.1-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @motionscript/browser
 
+## 0.1.1-alpha.0
+
+### Patch Changes
+
+- e279864: **Breaking:** the deprecated shims and dead exports are gone. Core drops the `SceneDocument`, `SceneEffect`, `SceneTimeline`, `integrateSpeedToSceneTime` and `sourceTimeAtSceneElapsed` aliases, `Sound.sceneDurationFor`, the `Precomp*` aliases of the asset-timeline names, `ImageFilters` and `VideoFilters` (use `Adjustments` and `VideoAdjustments`), `PropertyMeta.withdrawn`, `AssetTimelineOptions.lifespans`, and the unused `opacity` and `blend` of per-shape descriptors (`ShapeState`). The `filters` prop of image and video fills is removed too: write the grade as `preset: { adjustments }`. Documents move to format 3, and opening one that carries `filters` on a media fill moves it into `preset.adjustments`. Also removed as unused: `sampleParam`, `IDENTITY_AFFINE3`, `neutralPreset`, `resolveMediaPreset`'s second argument, `paramAtDistance`, `arcPointFunction`, `segmentChord`, `isStyleOnlySegment`, `withTransformDescriptor`, `easeKey`, `isParentNode`, `AudioParams`, `ResolvedSoundProps`, `StarProps`, `RotatedBoxProps`, `ModelView3DProps` and `NumberNodeFormat`. In headless, `Semaphore`, `withDeadline`, `toRenderError` and `cleanPageErrorMessage` were internal and are deleted.
+
+  Migration: a stored document needs nothing done to it. Opening a format 2 document moves a media fill's `filters` into `preset.adjustments` (dropped where `preset.adjustments` already states the grade), and saving it writes format 3. Code that named a removed export uses what it aliased: `Adjustments` for `ImageFilters`, `VideoAdjustments` for `VideoFilters`, and the asset-timeline names for the `Precomp*` aliases.
+
+- e9db554: An asset is downloaded and decoded once while it is loading, however many ask for it: the weights of one font family share its files (each weight used to fetch the whole family), two draws of one image or video share one decode, and every session, still and export on a page shares one request per source (`loadAssetBytes`, which the audio mix now goes through as well). A load that fails is asked for again next time.
+- Updated dependencies [3630b74]
+- Updated dependencies [1c43a37]
+- Updated dependencies [6b89575]
+- Updated dependencies [e279864]
+- Updated dependencies [e279864]
+- Updated dependencies [e9db554]
+- Updated dependencies [7cd4e53]
+  - @motionscript/core@0.1.1-alpha.0
+  - @motionscript/renderer@0.1.1-alpha.0
+
 ## 0.1.0
 
 ### Patch Changes

package/dist/asset-bytes.d.ts

@@ -1,59 +1,21 @@
 /**
- * Where a source URL's bytes come from: a host's local store, then the network.
- * The renderer's storage adapter reads every asset through it (`loadBytes`).
- *
- * ## Why the web adapter needs this at all
- *
- * The storage adapter addresses every asset by URL and fetches it. That is
- * right for an asset that lives somewhere, and wrong for one whose bytes the
- * host already has in hand — a file the user has just chosen, a render a local
- * model has just produced, a picture whose upload has not finished or cannot
- * start because there is no network. In all three the adapter downloads bytes
- * that never needed to travel.
- *
- * `NodeStorageAdapter` has had the answer since it was written: an injected
- * `AssetLoader`, with an `inline` map consulted ahead of the disk. This is the
- * same seam for the browser.
- *
- * ## Why it is module-level
- *
- * The storage adapter is constructed at several sites *inside* this package —
- * sessions, the exporter, the audio mixer and the still renderer — none of
- * which a host can reach. A constructor argument would
- * therefore cover the preview and leave export and stills on the network,
- * which is the worst of both: the picture a user sees would come from local
- * bytes and the one they render would not.
- *
- * So this is an *injection point*, not a cache. The adapter still owns every
- * decode, every cache, every size ceiling and every eviction rule; all this
- * changes is where the compressed bytes came from. A source that answers `null`
- * — which is what an unregistered URL, an evicted entry or a host with no local
- * store does — leaves the adapter exactly as it was.
+ * Where a source URL's bytes come from: a host's local store, then the network. The renderer's storage adapter reads
+ * every asset through it (`loadBytes`). The adapter otherwise fetches every asset by URL, which is wrong for bytes the
+ * host already holds (a file just chosen, a local model's render, an upload still in flight or offline).
+ *
+ * It is module-level because the adapter is constructed at several sites inside this package (sessions, the exporter,
+ * the audio mixer, the still renderer) a host cannot reach; a constructor argument would cover the preview and leave
+ * export and stills on the network. This is an *injection point*, not a cache: the adapter still owns every decode,
+ * cache and eviction rule, and a source answering `null` leaves it exactly as it was.
  */
 /** Local bytes for a source URL, or `null` to go to the network. */
 export type AssetByteSource = (src: string) => Promise<Blob | null>;
-/**
- * Installs the byte source for this browsing context, or clears it with `null`.
- *
- * Called once per window that renders. Later calls replace the previous source
- * rather than stacking, because two sources disagreeing about one URL has no
- * sensible answer.
- */
+/** Installs the byte source for this browsing context, or clears it with `null`. Later calls replace the previous source rather than stacking: two sources disagreeing about one URL has no sensible answer. */
 export declare function setAssetByteSource(next: AssetByteSource | null): void;
-/**
- * The bytes for `src`, or `null`.
- *
- * Swallows a throwing source on purpose. A host's local store failing is a
- * cache miss, not a render failure — the caller falls through to `fetch`, which
- * is what it would have done had the source never been installed.
- */
+/** The bytes for `src`, or `null`. Swallows a throwing source on purpose: a failing local store is a cache miss, not a render failure, and the caller falls through to `fetch`. */
 export declare function localAssetBytes(src: string): Promise<Blob | null>;
-/**
- * The network's bytes for `url`. A response that is not OK is a failed load,
- * never bytes: a 404 page handed to the font manager marked a family loaded
- * with no face in it.
- */
+/** The network's bytes for `url`. A non-OK response is a failed load, never bytes (a 404 page handed to the font manager marked a family loaded with no face). */
 export declare function fetchAssetBytes(url: string): Promise<Blob>;
-/** The bytes for `src`: the host's local store first, then the network. */
+/** The bytes for `src`: the host's local store first, then the network. A second ask while the first is out joins it, page-wide. */
 export declare function loadAssetBytes(src: string): Promise<Blob>;
 //# sourceMappingURL=asset-bytes.d.ts.map

package/dist/asset-bytes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"asset-bytes.d.ts","sourceRoot":"","sources":["../src/asset-bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;AAIpE;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAErE;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAOvE;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhE;AAED,2EAA2E;AAC3E,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/D"}
+{"version":3,"file":"asset-bytes.d.ts","sourceRoot":"","sources":["../src/asset-bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;AAIpE,gNAAgN;AAChN,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAErE;AAED,mLAAmL;AACnL,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAOvE;AAED,kKAAkK;AAClK,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhE;AAID,oIAAoI;AACpI,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMzD"}

package/dist/asset-bytes.js

@@ -1,53 +1,19 @@
 /**
- * Where a source URL's bytes come from: a host's local store, then the network.
- * The renderer's storage adapter reads every asset through it (`loadBytes`).
- *
- * ## Why the web adapter needs this at all
- *
- * The storage adapter addresses every asset by URL and fetches it. That is
- * right for an asset that lives somewhere, and wrong for one whose bytes the
- * host already has in hand — a file the user has just chosen, a render a local
- * model has just produced, a picture whose upload has not finished or cannot
- * start because there is no network. In all three the adapter downloads bytes
- * that never needed to travel.
- *
- * `NodeStorageAdapter` has had the answer since it was written: an injected
- * `AssetLoader`, with an `inline` map consulted ahead of the disk. This is the
- * same seam for the browser.
- *
- * ## Why it is module-level
- *
- * The storage adapter is constructed at several sites *inside* this package —
- * sessions, the exporter, the audio mixer and the still renderer — none of
- * which a host can reach. A constructor argument would
- * therefore cover the preview and leave export and stills on the network,
- * which is the worst of both: the picture a user sees would come from local
- * bytes and the one they render would not.
- *
- * So this is an *injection point*, not a cache. The adapter still owns every
- * decode, every cache, every size ceiling and every eviction rule; all this
- * changes is where the compressed bytes came from. A source that answers `null`
- * — which is what an unregistered URL, an evicted entry or a host with no local
- * store does — leaves the adapter exactly as it was.
+ * Where a source URL's bytes come from: a host's local store, then the network. The renderer's storage adapter reads
+ * every asset through it (`loadBytes`). The adapter otherwise fetches every asset by URL, which is wrong for bytes the
+ * host already holds (a file just chosen, a local model's render, an upload still in flight or offline).
+ *
+ * It is module-level because the adapter is constructed at several sites inside this package (sessions, the exporter,
+ * the audio mixer, the still renderer) a host cannot reach; a constructor argument would cover the preview and leave
+ * export and stills on the network. This is an *injection point*, not a cache: the adapter still owns every decode,
+ * cache and eviction rule, and a source answering `null` leaves it exactly as it was.
  */
 let source = null;
-/**
- * Installs the byte source for this browsing context, or clears it with `null`.
- *
- * Called once per window that renders. Later calls replace the previous source
- * rather than stacking, because two sources disagreeing about one URL has no
- * sensible answer.
- */
+/** Installs the byte source for this browsing context, or clears it with `null`. Later calls replace the previous source rather than stacking: two sources disagreeing about one URL has no sensible answer. */
 export function setAssetByteSource(next) {
     source = next;
 }
-/**
- * The bytes for `src`, or `null`.
- *
- * Swallows a throwing source on purpose. A host's local store failing is a
- * cache miss, not a render failure — the caller falls through to `fetch`, which
- * is what it would have done had the source never been installed.
- */
+/** The bytes for `src`, or `null`. Swallows a throwing source on purpose: a failing local store is a cache miss, not a render failure, and the caller falls through to `fetch`. */
 export async function localAssetBytes(src) {
     if (!source)
         return null;
@@ -58,11 +24,7 @@ export async function localAssetBytes(src) {
         return null;
     }
 }
-/**
- * The network's bytes for `url`. A response that is not OK is a failed load,
- * never bytes: a 404 page handed to the font manager marked a family loaded
- * with no face in it.
- */
+/** The network's bytes for `url`. A non-OK response is a failed load, never bytes (a 404 page handed to the font manager marked a family loaded with no face). */
 export async function fetchAssetBytes(url) {
     const response = await fetch(url);
     if (!response.ok) {
@@ -71,8 +33,14 @@ export async function fetchAssetBytes(url) {
     }
     return response.blob();
 }
-/** The bytes for `src`: the host's local store first, then the network. */
-export async function loadAssetBytes(src) {
-    return (await localAssetBytes(src)) ?? fetchAssetBytes(src);
+const loading = new Map();
+/** The bytes for `src`: the host's local store first, then the network. A second ask while the first is out joins it, page-wide. */
+export function loadAssetBytes(src) {
+    const running = loading.get(src);
+    if (running)
+        return running;
+    const job = (async () => (await localAssetBytes(src)) ?? fetchAssetBytes(src))().finally(() => loading.delete(src));
+    loading.set(src, job);
+    return job;
 }
 //# sourceMappingURL=asset-bytes.js.map

package/dist/asset-bytes.js.map

@@ -1 +1 @@
-{"version":3,"file":"asset-bytes.js","sourceRoot":"","sources":["../src/asset-bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,IAAI,MAAM,GAA2B,IAAI,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA4B;IAC3D,MAAM,GAAG,IAAI,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAW;IAC7C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC;QACD,OAAO,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,IAAI,CAAC;IAChB,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAW;IAC7C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;QACxG,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,kBAAkB,MAAM,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW;IAC5C,OAAO,CAAC,MAAM,eAAe,CAAC,GAAG,CAAC,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC;AAChE,CAAC","sourcesContent":["/**\n * Where a source URL's bytes come from: a host's local store, then the network.\n * The renderer's storage adapter reads every asset through it (`loadBytes`).\n *\n * ## Why the web adapter needs this at all\n *\n * The storage adapter addresses every asset by URL and fetches it. That is\n * right for an asset that lives somewhere, and wrong for one whose bytes the\n * host already has in hand — a file the user has just chosen, a render a local\n * model has just produced, a picture whose upload has not finished or cannot\n * start because there is no network. In all three the adapter downloads bytes\n * that never needed to travel.\n *\n * `NodeStorageAdapter` has had the answer since it was written: an injected\n * `AssetLoader`, with an `inline` map consulted ahead of the disk. This is the\n * same seam for the browser.\n *\n * ## Why it is module-level\n *\n * The storage adapter is constructed at several sites *inside* this package —\n * sessions, the exporter, the audio mixer and the still renderer — none of\n * which a host can reach. A constructor argument would\n * therefore cover the preview and leave export and stills on the network,\n * which is the worst of both: the picture a user sees would come from local\n * bytes and the one they render would not.\n *\n * So this is an *injection point*, not a cache. The adapter still owns every\n * decode, every cache, every size ceiling and every eviction rule; all this\n * changes is where the compressed bytes came from. A source that answers `null`\n * — which is what an unregistered URL, an evicted entry or a host with no local\n * store does — leaves the adapter exactly as it was.\n */\n\n/** Local bytes for a source URL, or `null` to go to the network. */\nexport type AssetByteSource = (src: string) => Promise<Blob | null>;\n\nlet source: AssetByteSource | null = null;\n\n/**\n * Installs the byte source for this browsing context, or clears it with `null`.\n *\n * Called once per window that renders. Later calls replace the previous source\n * rather than stacking, because two sources disagreeing about one URL has no\n * sensible answer.\n */\nexport function setAssetByteSource(next: AssetByteSource | null): void {\n    source = next;\n}\n\n/**\n * The bytes for `src`, or `null`.\n *\n * Swallows a throwing source on purpose. A host's local store failing is a\n * cache miss, not a render failure — the caller falls through to `fetch`, which\n * is what it would have done had the source never been installed.\n */\nexport async function localAssetBytes(src: string): Promise<Blob | null> {\n    if (!source) return null;\n    try {\n        return await source(src);\n    } catch {\n        return null;\n    }\n}\n\n/**\n * The network's bytes for `url`. A response that is not OK is a failed load,\n * never bytes: a 404 page handed to the font manager marked a family loaded\n * with no face in it.\n */\nexport async function fetchAssetBytes(url: string): Promise<Blob> {\n    const response = await fetch(url);\n    if (!response.ok) {\n        const status = response.statusText ? `${response.status} ${response.statusText}` : `${response.status}`;\n        throw new Error(`Fetching \"${url}\" failed: HTTP ${status}`);\n    }\n    return response.blob();\n}\n\n/** The bytes for `src`: the host's local store first, then the network. */\nexport async function loadAssetBytes(src: string): Promise<Blob> {\n    return (await localAssetBytes(src)) ?? fetchAssetBytes(src);\n}\n"]}
+{"version":3,"file":"asset-bytes.js","sourceRoot":"","sources":["../src/asset-bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,IAAI,MAAM,GAA2B,IAAI,CAAC;AAE1C,gNAAgN;AAChN,MAAM,UAAU,kBAAkB,CAAC,IAA4B;IAC3D,MAAM,GAAG,IAAI,CAAC;AAClB,CAAC;AAED,mLAAmL;AACnL,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAW;IAC7C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC;QACD,OAAO,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,IAAI,CAAC;IAChB,CAAC;AACL,CAAC;AAED,kKAAkK;AAClK,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAW;IAC7C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;QACxG,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,kBAAkB,MAAM,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;AAEjD,oIAAoI;AACpI,MAAM,UAAU,cAAc,CAAC,GAAW;IACtC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,MAAM,GAAG,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,eAAe,CAAC,GAAG,CAAC,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACpH,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACtB,OAAO,GAAG,CAAC;AACf,CAAC","sourcesContent":["/**\n * Where a source URL's bytes come from: a host's local store, then the network. The renderer's storage adapter reads\n * every asset through it (`loadBytes`). The adapter otherwise fetches every asset by URL, which is wrong for bytes the\n * host already holds (a file just chosen, a local model's render, an upload still in flight or offline).\n *\n * It is module-level because the adapter is constructed at several sites inside this package (sessions, the exporter,\n * the audio mixer, the still renderer) a host cannot reach; a constructor argument would cover the preview and leave\n * export and stills on the network. This is an *injection point*, not a cache: the adapter still owns every decode,\n * cache and eviction rule, and a source answering `null` leaves it exactly as it was.\n */\n\n/** Local bytes for a source URL, or `null` to go to the network. */\nexport type AssetByteSource = (src: string) => Promise<Blob | null>;\n\nlet source: AssetByteSource | null = null;\n\n/** Installs the byte source for this browsing context, or clears it with `null`. Later calls replace the previous source rather than stacking: two sources disagreeing about one URL has no sensible answer. */\nexport function setAssetByteSource(next: AssetByteSource | null): void {\n    source = next;\n}\n\n/** The bytes for `src`, or `null`. Swallows a throwing source on purpose: a failing local store is a cache miss, not a render failure, and the caller falls through to `fetch`. */\nexport async function localAssetBytes(src: string): Promise<Blob | null> {\n    if (!source) return null;\n    try {\n        return await source(src);\n    } catch {\n        return null;\n    }\n}\n\n/** The network's bytes for `url`. A non-OK response is a failed load, never bytes (a 404 page handed to the font manager marked a family loaded with no face). */\nexport async function fetchAssetBytes(url: string): Promise<Blob> {\n    const response = await fetch(url);\n    if (!response.ok) {\n        const status = response.statusText ? `${response.status} ${response.statusText}` : `${response.status}`;\n        throw new Error(`Fetching \"${url}\" failed: HTTP ${status}`);\n    }\n    return response.blob();\n}\n\nconst loading = new Map<string, Promise<Blob>>();\n\n/** The bytes for `src`: the host's local store first, then the network. A second ask while the first is out joins it, page-wide. */\nexport function loadAssetBytes(src: string): Promise<Blob> {\n    const running = loading.get(src);\n    if (running) return running;\n    const job = (async () => (await localAssetBytes(src)) ?? fetchAssetBytes(src))().finally(() => loading.delete(src));\n    loading.set(src, job);\n    return job;\n}\n"]}

package/dist/audio/bus-graph.d.ts

@@ -1,52 +1,17 @@
 import { type AudioBusStop } from "@motionscript/core";
-/**
- * The live chains for one audio context's buses.
- *
- * Held per context rather than per clip, because that is the whole difference
- * between a bus and per-clip processing: every clip naming a bus connects into
- * the *same* nodes, so a reverb on a bus is one tail the group shares rather
- * than one tail each. Flattening the levels into per-clip gain would sound
- * right; flattening the effects would not.
- */
+/** The live chains for one audio context's buses. Held per context, not per clip: every clip naming a bus connects into the *same* nodes, so a bus reverb is one shared tail (flattening levels into per-clip gain sounds right; flattening effects would not). */
 export declare class AudioBusGraph {
     private readonly ctx;
-    /** Where the last bus in a chain connects — the master, or the destination. */
     private readonly destination;
-    constructor(ctx: BaseAudioContext, 
-    /** Where the last bus in a chain connects — the master, or the destination. */
-    destination: AudioNode);
-    /**
-     * The input node a clip on `bus` should connect to, building the chain the
-     * first time it is asked for.
-     *
-     * `bus` is source-adjacent first, so `bus[0]` is the one the clip feeds and
-     * each stop after it is that bus's own parent. An empty or absent chain
-     * returns the destination, which is what every clip did before buses
-     * existed.
-     *
-     * `startTime` is the context time a new chain's schedule starts from, and
-     * `clipTime` the same instant in the stops' own seconds. A curve on a stop
-     * runs over its `startAt`–`endAt`, so the two are what place it.
-     */
+    constructor(ctx: BaseAudioContext, destination: AudioNode);
+    /** The input node a clip on `bus` should connect to, building the chain on first ask. `bus` is source-adjacent first (`bus[0]` is the one the clip feeds; each later stop is its parent); an empty or absent chain returns the destination. `startTime` is the context time a new chain's schedule starts from and `clipTime` the same instant in the stops' own seconds, which place a curve over its `startAt`–`endAt`. */
     inputFor(bus: readonly AudioBusStop[] | undefined, startTime: number, clipTime: number): AudioNode;
     /** Disconnect every live bus node, so the next {@link inputFor} builds afresh. Safe to call more than once. */
     dispose(): void;
     private readonly inputs;
     private readonly nodes;
     private readonly oscillators;
-    /**
-     * Build (or reuse) the chain for `bus[index]`, connected to whatever
-     * `bus[index + 1]` resolves to.
-     *
-     * Recursive rather than iterative because a bus's *output* has to exist
-     * before its own nodes can connect to it, and the outermost bus is the last
-     * entry.
-     *
-     * Reused by everything that changes what it sounds like, down to the master,
-     * not by id alone: a bus edited under a playing device, or one id on two
-     * tracks, is a different chain, and one built for the first would play the
-     * second through stale levels and a curve anchored to the wrong span.
-     */
+    /** Builds (or reuses) the chain for `bus[index]`, connected to whatever `bus[index + 1]` resolves to. Recursive because a bus's *output* must exist before its own nodes connect to it. Reuse is keyed by everything that changes what it sounds like, not by id alone: a bus edited under a playing device, or one id on two tracks, is a different chain, and a stale one would play stale levels and a curve anchored to the wrong span. */
     private chainFrom;
 }
 //# sourceMappingURL=bus-graph.d.ts.map

package/dist/audio/bus-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bus-graph.d.ts","sourceRoot":"","sources":["../../src/audio/bus-graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,YAAY,EAAoB,MAAM,oBAAoB,CAAC;AAGrF;;;;;;;;GAQG;AACH,qBAAa,aAAa;IAElB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAFX,GAAG,EAAE,gBAAgB;IACtC,+EAA+E;IAC9D,WAAW,EAAE,SAAS;IAG3C;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,GAAG,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS;IAKlG,+GAA+G;IAC/G,OAAO,IAAI,IAAI;IAYf,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;IAEpD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS;CAuCpB"}
+{"version":3,"file":"bus-graph.d.ts","sourceRoot":"","sources":["../../src/audio/bus-graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,YAAY,EAAoB,MAAM,oBAAoB,CAAC;AAGrF,mQAAmQ;AACnQ,qBAAa,aAAa;IAElB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,WAAW;gBADX,GAAG,EAAE,gBAAgB,EACrB,WAAW,EAAE,SAAS;IAG3C,6ZAA6Z;IAC7Z,QAAQ,CAAC,GAAG,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS;IAKlG,+GAA+G;IAC/G,OAAO,IAAI,IAAI;IAYf,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;IAEpD,+aAA+a;IAC/a,OAAO,CAAC,SAAS;CAuCpB"}

package/dist/audio/bus-graph.js

@@ -1,36 +1,14 @@
 import { busStopKey } from "@motionscript/core";
 import { applyTransitions, buildAudioEffectGraph } from "./effect-graph";
-/**
- * The live chains for one audio context's buses.
- *
- * Held per context rather than per clip, because that is the whole difference
- * between a bus and per-clip processing: every clip naming a bus connects into
- * the *same* nodes, so a reverb on a bus is one tail the group shares rather
- * than one tail each. Flattening the levels into per-clip gain would sound
- * right; flattening the effects would not.
- */
+/** The live chains for one audio context's buses. Held per context, not per clip: every clip naming a bus connects into the *same* nodes, so a bus reverb is one shared tail (flattening levels into per-clip gain sounds right; flattening effects would not). */
 export class AudioBusGraph {
     ctx;
     destination;
-    constructor(ctx, 
-    /** Where the last bus in a chain connects — the master, or the destination. */
-    destination) {
+    constructor(ctx, destination) {
         this.ctx = ctx;
         this.destination = destination;
     }
-    /**
-     * The input node a clip on `bus` should connect to, building the chain the
-     * first time it is asked for.
-     *
-     * `bus` is source-adjacent first, so `bus[0]` is the one the clip feeds and
-     * each stop after it is that bus's own parent. An empty or absent chain
-     * returns the destination, which is what every clip did before buses
-     * existed.
-     *
-     * `startTime` is the context time a new chain's schedule starts from, and
-     * `clipTime` the same instant in the stops' own seconds. A curve on a stop
-     * runs over its `startAt`–`endAt`, so the two are what place it.
-     */
+    /** The input node a clip on `bus` should connect to, building the chain on first ask. `bus` is source-adjacent first (`bus[0]` is the one the clip feeds; each later stop is its parent); an empty or absent chain returns the destination. `startTime` is the context time a new chain's schedule starts from and `clipTime` the same instant in the stops' own seconds, which place a curve over its `startAt`–`endAt`. */
     inputFor(bus, startTime, clipTime) {
         if (!bus || bus.length === 0)
             return this.destination;
@@ -57,19 +35,7 @@ export class AudioBusGraph {
     inputs = new Map();
     nodes = [];
     oscillators = [];
-    /**
-     * Build (or reuse) the chain for `bus[index]`, connected to whatever
-     * `bus[index + 1]` resolves to.
-     *
-     * Recursive rather than iterative because a bus's *output* has to exist
-     * before its own nodes can connect to it, and the outermost bus is the last
-     * entry.
-     *
-     * Reused by everything that changes what it sounds like, down to the master,
-     * not by id alone: a bus edited under a playing device, or one id on two
-     * tracks, is a different chain, and one built for the first would play the
-     * second through stale levels and a curve anchored to the wrong span.
-     */
+    /** Builds (or reuses) the chain for `bus[index]`, connected to whatever `bus[index + 1]` resolves to. Recursive because a bus's *output* must exist before its own nodes connect to it. Reuse is keyed by everything that changes what it sounds like, not by id alone: a bus edited under a playing device, or one id on two tracks, is a different chain, and a stale one would play stale levels and a curve anchored to the wrong span. */
     chainFrom(bus, index, startTime, clipTime) {
         if (index >= bus.length)
             return this.destination;

package/dist/audio/bus-graph.js.map

@@ -1 +1 @@
-{"version":3,"file":"bus-graph.js","sourceRoot":"","sources":["../../src/audio/bus-graph.ts"],"names":[],"mappings":"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","sourcesContent":["import { busStopKey, type AudioBusStop, type AudioEffect } from \"@motionscript/core\";\nimport { applyTransitions, buildAudioEffectGraph } from \"./effect-graph\";\n\n/**\n * The live chains for one audio context's buses.\n *\n * Held per context rather than per clip, because that is the whole difference\n * between a bus and per-clip processing: every clip naming a bus connects into\n * the *same* nodes, so a reverb on a bus is one tail the group shares rather\n * than one tail each. Flattening the levels into per-clip gain would sound\n * right; flattening the effects would not.\n */\nexport class AudioBusGraph {\n    constructor(\n        private readonly ctx: BaseAudioContext,\n        /** Where the last bus in a chain connects — the master, or the destination. */\n        private readonly destination: AudioNode,\n    ) { }\n\n    /**\n     * The input node a clip on `bus` should connect to, building the chain the\n     * first time it is asked for.\n     *\n     * `bus` is source-adjacent first, so `bus[0]` is the one the clip feeds and\n     * each stop after it is that bus's own parent. An empty or absent chain\n     * returns the destination, which is what every clip did before buses\n     * existed.\n     *\n     * `startTime` is the context time a new chain's schedule starts from, and\n     * `clipTime` the same instant in the stops' own seconds. A curve on a stop\n     * runs over its `startAt`–`endAt`, so the two are what place it.\n     */\n    inputFor(bus: readonly AudioBusStop[] | undefined, startTime: number, clipTime: number): AudioNode {\n        if (!bus || bus.length === 0) return this.destination;\n        return this.chainFrom(bus, 0, startTime, clipTime);\n    }\n\n    /** Disconnect every live bus node, so the next {@link inputFor} builds afresh. Safe to call more than once. */\n    dispose(): void {\n        for (const node of this.nodes) {\n            try { node.disconnect(); } catch { /* already torn down */ }\n        }\n        for (const osc of this.oscillators) {\n            try { osc.stop(); } catch { /* never started, or already stopped */ }\n        }\n        this.nodes.length = 0;\n        this.oscillators.length = 0;\n        this.inputs.clear();\n    }\n\n    private readonly inputs = new Map<string, AudioNode>();\n    private readonly nodes: AudioNode[] = [];\n    private readonly oscillators: OscillatorNode[] = [];\n\n    /**\n     * Build (or reuse) the chain for `bus[index]`, connected to whatever\n     * `bus[index + 1]` resolves to.\n     *\n     * Recursive rather than iterative because a bus's *output* has to exist\n     * before its own nodes can connect to it, and the outermost bus is the last\n     * entry.\n     *\n     * Reused by everything that changes what it sounds like, down to the master,\n     * not by id alone: a bus edited under a playing device, or one id on two\n     * tracks, is a different chain, and one built for the first would play the\n     * second through stale levels and a curve anchored to the wrong span.\n     */\n    private chainFrom(bus: readonly AudioBusStop[], index: number, startTime: number, clipTime: number): AudioNode {\n        if (index >= bus.length) return this.destination;\n\n        const stop = bus[index];\n        const key = bus.slice(index).map(busStopKey).join(\">\");\n        const existing = this.inputs.get(key);\n        if (existing) return existing;\n\n        const output = this.chainFrom(bus, index + 1, startTime, clipTime);\n\n        // A pass-through head every clip connects to, so the bus has one input\n        // whatever its effects turn out to be.\n        const input = this.ctx.createGain();\n        input.gain.value = 1;\n\n        // The level is a gain after the effects, as a sound's own level is, so a\n        // ramp on it is scheduled exactly as one in `effects` is.\n        const level: AudioEffect = { type: \"gain\", value: stop.mute ? 0 : stop.volume };\n        const span = stop.endAt - stop.startAt;\n        const graph = buildAudioEffectGraph(\n            this.ctx, input, [...(stop.effects ?? []), level], startTime, span, clipTime - stop.startAt,\n        );\n        let tail = graph.output;\n        if (stop.transitionIn || stop.transitionOut) {\n            const transition = this.ctx.createGain();\n            applyTransitions(transition.gain, span, stop.transitionIn, stop.transitionOut, startTime, clipTime - stop.startAt);\n            tail.connect(transition);\n            this.nodes.push(transition);\n            tail = transition;\n        }\n        tail.connect(output);\n\n        this.nodes.push(input, ...graph.nodes);\n        this.oscillators.push(...graph.oscillators);\n        for (const osc of graph.oscillators) osc.start(startTime);\n\n        this.inputs.set(key, input);\n        return input;\n    }\n}\n"]}
+{"version":3,"file":"bus-graph.js","sourceRoot":"","sources":["../../src/audio/bus-graph.ts"],"names":[],"mappings":"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","sourcesContent":["import { busStopKey, type AudioBusStop, type AudioEffect } from \"@motionscript/core\";\nimport { applyTransitions, buildAudioEffectGraph } from \"./effect-graph\";\n\n/** The live chains for one audio context's buses. Held per context, not per clip: every clip naming a bus connects into the *same* nodes, so a bus reverb is one shared tail (flattening levels into per-clip gain sounds right; flattening effects would not). */\nexport class AudioBusGraph {\n    constructor(\n        private readonly ctx: BaseAudioContext,\n        private readonly destination: AudioNode,\n    ) { }\n\n    /** The input node a clip on `bus` should connect to, building the chain on first ask. `bus` is source-adjacent first (`bus[0]` is the one the clip feeds; each later stop is its parent); an empty or absent chain returns the destination. `startTime` is the context time a new chain's schedule starts from and `clipTime` the same instant in the stops' own seconds, which place a curve over its `startAt`–`endAt`. */\n    inputFor(bus: readonly AudioBusStop[] | undefined, startTime: number, clipTime: number): AudioNode {\n        if (!bus || bus.length === 0) return this.destination;\n        return this.chainFrom(bus, 0, startTime, clipTime);\n    }\n\n    /** Disconnect every live bus node, so the next {@link inputFor} builds afresh. Safe to call more than once. */\n    dispose(): void {\n        for (const node of this.nodes) {\n            try { node.disconnect(); } catch { /* already torn down */ }\n        }\n        for (const osc of this.oscillators) {\n            try { osc.stop(); } catch { /* never started, or already stopped */ }\n        }\n        this.nodes.length = 0;\n        this.oscillators.length = 0;\n        this.inputs.clear();\n    }\n\n    private readonly inputs = new Map<string, AudioNode>();\n    private readonly nodes: AudioNode[] = [];\n    private readonly oscillators: OscillatorNode[] = [];\n\n    /** Builds (or reuses) the chain for `bus[index]`, connected to whatever `bus[index + 1]` resolves to. Recursive because a bus's *output* must exist before its own nodes connect to it. Reuse is keyed by everything that changes what it sounds like, not by id alone: a bus edited under a playing device, or one id on two tracks, is a different chain, and a stale one would play stale levels and a curve anchored to the wrong span. */\n    private chainFrom(bus: readonly AudioBusStop[], index: number, startTime: number, clipTime: number): AudioNode {\n        if (index >= bus.length) return this.destination;\n\n        const stop = bus[index];\n        const key = bus.slice(index).map(busStopKey).join(\">\");\n        const existing = this.inputs.get(key);\n        if (existing) return existing;\n\n        const output = this.chainFrom(bus, index + 1, startTime, clipTime);\n\n        // A pass-through head every clip connects to, so the bus has one input\n        // whatever its effects turn out to be.\n        const input = this.ctx.createGain();\n        input.gain.value = 1;\n\n        // The level is a gain after the effects, as a sound's own level is, so a\n        // ramp on it is scheduled exactly as one in `effects` is.\n        const level: AudioEffect = { type: \"gain\", value: stop.mute ? 0 : stop.volume };\n        const span = stop.endAt - stop.startAt;\n        const graph = buildAudioEffectGraph(\n            this.ctx, input, [...(stop.effects ?? []), level], startTime, span, clipTime - stop.startAt,\n        );\n        let tail = graph.output;\n        if (stop.transitionIn || stop.transitionOut) {\n            const transition = this.ctx.createGain();\n            applyTransitions(transition.gain, span, stop.transitionIn, stop.transitionOut, startTime, clipTime - stop.startAt);\n            tail.connect(transition);\n            this.nodes.push(transition);\n            tail = transition;\n        }\n        tail.connect(output);\n\n        this.nodes.push(input, ...graph.nodes);\n        this.oscillators.push(...graph.oscillators);\n        for (const osc of graph.oscillators) osc.start(startTime);\n\n        this.inputs.set(key, input);\n        return input;\n    }\n}\n"]}

package/dist/audio/effect-graph.d.ts

@@ -1,31 +1,13 @@
 import { type AudioEffect, type AudioRequest, type AudioTransition, type Ramp } from "@motionscript/core";
-/**
- * The Web Audio graph for one source's effect chain.
- *
- * `output` is the last node, to connect downstream; `nodes` are every node to
- * `disconnect()` on teardown; `oscillators` are tremolo LFOs the caller starts
- * and stops alongside the source.
- */
+/** The Web Audio graph for one source's effect chain: `output` is the last node to connect downstream, `nodes` every node to `disconnect()` on teardown, `oscillators` tremolo LFOs the caller starts and stops with the source. */
 export interface AudioEffectGraph {
     output: AudioNode;
     nodes: AudioNode[];
     oscillators: OscillatorNode[];
 }
-/**
- * Builds the Web Audio graph for a clip's effect chain, after an
- * already-created `source`. Shared by live playback ({@link WebAudioSink}) and
- * offline export (`mixAudio`) so both sound identical.
- *
- * `startTime` is the context time the source starts; `clipDuration` the clip
- * seconds ramps run over (a clip's, or a bus's span); `elapsed` the clip seconds
- * already played at a mid-clip seek (0 for a clean start, negative before the
- * span begins).
- */
+/** Builds the Web Audio graph for a clip's effect chain after an already-created `source`, shared by live playback ({@link WebAudioSink}) and offline export (`mixAudio`) so both sound identical. `startTime` is the context time the source starts; `clipDuration` the clip seconds ramps run over (a clip's, or a bus's span); `elapsed` the clip seconds already played at a mid-clip seek (0 for a clean start, negative before the span begins). */
 export declare function buildAudioEffectGraph(ctx: BaseAudioContext, source: AudioNode, effects: readonly AudioEffect[], startTime?: number, clipDuration?: number, elapsed?: number): AudioEffectGraph;
-/**
- * Schedule `transitionIn`/`transitionOut` onto a gain over a span `length`
- * seconds long, baked like an eased ramp. Between the two it holds at 1.
- */
+/** Schedules `transitionIn`/`transitionOut` onto a gain over a span `length` seconds long, baked like an eased ramp; holds at 1 between them. */
 export declare function applyTransitions(gain: AudioParam, length: number, transitionIn: AudioTransition | undefined, transitionOut: AudioTransition | undefined, startTime: number, elapsed: number): void;
 /** How one request plays its source: the rate, and the lengths its ramps and transitions run over. */
 export interface Playback {
@@ -50,13 +32,6 @@ export declare function buildLevel(ctx: BaseAudioContext, from: AudioNode, req:
     output: AudioNode;
     nodes: AudioNode[];
 };
-/**
- * Schedule a speed ramp onto an `AudioBufferSourceNode.playbackRate`.
- *
- * The ramp runs over **source** seconds and Web Audio schedules in context
- * seconds, so this walks clip time in small steps, converts each to a source
- * offset through the integral inverse, and lays down the rate there. `elapsed`
- * is clip seconds already played at a mid-clip seek.
- */
+/** Schedules a speed ramp onto `playbackRate`. The ramp runs over **source** seconds and Web Audio schedules in context seconds, so this walks clip time in small steps and converts each through the integral inverse. `elapsed` is clip seconds already played at a mid-clip seek. */
 export declare function applySpeedToPlaybackRate(rate: AudioParam, speed: Ramp | undefined, sourceLength: number, clipDuration: number, startTime: number, elapsed: number): void;
 //# sourceMappingURL=effect-graph.d.ts.map

package/dist/audio/effect-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"effect-graph.d.ts","sourceRoot":"","sources":["../../src/audio/effect-graph.ts"],"names":[],"mappings":"AAAA,OAAO,EASH,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,EAEpB,KAAK,IAAI,EACZ,MAAM,oBAAoB,CAAC;AAE5B;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,WAAW,EAAE,cAAc,EAAE,CAAC;CACjC;AA2ED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACjC,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,SAAS,GAAE,MAAwB,EACnC,YAAY,GAAE,MAAU,EACxB,OAAO,GAAE,MAAU,GACpB,gBAAgB,CAiFlB;AAUD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC5B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,eAAe,GAAG,SAAS,EACzC,aAAa,EAAE,eAAe,GAAG,SAAS,EAC1C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAChB,IAAI,CAoBN;AAED,sGAAsG;AACtG,MAAM,WAAW,QAAQ;IACrB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,GAAG,QAAQ,CAS9E;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAI9E;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACtB,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAChB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,SAAS,EAAE,CAAA;CAAE,CAS3C;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACpC,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,IAAI,GAAG,SAAS,EACvB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAChB,IAAI,CAaN"}
+{"version":3,"file":"effect-graph.d.ts","sourceRoot":"","sources":["../../src/audio/effect-graph.ts"],"names":[],"mappings":"AAAA,OAAO,EASH,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,EAEpB,KAAK,IAAI,EACZ,MAAM,oBAAoB,CAAC;AAE5B,oOAAoO;AACpO,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,WAAW,EAAE,cAAc,EAAE,CAAC;CACjC;AAmED,0bAA0b;AAC1b,wBAAgB,qBAAqB,CACjC,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,SAAS,GAAE,MAAwB,EACnC,YAAY,GAAE,MAAU,EACxB,OAAO,GAAE,MAAU,GACpB,gBAAgB,CAiFlB;AAUD,iJAAiJ;AACjJ,wBAAgB,gBAAgB,CAC5B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,eAAe,GAAG,SAAS,EACzC,aAAa,EAAE,eAAe,GAAG,SAAS,EAC1C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAChB,IAAI,CAoBN;AAED,sGAAsG;AACtG,MAAM,WAAW,QAAQ;IACrB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,GAAG,QAAQ,CAS9E;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAI9E;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACtB,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAChB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,SAAS,EAAE,CAAA;CAAE,CAS3C;AAED,wRAAwR;AACxR,wBAAgB,wBAAwB,CACpC,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,IAAI,GAAG,SAAS,EACvB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAChB,IAAI,CAaN"}

package/dist/audio/effect-graph.js

@@ -1,15 +1,7 @@
 import { clipTimeAtSource, isRamp, resolveRamp, sampleRamp, sourceTimeAtClip, staticValue, transitionGainAt, transitionSpans, } from "@motionscript/core";
 /** Sample points per second an eased segment or a transition is baked into: about every 5 ms. */
 const CURVE_SAMPLES_PER_SECOND = 200;
-/**
- * Apply a {@link Param} to a Web Audio {@link AudioParam}: a number once, a
- * ramp as a schedule — linear segments as `linearRampToValueAtTime`, eased
- * ones baked into `setValueCurveAtTime`.
- *
- * `elapsed` is the clip seconds already played when a mid-clip seek starts the
- * source, so "now" reads the ramp at the clip's current position. `clamp` keeps
- * every scheduled value in a param's valid range.
- */
+/** Applies a {@link Param} to a Web Audio {@link AudioParam}: a number once, a ramp as a schedule (linear segments via `linearRampToValueAtTime`, eased ones baked into `setValueCurveAtTime`). `elapsed` is the clip seconds already played at a mid-clip seek; `clamp` keeps scheduled values in the param's valid range. */
 function applyParam(audioParam, param, startTime, clipDuration, elapsed, clamp = (v) => v) {
     // The platform throws on a non-finite value.
     const finite = (v) => {
@@ -62,16 +54,7 @@ function applyParam(audioParam, param, startTime, clipDuration, elapsed, clamp =
         }
     }
 }
-/**
- * Builds the Web Audio graph for a clip's effect chain, after an
- * already-created `source`. Shared by live playback ({@link WebAudioSink}) and
- * offline export (`mixAudio`) so both sound identical.
- *
- * `startTime` is the context time the source starts; `clipDuration` the clip
- * seconds ramps run over (a clip's, or a bus's span); `elapsed` the clip seconds
- * already played at a mid-clip seek (0 for a clean start, negative before the
- * span begins).
- */
+/** Builds the Web Audio graph for a clip's effect chain after an already-created `source`, shared by live playback ({@link WebAudioSink}) and offline export (`mixAudio`) so both sound identical. `startTime` is the context time the source starts; `clipDuration` the clip seconds ramps run over (a clip's, or a bus's span); `elapsed` the clip seconds already played at a mid-clip seek (0 for a clean start, negative before the span begins). */
 export function buildAudioEffectGraph(ctx, source, effects, startTime = ctx.currentTime, clipDuration = 0, elapsed = 0) {
     const nodes = [];
     const oscillators = [];
@@ -149,10 +132,7 @@ function clamp01(v) {
 function maxOf(p) {
     return isRamp(p) ? Math.max(0, ...p.keys.map((k) => k.value)) : p;
 }
-/**
- * Schedule `transitionIn`/`transitionOut` onto a gain over a span `length`
- * seconds long, baked like an eased ramp. Between the two it holds at 1.
- */
+/** Schedules `transitionIn`/`transitionOut` onto a gain over a span `length` seconds long, baked like an eased ramp; holds at 1 between them. */
 export function applyTransitions(gain, length, transitionIn, transitionOut, startTime, elapsed) {
     if (!transitionIn && !transitionOut)
         return;
@@ -209,14 +189,7 @@ export function buildLevel(ctx, from, req, playback, startTime, elapsed) {
     level.connect(transition);
     return { output: transition, nodes: [level, transition] };
 }
-/**
- * Schedule a speed ramp onto an `AudioBufferSourceNode.playbackRate`.
- *
- * The ramp runs over **source** seconds and Web Audio schedules in context
- * seconds, so this walks clip time in small steps, converts each to a source
- * offset through the integral inverse, and lays down the rate there. `elapsed`
- * is clip seconds already played at a mid-clip seek.
- */
+/** Schedules a speed ramp onto `playbackRate`. The ramp runs over **source** seconds and Web Audio schedules in context seconds, so this walks clip time in small steps and converts each through the integral inverse. `elapsed` is clip seconds already played at a mid-clip seek. */
 export function applySpeedToPlaybackRate(rate, speed, sourceLength, clipDuration, startTime, elapsed) {
     if (!speed)
         return;