@motionscript/browser 0.1.0-alpha.9 → 0.1.1-alpha.0

package/dist/browser/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionscript/browser",
-  "version": "0.1.0-alpha.8",
+  "version": "0.1.0",
   "exports": {
     ".": "dist/browser/index.js",
     "./audio": "dist/browser/audio.js"

package/dist/concat.d.ts

@@ -1,79 +1,35 @@
 /**
- * Join encoded MP4 or WebM segments end to end, without re-encoding.
- *
- * The point of this is what it *doesn't* do: no decode, no encode, no pixels.
- * Each segment is demuxed to its encoded packets, the packets are re-stamped onto
- * one continuous timeline, and a single muxer writes them into one container. The
- * bytes of every frame survive untouched, so the result is bit-identical to the
- * segments and the whole thing runs at I/O speed rather than encode speed.
- *
- * It exists so an export can be **split across workers**. Rendering a timeline is
- * embarrassingly parallel per scene — each scene's generator is independent — but
- * the output has to be one file, and re-encoding the parts to join them would give
- * back everything the parallelism won (and lose a generation of quality). Joining
- * at the packet level is what makes splitting worth doing.
- *
- * ## What the caller has to guarantee
- *
- * **Every segment must be encoded with an identical configuration** — same
- * container, codec, resolution and bitrate settings. A container carries exactly one decoder
- * configuration for a track, so a segment whose parameter sets differ from the
- * first would be described by a configuration that isn't its own, and decode as
- * garbage from that point on. That is not a theoretical concern: hardware encoders
- * are free to pick different parameter sets for the same nominal settings. This is
- * checked rather than assumed — see {@link ConcatMismatchError} — because the
- * failure is silent corruption rather than an exception.
- *
- * **Every segment must begin with a key frame.** Otherwise its first packets refer
- * back to frames that lived in the previous segment's GOP and no longer precede
- * them. Encoders start with a key frame by default; a caller choosing an explicit
- * `keyFrameInterval` needs it to divide the segment length.
- *
- * Audio is *muxed* here but never *joined*: the segments' own audio is ignored
- * entirely, and a single already-mixed buffer is encoded once across the whole
- * result (see {@link ConcatOptions.audio}). Concatenating separately-encoded AAC
- * would put the encoder's priming delay at every join — a click at each boundary
- * and a track that drifts further out of sync with every one — so the timeline's
- * audio is mixed in one pass by whoever owns the timeline, and arrives here as
- * one buffer.
+ * Joins encoded MP4 or WebM segments end to end without re-encoding: segments are demuxed to packets, re-stamped onto
+ * one timeline and muxed into one container, so frame bytes survive untouched and it runs at I/O speed. It exists so an
+ * export can be **split across workers** without re-encoding the parts (which would lose a generation of quality).
+ *
+ * The caller must guarantee: **every segment is encoded with an identical configuration** (container, codec,
+ * resolution, bitrate settings), since a container carries one decoder configuration per track and a differing one
+ * decodes as garbage from that point (hardware encoders may pick different parameter sets for the same settings; this
+ * is checked, see {@link ConcatMismatchError}, because the failure is silent). And **every segment begins with a key
+ * frame**; a caller choosing an explicit `keyFrameInterval` needs it to divide the segment length.
+ *
+ * Audio is *muxed* here but never *joined*: the segments' own audio is ignored and one already-mixed buffer is encoded
+ * across the whole result (see {@link ConcatOptions.audio}), because separately-encoded AAC puts the encoder's priming
+ * delay at every join.
  */
 /** Thrown when segments can't be joined losslessly. Carries which segment disagreed. */
 export declare class ConcatMismatchError extends Error {
-    /** Index of the offending segment in the input array. */
     readonly segment: number;
-    constructor(
-    /** Index of the offending segment in the input array. */
-    segment: number, message: string);
+    constructor(segment: number, message: string);
 }
 export interface ConcatOptions {
-    /**
-     * One continuous audio track for the whole joined timeline.
-     *
-     * Mixed once by the caller (see `mixTimelineAudio`) rather than per segment,
-     * and that is not a convenience: separately-encoded AAC carries an encoder
-     * priming delay at the head of each piece, so joining them puts a click at
-     * every scene boundary and drifts the track further out of sync with each
-     * one. One buffer in, one encode, no seams.
-     */
+    /** One continuous audio track, mixed once by the caller (see `mixTimelineAudio`): separately-encoded AAC carries a priming delay per piece, so joining them clicks at every boundary and drifts out of sync. */
     audio?: AudioBuffer | null;
     /** Bitrate for that track: AAC in an MP4, Opus in a WebM. Defaults to 192 kbps. */
     audioBitrate?: number;
     /**
-     * Write the result out as it is muxed instead of returning it.
-     *
-     * With this the joined file never exists in memory as one buffer, which is
-     * the difference between an export the process can hold and one it can't:
-     * a 4× 60fps render is hundreds of megabytes, and the default path costs
-     * roughly twice that at the tail once the `Blob` copy is counted.
+     * Write the result out as it is muxed instead of returning it, so the joined file never exists in memory as one
+     * buffer (a 4x 60fps render is hundreds of megabytes, twice that at the tail once the `Blob` copy is counted).
      *
-     * **Chunks carry a byte `position` and do not arrive in file order** — a
-     * muxer seeks back to patch atom sizes. A sink that appends will produce a
-     * file of exactly the right length whose size fields belong to a different
-     * one: unplayable, and indistinguishable from success until it is opened.
-     * Honour `position`.
-     *
-     * `concatVideoSegments` resolves to an empty array when this is used; the
-     * bytes went to the sink.
+     * **Chunks carry a byte `position` and do not arrive in file order** (a muxer seeks back to patch atom sizes). A sink
+     * that appends produces a file of the right length that is unplayable, indistinguishable from success until opened.
+     * Honour `position`. `concatVideoSegments` resolves to an empty array when this is used.
      */
     stream?: WritableStream<{
         type: "write";
@@ -84,8 +40,7 @@ export interface ConcatOptions {
 /** Joins segments one at a time, in timeline order, as each becomes available. */
 export interface SegmentJoiner {
     /**
-     * Mux the next segment after the ones already appended. Appends must not
-     * overlap: await each before starting the next.
+     * Appends must not overlap: await each before starting the next.
      *
      * @throws {ConcatMismatchError} as {@link concatVideoSegments} does.
      */
@@ -95,27 +50,13 @@ export interface SegmentJoiner {
     /** Abandon the join; nothing more is written. */
     cancel(): Promise<void>;
 }
-/**
- * {@link concatVideoSegments} one segment at a time, so a split export can write
- * each piece the moment it and every piece before it exist, instead of holding
- * every segment until the last one lands.
- *
- * The audio, when given, is encoded as soon as the first segment fixes the
- * container, ahead of the video: the muxer holds the (small) audio packets and
- * interleaves them as the video catches up.
- */
+/** {@link concatVideoSegments} one segment at a time, so a split export writes each piece as soon as it and every piece before it exist. Audio is encoded as soon as the first segment fixes the container, ahead of the video; the muxer interleaves it as the video catches up. */
 export declare function createSegmentJoiner(options?: ConcatOptions): SegmentJoiner;
 /**
- * Concatenate `segments` (each a complete MP4, or each a complete WebM) into one
- * file of the same container.
- *
- * Segments are joined in array order. Returns the muxed bytes.
+ * Concatenates `segments` (all MP4 or all WebM) in array order into one file of the same container.
  *
- * @throws {ConcatMismatchError} if a segment carries no video track, is in another
- *         container than the first, or has a decoder configuration that differs
- *         from the first segment's. Callers that can
- *         fall back to a single-threaded export should catch this and do so — the
- *         alternative is shipping a file that decodes into garbage halfway through.
+ * @throws {ConcatMismatchError} if a segment has no video track, is in another container than the first, or has a
+ *         differing decoder configuration. Callers that can fall back to a single-threaded export should catch this.
  */
 export declare function concatVideoSegments(segments: Uint8Array[], options?: ConcatOptions): Promise<Uint8Array>;
 //# sourceMappingURL=concat.d.ts.map

package/dist/concat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"concat.d.ts","sourceRoot":"","sources":["../src/concat.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,wFAAwF;AACxF,qBAAa,mBAAoB,SAAQ,KAAK;IAEtC,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM;;IADxB,yDAAyD;IAChD,OAAO,EAAE,MAAM,EACxB,OAAO,EAAE,MAAM;CAKtB;AA2CD,MAAM,WAAW,aAAa;IAC1B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClF;AAED,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC1B;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,qFAAqF;IACrF,MAAM,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAC9B,iDAAiD;IACjD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,aAAkB,GAAG,aAAa,CAoE9E;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACrC,QAAQ,EAAE,UAAU,EAAE,EACtB,OAAO,GAAE,aAAkB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAcrB"}
+{"version":3,"file":"concat.d.ts","sourceRoot":"","sources":["../src/concat.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;GAcG;AAEH,wFAAwF;AACxF,qBAAa,mBAAoB,SAAQ,KAAK;IAEtC,QAAQ,CAAC,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM,EACxB,OAAO,EAAE,MAAM;CAKtB;AAoCD,MAAM,WAAW,aAAa;IAC1B,gNAAgN;IAChN,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClF;AAED,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC1B;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,qFAAqF;IACrF,MAAM,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAC9B,iDAAiD;IACjD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,qRAAqR;AACrR,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,aAAkB,GAAG,aAAa,CAgE9E;AAuBD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACrC,QAAQ,EAAE,UAAU,EAAE,EACtB,OAAO,GAAE,aAAkB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAcrB"}

package/dist/concat.js

@@ -1,62 +1,30 @@
 import { BufferSource, BufferTarget, EncodedPacketSink, EncodedVideoPacketSource, Input, MP4, Output, StreamTarget, WEBM, } from "mediabunny";
 import { audioTrackSource, formatSpec } from "./formats";
 /**
- * Join encoded MP4 or WebM segments end to end, without re-encoding.
+ * Joins encoded MP4 or WebM segments end to end without re-encoding: segments are demuxed to packets, re-stamped onto
+ * one timeline and muxed into one container, so frame bytes survive untouched and it runs at I/O speed. It exists so an
+ * export can be **split across workers** without re-encoding the parts (which would lose a generation of quality).
  *
- * The point of this is what it *doesn't* do: no decode, no encode, no pixels.
- * Each segment is demuxed to its encoded packets, the packets are re-stamped onto
- * one continuous timeline, and a single muxer writes them into one container. The
- * bytes of every frame survive untouched, so the result is bit-identical to the
- * segments and the whole thing runs at I/O speed rather than encode speed.
+ * The caller must guarantee: **every segment is encoded with an identical configuration** (container, codec,
+ * resolution, bitrate settings), since a container carries one decoder configuration per track and a differing one
+ * decodes as garbage from that point (hardware encoders may pick different parameter sets for the same settings; this
+ * is checked, see {@link ConcatMismatchError}, because the failure is silent). And **every segment begins with a key
+ * frame**; a caller choosing an explicit `keyFrameInterval` needs it to divide the segment length.
  *
- * It exists so an export can be **split across workers**. Rendering a timeline is
- * embarrassingly parallel per scene — each scene's generator is independent — but
- * the output has to be one file, and re-encoding the parts to join them would give
- * back everything the parallelism won (and lose a generation of quality). Joining
- * at the packet level is what makes splitting worth doing.
- *
- * ## What the caller has to guarantee
- *
- * **Every segment must be encoded with an identical configuration** — same
- * container, codec, resolution and bitrate settings. A container carries exactly one decoder
- * configuration for a track, so a segment whose parameter sets differ from the
- * first would be described by a configuration that isn't its own, and decode as
- * garbage from that point on. That is not a theoretical concern: hardware encoders
- * are free to pick different parameter sets for the same nominal settings. This is
- * checked rather than assumed — see {@link ConcatMismatchError} — because the
- * failure is silent corruption rather than an exception.
- *
- * **Every segment must begin with a key frame.** Otherwise its first packets refer
- * back to frames that lived in the previous segment's GOP and no longer precede
- * them. Encoders start with a key frame by default; a caller choosing an explicit
- * `keyFrameInterval` needs it to divide the segment length.
- *
- * Audio is *muxed* here but never *joined*: the segments' own audio is ignored
- * entirely, and a single already-mixed buffer is encoded once across the whole
- * result (see {@link ConcatOptions.audio}). Concatenating separately-encoded AAC
- * would put the encoder's priming delay at every join — a click at each boundary
- * and a track that drifts further out of sync with every one — so the timeline's
- * audio is mixed in one pass by whoever owns the timeline, and arrives here as
- * one buffer.
+ * Audio is *muxed* here but never *joined*: the segments' own audio is ignored and one already-mixed buffer is encoded
+ * across the whole result (see {@link ConcatOptions.audio}), because separately-encoded AAC puts the encoder's priming
+ * delay at every join.
  */
 /** Thrown when segments can't be joined losslessly. Carries which segment disagreed. */
 export class ConcatMismatchError extends Error {
     segment;
-    constructor(
-    /** Index of the offending segment in the input array. */
-    segment, message) {
+    constructor(segment, message) {
         super(message);
         this.segment = segment;
         this.name = "ConcatMismatchError";
     }
 }
-/**
- * Two decoder configurations describe the same bitstream.
- *
- * `description` holds the codec's parameter sets (the `avcC` box for H.264) and is
- * the field that actually decides decodability — a differing one is exactly the
- * silent-corruption case. Compared bytewise; the rest are compared by value.
- */
+/** Two decoder configurations describe the same bitstream. `description` (parameter sets, the `avcC` box for H.264) decides decodability and is compared bytewise; the rest by value. */
 function sameDecoderConfig(a, b) {
     if (a.codec !== b.codec)
         return false;
@@ -87,15 +55,7 @@ function toBytes(description) {
     }
     return new Uint8Array(description);
 }
-/**
- * {@link concatVideoSegments} one segment at a time, so a split export can write
- * each piece the moment it and every piece before it exist, instead of holding
- * every segment until the last one lands.
- *
- * The audio, when given, is encoded as soon as the first segment fixes the
- * container, ahead of the video: the muxer holds the (small) audio packets and
- * interleaves them as the video catches up.
- */
+/** {@link concatVideoSegments} one segment at a time, so a split export writes each piece as soon as it and every piece before it exist. Audio is encoded as soon as the first segment fixes the container, ahead of the video; the muxer interleaves it as the video catches up. */
 export function createSegmentJoiner(options = {}) {
     let first = null;
     let output = null;
@@ -109,9 +69,7 @@ export function createSegmentJoiner(options = {}) {
             ? new StreamTarget(options.stream)
             : new BufferTarget();
         output = new Output({ format: formatSpec(segment.format).container(), target });
-        // `codec` comes off the track rather than the decoder config: the latter's
-        // `codec` is the full codec *string* (`avc1.64001f`), while the source wants
-        // the family.
+        // `codec` comes off the track: the decoder config's is the full codec *string* (`avc1.64001f`), the source wants the family.
         source = new EncodedVideoPacketSource(segment.track.codec);
         output.addVideoTrack(source);
         // Declared before `start()`: a muxer fixes its track list up front.
@@ -132,9 +90,7 @@ export function createSegmentJoiner(options = {}) {
                     first = segment;
                     await start(segment);
                 }
-                // The decoder config is handed over with each segment's first packet.
-                // Only the first can take effect (a container holds one per track), but
-                // every one has been checked equal to it.
+                // The decoder config rides each segment's first packet; only the first can take effect (one per track), but all were checked equal.
                 let leading = true;
                 for await (const packet of new EncodedPacketSink(segment.track).packets()) {
                     await source.add(packet.clone({ timestamp: packet.timestamp + offset }), leading ? { decoderConfig: segment.config } : undefined);
@@ -187,16 +143,10 @@ async function openSegment(input, i, first) {
     return { format, track, config, duration: await track.computeDuration() };
 }
 /**
- * Concatenate `segments` (each a complete MP4, or each a complete WebM) into one
- * file of the same container.
- *
- * Segments are joined in array order. Returns the muxed bytes.
+ * Concatenates `segments` (all MP4 or all WebM) in array order into one file of the same container.
  *
- * @throws {ConcatMismatchError} if a segment carries no video track, is in another
- *         container than the first, or has a decoder configuration that differs
- *         from the first segment's. Callers that can
- *         fall back to a single-threaded export should catch this and do so — the
- *         alternative is shipping a file that decodes into garbage halfway through.
+ * @throws {ConcatMismatchError} if a segment has no video track, is in another container than the first, or has a
+ *         differing decoder configuration. Callers that can fall back to a single-threaded export should catch this.
  */
 export async function concatVideoSegments(segments, options = {}) {
     if (segments.length === 0)

package/dist/concat.js.map

@@ -1 +1 @@
-{"version":3,"file":"concat.js","sourceRoot":"","sources":["../src/concat.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    BufferSource,\n    BufferTarget,\n    EncodedPacketSink,\n    EncodedVideoPacketSource,\n    Input,\n    MP4,\n    Output,\n    StreamTarget,\n    WEBM,\n    type InputVideoTrack,\n    type VideoCodec,\n} from \"mediabunny\";\n\nimport { audioTrackSource, formatSpec, type VideoFormat } from \"./formats\";\n\n/**\n * Join encoded MP4 or WebM segments end to end, without re-encoding.\n *\n * The point of this is what it *doesn't* do: no decode, no encode, no pixels.\n * Each segment is demuxed to its encoded packets, the packets are re-stamped onto\n * one continuous timeline, and a single muxer writes them into one container. The\n * bytes of every frame survive untouched, so the result is bit-identical to the\n * segments and the whole thing runs at I/O speed rather than encode speed.\n *\n * It exists so an export can be **split across workers**. Rendering a timeline is\n * embarrassingly parallel per scene — each scene's generator is independent — but\n * the output has to be one file, and re-encoding the parts to join them would give\n * back everything the parallelism won (and lose a generation of quality). Joining\n * at the packet level is what makes splitting worth doing.\n *\n * ## What the caller has to guarantee\n *\n * **Every segment must be encoded with an identical configuration** — same\n * container, codec, resolution and bitrate settings. A container carries exactly one decoder\n * configuration for a track, so a segment whose parameter sets differ from the\n * first would be described by a configuration that isn't its own, and decode as\n * garbage from that point on. That is not a theoretical concern: hardware encoders\n * are free to pick different parameter sets for the same nominal settings. This is\n * checked rather than assumed — see {@link ConcatMismatchError} — because the\n * failure is silent corruption rather than an exception.\n *\n * **Every segment must begin with a key frame.** Otherwise its first packets refer\n * back to frames that lived in the previous segment's GOP and no longer precede\n * them. Encoders start with a key frame by default; a caller choosing an explicit\n * `keyFrameInterval` needs it to divide the segment length.\n *\n * Audio is *muxed* here but never *joined*: the segments' own audio is ignored\n * entirely, and a single already-mixed buffer is encoded once across the whole\n * result (see {@link ConcatOptions.audio}). Concatenating separately-encoded AAC\n * would put the encoder's priming delay at every join — a click at each boundary\n * and a track that drifts further out of sync with every one — so the timeline's\n * audio is mixed in one pass by whoever owns the timeline, and arrives here as\n * one buffer.\n */\n\n/** Thrown when segments can't be joined losslessly. Carries which segment disagreed. */\nexport class ConcatMismatchError extends Error {\n    constructor(\n        /** Index of the offending segment in the input array. */\n        readonly segment: number,\n        message: string,\n    ) {\n        super(message);\n        this.name = \"ConcatMismatchError\";\n    }\n}\n\n/** One segment's demuxed video track, plus the config that describes it. */\ninterface Segment {\n    format: VideoFormat;\n    track: InputVideoTrack;\n    config: VideoDecoderConfig;\n    duration: number;\n}\n\n/**\n * Two decoder configurations describe the same bitstream.\n *\n * `description` holds the codec's parameter sets (the `avcC` box for H.264) and is\n * the field that actually decides decodability — a differing one is exactly the\n * silent-corruption case. Compared bytewise; the rest are compared by value.\n */\nfunction sameDecoderConfig(a: VideoDecoderConfig, b: VideoDecoderConfig): boolean {\n    if (a.codec !== b.codec) return false;\n    if (a.codedWidth !== b.codedWidth) return false;\n    if (a.codedHeight !== b.codedHeight) return false;\n\n    const da = toBytes(a.description);\n    const db = toBytes(b.description);\n    if (da === null || db === null) return da === db;\n    if (da.length !== db.length) return false;\n    for (let i = 0; i < da.length; i++) {\n        if (da[i] !== db[i]) return false;\n    }\n    return true;\n}\n\nfunction toBytes(description: VideoDecoderConfig[\"description\"]): Uint8Array | null {\n    if (!description) return null;\n    // `description` is a BufferSource: an ArrayBuffer, a SharedArrayBuffer, or any\n    // view over one. Views carry an offset into a larger buffer, so they must be\n    // narrowed rather than wrapped whole.\n    if (ArrayBuffer.isView(description)) {\n        return new Uint8Array(description.buffer, description.byteOffset, description.byteLength);\n    }\n    return new Uint8Array(description);\n}\n\nexport interface ConcatOptions {\n    /**\n     * One continuous audio track for the whole joined timeline.\n     *\n     * Mixed once by the caller (see `mixTimelineAudio`) rather than per segment,\n     * and that is not a convenience: separately-encoded AAC carries an encoder\n     * priming delay at the head of each piece, so joining them puts a click at\n     * every scene boundary and drifts the track further out of sync with each\n     * one. One buffer in, one encode, no seams.\n     */\n    audio?: AudioBuffer | null;\n    /** Bitrate for that track: AAC in an MP4, Opus in a WebM. Defaults to 192 kbps. */\n    audioBitrate?: number;\n    /**\n     * Write the result out as it is muxed instead of returning it.\n     *\n     * With this the joined file never exists in memory as one buffer, which is\n     * the difference between an export the process can hold and one it can't:\n     * a 4× 60fps render is hundreds of megabytes, and the default path costs\n     * roughly twice that at the tail once the `Blob` copy is counted.\n     *\n     * **Chunks carry a byte `position` and do not arrive in file order** — a\n     * muxer seeks back to patch atom sizes. A sink that appends will produce a\n     * file of exactly the right length whose size fields belong to a different\n     * one: unplayable, and indistinguishable from success until it is opened.\n     * Honour `position`.\n     *\n     * `concatVideoSegments` resolves to an empty array when this is used; the\n     * bytes went to the sink.\n     */\n    stream?: WritableStream<{ type: \"write\"; data: Uint8Array; position: number }>;\n}\n\n/** Joins segments one at a time, in timeline order, as each becomes available. */\nexport interface SegmentJoiner {\n    /**\n     * Mux the next segment after the ones already appended. Appends must not\n     * overlap: await each before starting the next.\n     *\n     * @throws {ConcatMismatchError} as {@link concatVideoSegments} does.\n     */\n    append(segment: Uint8Array): Promise<void>;\n    /** Finish the container. The bytes, or an empty array when they went to `stream`. */\n    finish(): Promise<Uint8Array>;\n    /** Abandon the join; nothing more is written. */\n    cancel(): Promise<void>;\n}\n\n/**\n * {@link concatVideoSegments} one segment at a time, so a split export can write\n * each piece the moment it and every piece before it exist, instead of holding\n * every segment until the last one lands.\n *\n * The audio, when given, is encoded as soon as the first segment fixes the\n * container, ahead of the video: the muxer holds the (small) audio packets and\n * interleaves them as the video catches up.\n */\nexport function createSegmentJoiner(options: ConcatOptions = {}): SegmentJoiner {\n    let first: Segment | null = null;\n    let output: Output | null = null;\n    let source: EncodedVideoPacketSource | null = null;\n    let audioSource: ReturnType<typeof audioTrackSource> | null = null;\n    let target: StreamTarget | BufferTarget | null = null;\n    let index = 0;\n    let offset = 0;\n\n    const start = async (segment: Segment) => {\n        target = options.stream\n            ? new StreamTarget(options.stream as ConstructorParameters<typeof StreamTarget>[0])\n            : new BufferTarget();\n        output = new Output({ format: formatSpec(segment.format).container(), target });\n        // `codec` comes off the track rather than the decoder config: the latter's\n        // `codec` is the full codec *string* (`avc1.64001f`), while the source wants\n        // the family.\n        source = new EncodedVideoPacketSource(segment.track.codec as VideoCodec);\n        output.addVideoTrack(source);\n        // Declared before `start()`: a muxer fixes its track list up front.\n        audioSource = options.audio ? audioTrackSource(segment.format, options.audioBitrate) : null;\n        if (audioSource) output.addAudioTrack(audioSource);\n        await output.start();\n        if (audioSource && options.audio) await audioSource.add(options.audio);\n    };\n\n    return {\n        async append(bytes) {\n            const i = index++;\n            const input = new Input({ source: new BufferSource(bytes), formats: [MP4, WEBM] });\n            try {\n                const segment = await openSegment(input, i, first);\n                if (!first) {\n                    first = segment;\n                    await start(segment);\n                }\n                // The decoder config is handed over with each segment's first packet.\n                // Only the first can take effect (a container holds one per track), but\n                // every one has been checked equal to it.\n                let leading = true;\n                for await (const packet of new EncodedPacketSink(segment.track).packets()) {\n                    await source!.add(\n                        packet.clone({ timestamp: packet.timestamp + offset }),\n                        leading ? { decoderConfig: segment.config } : undefined,\n                    );\n                    leading = false;\n                }\n                // The segment's own duration rather than its last packet's end: summing\n                // packet durations accumulates rounding into a drift across many segments.\n                offset += segment.duration;\n            } finally {\n                input.dispose();\n            }\n        },\n        async finish() {\n            if (!output) throw new Error(\"concatVideoSegments: no segments\");\n            source!.close();\n            audioSource?.close();\n            await output.finalize();\n            if (options.stream) return new Uint8Array(0);\n            const buffer = (target as BufferTarget).buffer;\n            if (!buffer) throw new Error(\"concatVideoSegments produced no data\");\n            return new Uint8Array(buffer);\n        },\n        async cancel() {\n            if (output && output.state !== \"finalized\" && output.state !== \"canceled\") await output.cancel();\n        },\n    };\n}\n\n/** Demux one segment and check it can follow `first`. */\nasync function openSegment(input: Input, i: number, first: Segment | null): Promise<Segment> {\n    const format: VideoFormat = (await input.getFormat()) === WEBM ? \"webm\" : \"mp4\";\n    if (first && format !== first.format) {\n        throw new ConcatMismatchError(i, `Segment ${i} is ${format} and segment 0 is ${first.format}.`);\n    }\n    const track = await input.getPrimaryVideoTrack();\n    if (!track) throw new ConcatMismatchError(i, `Segment ${i} has no video track.`);\n    const config = await track.getDecoderConfig();\n    if (!config) throw new ConcatMismatchError(i, `Segment ${i} has no decoder configuration.`);\n    if (first && !sameDecoderConfig(first.config, config)) {\n        throw new ConcatMismatchError(\n            i,\n            `Segment ${i} was encoded differently from segment 0 (${first.config.codec} `\n            + `${first.config.codedWidth}x${first.config.codedHeight} vs ${config.codec} `\n            + `${config.codedWidth}x${config.codedHeight}); joining them would decode as garbage.`,\n        );\n    }\n    return { format, track, config, duration: await track.computeDuration() };\n}\n\n/**\n * Concatenate `segments` (each a complete MP4, or each a complete WebM) into one\n * file of the same container.\n *\n * Segments are joined in array order. Returns the muxed bytes.\n *\n * @throws {ConcatMismatchError} if a segment carries no video track, is in another\n *         container than the first, or has a decoder configuration that differs\n *         from the first segment's. Callers that can\n *         fall back to a single-threaded export should catch this and do so — the\n *         alternative is shipping a file that decodes into garbage halfway through.\n */\nexport async function concatVideoSegments(\n    segments: Uint8Array[],\n    options: ConcatOptions = {},\n): Promise<Uint8Array> {\n    if (segments.length === 0) throw new Error(\"concatVideoSegments: no segments\");\n    // A lone segment is already the finished file — unless a track has to be added\n    // to it, or it has to go to a sink, either of which means muxing after all.\n    if (segments.length === 1 && !options.audio && !options.stream) return segments[0];\n\n    const joiner = createSegmentJoiner(options);\n    try {\n        for (const segment of segments) await joiner.append(segment);\n        return await joiner.finish();\n    } catch (error) {\n        await joiner.cancel().catch(() => {});\n        throw error;\n    }\n}\n"]}
+{"version":3,"file":"concat.js","sourceRoot":"","sources":["../src/concat.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,wBAAwB,EACxB,KAAK,EACL,GAAG,EACH,MAAM,EACN,YAAY,EACZ,IAAI,GAGP,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAoB,MAAM,WAAW,CAAC;AAE3E;;;;;;;;;;;;;;GAcG;AAEH,wFAAwF;AACxF,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAE7B;IADb,YACa,OAAe,EACxB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,YAAO,GAAP,OAAO,CAAQ;QAIxB,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACtC,CAAC;CACJ;AASD,yLAAyL;AACzL,SAAS,iBAAiB,CAAC,CAAqB,EAAE,CAAqB;IACnE,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAElD,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IAClC,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IAClC,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACjD,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACjC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACtC,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,SAAS,OAAO,CAAC,WAA8C;IAC3D,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAC9B,+EAA+E;IAC/E,6EAA6E;IAC7E,sCAAsC;IACtC,IAAI,WAAW,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QAClC,OAAO,IAAI,UAAU,CAAC,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,UAAU,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,IAAI,UAAU,CAAC,WAAW,CAAC,CAAC;AACvC,CAAC;AAgCD,qRAAqR;AACrR,MAAM,UAAU,mBAAmB,CAAC,UAAyB,EAAE;IAC3D,IAAI,KAAK,GAAmB,IAAI,CAAC;IACjC,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,IAAI,MAAM,GAAoC,IAAI,CAAC;IACnD,IAAI,WAAW,GAA+C,IAAI,CAAC;IACnE,IAAI,MAAM,GAAuC,IAAI,CAAC;IACtD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,MAAM,KAAK,GAAG,KAAK,EAAE,OAAgB,EAAE,EAAE;QACrC,MAAM,GAAG,OAAO,CAAC,MAAM;YACnB,CAAC,CAAC,IAAI,YAAY,CAAC,OAAO,CAAC,MAAuD,CAAC;YACnF,CAAC,CAAC,IAAI,YAAY,EAAE,CAAC;QACzB,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QAChF,6HAA6H;QAC7H,MAAM,GAAG,IAAI,wBAAwB,CAAC,OAAO,CAAC,KAAK,CAAC,KAAmB,CAAC,CAAC;QACzE,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QAC7B,oEAAoE;QACpE,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC5F,IAAI,WAAW;YAAE,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;QACnD,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,WAAW,IAAI,OAAO,CAAC,KAAK;YAAE,MAAM,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3E,CAAC,CAAC;IAEF,OAAO;QACH,KAAK,CAAC,MAAM,CAAC,KAAK;YACd,MAAM,CAAC,GAAG,KAAK,EAAE,CAAC;YAClB,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;YACnF,IAAI,CAAC;gBACD,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;gBACnD,IAAI,CAAC,KAAK,EAAE,CAAC;oBACT,KAAK,GAAG,OAAO,CAAC;oBAChB,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;gBACzB,CAAC;gBACD,oIAAoI;gBACpI,IAAI,OAAO,GAAG,IAAI,CAAC;gBACnB,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,IAAI,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;oBACxE,MAAM,MAAO,CAAC,GAAG,CACb,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,GAAG,MAAM,EAAE,CAAC,EACtD,OAAO,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAC1D,CAAC;oBACF,OAAO,GAAG,KAAK,CAAC;gBACpB,CAAC;gBACD,wEAAwE;gBACxE,2EAA2E;gBAC3E,MAAM,IAAI,OAAO,CAAC,QAAQ,CAAC;YAC/B,CAAC;oBAAS,CAAC;gBACP,KAAK,CAAC,OAAO,EAAE,CAAC;YACpB,CAAC;QACL,CAAC;QACD,KAAK,CAAC,MAAM;YACR,IAAI,CAAC,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;YACjE,MAAO,CAAC,KAAK,EAAE,CAAC;YAChB,WAAW,EAAE,KAAK,EAAE,CAAC;YACrB,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;YACxB,IAAI,OAAO,CAAC,MAAM;gBAAE,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;YAC7C,MAAM,MAAM,GAAI,MAAuB,CAAC,MAAM,CAAC;YAC/C,IAAI,CAAC,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;YACrE,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;QACD,KAAK,CAAC,MAAM;YACR,IAAI,MAAM,IAAI,MAAM,CAAC,KAAK,KAAK,WAAW,IAAI,MAAM,CAAC,KAAK,KAAK,UAAU;gBAAE,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;QACrG,CAAC;KACJ,CAAC;AACN,CAAC;AAED,yDAAyD;AACzD,KAAK,UAAU,WAAW,CAAC,KAAY,EAAE,CAAS,EAAE,KAAqB;IACrE,MAAM,MAAM,GAAgB,CAAC,MAAM,KAAK,CAAC,SAAS,EAAE,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;IAChF,IAAI,KAAK,IAAI,MAAM,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;QACnC,MAAM,IAAI,mBAAmB,CAAC,CAAC,EAAE,WAAW,CAAC,OAAO,MAAM,qBAAqB,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IACpG,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,oBAAoB,EAAE,CAAC;IACjD,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,mBAAmB,CAAC,CAAC,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;IACjF,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,gBAAgB,EAAE,CAAC;IAC9C,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,mBAAmB,CAAC,CAAC,EAAE,WAAW,CAAC,gCAAgC,CAAC,CAAC;IAC5F,IAAI,KAAK,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,mBAAmB,CACzB,CAAC,EACD,WAAW,CAAC,4CAA4C,KAAK,CAAC,MAAM,CAAC,KAAK,GAAG;cAC3E,GAAG,KAAK,CAAC,MAAM,CAAC,UAAU,IAAI,KAAK,CAAC,MAAM,CAAC,WAAW,OAAO,MAAM,CAAC,KAAK,GAAG;cAC5E,GAAG,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,WAAW,0CAA0C,CACzF,CAAC;IACN,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC,eAAe,EAAE,EAAE,CAAC;AAC9E,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACrC,QAAsB,EACtB,UAAyB,EAAE;IAE3B,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAC/E,+EAA+E;IAC/E,4EAA4E;IAC5E,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC;IAEnF,MAAM,MAAM,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC;QACD,KAAK,MAAM,OAAO,IAAI,QAAQ;YAAE,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC7D,OAAO,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACtC,MAAM,KAAK,CAAC;IAChB,CAAC;AACL,CAAC","sourcesContent":["import {\n    BufferSource,\n    BufferTarget,\n    EncodedPacketSink,\n    EncodedVideoPacketSource,\n    Input,\n    MP4,\n    Output,\n    StreamTarget,\n    WEBM,\n    type InputVideoTrack,\n    type VideoCodec,\n} from \"mediabunny\";\n\nimport { audioTrackSource, formatSpec, type VideoFormat } from \"./formats\";\n\n/**\n * Joins encoded MP4 or WebM segments end to end without re-encoding: segments are demuxed to packets, re-stamped onto\n * one timeline and muxed into one container, so frame bytes survive untouched and it runs at I/O speed. It exists so an\n * export can be **split across workers** without re-encoding the parts (which would lose a generation of quality).\n *\n * The caller must guarantee: **every segment is encoded with an identical configuration** (container, codec,\n * resolution, bitrate settings), since a container carries one decoder configuration per track and a differing one\n * decodes as garbage from that point (hardware encoders may pick different parameter sets for the same settings; this\n * is checked, see {@link ConcatMismatchError}, because the failure is silent). And **every segment begins with a key\n * frame**; a caller choosing an explicit `keyFrameInterval` needs it to divide the segment length.\n *\n * Audio is *muxed* here but never *joined*: the segments' own audio is ignored and one already-mixed buffer is encoded\n * across the whole result (see {@link ConcatOptions.audio}), because separately-encoded AAC puts the encoder's priming\n * delay at every join.\n */\n\n/** Thrown when segments can't be joined losslessly. Carries which segment disagreed. */\nexport class ConcatMismatchError extends Error {\n    constructor(\n        readonly segment: number,\n        message: string,\n    ) {\n        super(message);\n        this.name = \"ConcatMismatchError\";\n    }\n}\n\ninterface Segment {\n    format: VideoFormat;\n    track: InputVideoTrack;\n    config: VideoDecoderConfig;\n    duration: number;\n}\n\n/** Two decoder configurations describe the same bitstream. `description` (parameter sets, the `avcC` box for H.264) decides decodability and is compared bytewise; the rest by value. */\nfunction sameDecoderConfig(a: VideoDecoderConfig, b: VideoDecoderConfig): boolean {\n    if (a.codec !== b.codec) return false;\n    if (a.codedWidth !== b.codedWidth) return false;\n    if (a.codedHeight !== b.codedHeight) return false;\n\n    const da = toBytes(a.description);\n    const db = toBytes(b.description);\n    if (da === null || db === null) return da === db;\n    if (da.length !== db.length) return false;\n    for (let i = 0; i < da.length; i++) {\n        if (da[i] !== db[i]) return false;\n    }\n    return true;\n}\n\nfunction toBytes(description: VideoDecoderConfig[\"description\"]): Uint8Array | null {\n    if (!description) return null;\n    // `description` is a BufferSource: an ArrayBuffer, a SharedArrayBuffer, or any\n    // view over one. Views carry an offset into a larger buffer, so they must be\n    // narrowed rather than wrapped whole.\n    if (ArrayBuffer.isView(description)) {\n        return new Uint8Array(description.buffer, description.byteOffset, description.byteLength);\n    }\n    return new Uint8Array(description);\n}\n\nexport interface ConcatOptions {\n    /** One continuous audio track, mixed once by the caller (see `mixTimelineAudio`): separately-encoded AAC carries a priming delay per piece, so joining them clicks at every boundary and drifts out of sync. */\n    audio?: AudioBuffer | null;\n    /** Bitrate for that track: AAC in an MP4, Opus in a WebM. Defaults to 192 kbps. */\n    audioBitrate?: number;\n    /**\n     * Write the result out as it is muxed instead of returning it, so the joined file never exists in memory as one\n     * buffer (a 4x 60fps render is hundreds of megabytes, twice that at the tail once the `Blob` copy is counted).\n     *\n     * **Chunks carry a byte `position` and do not arrive in file order** (a muxer seeks back to patch atom sizes). A sink\n     * that appends produces a file of the right length that is unplayable, indistinguishable from success until opened.\n     * Honour `position`. `concatVideoSegments` resolves to an empty array when this is used.\n     */\n    stream?: WritableStream<{ type: \"write\"; data: Uint8Array; position: number }>;\n}\n\n/** Joins segments one at a time, in timeline order, as each becomes available. */\nexport interface SegmentJoiner {\n    /**\n     * Appends must not overlap: await each before starting the next.\n     *\n     * @throws {ConcatMismatchError} as {@link concatVideoSegments} does.\n     */\n    append(segment: Uint8Array): Promise<void>;\n    /** Finish the container. The bytes, or an empty array when they went to `stream`. */\n    finish(): Promise<Uint8Array>;\n    /** Abandon the join; nothing more is written. */\n    cancel(): Promise<void>;\n}\n\n/** {@link concatVideoSegments} one segment at a time, so a split export writes each piece as soon as it and every piece before it exist. Audio is encoded as soon as the first segment fixes the container, ahead of the video; the muxer interleaves it as the video catches up. */\nexport function createSegmentJoiner(options: ConcatOptions = {}): SegmentJoiner {\n    let first: Segment | null = null;\n    let output: Output | null = null;\n    let source: EncodedVideoPacketSource | null = null;\n    let audioSource: ReturnType<typeof audioTrackSource> | null = null;\n    let target: StreamTarget | BufferTarget | null = null;\n    let index = 0;\n    let offset = 0;\n\n    const start = async (segment: Segment) => {\n        target = options.stream\n            ? new StreamTarget(options.stream as ConstructorParameters<typeof StreamTarget>[0])\n            : new BufferTarget();\n        output = new Output({ format: formatSpec(segment.format).container(), target });\n        // `codec` comes off the track: the decoder config's is the full codec *string* (`avc1.64001f`), the source wants the family.\n        source = new EncodedVideoPacketSource(segment.track.codec as VideoCodec);\n        output.addVideoTrack(source);\n        // Declared before `start()`: a muxer fixes its track list up front.\n        audioSource = options.audio ? audioTrackSource(segment.format, options.audioBitrate) : null;\n        if (audioSource) output.addAudioTrack(audioSource);\n        await output.start();\n        if (audioSource && options.audio) await audioSource.add(options.audio);\n    };\n\n    return {\n        async append(bytes) {\n            const i = index++;\n            const input = new Input({ source: new BufferSource(bytes), formats: [MP4, WEBM] });\n            try {\n                const segment = await openSegment(input, i, first);\n                if (!first) {\n                    first = segment;\n                    await start(segment);\n                }\n                // The decoder config rides each segment's first packet; only the first can take effect (one per track), but all were checked equal.\n                let leading = true;\n                for await (const packet of new EncodedPacketSink(segment.track).packets()) {\n                    await source!.add(\n                        packet.clone({ timestamp: packet.timestamp + offset }),\n                        leading ? { decoderConfig: segment.config } : undefined,\n                    );\n                    leading = false;\n                }\n                // The segment's own duration rather than its last packet's end: summing\n                // packet durations accumulates rounding into a drift across many segments.\n                offset += segment.duration;\n            } finally {\n                input.dispose();\n            }\n        },\n        async finish() {\n            if (!output) throw new Error(\"concatVideoSegments: no segments\");\n            source!.close();\n            audioSource?.close();\n            await output.finalize();\n            if (options.stream) return new Uint8Array(0);\n            const buffer = (target as BufferTarget).buffer;\n            if (!buffer) throw new Error(\"concatVideoSegments produced no data\");\n            return new Uint8Array(buffer);\n        },\n        async cancel() {\n            if (output && output.state !== \"finalized\" && output.state !== \"canceled\") await output.cancel();\n        },\n    };\n}\n\n/** Demux one segment and check it can follow `first`. */\nasync function openSegment(input: Input, i: number, first: Segment | null): Promise<Segment> {\n    const format: VideoFormat = (await input.getFormat()) === WEBM ? \"webm\" : \"mp4\";\n    if (first && format !== first.format) {\n        throw new ConcatMismatchError(i, `Segment ${i} is ${format} and segment 0 is ${first.format}.`);\n    }\n    const track = await input.getPrimaryVideoTrack();\n    if (!track) throw new ConcatMismatchError(i, `Segment ${i} has no video track.`);\n    const config = await track.getDecoderConfig();\n    if (!config) throw new ConcatMismatchError(i, `Segment ${i} has no decoder configuration.`);\n    if (first && !sameDecoderConfig(first.config, config)) {\n        throw new ConcatMismatchError(\n            i,\n            `Segment ${i} was encoded differently from segment 0 (${first.config.codec} `\n            + `${first.config.codedWidth}x${first.config.codedHeight} vs ${config.codec} `\n            + `${config.codedWidth}x${config.codedHeight}); joining them would decode as garbage.`,\n        );\n    }\n    return { format, track, config, duration: await track.computeDuration() };\n}\n\n/**\n * Concatenates `segments` (all MP4 or all WebM) in array order into one file of the same container.\n *\n * @throws {ConcatMismatchError} if a segment has no video track, is in another container than the first, or has a\n *         differing decoder configuration. Callers that can fall back to a single-threaded export should catch this.\n */\nexport async function concatVideoSegments(\n    segments: Uint8Array[],\n    options: ConcatOptions = {},\n): Promise<Uint8Array> {\n    if (segments.length === 0) throw new Error(\"concatVideoSegments: no segments\");\n    // A lone segment is already the finished file — unless a track has to be added\n    // to it, or it has to go to a sink, either of which means muxing after all.\n    if (segments.length === 1 && !options.audio && !options.stream) return segments[0];\n\n    const joiner = createSegmentJoiner(options);\n    try {\n        for (const segment of segments) await joiner.append(segment);\n        return await joiner.finish();\n    } catch (error) {\n        await joiner.cancel().catch(() => {});\n        throw error;\n    }\n}\n"]}

package/dist/dynamic-nodes.d.ts

@@ -1,9 +1,4 @@
 import type { DynamicNodeConfig } from "@motionscript/core";
-/**
- * Resolves a full `DynamicNodeConfig`, filling in whatever the caller left
- * unset with `browser`'s own default. Synchronous — the WASM import happens
- * on `compile`'s first actual call, not here, so attaching this to every
- * engine costs nothing until a source string is genuinely registered.
- */
+/** Resolves a full `DynamicNodeConfig`, filling unset fields with `browser`'s default. Synchronous: the WASM import happens on `compile`'s first call, so attaching this to every engine is free until a source string is registered. */
 export declare function resolveDynamicNodes(partial: Partial<DynamicNodeConfig> | undefined, compilerWasmUrl?: string): DynamicNodeConfig;
 //# sourceMappingURL=dynamic-nodes.d.ts.map

package/dist/dynamic-nodes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-nodes.d.ts","sourceRoot":"","sources":["../src/dynamic-nodes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AA6C5D;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAC/B,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,SAAS,EAC/C,eAAe,CAAC,EAAE,MAAM,GACzB,iBAAiB,CAMnB"}
+{"version":3,"file":"dynamic-nodes.d.ts","sourceRoot":"","sources":["../src/dynamic-nodes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AA6B5D,yOAAyO;AACzO,wBAAgB,mBAAmB,CAC/B,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,SAAS,EAC/C,eAAe,CAAC,EAAE,MAAM,GACzB,iBAAiB,CAMnB"}

package/dist/dynamic-nodes.js

@@ -1,23 +1,7 @@
 import * as sdk from "@motionscript/core/sdk";
 import * as esbuild from "esbuild-wasm";
-/**
- * `browser`'s real, working default for `Registry.addNodeFromSource` — the
- * `sdk` half is cheap (re-exports, no WASM) and imported eagerly; the compiler
- * is the expensive half, and stays behind a lazy `import()` so an app that
- * never registers a source-string node never pays for it, however long the
- * engine has been running.
- *
- * `core` has no compiler dependency of its own and cannot import the published
- * `@motionscript/sdk` barrel (that package depends on `core`, so the reverse
- * would be circular) — `browser` is where this concern actually belongs: the
- * package whose entire job is "what running in an actual browser tab looks
- * like" already owns the renderer, `WebAudioSink` and `WebTicker` on exactly that
- * basis.
- */
-// Default to the wasm shipped by esbuild-wasm, resolved lazily — `import.meta.url`
-// is empty in a non-ESM output (an IIFE bundle, which is what the headless page
-// loads), and `new URL("…", "")` throws on import, before a caller has had the
-// chance to pass an explicit URL that would have made the default irrelevant.
+/** `browser`'s working default for `Registry.addNodeFromSource`: the cheap `sdk` half is imported eagerly, the compiler stays behind a lazy `import()` so an app that never registers a source-string node never pays for it. `core` cannot import the published `@motionscript/sdk` barrel (circular) and has no compiler dependency, so the concern lives here, which already owns the renderer, `WebAudioSink` and `WebTicker`. */
+// Default to the wasm shipped by esbuild-wasm, resolved lazily: `import.meta.url` is empty in a non-ESM output (the headless page's IIFE), and `new URL("…", "")` would throw on import before a caller could pass an explicit URL.
 function defaultCompilerWasmUrl() {
     return new URL("esbuild-wasm/esbuild.wasm", import.meta.url).href;
 }
@@ -37,12 +21,7 @@ function defaultCompiler(wasmUrl) {
         };
     })());
 }
-/**
- * Resolves a full `DynamicNodeConfig`, filling in whatever the caller left
- * unset with `browser`'s own default. Synchronous — the WASM import happens
- * on `compile`'s first actual call, not here, so attaching this to every
- * engine costs nothing until a source string is genuinely registered.
- */
+/** Resolves a full `DynamicNodeConfig`, filling unset fields with `browser`'s default. Synchronous: the WASM import happens on `compile`'s first call, so attaching this to every engine is free until a source string is registered. */
 export function resolveDynamicNodes(partial, compilerWasmUrl) {
     return {
         sdk: partial?.sdk ?? sdk,

package/dist/dynamic-nodes.js.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-nodes.js","sourceRoot":"","sources":["../src/dynamic-nodes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,GAAG,MAAM,wBAAwB,CAAC;AAC9C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AAExC;;;;;;;;;;;;;GAaG;AAEH,mFAAmF;AACnF,gFAAgF;AAChF,+EAA+E;AAC/E,8EAA8E;AAC9E,SAAS,sBAAsB;IAC3B,OAAO,IAAI,GAAG,CAAC,2BAA2B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;AACtE,CAAC;AAED,IAAI,eAAyE,CAAC;AAE9E,0CAA0C;AAC1C,SAAS,eAAe,CAAC,OAAgB;IACrC,OAAO,CAAC,eAAe,KAAK,CAAC,KAAK,IAAI,EAAE;QACpC,MAAM,OAAO,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,sBAAsB,EAAE,EAAE,CAAC,CAAC;QAC3E,OAAO,KAAK,EAAE,MAAc,EAAE,EAAE;YAC5B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE;gBAC7C,iEAAiE;gBACjE,MAAM,EAAE,IAAI;gBACZ,MAAM,EAAE,KAAK;gBACb,MAAM,EAAE,QAAQ;aACnB,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QAChB,CAAC,CAAC;IACN,CAAC,CAAC,EAAE,CAAC,CAAC;AACV,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAC/B,OAA+C,EAC/C,eAAwB;IAExB,OAAO;QACH,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,GAAG;QACxB,OAAO,EAAE,OAAO,EAAE,OAAO;QACzB,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,eAAe,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;KACpG,CAAC;AACN,CAAC","sourcesContent":["import type { DynamicNodeConfig } from \"@motionscript/core\";\nimport * as sdk from \"@motionscript/core/sdk\";\nimport * as esbuild from \"esbuild-wasm\";\n\n/**\n * `browser`'s real, working default for `Registry.addNodeFromSource` — the\n * `sdk` half is cheap (re-exports, no WASM) and imported eagerly; the compiler\n * is the expensive half, and stays behind a lazy `import()` so an app that\n * never registers a source-string node never pays for it, however long the\n * engine has been running.\n *\n * `core` has no compiler dependency of its own and cannot import the published\n * `@motionscript/sdk` barrel (that package depends on `core`, so the reverse\n * would be circular) — `browser` is where this concern actually belongs: the\n * package whose entire job is \"what running in an actual browser tab looks\n * like\" already owns the renderer, `WebAudioSink` and `WebTicker` on exactly that\n * basis.\n */\n\n// Default to the wasm shipped by esbuild-wasm, resolved lazily — `import.meta.url`\n// is empty in a non-ESM output (an IIFE bundle, which is what the headless page\n// loads), and `new URL(\"…\", \"\")` throws on import, before a caller has had the\n// chance to pass an explicit URL that would have made the default irrelevant.\nfunction defaultCompilerWasmUrl(): string {\n    return new URL(\"esbuild-wasm/esbuild.wasm\", import.meta.url).href;\n}\n\nlet compilerPromise: Promise<(source: string) => Promise<string>> | undefined;\n\n/** Loaded once, memoized process-wide. */\nfunction defaultCompiler(wasmUrl?: string): Promise<(source: string) => Promise<string>> {\n    return (compilerPromise ??= (async () => {\n        await esbuild.initialize({ wasmURL: wasmUrl ?? defaultCompilerWasmUrl() });\n        return async (source: string) => {\n            const { code } = await esbuild.transform(source, {\n                // A component is written with calls: there is no JSX to compile.\n                loader: \"ts\",\n                format: \"cjs\",\n                target: \"es2020\",\n            });\n            return code;\n        };\n    })());\n}\n\n/**\n * Resolves a full `DynamicNodeConfig`, filling in whatever the caller left\n * unset with `browser`'s own default. Synchronous — the WASM import happens\n * on `compile`'s first actual call, not here, so attaching this to every\n * engine costs nothing until a source string is genuinely registered.\n */\nexport function resolveDynamicNodes(\n    partial: Partial<DynamicNodeConfig> | undefined,\n    compilerWasmUrl?: string,\n): DynamicNodeConfig {\n    return {\n        sdk: partial?.sdk ?? sdk,\n        modules: partial?.modules,\n        compile: partial?.compile ?? (async (source) => (await defaultCompiler(compilerWasmUrl))(source)),\n    };\n}\n"]}
+{"version":3,"file":"dynamic-nodes.js","sourceRoot":"","sources":["../src/dynamic-nodes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,GAAG,MAAM,wBAAwB,CAAC;AAC9C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AAExC,saAAsa;AAEta,oOAAoO;AACpO,SAAS,sBAAsB;IAC3B,OAAO,IAAI,GAAG,CAAC,2BAA2B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;AACtE,CAAC;AAED,IAAI,eAAyE,CAAC;AAE9E,0CAA0C;AAC1C,SAAS,eAAe,CAAC,OAAgB;IACrC,OAAO,CAAC,eAAe,KAAK,CAAC,KAAK,IAAI,EAAE;QACpC,MAAM,OAAO,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,sBAAsB,EAAE,EAAE,CAAC,CAAC;QAC3E,OAAO,KAAK,EAAE,MAAc,EAAE,EAAE;YAC5B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE;gBAC7C,iEAAiE;gBACjE,MAAM,EAAE,IAAI;gBACZ,MAAM,EAAE,KAAK;gBACb,MAAM,EAAE,QAAQ;aACnB,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QAChB,CAAC,CAAC;IACN,CAAC,CAAC,EAAE,CAAC,CAAC;AACV,CAAC;AAED,yOAAyO;AACzO,MAAM,UAAU,mBAAmB,CAC/B,OAA+C,EAC/C,eAAwB;IAExB,OAAO;QACH,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,GAAG;QACxB,OAAO,EAAE,OAAO,EAAE,OAAO;QACzB,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,eAAe,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;KACpG,CAAC;AACN,CAAC","sourcesContent":["import type { DynamicNodeConfig } from \"@motionscript/core\";\nimport * as sdk from \"@motionscript/core/sdk\";\nimport * as esbuild from \"esbuild-wasm\";\n\n/** `browser`'s working default for `Registry.addNodeFromSource`: the cheap `sdk` half is imported eagerly, the compiler stays behind a lazy `import()` so an app that never registers a source-string node never pays for it. `core` cannot import the published `@motionscript/sdk` barrel (circular) and has no compiler dependency, so the concern lives here, which already owns the renderer, `WebAudioSink` and `WebTicker`. */\n\n// Default to the wasm shipped by esbuild-wasm, resolved lazily: `import.meta.url` is empty in a non-ESM output (the headless page's IIFE), and `new URL(\"…\", \"\")` would throw on import before a caller could pass an explicit URL.\nfunction defaultCompilerWasmUrl(): string {\n    return new URL(\"esbuild-wasm/esbuild.wasm\", import.meta.url).href;\n}\n\nlet compilerPromise: Promise<(source: string) => Promise<string>> | undefined;\n\n/** Loaded once, memoized process-wide. */\nfunction defaultCompiler(wasmUrl?: string): Promise<(source: string) => Promise<string>> {\n    return (compilerPromise ??= (async () => {\n        await esbuild.initialize({ wasmURL: wasmUrl ?? defaultCompilerWasmUrl() });\n        return async (source: string) => {\n            const { code } = await esbuild.transform(source, {\n                // A component is written with calls: there is no JSX to compile.\n                loader: \"ts\",\n                format: \"cjs\",\n                target: \"es2020\",\n            });\n            return code;\n        };\n    })());\n}\n\n/** Resolves a full `DynamicNodeConfig`, filling unset fields with `browser`'s default. Synchronous: the WASM import happens on `compile`'s first call, so attaching this to every engine is free until a source string is registered. */\nexport function resolveDynamicNodes(\n    partial: Partial<DynamicNodeConfig> | undefined,\n    compilerWasmUrl?: string,\n): DynamicNodeConfig {\n    return {\n        sdk: partial?.sdk ?? sdk,\n        modules: partial?.modules,\n        compile: partial?.compile ?? (async (source) => (await defaultCompiler(compilerWasmUrl))(source)),\n    };\n}\n"]}

package/dist/engine.d.ts

@@ -4,28 +4,11 @@ import { type RendererWasmOption } from "./renderer";
 import { type AudioEncoderOptions, type VideoEncoderOptions } from "./exporter";
 import { type ExportFormat } from "./formats";
 export interface BrowserEngineOptions extends Omit<EngineOptions, "nodes" | "dynamicNodes">, RendererWasmOption {
-    /**
-     * Node types any document opened here may name — components as an array
-     * or a record naming each key outright, same as `EngineOptions`, plus a
-     * TS source string in the **array** form only. A string default-exports a
-     * component, whose `key` is its key — the record form takes no string, so
-     * there is exactly one place a dynamic node's key comes from, not two that
-     * could disagree.
-     */
+    /** Node types any document opened here may name: components as an array or a record, plus a TS source string in the **array** form only (a string default-exports a component whose `key` is its key, so a dynamic node's key has one source). */
     nodes?: readonly (NodeConstructor | string)[] | NodeTypeMap;
-    /**
-     * Enables a source string in `nodes`, and `engine.registerNode(source)`
-     * at any point afterward. Any field left unset falls back to `browser`'s
-     * own default — `@motionscript/core/sdk` for `sdk`, a lazily-loaded
-     * `esbuild-wasm` for `compile` — so this never needs to be passed at all
-     * for the common case. `modules` has no default: only the host knows
-     * which loaded packages a script it compiles may reach.
-     */
+    /** Enables a source string in `nodes` and `engine.registerNode(source)`. Unset fields fall back to `browser`'s defaults (`@motionscript/core/sdk`, a lazy `esbuild-wasm`); `modules` has none, since only the host knows which packages a script may reach. */
     dynamicNodes?: Partial<DynamicNodeConfig>;
-    /**
-     * Where `esbuild-wasm`'s own `.wasm` binary is served — only read if the
-     * default compiler is actually used.
-     */
+    /** Where `esbuild-wasm`'s `.wasm` is served; only read if the default compiler is used. */
     compilerWasmUrl?: string;
     /** Default video encoder settings for `session.export()`. Overridable per call. */
     video?: VideoEncoderOptions;
@@ -41,25 +24,13 @@ export interface BrowserRenderer<TStorage extends StorageAdapter = StorageAdapte
 }
 /** A render context as this package drives it: an engine one, plus what exports and stills ask of it. */
 export type BrowserRenderContext = EngineRenderContext & {
-    /**
-     * Settles once the surface `mount` began can draw. A backend whose surface
-     * comes up asynchronously (a GPU device) must have it, or the first frame
-     * draws onto nothing.
-     */
+    /** Settles once the surface `mount` began can draw; a backend with an asynchronous surface (a GPU device) must have it or the first frame draws onto nothing. */
     whenMounted?(): Promise<void>;
-    /**
-     * The frame last drawn, copied into a fresh 2D canvas, or `undefined` before
-     * one was. What a still encodes; a WebGPU canvas is readable only in the task
-     * that drew it, so a backend may draw it again here.
-     */
+    /** The frame last drawn, copied into a fresh 2D canvas (what a still encodes), or `undefined` before one was. A WebGPU canvas is readable only in the task that drew it, so a backend may draw again here. */
     snapshotCanvas?(): HTMLCanvasElement | undefined;
 };
-/** What `session.export({ encode })` accepts in this environment. */
 export interface BrowserEncodeOptions {
-    /**
-     * Defaults to `'mp4'`. An audio format (`'wav'`, `'mp3'`, `'m4a'`) renders no
-     * frames and ignores `scale`, `frames`, `includeAudio`, `video` and `supersample`.
-     */
+    /** Defaults to `'mp4'`. An audio format (`'wav'`, `'mp3'`, `'m4a'`) renders no frames and ignores `scale`, `frames`, `includeAudio`, `video` and `supersample`. */
     format?: ExportFormat;
     video?: VideoEncoderOptions;
     audio?: AudioEncoderOptions;
@@ -69,13 +40,9 @@ export interface BrowserEncodeOptions {
     filename?: string;
 }
 /**
- * An engine backed by the browser: WebGPU surfaces, Web Audio, WebCodecs.
- * Rejects with `WebGpuUnavailableError` where this browser has no WebGPU adapter.
- *
- * Async because the renderer is a wasm module and every seam below needs it. Await
- * once, at app start, and share the result — the caches underneath (registered
- * fonts, decoded images, shaped paragraphs) are the point of keeping one engine
- * rather than one per canvas.
+ * An engine backed by the browser: WebGPU surfaces, Web Audio, WebCodecs. Rejects with `WebGpuUnavailableError` where
+ * there is no WebGPU adapter. Async because the renderer is a wasm module; await once at app start and share the
+ * result, since the caches underneath (fonts, decoded images, shaped paragraphs) are the point of one engine.
  *
  * ```ts
  * const engine = await createBrowserEngine({ nodes: { pulseRing: PulseRing } });

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,MAAM,EACN,aAAa,EAEb,mBAAmB,EAOnB,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,WAAW,EACnB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAInE,OAAO,EAAkC,KAAK,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEhH,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAG7D,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,aAAa,EAAE,OAAO,GAAG,cAAc,CAAC,EAAE,kBAAkB;IAC3G;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC,eAAe,GAAG,MAAM,CAAC,EAAE,GAAG,WAAW,CAAC;IAC5D;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC1C;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,mFAAmF;IACnF,KAAK,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AAED,6FAA6F;AAC7F,MAAM,WAAW,eAAe,CAAC,QAAQ,SAAS,cAAc,GAAG,cAAc;IAC7E,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,CAAC;IACnD,mBAAmB,CAAC,OAAO,EAAE,QAAQ,GAAG,oBAAoB,CAAC;IAC7D,oBAAoB,CAAC,OAAO,EAAE,QAAQ,GAAG,gBAAgB,CAAC;IAC1D,OAAO,CAAC,IAAI,IAAI,CAAC;CACpB;AAED,yGAAyG;AACzG,MAAM,MAAM,oBAAoB,GAAG,mBAAmB,GAAG;IACrD;;;;OAIG;IACH,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B;;;;OAIG;IACH,cAAc,CAAC,IAAI,iBAAiB,GAAG,SAAS,CAAC;CACpD,CAAC;AAEF,qEAAqE;AACrE,MAAM,WAAW,oBAAoB;IACjC;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AA2HD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACrC,OAAO,GAAE,oBAAyB,GACnC,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAsDrC"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,MAAM,EACN,aAAa,EAEb,mBAAmB,EAOnB,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,WAAW,EACnB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAInE,OAAO,EAAkC,KAAK,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEhH,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAG7D,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,aAAa,EAAE,OAAO,GAAG,cAAc,CAAC,EAAE,kBAAkB;IAC3G,kPAAkP;IAClP,KAAK,CAAC,EAAE,SAAS,CAAC,eAAe,GAAG,MAAM,CAAC,EAAE,GAAG,WAAW,CAAC;IAC5D,+PAA+P;IAC/P,YAAY,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC1C,2FAA2F;IAC3F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,mFAAmF;IACnF,KAAK,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AAED,6FAA6F;AAC7F,MAAM,WAAW,eAAe,CAAC,QAAQ,SAAS,cAAc,GAAG,cAAc;IAC7E,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,CAAC;IACnD,mBAAmB,CAAC,OAAO,EAAE,QAAQ,GAAG,oBAAoB,CAAC;IAC7D,oBAAoB,CAAC,OAAO,EAAE,QAAQ,GAAG,gBAAgB,CAAC;IAC1D,OAAO,CAAC,IAAI,IAAI,CAAC;CACpB;AAED,yGAAyG;AACzG,MAAM,MAAM,oBAAoB,GAAG,mBAAmB,GAAG;IACrD,iKAAiK;IACjK,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,8MAA8M;IAC9M,cAAc,CAAC,IAAI,iBAAiB,GAAG,SAAS,CAAC;CACpD,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACjC,mKAAmK;IACnK,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAuGD;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACrC,OAAO,GAAE,oBAAyB,GACnC,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CA4CrC"}