@blockcast/fec-worker 0.1.0

package/README.md

@@ -0,0 +1,213 @@
+# @blockcast/fec-worker
+
+A Web Worker wrapper around `@blockcast/mmt-fec` that moves the RaptorQ decode off the main thread. The main-thread client posts source and repair symbols to a dedicated worker via `postMessage` with `Transferable` `ArrayBuffer` ownership transfer, so packet payloads cross the thread boundary with **zero copies**. Decoded / FEC-recovered frames travel back the same way. Critical for IWA / web players where main-thread blocking on FEC decode would cause frame drops at the renderer.
+
+## Install
+
+```bash
+pnpm add @blockcast/fec-worker
+```
+
+The package is dual-shaped: the main-thread side (`FecWorkerClient`, types) is the default export; the worker entry is exposed as the `./worker` subpath so consumers can hand its URL to `new Worker(...)` (or to the `FecWorkerClient` constructor, which spawns it for you).
+
+## Quick start
+
+```ts
+import { FecWorkerClient, type FecTrackConfig } from "@blockcast/fec-worker"
+
+// Worker URL resolved against your bundler. ?worker / new URL() / import.meta —
+// any pattern that gives you a module-Worker URL works.
+const workerUrl = new URL("./fec-worker-entry.js", import.meta.url)
+
+const client = new FecWorkerClient(workerUrl)
+
+client.onFrame((data, meta) => {
+  // data is an ArrayBuffer transferred from the worker (zero-copy).
+  // meta tells you whether this frame was recovered via FEC and (if ALTA is
+  // configured) whether its source-packet trailer verified.
+  decoder.decode(data) // hand off to WebCodecs / MSE
+})
+client.onSnapshot((stats) => fecPanel.render(stats))
+client.onError((msg) => console.error("[fec]", msg))
+
+// Configure with a pre-compiled mmt-wasm Module from your loader's importmap.
+const config: FecTrackConfig = {
+  codec: "avc1.64001f",
+  trackName: "video/base",
+  trackType: "video",
+  resolution: { w: 1920, h: 1080 },
+  framerate: 30,
+  algorithm: "raptor",
+  k: 32,
+  repairCount: 8,
+  symbolSize: 1312,
+  interleaveDepth: 30,
+  interleaveMs: 1000, // 30 frames @ 30 fps
+  deliveryWindowMs: 2000, // computeFecDeliveryWindowMs(...) from the catalog
+  fecMode: "subframe",
+  altaEnabled: false,
+  relayBlockSigEnabled: false,
+}
+client.configure(config, mmtWasmModule)
+
+// Feed packets as they arrive from transport. ArrayBuffers are transferred —
+// caller MUST NOT touch `data` after the call.
+client.feedSource(ssId, packetBuffer, captureTs)
+client.feedRepair(ssStart, ssbLength, rsId, repairBuffer, captureTs)
+```
+
+`FecWorkerClient` accepts either a `URL` (it spawns the worker for you with `{ type: "module" }`) or a pre-created `Worker` instance (used in tests for constructor injection).
+
+## Why a Worker
+
+A 1080p30 stream with `K=32, P=8, symbolSize=1312` produces ~1 RaptorQ source-block decode every second per track. Decode time is amortized across SIMD lanes inside the WASM, but the *worst-case* block — one with the maximum recoverable loss pattern — can spike past 16 ms. Run that on the main thread and you've blown a frame; the renderer drops, the user sees a stutter, and CMCD reports a pacing violation.
+
+Pushing the decode into a dedicated Worker keeps the main thread free for input handling, MSE buffer maintenance, and frame pacing. The same module compiled into both contexts decodes identically; what changes is who's blocked when a worst-case block hits.
+
+This is the **Worker-per-track FEC pipeline** architectural decision tracked in the parent monorepo as a v2.0 milestone (`pim-multicast-gateway/.planning/MILESTONES.md` — "Worker-per-track FEC pipeline with zero-copy ArrayBuffer transfers"). Each track (base / delta / repair / audio) runs in its own Worker, so a stall on one track's decode never starves the others.
+
+## Architecture
+
+```
+   Main thread                              │   FEC Worker (per track)
+                                            │
+   transport packet                         │
+        │                                   │
+        ▼                                   │
+   FecWorkerClient.feedSource(...)          │
+        │                                   │
+        │  postMessage(cmd, [data, ...])    │
+        │   ─ data: ArrayBuffer (transferred, neutered on sender)
+        │   ─ wasmModule: WebAssembly.Module (structured-cloned)
+        ├──────────────────────────────────►│  self.onmessage
+        │                                   │       │
+        │                                   │       ▼
+        │                                   │  WasmFecDecoder.add_source(...)
+        │                                   │       │
+        │                                   │       ▼  (recovered or pass-through)
+        │                                   │  postMessage({type:"frame", data}, [data])
+        │◄──────────────────────────────────┤
+        │                                   │
+        ▼                                   │
+   FecWorkerClient.onFrame(data, meta)      │
+        │                                   │
+        ▼                                   │
+   WebCodecs / MSE                          │
+```
+
+Buffers cross the boundary via the `Transferable` list. After `postMessage`, the sender's `ArrayBuffer` is detached — touching it throws. This is the contract that makes zero-copy safe: there is no aliased view that could be mutated mid-decode.
+
+`WebAssembly.Module` is structured-cloneable (not transferable) and is *cloned* (cheap — the underlying compiled module is shared across realms). The ALTA public key, on the other hand, is a regular `ArrayBuffer` and *is* transferred.
+
+Errors that escape the worker's `try/catch` (in either the sync command path or the async configure path) are emitted as `{type: "error", message}` events rather than thrown — the main thread surfaces them through `onError`.
+
+## Message protocol
+
+All messages are typed as discriminated unions in `fec-worker-types.ts`. Both the worker and the client import the same definitions, so adding a message variant is a single-file change that the compiler enforces on both sides.
+
+### Inbound — `FecWorkerCommand` (main → worker)
+
+| `type` | Payload | Transferred |
+|--------|---------|-------------|
+| `configure` | `config: FecTrackConfig`, `wasmModule: WebAssembly.Module`, `altaPublicKey?: ArrayBuffer`, `altaWasmModule?: WebAssembly.Module` | `altaPublicKey` only — WASM modules are structured-cloned |
+| `feedSource` | `ssId: number`, `data: ArrayBuffer`, `ts: number`, optional `altaAuth: ArrayBuffer` + `altaPayloadEnd: number` | `data` and `altaAuth` |
+| `feedRepair` | `ssStart: number`, `ssbLength: number`, `rsId: number`, `data: ArrayBuffer`, `ts: number` | `data` |
+| `relayBlockSig` | `sbn: number`, `sig: ArrayBuffer`, `hash: ArrayBuffer` | `sig`, `hash` |
+| `cleanup` | `sbns: number[]` (all timed-out blocks covered by this coalesced barrier) | none |
+| `dispose` | — | none |
+
+`feedSource` carries the **flat 32-bit Source Symbol ID** from the MMTP Source FEC Payload ID (ISO 23008-1 §C.5.2). The WASM decoder derives `SBN = floor(ssId / K)` and `ESI = ssId % K` internally — do not pre-compute these.
+
+`feedRepair` carries the wire-level Repair FEC Payload ID fields directly (ISO 23008-1 §C.5.3): `ssStart` is the SS_ID of the first source symbol in the block, `ssbLength` must equal the track's configured K, and `rsId` is the repair index within the block. A different K starts a new configured decoder epoch; it is never inferred from repair traffic.
+
+### Outbound — `FecWorkerEvent` (worker → main)
+
+| `type` | Payload | Transferred back |
+|--------|---------|------------------|
+| `frame` | `data: ArrayBuffer`, `meta: FrameMeta` | `data` |
+| `snapshot` | `stats: FecTrackStats` | none (structured clone) |
+| `blockUpdate` | `block: FecBlockSnapshot` | none |
+| `greenFill` | `sbn: number`, `data: ArrayBuffer` | `data` |
+| `cleanupComplete` | `sbns: number[]` | none |
+| `error` | `message: string` | none |
+
+`FrameMeta` carries `recovered: boolean` (this frame came out of the FEC decode, not the direct path), `sbn: number`, and `altaVerified: boolean | null` (signature outcome, or `null` when ALTA is not configured / verification is pending).
+
+## Lifecycle
+
+```
+new FecWorkerClient(url)
+        │  worker spawned with { type: "module" }
+        ▼
+client.configure(config, wasmModule [, altaPublicKey, altaWasmModule])
+        │  worker initSyncs WASM, instantiates MmtFecDecoder(interleaveDepth, videoFill),
+        │  immediately configures exact catalog K/T (no decoder defaults),
+        │  derives pendingVerifyCap = ceil(D × 1.5) and TTL = ceil(K × interleaveMs × 1.5)
+        │  from catalog values, throws if any of K / D / interleaveMs ≤ 0,
+        │  starts the 200 ms snapshot timer, emits initial snapshot
+        ▼
+client.feedSource(...) / feedRepair(...)         ◄── steady state
+        │  every transferred ArrayBuffer detaches on the main thread
+        │  decoded / recovered frames flow back as {type:"frame"}
+        │  every 200 ms a {type:"snapshot"} carries FecTrackStats
+        ▼
+client.cleanup(sbn)                              ◄── per-block inactivity deadline
+        │  coalesces queued SBNs behind one worker queue-drain barrier
+        │  evicts blocks relative to max(sbns) − D × 3
+        │  emits green-fill with the true SBN from WASM cleanup_blocks_detailed()
+        │  acknowledges every SBN in {type:"cleanupComplete", sbns}
+        │  any block still in "collecting" at eviction time is counted as failed
+        ▼
+client.dispose()
+           sends {type:"dispose"}, terminates worker. WASM decoder and ALTA
+           verifier are explicitly free()'d before terminate so their linear
+           memory is released (FinalizationRegistry would not run between
+           dispose and terminate). Idempotent.
+```
+
+### Backpressure
+
+`postMessage` is fire-and-forget at the JS level — there is no built-in flow control. If the main thread can't drain `frame` events fast enough, the worker's outbound queue grows. The remedy is upstream of this package: pace your input (`feedSource` / `feedRepair`) against actual decode capacity by watching the `avgRecoveryMs` / `maxRecoveryMs` fields of each `snapshot`. Spikes in `maxRecoveryMs` past your frame budget are the early signal.
+
+## Stats
+
+The `snapshot` event delivers a `FecTrackStats` every 200 ms (catalog-derived; not configurable from this layer). Key fields:
+
+| Field | Meaning |
+|-------|---------|
+| `sourceSymbols`, `repairSymbols` | Raw ingress counters |
+| `blocksComplete` | Block had all K source symbols without needing repair |
+| `blocksRecovered` | Block was recovered using ≥1 repair symbol |
+| `blocksFailed` | Block aged out before reaching K |
+| `greenFillFrames` | Frames substituted with green-fill on unrecoverable loss |
+| `recoveryRate` | `recovered / (recovered + failed)`, 0–100 |
+| `avgRecoveryMs`, `maxRecoveryMs` | Rolling decode latency (capped at 1000 samples) |
+| `liveSbn` | Highest source-block number observed |
+| `blocks` | Up to `max(D × 3, 24)` recent `FecBlockSnapshot`s for live visualization |
+| `interleaveWindowBlocks` | `D` from config |
+
+When ALTA is enabled, the snapshot also carries the four-state verification accounting — `altaVerified` (crypto passed), `altaFailed` (tamper-confirmed), `altaPending` (unverifiable, e.g. missing trailer / late-joiner anchor gap), `altaError` (verifier threw — infrastructure flake, not tamper) — plus `altaInitFailed` (true if the ALTA WASM didn't initialize), `altaPendingEvictedCap` / `altaPendingEvictedTtl` (deferred-queue eviction reasons), and a bounded `altaFailedDetails[]` ring with the last ≤16 tamper events. The four-way split exists so ops alerting can distinguish a network problem (`altaPending` rising) from an attack (`altaFailed` rising) from a runtime bug (`altaError` rising).
+
+`FecTrackStats` is also the shape consumed downstream by `@blockcast/mmt-container`'s `CmcdProducer` and the diagnostics `fec-panel` — keep it stable when you extend it.
+
+## Related packages
+
+- **`@blockcast/mmt-fec`** — the wrapped library. Container-agnostic RaptorQ decoder + block manager + reorder buffer. Lives on the main thread when you don't need a Worker; this package is the off-thread variant of the same decoder.
+- **`@blockcast/mmt-container`** — the consumer that wires this Worker into the data path. `FecManager` instantiates one `FecWorkerClient` per track, routes MMTP source/repair payloads in, and pumps recovered frames into the MFU reassembler / fmp4 segmenter.
+- **`@blockcast/mmt-alta-parse`** — ALTA trailer extraction. Used inside the Worker to parse the `[0xF0A1][len][auth]` trailer off recovered source symbols (publisher-stripped trailers don't appear on direct-source packets, which carry the trailer in band).
+
+## Testing
+
+```bash
+pnpm test           # vitest run
+pnpm test:watch     # vitest in watch mode
+pnpm typecheck      # tsc --noEmit
+```
+
+Tests cover:
+- The message-protocol type narrowing (`fec-worker-types.test.ts`)
+- The main-thread client's transfer-list construction, callback dispatch, and dispose idempotence (`fec-worker-client.test.ts`) — the Worker is injected via constructor as a stub so the tests don't need a real WASM build
+
+## License
+
+Apache-2.0 — see `LICENSE`.

package/dist/fec-worker-client.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @blockcast/fec-worker — Main-Thread Client
+ *
+ * Wraps one Worker per track instance. Provides typed API for the
+ * FecWorkerCommand/FecWorkerEvent protocol with zero-copy ArrayBuffer transfers.
+ *
+ * Constructor accepts either a URL (creates Worker internally) or a pre-created
+ * Worker instance (for testing via constructor injection).
+ */
+import type { FecTrackConfig, FecTrackStats, FecBlockSnapshot, FrameMeta, FecWorkerErrorCode } from "./fec-worker-types.js";
+export declare class FecWorkerClient {
+    #private;
+    /**
+     * Create a FecWorkerClient.
+     * @param workerOrUrl - Either a Worker instance (for testing) or a URL to create one
+     */
+    constructor(workerOrUrl: Worker | URL);
+    /**
+     * Configure the Worker with FEC parameters and WASM module.
+     * wasmModule is transferred (not neutered — WebAssembly.Module is shareable).
+     * altaPublicKey is PKCS#8 SPKI DER bytes (self-describing — algorithm detected from OID).
+     *   Transferred (detached from sender).
+     * altaWasmModule is structured-cloneable (NOT transferable — do not add to transfer list).
+     */
+    configure(config: FecTrackConfig, wasmModule: WebAssembly.Module, altaPublicKey?: ArrayBuffer, altaWasmModule?: WebAssembly.Module): void;
+    /**
+     * Feed a source symbol to the Worker. data ArrayBuffer is transferred (zero-copy).
+     * Caller must not access data after this call — it is detached.
+     *
+     * Optional `alta` carries the detached ALTA authenticator bytes and the
+     * byte offset in `data` where the signed payload ends. The auth buffer is
+     * transferred zero-copy alongside `data`. Use {@link getMmtpAltaTrailer}
+     * upstream (mmtp-router) to extract it from the wire packet.
+     */
+    feedSource(ssId: number, data: ArrayBuffer, ts: number, alta?: {
+        auth: ArrayBuffer;
+        payloadEnd: number;
+    }): void;
+    /**
+     * Feed a repair symbol to the Worker. data ArrayBuffer is transferred (zero-copy).
+     * Caller must not access data after this call — it is detached.
+     *
+     * Carries the wire-level Repair FEC Payload ID fields (ISO 23008-1 §C.5.3):
+     * - ssStart:   SS_ID of first source symbol in the block (= SBN * SSB_length)
+     * - ssbLength: K for this block
+     * - rsId:      repair symbol index within the block
+     */
+    feedRepair(ssStart: number, ssbLength: number, rsId: number, data: ArrayBuffer, ts: number): void;
+    /**
+     * Submit relay block signature for verification. sig and hash are transferred.
+     */
+    relayBlockSig(sbn: number, sig: ArrayBuffer, hash: ArrayBuffer): void;
+    /**
+     * Trigger cleanup after a block's inactivity deadline.
+     *
+     * While one queue-drain barrier is in flight, later SBNs are coalesced into
+     * the next command without losing their individual acknowledgement identity.
+     */
+    cleanup(currentSbn: number): void;
+    /** Reset this track's decoder epoch while preserving Worker configuration. */
+    reset(): void;
+    /** Register callback for decoded/recovered frames (FEC-03). */
+    onFrame(cb: (data: ArrayBuffer, meta: FrameMeta) => void): void;
+    /** Register callback for periodic stats snapshots (FEC-04). */
+    onSnapshot(cb: (stats: FecTrackStats) => void): void;
+    /** Register callback for individual block state changes. */
+    onBlockUpdate(cb: (block: FecBlockSnapshot) => void): void;
+    /** Register callback for green-fill frames. */
+    onGreenFill(cb: (sbn: number, data: ArrayBuffer) => void): void;
+    /** Register callback fired after the Worker drains all commands queued before cleanup. */
+    onCleanupComplete(cb: (sbn: number) => void): void;
+    /** Register callback for Worker errors. */
+    onError(cb: (message: string, code?: FecWorkerErrorCode) => void): void;
+    /**
+     * Dispose the Worker. Sends dispose command then terminates.
+     * Idempotent — safe to call multiple times.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=fec-worker-client.d.ts.map

package/dist/fec-worker-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fec-worker-client.d.ts","sourceRoot":"","sources":["../src/fec-worker-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAGX,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,SAAS,EACT,kBAAkB,EAClB,MAAM,uBAAuB,CAAC;AAE/B,qBAAa,eAAe;;IAc3B;;;OAGG;gBACS,WAAW,EAAE,MAAM,GAAG,GAAG;IAgBrC;;;;;;OAMG;IACH,SAAS,CACR,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,WAAW,CAAC,MAAM,EAC9B,aAAa,CAAC,EAAE,WAAW,EAC3B,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,GACjC,IAAI;IAkBP;;;;;;;;OAQG;IACH,UAAU,CACT,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,MAAM,EACV,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAC9C,IAAI;IAgBP;;;;;;;;OAQG;IACH,UAAU,CACT,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,MAAM,GACR,IAAI;IAeP;;OAEG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI;IAQrE;;;;;OAKG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAgBjC,8EAA8E;IAC9E,KAAK,IAAI,IAAI;IAgBb,+DAA+D;IAC/D,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI;IAI/D,+DAA+D;IAC/D,UAAU,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI;IAIpD,4DAA4D;IAC5D,aAAa,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI;IAI1D,+CAA+C;IAC/C,WAAW,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI;IAI/D,0FAA0F;IAC1F,iBAAiB,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAIlD,2CAA2C;IAC3C,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,KAAK,IAAI,GAAG,IAAI;IAIvE;;;OAGG;IACH,OAAO,IAAI,IAAI;CAmDf"}

package/dist/fec-worker-client.js

@@ -0,0 +1,270 @@
+/**
+ * @blockcast/fec-worker — Main-Thread Client
+ *
+ * Wraps one Worker per track instance. Provides typed API for the
+ * FecWorkerCommand/FecWorkerEvent protocol with zero-copy ArrayBuffer transfers.
+ *
+ * Constructor accepts either a URL (creates Worker internally) or a pre-created
+ * Worker instance (for testing via constructor injection).
+ */
+export class FecWorkerClient {
+    #worker;
+    #onFrame = null;
+    #onSnapshot = null;
+    #onBlockUpdate = null;
+    #onGreenFill = null;
+    #onCleanupComplete = null;
+    #onError = null;
+    #cleanupInFlight = null;
+    #queuedCleanupSbns = new Set();
+    #pendingResets = 0;
+    #resetFailed = false;
+    #disposed = false;
+    /**
+     * Create a FecWorkerClient.
+     * @param workerOrUrl - Either a Worker instance (for testing) or a URL to create one
+     */
+    constructor(workerOrUrl) {
+        if (workerOrUrl instanceof URL) {
+            this.#worker = new Worker(workerOrUrl, { type: "module" });
+        }
+        else {
+            this.#worker = workerOrUrl;
+        }
+        this.#worker.onmessage = (e) => this.#handleEvent(e.data);
+        this.#worker.onerror = (e) => {
+            this.#onError?.(formatWorkerError(e), "worker-runtime");
+        };
+        this.#worker.onmessageerror = (e) => {
+            this.#onError?.(formatWorkerMessageError(e), "worker-message");
+        };
+    }
+    /**
+     * Configure the Worker with FEC parameters and WASM module.
+     * wasmModule is transferred (not neutered — WebAssembly.Module is shareable).
+     * altaPublicKey is PKCS#8 SPKI DER bytes (self-describing — algorithm detected from OID).
+     *   Transferred (detached from sender).
+     * altaWasmModule is structured-cloneable (NOT transferable — do not add to transfer list).
+     */
+    configure(config, wasmModule, altaPublicKey, altaWasmModule) {
+        if (this.#disposed)
+            throw new Error("[FecWorkerClient] disposed");
+        const cmd = {
+            type: "configure",
+            config,
+            wasmModule,
+            altaPublicKey,
+            altaWasmModule,
+        };
+        // WebAssembly.Module is structured-cloneable, NOT transferable.
+        // Pass it in the message body (Chrome clones it automatically).
+        // Only ArrayBuffers (like altaPublicKey) go in the transfer list.
+        const transferList = [];
+        if (altaPublicKey)
+            transferList.push(altaPublicKey);
+        // altaWasmModule is structured-cloneable — NOT added to transferList
+        this.#worker.postMessage(cmd, transferList);
+    }
+    /**
+     * Feed a source symbol to the Worker. data ArrayBuffer is transferred (zero-copy).
+     * Caller must not access data after this call — it is detached.
+     *
+     * Optional `alta` carries the detached ALTA authenticator bytes and the
+     * byte offset in `data` where the signed payload ends. The auth buffer is
+     * transferred zero-copy alongside `data`. Use {@link getMmtpAltaTrailer}
+     * upstream (mmtp-router) to extract it from the wire packet.
+     */
+    feedSource(ssId, data, ts, alta) {
+        if (this.#disposed)
+            return;
+        const cmd = alta
+            ? {
+                type: "feedSource",
+                ssId,
+                data,
+                ts,
+                altaAuth: alta.auth,
+                altaPayloadEnd: alta.payloadEnd,
+            }
+            : { type: "feedSource", ssId, data, ts };
+        const transfer = alta ? [data, alta.auth] : [data];
+        this.#worker.postMessage(cmd, transfer);
+    }
+    /**
+     * Feed a repair symbol to the Worker. data ArrayBuffer is transferred (zero-copy).
+     * Caller must not access data after this call — it is detached.
+     *
+     * Carries the wire-level Repair FEC Payload ID fields (ISO 23008-1 §C.5.3):
+     * - ssStart:   SS_ID of first source symbol in the block (= SBN * SSB_length)
+     * - ssbLength: K for this block
+     * - rsId:      repair symbol index within the block
+     */
+    feedRepair(ssStart, ssbLength, rsId, data, ts) {
+        if (this.#disposed)
+            return;
+        this.#worker.postMessage({
+            type: "feedRepair",
+            ssStart,
+            ssbLength,
+            rsId,
+            data,
+            ts,
+        }, [data]);
+    }
+    /**
+     * Submit relay block signature for verification. sig and hash are transferred.
+     */
+    relayBlockSig(sbn, sig, hash) {
+        if (this.#disposed)
+            return;
+        this.#worker.postMessage({ type: "relayBlockSig", sbn, sig, hash }, [sig, hash]);
+    }
+    /**
+     * Trigger cleanup after a block's inactivity deadline.
+     *
+     * While one queue-drain barrier is in flight, later SBNs are coalesced into
+     * the next command without losing their individual acknowledgement identity.
+     */
+    cleanup(currentSbn) {
+        if (this.#disposed)
+            return;
+        if (!Number.isInteger(currentSbn) ||
+            currentSbn < 0 ||
+            currentSbn > 0xffff_ffff) {
+            throw new Error("[FecWorkerClient] cleanup: SBN must be a uint32");
+        }
+        if (this.#cleanupInFlight) {
+            this.#queuedCleanupSbns.add(currentSbn);
+            return;
+        }
+        this.#postCleanup(new Set([currentSbn]));
+    }
+    /** Reset this track's decoder epoch while preserving Worker configuration. */
+    reset() {
+        if (this.#disposed)
+            return;
+        this.#pendingResets++;
+        this.#cleanupInFlight = null;
+        this.#queuedCleanupSbns.clear();
+        this.#worker.postMessage({ type: "reset" });
+    }
+    #postCleanup(sbns) {
+        this.#cleanupInFlight = sbns;
+        const orderedSbns = [...sbns].sort((a, b) => a - b);
+        this.#worker.postMessage({ type: "cleanup", sbns: orderedSbns });
+    }
+    /** Register callback for decoded/recovered frames (FEC-03). */
+    onFrame(cb) {
+        this.#onFrame = cb;
+    }
+    /** Register callback for periodic stats snapshots (FEC-04). */
+    onSnapshot(cb) {
+        this.#onSnapshot = cb;
+    }
+    /** Register callback for individual block state changes. */
+    onBlockUpdate(cb) {
+        this.#onBlockUpdate = cb;
+    }
+    /** Register callback for green-fill frames. */
+    onGreenFill(cb) {
+        this.#onGreenFill = cb;
+    }
+    /** Register callback fired after the Worker drains all commands queued before cleanup. */
+    onCleanupComplete(cb) {
+        this.#onCleanupComplete = cb;
+    }
+    /** Register callback for Worker errors. */
+    onError(cb) {
+        this.#onError = cb;
+    }
+    /**
+     * Dispose the Worker. Sends dispose command then terminates.
+     * Idempotent — safe to call multiple times.
+     */
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#cleanupInFlight = null;
+        this.#queuedCleanupSbns.clear();
+        this.#worker.postMessage({ type: "dispose" });
+        this.#worker.terminate();
+    }
+    #handleEvent(event) {
+        if (event.type === "resetComplete") {
+            this.#pendingResets = Math.max(0, this.#pendingResets - 1);
+            this.#resetFailed = false;
+            return;
+        }
+        if (event.type === "error") {
+            if (event.code === "reset-failed") {
+                this.#pendingResets = Math.max(0, this.#pendingResets - 1);
+                this.#resetFailed = true;
+            }
+            if (event.code)
+                this.#onError?.(event.message, event.code);
+            else
+                this.#onError?.(event.message);
+            return;
+        }
+        if (this.#pendingResets > 0 || this.#resetFailed)
+            return;
+        switch (event.type) {
+            case "frame":
+                this.#onFrame?.(event.data, event.meta);
+                break;
+            case "snapshot":
+                this.#onSnapshot?.(event.stats);
+                break;
+            case "blockUpdate":
+                this.#onBlockUpdate?.(event.block);
+                break;
+            case "greenFill":
+                this.#onGreenFill?.(event.sbn, event.data);
+                break;
+            case "cleanupComplete":
+                for (const sbn of event.sbns) {
+                    this.#onCleanupComplete?.(sbn);
+                }
+                this.#cleanupInFlight = null;
+                if (this.#queuedCleanupSbns.size > 0) {
+                    const next = this.#queuedCleanupSbns;
+                    this.#queuedCleanupSbns = new Set();
+                    this.#postCleanup(next);
+                }
+                break;
+        }
+    }
+}
+function formatWorkerError(event) {
+    const parts = ["Worker error"];
+    if (event.message)
+        parts.push(event.message);
+    if (event.filename) {
+        const location = [event.filename];
+        if (event.lineno)
+            location.push(String(event.lineno));
+        if (event.colno)
+            location.push(String(event.colno));
+        parts.push(`at ${location.join(":")}`);
+    }
+    if (event.error instanceof Error) {
+        if (event.error.message && event.error.message !== event.message) {
+            parts.push(event.error.message);
+        }
+        if (event.error.stack)
+            parts.push(event.error.stack);
+    }
+    else if (event.error != null) {
+        parts.push(String(event.error));
+    }
+    return parts.join(": ");
+}
+function formatWorkerMessageError(event) {
+    const data = event.data;
+    const detail = data == null ? "" :
+        data instanceof Error ? `: ${data.message}` :
+            `: ${Object.prototype.toString.call(data)}`;
+    return `Worker messageerror: failed to deserialize worker message${detail}`;
+}
+//# sourceMappingURL=fec-worker-client.js.map

package/dist/fec-worker-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fec-worker-client.js","sourceRoot":"","sources":["../src/fec-worker-client.ts"],"names":[],"mappings":"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"}