@camstack/addon-pipeline 0.1.20 → 0.2.0

package/dist/decoder-nodeav/index.mjs

@@ -1,1441 +1,1385 @@
+import { O as decoderCapability, _ as RingBuffer, h as HWACCEL_OPTIONS, i as BaseAddon, j as errMsg, l as DEFAULT_DECODER_HWACCEL_CONFIG } from "../dist-C5jnNl0n.mjs";
+import { FrameRingReaderCache, FrameRingWriter, MIN_RING_SLOTS, computeSegmentSize, computeSlotByteLength, createSegment, deriveSlotCount } from "@camstack/shm-ring";
 import { randomUUID } from "node:crypto";
-import { e as errMsg, B as BaseAddon, w as DEFAULT_DECODER_HWACCEL_CONFIG, H as HWACCEL_OPTIONS, x as decoderCapability, R as RingBuffer } from "../index-5aYef068.mjs";
-import { computeSlotByteLength, computeSegmentSize, deriveSlotCount, MIN_RING_SLOTS, createSegment, FrameRingWriter, FrameRingReaderCache } from "@camstack/shm-ring";
-const RING_BUDGET_MB = (() => {
-  const raw = Number(process.env["CAMSTACK_SHM_RING_BUDGET_MB"]);
-  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 128;
+//#region src/decoder-nodeav/frame-ring-sink.ts
+/**
+* `DecoderFrameRingSink` — the decoder's shared-memory write side (Phase 5 / D9).
+*
+* When a decoder session is configured with `frameSink: 'shm'`, the decoder
+* **owns** the shared-memory ring segment for that stream: it creates the
+* segment on the first decoded frame (when the output geometry is known),
+* writes every subsequent decoded frame into the ring via a `FrameRingWriter`,
+* and closes + unlinks the segment when the session is destroyed.
+*
+* What leaves the decoder is no longer the pixel `Buffer` — it is a tiny,
+* serialisable `FrameHandle` (`FrameRingWriter.writeFrame`'s return value).
+* Same-host consumers (motion, detection, the WebRTC encoder) open the same
+* segment with a `FrameRingReader` and read the pixels zero-copy.
+*
+* ## Lazy segment creation
+*
+* The segment cannot be sized until the first frame: `slotByteLength` is
+* `width × height × bytesPerPixel`, and the output dimensions are only known
+* once the scaler has produced its first `dstFrame`. So `writeFrame` is a
+* no-op-until-armed: the first call sizes + creates the segment, every later
+* call writes into it.
+*
+* ## Resolution-change decision
+*
+* A live camera stream can change resolution mid-stream (the decoder's scaler
+* is rebuilt on a config toggle, or the source renegotiates). The slot is
+* sized for the **first** frame's geometry. A later frame that no longer fits
+* the slot triggers a **segment re-create**: the old segment is closed +
+* unlinked and a fresh, larger segment is created under a new generation-tagged
+* name. This is simpler and leak-free versus over-allocating slots for a
+* worst-case 4K frame on every stream; resolution changes on a live camera are
+* rare, and a brief gap while consumers re-open the segment is acceptable
+* (latest-wins — a missed frame is correct behaviour).
+*/
+/**
+* Per-ring shared-memory budget (MB) — the slot count is derived per-resolution
+* from this budget via {@link deriveSlotCount}, so a 360p stream gets many
+* slots and a 4K stream a few, both inside the same memory footprint.
+*
+* Read ONCE at module load from `CAMSTACK_SHM_RING_BUDGET_MB`; a non-finite or
+* non-positive value falls back to the 128 MB default.
+*/
+var RING_BUDGET_MB = (() => {
+	const raw = Number(process.env["CAMSTACK_SHM_RING_BUDGET_MB"]);
+	return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 128;
 })();
-const RING_BUDGET_BYTES = RING_BUDGET_MB * 1024 * 1024;
+/** {@link RING_BUDGET_MB} in bytes — the budget passed to `deriveSlotCount`. */
+var RING_BUDGET_BYTES = RING_BUDGET_MB * 1024 * 1024;
+/** A unique, stable shared-memory segment name for a decoder stream.
+*
+* macOS POSIX shm names are capped at ~31 characters (`PSHMNAMLEN`). A
+* `camstack.frames.<deviceId>.<streamId>` scheme overflows that for realistic
+* ids, so the sink uses a short, collision-resistant scheme instead:
+* `csf.<base36 hash>.<gen>`. The hash folds the device id, the session tag
+* and a per-process random salt; the generation suffix makes a re-created
+* segment (resolution change) a distinct name so a stale consumer mapping is
+* never silently reused.
+*/
 function makeSegmentName(seed, generation) {
-  let hash = 5381;
-  for (let i = 0; i < seed.length; i += 1) {
-    hash = (hash << 5) + hash + seed.charCodeAt(i) | 0;
-  }
-  const tag = (hash >>> 0).toString(36);
-  return `csf.${tag}.${generation}`;
-}
-class DecoderFrameRingSink {
-  seed;
-  logger;
-  nodeId;
-  segment = null;
-  writer = null;
-  segmentName = null;
-  slotByteLength = 0;
-  generation = 0;
-  destroyed = false;
-  /** Frames committed into the ring across this sink's lifetime (all generations). */
-  framesWritten = 0;
-  constructor(options) {
-    const salt = Math.random().toString(36).slice(2, 8);
-    this.seed = `${options.seed}.${salt}`;
-    this.logger = options.logger;
-    this.nodeId = options.nodeId;
-  }
-  /** Whether a segment has been created (i.e. at least one frame written). */
-  get isArmed() {
-    return this.writer !== null;
-  }
-  /** The current segment name, or `null` before the first frame. */
-  get currentSegmentName() {
-    return this.segmentName;
-  }
-  /**
-   * Write one decoded frame into the ring and return its `FrameHandle`.
-   *
-   * On the first call (or after a geometry change that overflows the current
-   * slot) the segment is created / re-created sized for this frame. Returns
-   * `null` only when the sink has been destroyed.
-   *
-   * This is the copy-in convenience form (it copies `pixels` into the slot).
-   * The decoder's hot path uses the zero-copy {@link beginFrame} /
-   * {@link commitFrame} scatter-write pair instead — the scaler produces its
-   * packed output directly into the slot, eliminating the write-side memcpy.
-   */
-  writeFrame(pixels, meta) {
-    if (this.destroyed) return null;
-    if (this.writer === null || computeSlotByteLength(meta.width, meta.height, meta.format) > this.slotByteLength) {
-      this.recreateSegment(
-        computeSlotByteLength(meta.width, meta.height, meta.format)
-      );
-    }
-    const writer = this.writer;
-    if (writer === null) {
-      return null;
-    }
-    const handle = writer.writeFrame(pixels, meta);
-    this.framesWritten += 1;
-    return handle;
-  }
-  /**
-   * Reserve a ring slot for a frame of the given geometry — the **zero-copy**
-   * scatter-write entry point (Phase 5 / D9 Task 7c).
-   *
-   * The segment is created / re-created here if this is the first frame or the
-   * geometry overflows the current slot capacity, so the slot is correctly
-   * sized before the caller fills it. The returned `buffer` is a writable view
-   * **directly over the mapped segment** — the node-av scaler scatters its
-   * packed output straight into it, with no intermediate copy. The caller MUST
-   * call {@link commitFrame} with the returned `slot` once the slot is filled.
-   *
-   * Returns `null` when the sink is destroyed or the segment cannot be created.
-   */
-  beginFrame(width, height, format) {
-    if (this.destroyed) return null;
-    const requiredSlotBytes = computeSlotByteLength(width, height, format);
-    if (this.writer === null || requiredSlotBytes > this.slotByteLength) {
-      this.recreateSegment(requiredSlotBytes);
-    }
-    const writer = this.writer;
-    if (writer === null) {
-      return null;
-    }
-    const { slot, buffer } = writer.beginFrame();
-    return { slot, buffer };
-  }
-  /**
-   * Publish the frame whose slot was reserved by {@link beginFrame} and filled
-   * in place by the caller. `slot` MUST be the value from the matching
-   * `beginFrame`. Returns the published `FrameHandle`, or `null` if the sink
-   * was destroyed (or the segment lost) between begin and commit.
-   */
-  commitFrame(slot, meta) {
-    if (this.destroyed) return null;
-    const writer = this.writer;
-    if (writer === null) return null;
-    const handle = writer.commitFrame(slot, meta);
-    this.framesWritten += 1;
-    return handle;
-  }
-  /**
-   * Current shm ring usage — `null` until the first frame arms the segment.
-   * Surfaced through `decoder.getShmStats` so a downstream consumer can
-   * observe ring pressure (slot depth, byte budget, frames written).
-   */
-  getShmStats() {
-    if (this.writer === null) return null;
-    return {
-      slotCount: this.writer.slotCount,
-      slotByteLength: this.slotByteLength,
-      segmentBytes: computeSegmentSize(this.writer.slotCount, this.slotByteLength),
-      framesWritten: this.framesWritten
-    };
-  }
-  /**
-   * Abandon a slot reserved by {@link beginFrame} **without publishing it** —
-   * the degenerate-path counterpart of {@link commitFrame}.
-   *
-   * A caller that reserved a slot but then could not produce valid pixels (no
-   * decoded source planes, or the scaler threw) MUST call this instead of
-   * `commitFrame`: it closes the open seqlock without advancing `writeIndex`,
-   * so no reader ever sees the slot's uninitialised bytes as a real frame, and
-   * no `FrameHandle` is handed downstream. `slot` MUST be the value from the
-   * matching `beginFrame`. A no-op if the sink was destroyed (or the segment
-   * lost) between begin and abort.
-   */
-  abortFrame(slot) {
-    if (this.destroyed) return;
-    const writer = this.writer;
-    if (writer === null) return;
-    writer.abortFrame(slot);
-  }
-  /** Close + unlink the segment. Idempotent. */
-  destroy() {
-    if (this.destroyed) return;
-    this.destroyed = true;
-    this.releaseSegment();
-  }
-  /**
-   * Create a fresh segment sized for at least `slotByteLength` bytes per slot,
-   * replacing any prior one. A re-create bumps the generation so the new
-   * segment has a distinct name — a consumer holding the old mapping is never
-   * silently handed a resized segment.
-   */
-  recreateSegment(slotByteLength) {
-    this.releaseSegment();
-    this.generation += 1;
-    const name = makeSegmentName(this.seed, this.generation);
-    const slotCount = deriveSlotCount(RING_BUDGET_BYTES, slotByteLength);
-    if (slotCount === MIN_RING_SLOTS && MIN_RING_SLOTS * slotByteLength > RING_BUDGET_BYTES) {
-      this.logger.warn(
-        "decoder shm ring: budget too small for resolution — using MIN slots",
-        { meta: { slotByteLength, budgetMb: RING_BUDGET_MB } }
-      );
-    }
-    const totalBytes = computeSegmentSize(slotCount, slotByteLength);
-    try {
-      const segment = createSegment(name, totalBytes);
-      this.segment = segment;
-      this.segmentName = name;
-      this.slotByteLength = slotByteLength;
-      this.writer = new FrameRingWriter(
-        segment.buffer,
-        name,
-        slotCount,
-        slotByteLength,
-        this.nodeId
-      );
-      this.logger.info("decoder shm ring: segment created", {
-        meta: {
-          segment: name,
-          slotCount,
-          slotByteLength,
-          totalBytes,
-          generation: this.generation
-        }
-      });
-    } catch (err) {
-      this.segment = null;
-      this.writer = null;
-      this.segmentName = null;
-      this.slotByteLength = 0;
-      this.logger.error("decoder shm ring: segment create failed", {
-        meta: {
-          segment: name,
-          slotByteLength,
-          error: err instanceof Error ? err.message : String(err)
-        }
-      });
-    }
-  }
-  /** Unmap + unlink the current segment, if any. */
-  releaseSegment() {
-    const segment = this.segment;
-    if (segment === null) return;
-    this.segment = null;
-    this.writer = null;
-    const name = this.segmentName;
-    this.segmentName = null;
-    try {
-      segment.close();
-      segment.unlink();
-      this.logger.info("decoder shm ring: segment released", {
-        meta: { segment: name }
-      });
-    } catch (err) {
-      this.logger.warn("decoder shm ring: segment release failed", {
-        meta: {
-          segment: name,
-          error: err instanceof Error ? err.message : String(err)
-        }
-      });
-    }
-  }
+	let hash = 5381;
+	for (let i = 0; i < seed.length; i += 1) hash = (hash << 5) + hash + seed.charCodeAt(i) | 0;
+	return `csf.${(hash >>> 0).toString(36)}.${generation}`;
 }
+/**
+* The decoder-side owner of one stream's shared-memory frame ring.
+*
+* Not constructed until a session actually uses the shm sink; the segment
+* itself is created lazily on the first `writeFrame`.
+*/
+var DecoderFrameRingSink = class {
+	seed;
+	logger;
+	nodeId;
+	segment = null;
+	writer = null;
+	segmentName = null;
+	slotByteLength = 0;
+	generation = 0;
+	destroyed = false;
+	/** Frames committed into the ring across this sink's lifetime (all generations). */
+	framesWritten = 0;
+	constructor(options) {
+		const salt = Math.random().toString(36).slice(2, 8);
+		this.seed = `${options.seed}.${salt}`;
+		this.logger = options.logger;
+		this.nodeId = options.nodeId;
+	}
+	/** Whether a segment has been created (i.e. at least one frame written). */
+	get isArmed() {
+		return this.writer !== null;
+	}
+	/** The current segment name, or `null` before the first frame. */
+	get currentSegmentName() {
+		return this.segmentName;
+	}
+	/**
+	* Write one decoded frame into the ring and return its `FrameHandle`.
+	*
+	* On the first call (or after a geometry change that overflows the current
+	* slot) the segment is created / re-created sized for this frame. Returns
+	* `null` only when the sink has been destroyed.
+	*
+	* This is the copy-in convenience form (it copies `pixels` into the slot).
+	* The decoder's hot path uses the zero-copy {@link beginFrame} /
+	* {@link commitFrame} scatter-write pair instead — the scaler produces its
+	* packed output directly into the slot, eliminating the write-side memcpy.
+	*/
+	writeFrame(pixels, meta) {
+		if (this.destroyed) return null;
+		if (this.writer === null || computeSlotByteLength(meta.width, meta.height, meta.format) > this.slotByteLength) this.recreateSegment(computeSlotByteLength(meta.width, meta.height, meta.format));
+		const writer = this.writer;
+		if (writer === null) return null;
+		const handle = writer.writeFrame(pixels, meta);
+		this.framesWritten += 1;
+		return handle;
+	}
+	/**
+	* Reserve a ring slot for a frame of the given geometry — the **zero-copy**
+	* scatter-write entry point (Phase 5 / D9 Task 7c).
+	*
+	* The segment is created / re-created here if this is the first frame or the
+	* geometry overflows the current slot capacity, so the slot is correctly
+	* sized before the caller fills it. The returned `buffer` is a writable view
+	* **directly over the mapped segment** — the node-av scaler scatters its
+	* packed output straight into it, with no intermediate copy. The caller MUST
+	* call {@link commitFrame} with the returned `slot` once the slot is filled.
+	*
+	* Returns `null` when the sink is destroyed or the segment cannot be created.
+	*/
+	beginFrame(width, height, format) {
+		if (this.destroyed) return null;
+		const requiredSlotBytes = computeSlotByteLength(width, height, format);
+		if (this.writer === null || requiredSlotBytes > this.slotByteLength) this.recreateSegment(requiredSlotBytes);
+		const writer = this.writer;
+		if (writer === null) return null;
+		const { slot, buffer } = writer.beginFrame();
+		return {
+			slot,
+			buffer
+		};
+	}
+	/**
+	* Publish the frame whose slot was reserved by {@link beginFrame} and filled
+	* in place by the caller. `slot` MUST be the value from the matching
+	* `beginFrame`. Returns the published `FrameHandle`, or `null` if the sink
+	* was destroyed (or the segment lost) between begin and commit.
+	*/
+	commitFrame(slot, meta) {
+		if (this.destroyed) return null;
+		const writer = this.writer;
+		if (writer === null) return null;
+		const handle = writer.commitFrame(slot, meta);
+		this.framesWritten += 1;
+		return handle;
+	}
+	/**
+	* Current shm ring usage — `null` until the first frame arms the segment.
+	* Surfaced through `decoder.getShmStats` so a downstream consumer can
+	* observe ring pressure (slot depth, byte budget, frames written).
+	*/
+	getShmStats() {
+		if (this.writer === null) return null;
+		return {
+			slotCount: this.writer.slotCount,
+			slotByteLength: this.slotByteLength,
+			segmentBytes: computeSegmentSize(this.writer.slotCount, this.slotByteLength),
+			framesWritten: this.framesWritten
+		};
+	}
+	/**
+	* Abandon a slot reserved by {@link beginFrame} **without publishing it** —
+	* the degenerate-path counterpart of {@link commitFrame}.
+	*
+	* A caller that reserved a slot but then could not produce valid pixels (no
+	* decoded source planes, or the scaler threw) MUST call this instead of
+	* `commitFrame`: it closes the open seqlock without advancing `writeIndex`,
+	* so no reader ever sees the slot's uninitialised bytes as a real frame, and
+	* no `FrameHandle` is handed downstream. `slot` MUST be the value from the
+	* matching `beginFrame`. A no-op if the sink was destroyed (or the segment
+	* lost) between begin and abort.
+	*/
+	abortFrame(slot) {
+		if (this.destroyed) return;
+		const writer = this.writer;
+		if (writer === null) return;
+		writer.abortFrame(slot);
+	}
+	/** Close + unlink the segment. Idempotent. */
+	destroy() {
+		if (this.destroyed) return;
+		this.destroyed = true;
+		this.releaseSegment();
+	}
+	/**
+	* Create a fresh segment sized for at least `slotByteLength` bytes per slot,
+	* replacing any prior one. A re-create bumps the generation so the new
+	* segment has a distinct name — a consumer holding the old mapping is never
+	* silently handed a resized segment.
+	*/
+	recreateSegment(slotByteLength) {
+		this.releaseSegment();
+		this.generation += 1;
+		const name = makeSegmentName(this.seed, this.generation);
+		const slotCount = deriveSlotCount(RING_BUDGET_BYTES, slotByteLength);
+		if (slotCount === MIN_RING_SLOTS && MIN_RING_SLOTS * slotByteLength > RING_BUDGET_BYTES) this.logger.warn("decoder shm ring: budget too small for resolution — using MIN slots", { meta: {
+			slotByteLength,
+			budgetMb: RING_BUDGET_MB
+		} });
+		const totalBytes = computeSegmentSize(slotCount, slotByteLength);
+		try {
+			const segment = createSegment(name, totalBytes);
+			this.segment = segment;
+			this.segmentName = name;
+			this.slotByteLength = slotByteLength;
+			this.writer = new FrameRingWriter(segment.buffer, name, slotCount, slotByteLength, this.nodeId);
+			this.logger.info("decoder shm ring: segment created", { meta: {
+				segment: name,
+				slotCount,
+				slotByteLength,
+				totalBytes,
+				generation: this.generation
+			} });
+		} catch (err) {
+			this.segment = null;
+			this.writer = null;
+			this.segmentName = null;
+			this.slotByteLength = 0;
+			this.logger.error("decoder shm ring: segment create failed", { meta: {
+				segment: name,
+				slotByteLength,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+	/** Unmap + unlink the current segment, if any. */
+	releaseSegment() {
+		const segment = this.segment;
+		if (segment === null) return;
+		this.segment = null;
+		this.writer = null;
+		const name = this.segmentName;
+		this.segmentName = null;
+		try {
+			segment.close();
+			segment.unlink();
+			this.logger.info("decoder shm ring: segment released", { meta: { segment: name } });
+		} catch (err) {
+			this.logger.warn("decoder shm ring: segment release failed", { meta: {
+				segment: name,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+};
+//#endregion
+//#region src/decoder-nodeav/nodeav-decoder-session.ts
+/** Map our canonical backend name to the node-av `AV_HWDEVICE_TYPE_*` constant. */
 function backendToHwDeviceConst(backend, consts) {
-  switch (backend) {
-    case "videotoolbox":
-      return consts.AV_HWDEVICE_TYPE_VIDEOTOOLBOX;
-    case "cuda":
-      return consts.AV_HWDEVICE_TYPE_CUDA;
-    case "nvdec":
-      return consts.AV_HWDEVICE_TYPE_CUDA;
-    // node-av exposes only CUDA; nvdec aliases to it
-    case "vaapi":
-      return consts.AV_HWDEVICE_TYPE_VAAPI;
-    case "qsv":
-      return consts.AV_HWDEVICE_TYPE_QSV;
-    case "d3d11va":
-      return consts.AV_HWDEVICE_TYPE_D3D11VA;
-    case "dxva2":
-      return consts.AV_HWDEVICE_TYPE_DXVA2;
-    case "amf":
-      return consts.AV_HWDEVICE_TYPE_AMF;
-    case "vdpau":
-      return consts.AV_HWDEVICE_TYPE_VDPAU;
-    case "drm":
-      return consts.AV_HWDEVICE_TYPE_DRM;
-    default:
-      return null;
-  }
+	switch (backend) {
+		case "videotoolbox": return consts.AV_HWDEVICE_TYPE_VIDEOTOOLBOX;
+		case "cuda": return consts.AV_HWDEVICE_TYPE_CUDA;
+		case "nvdec": return consts.AV_HWDEVICE_TYPE_CUDA;
+		case "vaapi": return consts.AV_HWDEVICE_TYPE_VAAPI;
+		case "qsv": return consts.AV_HWDEVICE_TYPE_QSV;
+		case "d3d11va": return consts.AV_HWDEVICE_TYPE_D3D11VA;
+		case "dxva2": return consts.AV_HWDEVICE_TYPE_DXVA2;
+		case "amf": return consts.AV_HWDEVICE_TYPE_AMF;
+		case "vdpau": return consts.AV_HWDEVICE_TYPE_VDPAU;
+		case "drm": return consts.AV_HWDEVICE_TYPE_DRM;
+		default: return null;
+	}
 }
+/** Pick the hw pixel format for a given backend — used in get_format callback. */
 function backendToHwPixFmt(backend, consts) {
-  switch (backend) {
-    case "videotoolbox":
-      return consts.AV_PIX_FMT_VIDEOTOOLBOX;
-    case "cuda":
-      return consts.AV_PIX_FMT_CUDA;
-    case "nvdec":
-      return consts.AV_PIX_FMT_CUDA;
-    case "vaapi":
-      return consts.AV_PIX_FMT_VAAPI;
-    case "qsv":
-      return consts.AV_PIX_FMT_QSV;
-    case "d3d11va":
-      return consts.AV_PIX_FMT_D3D11;
-    case "dxva2":
-      return consts.AV_PIX_FMT_DXVA2_VLD;
-    case "amf":
-      return consts.AV_PIX_FMT_D3D11;
-    case "vdpau":
-      return consts.AV_PIX_FMT_VDPAU;
-    case "drm":
-      return consts.AV_PIX_FMT_DRM_PRIME;
-    default:
-      return null;
-  }
+	switch (backend) {
+		case "videotoolbox": return consts.AV_PIX_FMT_VIDEOTOOLBOX;
+		case "cuda": return consts.AV_PIX_FMT_CUDA;
+		case "nvdec": return consts.AV_PIX_FMT_CUDA;
+		case "vaapi": return consts.AV_PIX_FMT_VAAPI;
+		case "qsv": return consts.AV_PIX_FMT_QSV;
+		case "d3d11va": return consts.AV_PIX_FMT_D3D11;
+		case "dxva2": return consts.AV_PIX_FMT_DXVA2_VLD;
+		case "amf": return consts.AV_PIX_FMT_D3D11;
+		case "vdpau": return consts.AV_PIX_FMT_VDPAU;
+		case "drm": return consts.AV_PIX_FMT_DRM_PRIME;
+		default: return null;
+	}
 }
-let _nav = null;
-let _consts = null;
-let _sharp = null;
+var _nav = null;
+var _consts = null;
+var _sharp = null;
 async function getNodeAv() {
-  if (!_nav) _nav = await import("node-av");
-  return _nav;
+	if (!_nav) _nav = await import("node-av");
+	return _nav;
 }
 async function getConstants() {
-  if (!_consts) _consts = await import("../index-CYb7cFrv.mjs");
-  return _consts;
+	if (!_consts) _consts = await import("../constants-B_b0a-6h.mjs");
+	return _consts;
 }
 async function getSharp() {
-  if (!_sharp) {
-    const mod = await import("sharp");
-    _sharp = mod.default;
-  }
-  return _sharp;
+	if (!_sharp) _sharp = (await import("sharp")).default;
+	return _sharp;
 }
-const noopLogger = {
-  debug() {
-  },
-  info() {
-  },
-  warn() {
-  },
-  error() {
-  },
-  child() {
-    return noopLogger;
-  },
-  withTags() {
-    return noopLogger;
-  }
+var noopLogger = {
+	debug() {},
+	info() {},
+	warn() {},
+	error() {},
+	child() {
+		return noopLogger;
+	},
+	withTags() {
+		return noopLogger;
+	}
 };
-class NodeAvDecoderSession {
-  config;
-  logger;
-  frameCallbacks = /* @__PURE__ */ new Set();
-  handleCallbacks = /* @__PURE__ */ new Set();
-  destroyed = false;
-  /**
-   * Frame delivery mode (see {@link DecoderFrameSink}). `'shm'` lazily
-   * constructs `frameRingSink` and routes every decoded frame through it.
-   */
-  frameSink;
-  /**
-   * The shared-memory ring writer for this stream. Created lazily on the
-   * first decoded frame in `'shm'` mode (the segment cannot be sized until
-   * the output geometry is known) and torn down in `destroy`.
-   */
-  frameRingSink = null;
-  // Low-level node-av objects (initialized on first keyframe)
-  parser = null;
-  codecCtx = null;
-  scaler = null;
-  avPacket = null;
-  avFrame = null;
-  dstFrame = null;
-  // Cached constants (loaded during init, used in hot path)
-  // Hard-coded numeric defaults are replaced in initDecoder() with the real
-  // branded constants from `node-av/constants`. The `as` cast at the literal
-  // is a one-time branding bridge — once initDecoder runs we hold the exact
-  // AVPixelFormat/SwsFlags/AVError values.
-  EAGAIN = -11;
-  PIX_FMT_GRAY8 = 8;
-  PIX_FMT_RGB24 = 2;
-  SWS_FAST_BILINEAR = 1;
-  /**
-   * Decoder output mode. Drives both the scaler's destination pixel
-   * format and whether sharp runs the JPEG encode at the end:
-   *
-   * - `'jpeg'` — scaler→RGB24 → sharp encode → emit JPEG bytes
-   * - `'rgb'`  — scaler→RGB24 → emit raw RGB24 (no sharp)
-   * - `'gray'` — scaler→GRAY8 → emit raw GRAY8 (no sharp)
-   *
-   * The broker holds the policy decision on which mode to request based
-   * on its active subscribers; on-the-fly conversion (e.g. RGB→JPEG for
-   * a WebRTC consumer that joined while detection holds the decoder in
-   * RGB mode) happens broker-side via the per-frame conversion cache.
-   */
-  outputMode;
-  sharpFn = null;
-  /**
-   * Backpressure for the sharp JPEG encode pipeline. The broker
-   * currently creates sessions with `maxFps: 0` (unlimited) and relies
-   * on per-subscriber throttling, so without a bound the
-   * fire-and-forget `sharp(...).toBuffer()` chain would accumulate
-   * unboundedly whenever sharp falls behind the decoder. Cap at
-   * `MAX_JPEG_INFLIGHT` pending encodes per session — any frame that
-   * arrives while the cap is saturated is dropped and counted.
-   */
-  static MAX_JPEG_INFLIGHT = 2;
-  jpegEncodeInFlight = 0;
-  /**
-   * Map a `DecoderSessionConfig.outputFormat` value to one of the three
-   * native scaler/encoder modes the session understands. The cap-level
-   * format vocabulary is broader (it accepts `bgr`, `yuv420`) than what
-   * libav's scaler is wired for here — anything else degrades to RGB
-   * (the canonical raw mode) and the broker is expected to convert
-   * downstream if a subscriber needs a different shape.
-   */
-  static resolveOutputMode(format) {
-    if (format === "jpeg" || format === void 0) return "jpeg";
-    if (format === "gray") return "gray";
-    return "rgb";
-  }
-  initialized = false;
-  initializing = false;
-  scalerInitializing = false;
-  /**
-   * Monotonic counter incremented by `updateConfig` whenever the
-   * scaler + dstFrame get invalidated (e.g. output format toggle).
-   * `initScaler` captures the current value at entry and aborts — or
-   * disposes the locally-built scaler — if the epoch moved while
-   * its async init was in flight. Without this, a toggle racing an
-   * in-flight init could leave two scalers allocated natively while
-   * `this.scaler` only holds a reference to one → libav leak.
-   */
-  scalerEpoch = 0;
-  /**
-   * One-shot guard for the "first frame" diagnostic log + raw frame
-   * dump. Setting this synchronously inside `emitDecodedFrame`
-   * prevents re-entry — without it we were using `outputFrames === 0`
-   * which stays true until the async sharp encode callback runs, so
-   * several decoded frames could trigger the dump before the first
-   * JPEG landed.
-   */
-  firstFrameLogged = false;
-  // Output dimensions
-  outWidth = 0;
-  outHeight = 0;
-  // FPS limiter
-  lastEmitTime = 0;
-  minIntervalMs;
-  // Stats
-  inputPackets = 0;
-  outputFrames = 0;
-  droppedFrames = 0;
-  totalDecodeTimeMs = 0;
-  startTime = Date.now();
-  hwaccelPref;
-  hwaccelResolver;
-  /** Cluster node id stamped into every `FrameHandle` the `'shm'` sink emits. */
-  nodeId;
-  /** The backend that actually initialised successfully — `'none'` = software fallback. */
-  activeHwAccel = "none";
-  hwDevice = null;
-  swTransferFrame = null;
-  constructor(config, logger = noopLogger, options) {
-    this.config = { ...config };
-    const sessionTags = {};
-    if (typeof config.deviceId === "number") sessionTags["deviceId"] = config.deviceId;
-    if (typeof config.tag === "string" && config.tag.length > 0) sessionTags["tag"] = config.tag;
-    this.logger = Object.keys(sessionTags).length > 0 ? logger.withTags(sessionTags) : logger;
-    this.minIntervalMs = config.maxFps > 0 ? 1e3 / config.maxFps : 0;
-    this.outputMode = NodeAvDecoderSession.resolveOutputMode(config.outputFormat);
-    this.hwaccelPref = options?.hwaccel ?? "auto";
-    this.hwaccelResolver = options?.hwaccelResolver ?? null;
-    this.frameSink = options?.frameSink ?? "callback";
-    this.nodeId = options?.nodeId ?? "local";
-  }
-  /**
-   * The shared-memory ring sink for this stream, or `null` before the first
-   * `'shm'`-mode frame lazily creates it. Exposed so the owning addon can
-   * surface ring stats via `decoder.getShmStats`.
-   */
-  get frameRingSinkOrNull() {
-    return this.frameRingSink;
-  }
-  /**
-   * Lazily build the shared-memory ring sink for this stream. The segment
-   * itself is still created lazily by the sink on its first `writeFrame`,
-   * once the decoded geometry is known.
-   */
-  ensureFrameRingSink() {
-    if (this.frameRingSink === null) {
-      const seedParts = [];
-      if (typeof this.config.deviceId === "number") {
-        seedParts.push(String(this.config.deviceId));
-      }
-      if (typeof this.config.tag === "string" && this.config.tag.length > 0) {
-        seedParts.push(this.config.tag);
-      }
-      const seed = seedParts.length > 0 ? seedParts.join(":") : "anon";
-      this.frameRingSink = new DecoderFrameRingSink({
-        seed,
-        logger: this.logger,
-        nodeId: this.nodeId
-      });
-    }
-    return this.frameRingSink;
-  }
-  /**
-   * Resolve the backend preference list and try each one against
-   * node-av's HW context APIs. The first backend whose
-   * `HardwareDeviceContext.create()` succeeds gets attached to
-   * `codecCtx.hwDeviceCtx` + its hw pixel format registered via
-   * `setHardwarePixelFormat`. On any failure, falls through to the
-   * next backend; if all fail, returns with `activeHwAccel='none'`
-   * and the decoder runs in software on the same context.
-   */
-  async tryAttachHwAccel(nav, C) {
-    if (!this.codecCtx) return;
-    if (this.hwaccelPref === "none") {
-      this.activeHwAccel = "none";
-      return;
-    }
-    const explicit = this.hwaccelPref === "auto" ? null : this.hwaccelPref;
-    const resolution = this.hwaccelResolver ? await this.hwaccelResolver.resolve(explicit) : explicit ? { preferred: [explicit], rationale: "explicit (no resolver)" } : { preferred: [], rationale: "auto + no resolver → software" };
-    if (resolution.preferred.length === 0) {
-      this.activeHwAccel = "none";
-      return;
-    }
-    for (const backend of resolution.preferred) {
-      const deviceType = backendToHwDeviceConst(backend, C);
-      const hwPixFmt = backendToHwPixFmt(backend, C);
-      if (!deviceType || !hwPixFmt) continue;
-      const device = new nav.HardwareDeviceContext();
-      const rc = device.create(deviceType);
-      if (rc < 0) {
-        this.logger.warn("node-av: hwaccel device create failed — trying next", {
-          meta: { backend, rc }
-        });
-        device.free();
-        continue;
-      }
-      try {
-        this.codecCtx.hwDeviceCtx = device;
-        this.codecCtx.setHardwarePixelFormat(hwPixFmt);
-      } catch (err) {
-        this.logger.warn("node-av: hwaccel context attach failed — trying next", {
-          meta: { backend, error: errMsg(err) }
-        });
-        device.free();
-        continue;
-      }
-      this.hwDevice = device;
-      this.activeHwAccel = backend;
-      return;
-    }
-    this.logger.warn("node-av: no hwaccel backend initialised — using software", {
-      meta: { attempted: resolution.preferred.join(","), rationale: resolution.rationale }
-    });
-    this.activeHwAccel = "none";
-  }
-  /**
-   * Download a HW frame (format == hw pix fmt) into a SW frame so the
-   * rest of the pipeline (scaler, JPEG encoder, grayscale passthrough)
-   * handles it identically to the pure-software path. Uses the sync
-   * variant so the synchronous receive loop below doesn't need to be
-   * async-ified. Returns `null` on transfer failure, meaning the
-   * caller should drop the frame.
-   */
-  transferHwFrame(hwFrame) {
-    if (this.activeHwAccel === "none" || !this.swTransferFrame) return hwFrame;
-    const rc = hwFrame.hwframeTransferDataSync(this.swTransferFrame, 0);
-    if (rc < 0) {
-      this.logger.warn("node-av: hwframeTransferData failed", { meta: { rc } });
-      return null;
-    }
-    return this.swTransferFrame;
-  }
-  /**
-   * Initialize the decoder pipeline on the first keyframe.
-   * After this returns, all hot-path methods are fully synchronous (except JPEG encode).
-   */
-  async initDecoder() {
-    if (this.initialized || this.initializing || this.destroyed) return;
-    this.initializing = true;
-    try {
-      const nav = await getNodeAv();
-      const C = await getConstants();
-      this.EAGAIN = C.AVERROR_EAGAIN;
-      this.PIX_FMT_GRAY8 = C.AV_PIX_FMT_GRAY8;
-      this.PIX_FMT_RGB24 = C.AV_PIX_FMT_RGB24;
-      this.SWS_FAST_BILINEAR = C.SWS_FAST_BILINEAR;
-      if (this.outputMode === "jpeg") {
-        this.sharpFn = await getSharp();
-      }
-      nav.Log.setLevel(C.AV_LOG_FATAL);
-      const isHevc = this.config.codec === "h265" || this.config.codec === "hevc";
-      const codecId = isHevc ? C.AV_CODEC_ID_HEVC : C.AV_CODEC_ID_H264;
-      this.parser = new nav.CodecParser();
-      this.parser.init(codecId);
-      const codec = nav.Codec.findDecoder(codecId);
-      if (!codec) {
-        this.logger.error("node-av: no decoder found", { meta: { codec: this.config.codec } });
-        return;
-      }
-      this.codecCtx = new nav.CodecContext();
-      this.codecCtx.allocContext3(codec);
-      if (this.config.width && this.config.height) {
-        this.codecCtx.width = this.config.width;
-        this.codecCtx.height = this.config.height;
-      }
-      this.codecCtx.threadCount = 1;
-      await this.tryAttachHwAccel(nav, C);
-      const ret = await this.codecCtx.open2(codec);
-      if (ret < 0) {
-        if (this.activeHwAccel !== "none") {
-          this.logger.warn("node-av: open2 failed with hwaccel — retrying in software", {
-            meta: { ret, hwAccel: this.activeHwAccel }
-          });
-          this.hwDevice?.free();
-          this.hwDevice = null;
-          this.activeHwAccel = "none";
-          this.codecCtx = new nav.CodecContext();
-          this.codecCtx.allocContext3(codec);
-          if (this.config.width && this.config.height) {
-            this.codecCtx.width = this.config.width;
-            this.codecCtx.height = this.config.height;
-          }
-          this.codecCtx.threadCount = 1;
-          const retry = await this.codecCtx.open2(codec);
-          if (retry < 0) {
-            this.logger.error("node-av: failed to open decoder (sw fallback)", { meta: { ret: retry } });
-            return;
-          }
-        } else {
-          this.logger.error("node-av: failed to open decoder", { meta: { ret } });
-          return;
-        }
-      }
-      if (this.activeHwAccel !== "none") {
-        this.swTransferFrame = new nav.Frame();
-        this.swTransferFrame.alloc();
-      }
-      this.avPacket = new nav.Packet();
-      this.avPacket.alloc();
-      this.avFrame = new nav.Frame();
-      this.avFrame.alloc();
-      this.initialized = true;
-      this.logger.info("node-av push decoder initialized", {
-        meta: {
-          codec: this.config.codec,
-          output: this.outputMode,
-          // Reports the backend that actually succeeded at
-          // `open2(codec)` with `hwDeviceCtx` attached, or `'none'` if
-          // we fell back to software (explicit `hwaccel: 'none'`
-          // override, empty resolver output, or every attempted
-          // backend failed init).
-          hwAccel: this.activeHwAccel
-        }
-      });
-    } catch (err) {
-      this.logger.error("node-av init error", { meta: { error: errMsg(err) } });
-    } finally {
-      this.initializing = false;
-    }
-  }
-  /**
-   * Initialize the scaler after the first frame tells us the actual
-   * dimensions. Output pixel format: RGB24 for JPEG encoding, GRAY8
-   * for raw motion.
-   *
-   * Builds `scaler` + `dstFrame` on local variables and publishes
-   * them onto `this` in a single atomic step at the end. Captures
-   * `scalerEpoch` at entry; if `updateConfig` invalidated the scaler
-   * while this init was in flight (epoch mismatch), the locally
-   * built pair is disposed and discarded so the later init wins.
-   * Without the local-first approach, partial state (scaler set,
-   * dstFrame still null) could be observed by a concurrent
-   * `emitDecodedFrame` call.
-   */
-  async initScaler(srcW, srcH, srcFmt) {
-    if (this.scalerInitializing) return;
-    this.scalerInitializing = true;
-    const myEpoch = this.scalerEpoch;
-    let localScaler = null;
-    let localDstFrame = null;
-    try {
-      const nav = await getNodeAv();
-      if (this.destroyed || myEpoch !== this.scalerEpoch) return;
-      const scale = this.config.scale > 1 ? this.config.scale : 1;
-      const maxW = Math.floor(640 / scale);
-      const outWidth = Math.min(srcW, maxW);
-      const outHeight = Math.round(outWidth * srcH / srcW);
-      const dstFmt = this.outputMode === "gray" ? this.PIX_FMT_GRAY8 : this.PIX_FMT_RGB24;
-      const fmtName = this.outputMode === "gray" ? "gray8" : "rgb24";
-      localScaler = new nav.SoftwareScaleContext();
-      localScaler.getContext(
-        srcW,
-        srcH,
-        srcFmt,
-        outWidth,
-        outHeight,
-        dstFmt,
-        this.SWS_FAST_BILINEAR
-      );
-      const ret = localScaler.initContext();
-      if (ret < 0) {
-        this.logger.error("node-av: sws_init_context failed", { meta: { ret } });
-        return;
-      }
-      localDstFrame = new nav.Frame();
-      localDstFrame.alloc();
-      localDstFrame.width = outWidth;
-      localDstFrame.height = outHeight;
-      localDstFrame.format = dstFmt;
-      const allocRet = localDstFrame.allocBuffer();
-      if (allocRet < 0) {
-        this.logger.error("node-av: dst frame allocBuffer failed", { meta: { ret: allocRet } });
-        return;
-      }
-      if (this.destroyed || myEpoch !== this.scalerEpoch) return;
-      this.scaler?.[Symbol.dispose]?.();
-      this.dstFrame?.[Symbol.dispose]?.();
-      this.scaler = localScaler;
-      this.dstFrame = localDstFrame;
-      this.outWidth = outWidth;
-      this.outHeight = outHeight;
-      localScaler = null;
-      localDstFrame = null;
-      this.logger.info("node-av scaler initialized", {
-        meta: { srcWidth: srcW, srcHeight: srcH, outWidth, outHeight, format: fmtName }
-      });
-    } catch (err) {
-      this.logger.error("Scaler init failed", { meta: { error: errMsg(err) } });
-    } finally {
-      localScaler?.[Symbol.dispose]?.();
-      localDstFrame?.[Symbol.dispose]?.();
-      this.scalerInitializing = false;
-    }
-  }
-  pushPacket(packet) {
-    if (this.destroyed) return;
-    this.inputPackets++;
-    if (!this.initialized && !this.initializing && packet.keyframe) {
-      this.initDecoder().then(() => {
-        if (this.initialized) this.decodeRawData(packet.data, packet.pts ?? Date.now());
-      }).catch((err) => {
-        this.logger.error("node-av init failed", { meta: { error: errMsg(err) } });
-      });
-      return;
-    }
-    if (!this.initialized) return;
-    this.decodeRawData(packet.data, packet.pts ?? Date.now());
-  }
-  decodeRawData(data, pts) {
-    if (!this.parser || !this.codecCtx || !this.avPacket || !this.avFrame) return;
-    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
-    const bigPts = BigInt(pts);
-    let offset = 0;
-    while (offset < buf.length) {
-      const remaining = buf.subarray(offset);
-      const consumed = this.parser.parse2(
-        this.codecCtx,
-        this.avPacket,
-        remaining,
-        bigPts,
-        bigPts,
-        offset
-      );
-      if (consumed < 0) {
-        this.logger.warn("node-av parser error", { meta: { ret: consumed } });
-        break;
-      }
-      offset += consumed;
-      if (this.avPacket.size > 0) {
-        this.decodePacket();
-        this.avPacket.unref();
-      }
-    }
-  }
-  decodePacket() {
-    if (!this.codecCtx || !this.avFrame) return;
-    const sendRet = this.codecCtx.sendPacketSync(this.avPacket);
-    if (sendRet < 0 && sendRet !== this.EAGAIN) {
-      this.logger.warn("node-av sendPacket error", { meta: { ret: sendRet } });
-      return;
-    }
-    while (true) {
-      const recvRet = this.codecCtx.receiveFrameSync(this.avFrame);
-      if (recvRet < 0) break;
-      const frame = this.transferHwFrame(this.avFrame);
-      if (!frame) continue;
-      this.emitDecodedFrame(frame);
-    }
-  }
-  emitDecodedFrame(frame) {
-    const now = performance.now();
-    if (this.minIntervalMs > 0 && now - this.lastEmitTime < this.minIntervalMs) {
-      this.droppedFrames++;
-      return;
-    }
-    if (!this.scaler && !this.scalerInitializing) {
-      this.initScaler(frame.width, frame.height, frame.format);
-      return;
-    }
-    if (!this.dstFrame || !this.scaler) return;
-    const decodeStart = performance.now();
-    if (this.frameSink === "shm" && this.outputMode !== "jpeg") {
-      this.scaleIntoRingSlot(frame, decodeStart);
-      return;
-    }
-    try {
-      this.dstFrame.makeWritable();
-      this.scaler.scaleFrameSync(this.dstFrame, frame);
-    } catch (err) {
-      this.logger.warn("node-av scale error", { meta: { error: errMsg(err) } });
-      return;
-    }
-    if (!this.firstFrameLogged) {
-      this.firstFrameLogged = true;
-      const channels = this.outputMode === "gray" ? 1 : 3;
-      const ls = this.dstFrame.linesize;
-      const buf = this.dstFrame.toBuffer();
-      this.logger.info("dstFrame after scale", {
-        meta: {
-          phase: "frame-debug",
-          width: this.dstFrame.width,
-          height: this.dstFrame.height,
-          linesize: [ls[0], ls[1], ls[2]],
-          expectedStride: this.dstFrame.width * channels,
-          bufLen: buf.length,
-          expectedPacked: this.dstFrame.width * channels * this.dstFrame.height,
-          srcFormat: frame.format ?? "?"
-        }
-      });
-      if (this.outputMode !== "gray") {
-        import("node:fs").then((fsModule) => {
-          import("node:path").then((pathModule) => {
-            const dumpPath = pathModule.join(process.cwd(), "camstack-data", "debug-frame-rgb24.raw");
-            fsModule.writeFileSync(dumpPath, buf);
-            this.logger.info("Dumped first RGB24 frame", { meta: { phase: "frame-debug", path: dumpPath, bytes: buf.length } });
-          }).catch(() => {
-          });
-        }).catch(() => {
-        });
-      }
-    }
-    const rawBuf = this.extractPackedBuffer(this.dstFrame);
-    if (this.outputMode === "jpeg") {
-      this.encodeAndEmitJpeg(rawBuf, decodeStart);
-    } else if (this.outputMode === "rgb") {
-      this.emitRawFrame(rawBuf, "rgb", decodeStart);
-    } else {
-      this.emitRawFrame(rawBuf, "gray", decodeStart);
-    }
-  }
-  /**
-   * Scale a decoded frame **directly into a shared-memory ring slot** — the
-   * zero write-side copy path (Phase 5 / D9 Task 7c).
-   *
-   * `beginFrame` reserves the slot (its seqlock open / odd — readers skip it);
-   * `SoftwareScaleContext.scaleSync` (the low-level `sws_scale` mapping) writes
-   * the packed pixels straight into the slot buffer with `linesize = width ×
-   * bpp` — no linesize padding, so there is nothing to strip and nothing to
-   * memcpy; `commitFrame` writes the metadata, closes the seqlock and publishes
-   * the slot. The decoded source planes feed `scaleSync` as `srcSlice` +
-   * `srcStride` (`frame.data` / `frame.linesize`).
-   *
-   * Used only for raw output formats (rgb/bgr/gray). The jpeg path keeps the
-   * `dstFrame` + sharp encode route because sharp must consume an RGB buffer
-   * before the final (variable-length) jpeg bytes exist.
-   */
-  scaleIntoRingSlot(frame, decodeStart) {
-    if (!this.scaler) return;
-    const format = this.outputMode === "gray" ? "gray" : "rgb";
-    const channels = this.outputMode === "gray" ? 1 : 3;
-    const sink = this.ensureFrameRingSink();
-    const reserved = sink.beginFrame(this.outWidth, this.outHeight, format);
-    if (reserved === null) {
-      this.droppedFrames++;
-      return;
-    }
-    const srcPlanes = frame.data;
-    if (!srcPlanes || srcPlanes.length === 0) {
-      sink.abortFrame(reserved.slot);
-      this.droppedFrames++;
-      return;
-    }
-    const dstStride = this.outWidth * channels;
-    try {
-      const srcStrides = Array.from(frame.linesize).slice(0, srcPlanes.length);
-      this.scaler.scaleSync(
-        Array.from(srcPlanes),
-        srcStrides,
-        0,
-        frame.height,
-        [reserved.buffer],
-        [dstStride]
-      );
-    } catch (err) {
-      this.logger.warn("node-av scale-into-slot error", {
-        meta: { error: errMsg(err) }
-      });
-      sink.abortFrame(reserved.slot);
-      this.droppedFrames++;
-      return;
-    }
-    const decodeMs = performance.now() - decodeStart;
-    this.totalDecodeTimeMs += decodeMs;
-    this.outputFrames++;
-    this.lastEmitTime = performance.now();
-    if (!this.firstFrameLogged) {
-      this.firstFrameLogged = true;
-      this.logger.info("node-av: scaled directly into shm ring slot", {
-        meta: {
-          phase: "frame-debug",
-          width: this.outWidth,
-          height: this.outHeight,
-          dstStride,
-          format
-        }
-      });
-    }
-    if (this.outputFrames === 1 || this.outputFrames % 500 === 0) {
-      this.logger.info("node-av frame emitted", {
-        meta: {
-          frameNumber: this.outputFrames,
-          width: this.outWidth,
-          height: this.outHeight,
-          format,
-          decodeMs,
-          sink: "shm",
-          subs: this.handleCallbacks.size
-        }
-      });
-    }
-    const handle = sink.commitFrame(reserved.slot, {
-      width: this.outWidth,
-      height: this.outHeight,
-      format,
-      // pts uses performance.now() (monotonic, process-relative) for
-      // ring-ordering; DecodedFrameHandle.timestamp carries the wall clock.
-      pts: performance.now(),
-      byteLength: dstStride * this.outHeight
-    });
-    if (handle === null) {
-      this.droppedFrames++;
-      return;
-    }
-    const delivered = { handle, timestamp: Date.now() };
-    for (const cb of this.handleCallbacks) {
-      cb(delivered);
-    }
-  }
-  /**
-   * Extract packed pixel buffer from a decoded frame.
-   * FFmpeg's av_frame_get_buffer() may pad each row to alignment (32/64 bytes).
-   * Sharp and WASM consumers expect tightly-packed rows (stride = width * channels).
-   * If linesize matches expected stride, return the buffer directly (zero-copy).
-   */
-  extractPackedBuffer(frame) {
-    const channels = this.outputMode === "gray" ? 1 : 3;
-    const expectedStride = frame.width * channels;
-    const actualStride = frame.linesize[0] ?? expectedStride;
-    const src = frame.data?.[0];
-    if (!src) {
-      return frame.toBuffer();
-    }
-    if (actualStride === expectedStride) {
-      return Buffer.from(src.buffer, src.byteOffset, expectedStride * frame.height);
-    }
-    const dst = Buffer.allocUnsafe(expectedStride * frame.height);
-    for (let y = 0; y < frame.height; y++) {
-      src.copy(dst, y * expectedStride, y * actualStride, y * actualStride + expectedStride);
-    }
-    return dst;
-  }
-  /**
-   * Encode RGB24 raw buffer as JPEG and emit.
-   *
-   * Drops the frame (and counts it) when `MAX_JPEG_INFLIGHT` encodes
-   * are already pending — prevents unbounded growth of the
-   * fire-and-forget promise chain when sharp cannot keep up with the
-   * decode rate.
-   */
-  encodeAndEmitJpeg(rgb, decodeStart) {
-    if (!this.sharpFn) return;
-    if (this.jpegEncodeInFlight >= NodeAvDecoderSession.MAX_JPEG_INFLIGHT) {
-      this.droppedFrames++;
-      return;
-    }
-    this.jpegEncodeInFlight++;
-    this.sharpFn(rgb, {
-      raw: { width: this.outWidth, height: this.outHeight, channels: 3 }
-    }).jpeg({ quality: 80, mozjpeg: false }).toBuffer().then((jpegBuf) => {
-      if (this.destroyed) return;
-      this.emitRawFrame(jpegBuf, "jpeg", decodeStart);
-    }).catch((err) => {
-      this.logger.warn("sharp jpeg encode error", { meta: { error: errMsg(err) } });
-    }).finally(() => {
-      this.jpegEncodeInFlight--;
-    });
-  }
-  emitRawFrame(data, format, decodeStart) {
-    const decodeMs = performance.now() - decodeStart;
-    this.totalDecodeTimeMs += decodeMs;
-    this.outputFrames++;
-    this.lastEmitTime = performance.now();
-    if (this.outputFrames === 1 || this.outputFrames % 500 === 0) {
-      this.logger.info("node-av frame emitted", {
-        meta: {
-          frameNumber: this.outputFrames,
-          width: this.outWidth,
-          height: this.outHeight,
-          format,
-          decodeMs,
-          sink: this.frameSink,
-          subs: this.frameSink === "shm" ? this.handleCallbacks.size : this.frameCallbacks.size
-        }
-      });
-    }
-    if (this.frameSink === "shm") {
-      this.emitShmFrame(data, format);
-      return;
-    }
-    const decodedFrame = {
-      data,
-      width: this.outWidth,
-      height: this.outHeight,
-      format,
-      timestamp: Date.now()
-    };
-    for (const cb of this.frameCallbacks) {
-      cb(decodedFrame);
-    }
-  }
-  /**
-   * Write a decoded frame into this stream's shared-memory ring and deliver
-   * the resulting `FrameHandle` to `onFrameHandle` subscribers. No pixel
-   * `Buffer` is handed to callbacks — consumers open the segment and read the
-   * pixels zero-copy via a `FrameRingReader`.
-   */
-  emitShmFrame(data, format) {
-    const sink = this.ensureFrameRingSink();
-    const handle = sink.writeFrame(data, {
-      width: this.outWidth,
-      height: this.outHeight,
-      format,
-      // The decoder does not carry a source PTS down to this point; use a
-      // monotone-ish wall clock so a consumer can still order frames.
-      // NOTE: pts uses performance.now() (monotonic, process-relative) while
-      // DecodedFrameHandle.timestamp uses Date.now() (wall-clock epoch).
-      // The two clocks are intentionally distinct — pts is for ring-ordering,
-      // timestamp is for wall-clock correlation — and must not be compared.
-      pts: performance.now(),
-      byteLength: data.byteLength
-    });
-    if (handle === null) {
-      this.droppedFrames++;
-      return;
-    }
-    const frame = { handle, timestamp: Date.now() };
-    for (const cb of this.handleCallbacks) {
-      cb(frame);
-    }
-  }
-  onFrame(callback) {
-    this.frameCallbacks.add(callback);
-    return () => {
-      this.frameCallbacks.delete(callback);
-    };
-  }
-  /**
-   * Subscribe to shared-memory frame handles. Fires only when the session was
-   * created with `frameSink: 'shm'`; in the legacy `'callback'` mode no
-   * handles are produced and this subscription never fires.
-   */
-  onFrameHandle(callback) {
-    this.handleCallbacks.add(callback);
-    return () => {
-      this.handleCallbacks.delete(callback);
-    };
-  }
-  updateConfig(update) {
-    const prevFormat = this.config.outputFormat;
-    this.config = { ...this.config, ...update };
-    if (update.maxFps !== void 0) {
-      this.minIntervalMs = update.maxFps > 0 ? 1e3 / update.maxFps : 0;
-    }
-    if (update.outputFormat !== void 0 && update.outputFormat !== prevFormat) {
-      const prevMode = this.outputMode;
-      this.outputMode = NodeAvDecoderSession.resolveOutputMode(update.outputFormat);
-      if (this.outputMode === prevMode) return;
-      this.scalerEpoch++;
-      if (this.scaler) {
-        this.scaler[Symbol.dispose]?.();
-        this.scaler = null;
-      }
-      if (this.dstFrame) {
-        this.dstFrame[Symbol.dispose]?.();
-        this.dstFrame = null;
-      }
-      if (this.outputMode === "jpeg" && !this.sharpFn) {
-        getSharp().then((fn) => {
-          this.sharpFn = fn;
-        }).catch(() => {
-        });
-      }
-      this.logger.info("node-av: output format changed — scaler will reinit", {
-        meta: { from: prevFormat, to: update.outputFormat, mode: this.outputMode }
-      });
-    }
-  }
-  async destroy() {
-    if (this.destroyed) return;
-    this.destroyed = true;
-    this.frameCallbacks.clear();
-    this.handleCallbacks.clear();
-    this.frameRingSink?.destroy();
-    this.frameRingSink = null;
-    this.dstFrame?.[Symbol.dispose]?.();
-    this.avFrame?.[Symbol.dispose]?.();
-    this.avPacket?.[Symbol.dispose]?.();
-    this.scaler?.[Symbol.dispose]?.();
-    this.parser?.[Symbol.dispose]?.();
-    this.swTransferFrame?.[Symbol.dispose]?.();
-    this.codecCtx?.[Symbol.dispose]?.();
-    this.hwDevice?.free();
-    this.dstFrame = null;
-    this.avFrame = null;
-    this.avPacket = null;
-    this.scaler = null;
-    this.parser = null;
-    this.codecCtx = null;
-    this.swTransferFrame = null;
-    this.hwDevice = null;
-  }
-  getStats() {
-    const uptimeSec = Math.max((Date.now() - this.startTime) / 1e3, 1);
-    return {
-      inputFps: this.inputPackets / uptimeSec,
-      outputFps: this.outputFrames / uptimeSec,
-      avgDecodeTimeMs: this.outputFrames > 0 ? this.totalDecodeTimeMs / this.outputFrames : 0,
-      droppedFrames: this.droppedFrames
-    };
-  }
-  get isPullMode() {
-    return false;
-  }
-}
-const FRAME_BUFFER_CAPACITY = 32;
-class DecoderNodeAvAddon extends BaseAddon {
-  /**
-   * Sessions are stored as the concrete `NodeAvDecoderSession` (the only type
-   * this addon ever creates) so `getShmStats` can reach the per-session shm
-   * ring sink — `IDecoderSession` does not expose it.
-   */
-  sessions = /* @__PURE__ */ new Map();
-  /** Pixel-frame buffers — populated only for `frameSink: 'callback'` sessions. */
-  frameBuffers = /* @__PURE__ */ new Map();
-  /** `FrameHandle` buffers — populated only for `frameSink: 'shm'` sessions. */
-  handleBuffers = /* @__PURE__ */ new Map();
-  unsubscribers = /* @__PURE__ */ new Map();
-  sessionMeta = /* @__PURE__ */ new Map();
-  /**
-   * Per-shm-segment `FrameRingReader` cache backing `getFrame`. Opens each
-   * named segment once and reuses the reader for every later handle on it;
-   * built in `onInitialize` (it needs the scoped logger) and closed in
-   * `onShutdown`.
-   */
-  frameReaders = null;
-  /** Running `getFrame` hit/miss counters surfaced via `getShmStats`. */
-  getFrameHits = 0;
-  getFrameMisses = 0;
-  constructor() {
-    super(DEFAULT_DECODER_HWACCEL_CONFIG);
-  }
-  globalSettingsSchema() {
-    return this.schema({
-      sections: [{
-        id: "hwaccel",
-        title: "Hardware acceleration",
-        tab: "decoder",
-        description: 'Backend used by node-av decoder sessions. "Auto" defers to the probed best; concrete backends force it. Changes apply to NEW sessions — existing sessions keep the backend they were created with.',
-        fields: [
-          this.field({
-            type: "select",
-            key: "hwaccel",
-            label: "Preferred backend",
-            options: [...HWACCEL_OPTIONS],
-            default: "auto",
-            immediate: true
-          }),
-          this.field({
-            type: "text",
-            key: "probedBestHwaccel",
-            label: "Probed best",
-            description: "Auto-detected best decoder backend on this host. Click the refresh icon to re-run the probe.",
-            readonlyField: true,
-            default: "",
-            actions: [
-              { action: "reprobe-hwaccel", icon: "refresh-cw", tooltip: "Re-probe hwaccel" }
-            ]
-          })
-        ]
-      }]
-    });
-  }
-  async onInitialize() {
-    this.ctx.logger.info("node-av decoder addon initialized");
-    this.frameReaders = new FrameRingReaderCache(this.ctx.logger);
-    if (!this.config.probedBestHwaccel) {
-      this.reprobeHwaccel().catch((err) => {
-        this.ctx.logger.warn("nodeav: auto-reprobe hwaccel failed", {
-          meta: { error: err instanceof Error ? err.message : String(err) }
-        });
-      });
-    }
-    return [{ capability: decoderCapability, provider: this }];
-  }
-  /**
-   * Resolve the effective hwaccel backend for a new session. Reads
-   * this addon's own `hwaccel` setting first. `'auto'` defers to the
-   * session's local resolver (`ctx.kernel.hwaccel`) which probes the
-   * host and picks. No more orchestrator round-trip — decoder addon
-   * is self-sufficient for this setting as of phase 2d.
-   */
-  resolveHwAccelPref() {
-    return this.config.hwaccel;
-  }
-  /**
-   * Re-run the platform probe on this host and persist the detected
-   * backend as `probedBestHwaccel`. The operator's `hwaccel` setting
-   * is intentionally left alone — the probe only updates the hint.
-   */
-  async reprobeHwaccel() {
-    const resolver = this.ctx.kernel.hwaccel;
-    if (!resolver) {
-      this.ctx.logger.warn("reprobeHwaccel: no kernel hwaccel resolver — returning none");
-      await this.ctx.settings?.writeAddonStore({ probedBestHwaccel: "none" });
-      return { backend: "none" };
-    }
-    try {
-      const res = await resolver.resolve();
-      const backend = res.preferred[0] ?? "none";
-      await this.ctx.settings?.writeAddonStore({ probedBestHwaccel: backend });
-      this.ctx.logger.info("reprobeHwaccel: wrote probedBestHwaccel", {
-        meta: { backend, rationale: res.rationale, preferred: res.preferred }
-      });
-      return { backend };
-    } catch (err) {
-      this.ctx.logger.warn("reprobeHwaccel failed", {
-        meta: { error: err instanceof Error ? err.message : String(err) }
-      });
-      await this.ctx.settings?.writeAddonStore({ probedBestHwaccel: "none" });
-      return { backend: "none" };
-    }
-  }
-  async supportsCodec(input) {
-    return ["h264", "h265", "hevc"].includes(input.codec.toLowerCase());
-  }
-  async getInfo() {
-    return {
-      id: "decoder-nodeav",
-      name: "Decoder (node-av)",
-      isPullMode: false,
-      priority: 10
-    };
-  }
-  /**
-   * The cluster node id of this decoder — the Moleculer nodeID (`hub`,
-   * `dev-agent-0`, …), not the addon id. Stamped into session-owned
-   * `FrameHandle`s so a downstream consumer routes `getFrame` to the node
-   * that holds the shm ring. A hierarchical broker nodeID (`hub/...`) is
-   * collapsed to the cluster-visible parent; in-process boot is left as-is.
-   * Mirrors the resolution `PipelineRunnerAddon.onInitialize` performs.
-   */
-  resolveLocalNodeId() {
-    const raw = this.ctx.kernel.localNodeId ?? this.ctx.id;
-    return raw.includes("/") ? raw.split("/")[0] : raw;
-  }
-  async createSession(config) {
-    const sessionId = randomUUID();
-    const hwaccel = this.resolveHwAccelPref();
-    const { frameSink } = config;
-    const nodeId = this.resolveLocalNodeId();
-    const session = new NodeAvDecoderSession(config, this.ctx.logger, {
-      hwaccel,
-      hwaccelResolver: this.ctx.kernel.hwaccel,
-      frameSink,
-      nodeId
-    });
-    const unsub = frameSink === "shm" ? this.wireShmSink(sessionId, session) : this.wireCallbackSink(sessionId, session);
-    this.sessions.set(sessionId, session);
-    this.unsubscribers.set(sessionId, unsub);
-    this.sessionMeta.set(sessionId, {
-      codec: config.codec,
-      outputFormat: config.outputFormat,
-      createdAtMs: Date.now()
-    });
-    this.ctx.logger.info("node-av: created session", { meta: { sessionId, codec: config.codec, hwaccelPref: hwaccel, frameSink, nodeId } });
-    return { sessionId, nodeId };
-  }
-  /**
-   * Subscribe a `'callback'` session's pixel frames into a per-session
-   * ring buffer drained by `pullFrames`.
-   */
-  wireCallbackSink(sessionId, session) {
-    const ringBuffer = new RingBuffer(FRAME_BUFFER_CAPACITY);
-    this.frameBuffers.set(sessionId, ringBuffer);
-    return session.onFrame((frame) => {
-      const { format } = frame;
-      if (format !== "jpeg" && format !== "rgb" && format !== "bgr" && format !== "yuv420" && format !== "gray") return;
-      const arrayBuf = new ArrayBuffer(frame.data.byteLength);
-      new Uint8Array(arrayBuf).set(frame.data);
-      const capData = new Uint8Array(arrayBuf);
-      const capFrame = {
-        data: capData,
-        width: frame.width,
-        height: frame.height,
-        format,
-        timestamp: frame.timestamp
-      };
-      ringBuffer.push(capFrame);
-    });
-  }
-  /**
-   * Subscribe a `'shm'` session's `FrameHandle`s into a per-session ring
-   * buffer drained by `pullHandles`. No pixel bytes cross the cap boundary
-   * — the broker opens the named segment and reads the pixels zero-copy.
-   */
-  wireShmSink(sessionId, session) {
-    const handleRing = new RingBuffer(FRAME_BUFFER_CAPACITY);
-    this.handleBuffers.set(sessionId, handleRing);
-    return session.onFrameHandle((frame) => {
-      handleRing.push(frame.handle);
-    });
-  }
-  async destroySession(input) {
-    const { sessionId } = input;
-    const session = this.sessions.get(sessionId);
-    if (!session) {
-      throw new Error(`decoder-nodeav: unknown sessionId ${sessionId}`);
-    }
-    const unsub = this.unsubscribers.get(sessionId);
-    if (unsub) unsub();
-    await session.destroy();
-    this.sessions.delete(sessionId);
-    this.frameBuffers.delete(sessionId);
-    this.handleBuffers.delete(sessionId);
-    this.unsubscribers.delete(sessionId);
-    this.sessionMeta.delete(sessionId);
-    this.ctx.logger.info("node-av: destroyed session", { meta: { sessionId } });
-  }
-  async listActiveSessions() {
-    const out = [];
-    for (const [sessionId, meta] of this.sessionMeta) {
-      out.push({ sessionId, codec: meta.codec, outputFormat: meta.outputFormat, createdAtMs: meta.createdAtMs });
-    }
-    return out;
-  }
-  async pushPacket(input) {
-    const session = this.sessions.get(input.sessionId);
-    if (!session) {
-      throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
-    }
-    const rawData = input.packet.data;
-    const data = Buffer.isBuffer(rawData) ? rawData : rawData instanceof Uint8Array ? Buffer.from(rawData.buffer, rawData.byteOffset, rawData.byteLength) : Buffer.from(rawData);
-    session.pushPacket({ ...input.packet, data });
-  }
-  async openStream(input) {
-    const session = this.sessions.get(input.sessionId);
-    if (!session) {
-      throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
-    }
-    void input.url;
-  }
-  async pullFrames(input) {
-    if (!this.sessions.has(input.sessionId)) {
-      throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
-    }
-    const ringBuffer = this.frameBuffers.get(input.sessionId);
-    if (!ringBuffer) return [];
-    return ringBuffer.drain(input.maxCount);
-  }
-  async pullHandles(input) {
-    if (!this.sessions.has(input.sessionId)) {
-      throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
-    }
-    const handleRing = this.handleBuffers.get(input.sessionId);
-    if (!handleRing) return [];
-    return handleRing.drain(input.maxCount);
-  }
-  async updateConfig(input) {
-    const session = this.sessions.get(input.sessionId);
-    if (!session) {
-      throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
-    }
-    session.updateConfig(input.config);
-  }
-  async getStats(input) {
-    const session = this.sessions.get(input.sessionId);
-    if (!session) {
-      throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
-    }
-    return session.getStats();
-  }
-  /**
-   * Read back the pixels a `FrameHandle` refers to from this node's shm ring
-   * (Phase 5 / D9 downstream access). Returns `null` when the slot was
-   * already recycled (latest-wins drop) or the segment could not be opened.
-   * The reader cache opens each named segment once and reuses the reader.
-   *
-   * The reader hands back a `Buffer` view over its **reusable scratch
-   * buffer**, only valid until the next `read` on the same reader; the
-   * cap caller may keep the frame across reads, so the pixels are copied
-   * into a fresh detached `ArrayBuffer` here. This matches the existing
-   * callback-path copy in `wireCallbackSink`.
-   */
-  async getFrame(input) {
-    const frame = this.frameReaders?.read(input.handle) ?? null;
-    if (!frame) {
-      this.getFrameMisses += 1;
-      return null;
-    }
-    this.getFrameHits += 1;
-    const arrayBuf = new ArrayBuffer(frame.data.byteLength);
-    new Uint8Array(arrayBuf).set(frame.data);
-    return {
-      data: new Uint8Array(arrayBuf),
-      width: frame.width,
-      height: frame.height,
-      format: frame.format,
-      timestamp: frame.timestamp
-    };
-  }
-  /**
-   * shm ring usage stats for a `frameSink: 'shm'` session — slot geometry,
-   * frames written, byte budget, plus this addon's running `getFrame`
-   * hit/miss counters. Returns `null` for an unknown session or one whose
-   * shm ring has not yet been armed by a first decoded frame.
-   */
-  async getShmStats(input) {
-    const session = this.sessions.get(input.sessionId);
-    const stats = session?.frameRingSinkOrNull?.getShmStats() ?? null;
-    if (!stats) return null;
-    return {
-      sessionId: input.sessionId,
-      ...stats,
-      budgetMb: RING_BUDGET_MB,
-      getFrameHits: this.getFrameHits,
-      getFrameMisses: this.getFrameMisses
-    };
-  }
-  async onShutdown() {
-    this.ctx.logger.info("node-av decoder addon shutdown — destroying all sessions");
-    const destroyPromises = [];
-    for (const [sessionId, session] of this.sessions) {
-      const unsub = this.unsubscribers.get(sessionId);
-      if (unsub) unsub();
-      destroyPromises.push(session.destroy());
-    }
-    await Promise.all(destroyPromises);
-    this.sessions.clear();
-    this.frameBuffers.clear();
-    this.handleBuffers.clear();
-    this.unsubscribers.clear();
-    this.sessionMeta.clear();
-    this.frameReaders?.close();
-    this.frameReaders = null;
-  }
-}
-export {
-  DecoderFrameRingSink,
-  DecoderNodeAvAddon,
-  NodeAvDecoderSession,
-  DecoderNodeAvAddon as default,
-  makeSegmentName
+var NodeAvDecoderSession = class NodeAvDecoderSession {
+	config;
+	logger;
+	frameCallbacks = /* @__PURE__ */ new Set();
+	handleCallbacks = /* @__PURE__ */ new Set();
+	destroyed = false;
+	/**
+	* Frame delivery mode (see {@link DecoderFrameSink}). `'shm'` lazily
+	* constructs `frameRingSink` and routes every decoded frame through it.
+	*/
+	frameSink;
+	/**
+	* The shared-memory ring writer for this stream. Created lazily on the
+	* first decoded frame in `'shm'` mode (the segment cannot be sized until
+	* the output geometry is known) and torn down in `destroy`.
+	*/
+	frameRingSink = null;
+	parser = null;
+	codecCtx = null;
+	scaler = null;
+	avPacket = null;
+	avFrame = null;
+	dstFrame = null;
+	EAGAIN = -11;
+	PIX_FMT_GRAY8 = 8;
+	PIX_FMT_RGB24 = 2;
+	SWS_FAST_BILINEAR = 1;
+	/**
+	* Decoder output mode. Drives both the scaler's destination pixel
+	* format and whether sharp runs the JPEG encode at the end:
+	*
+	* - `'jpeg'` — scaler→RGB24 → sharp encode → emit JPEG bytes
+	* - `'rgb'`  — scaler→RGB24 → emit raw RGB24 (no sharp)
+	* - `'gray'` — scaler→GRAY8 → emit raw GRAY8 (no sharp)
+	*
+	* The broker holds the policy decision on which mode to request based
+	* on its active subscribers; on-the-fly conversion (e.g. RGB→JPEG for
+	* a WebRTC consumer that joined while detection holds the decoder in
+	* RGB mode) happens broker-side via the per-frame conversion cache.
+	*/
+	outputMode;
+	sharpFn = null;
+	/**
+	* Backpressure for the sharp JPEG encode pipeline. The broker
+	* currently creates sessions with `maxFps: 0` (unlimited) and relies
+	* on per-subscriber throttling, so without a bound the
+	* fire-and-forget `sharp(...).toBuffer()` chain would accumulate
+	* unboundedly whenever sharp falls behind the decoder. Cap at
+	* `MAX_JPEG_INFLIGHT` pending encodes per session — any frame that
+	* arrives while the cap is saturated is dropped and counted.
+	*/
+	static MAX_JPEG_INFLIGHT = 2;
+	jpegEncodeInFlight = 0;
+	/**
+	* Map a `DecoderSessionConfig.outputFormat` value to one of the three
+	* native scaler/encoder modes the session understands. The cap-level
+	* format vocabulary is broader (it accepts `bgr`, `yuv420`) than what
+	* libav's scaler is wired for here — anything else degrades to RGB
+	* (the canonical raw mode) and the broker is expected to convert
+	* downstream if a subscriber needs a different shape.
+	*/
+	static resolveOutputMode(format) {
+		if (format === "jpeg" || format === void 0) return "jpeg";
+		if (format === "gray") return "gray";
+		return "rgb";
+	}
+	initialized = false;
+	initializing = false;
+	scalerInitializing = false;
+	/**
+	* Monotonic counter incremented by `updateConfig` whenever the
+	* scaler + dstFrame get invalidated (e.g. output format toggle).
+	* `initScaler` captures the current value at entry and aborts — or
+	* disposes the locally-built scaler — if the epoch moved while
+	* its async init was in flight. Without this, a toggle racing an
+	* in-flight init could leave two scalers allocated natively while
+	* `this.scaler` only holds a reference to one → libav leak.
+	*/
+	scalerEpoch = 0;
+	/**
+	* One-shot guard for the "first frame" diagnostic log + raw frame
+	* dump. Setting this synchronously inside `emitDecodedFrame`
+	* prevents re-entry — without it we were using `outputFrames === 0`
+	* which stays true until the async sharp encode callback runs, so
+	* several decoded frames could trigger the dump before the first
+	* JPEG landed.
+	*/
+	firstFrameLogged = false;
+	outWidth = 0;
+	outHeight = 0;
+	lastEmitTime = 0;
+	minIntervalMs;
+	inputPackets = 0;
+	outputFrames = 0;
+	droppedFrames = 0;
+	totalDecodeTimeMs = 0;
+	startTime = Date.now();
+	hwaccelPref;
+	hwaccelResolver;
+	/** Cluster node id stamped into every `FrameHandle` the `'shm'` sink emits. */
+	nodeId;
+	/** The backend that actually initialised successfully — `'none'` = software fallback. */
+	activeHwAccel = "none";
+	hwDevice = null;
+	swTransferFrame = null;
+	constructor(config, logger = noopLogger, options) {
+		this.config = { ...config };
+		const sessionTags = {};
+		if (typeof config.deviceId === "number") sessionTags["deviceId"] = config.deviceId;
+		if (typeof config.tag === "string" && config.tag.length > 0) sessionTags["tag"] = config.tag;
+		this.logger = Object.keys(sessionTags).length > 0 ? logger.withTags(sessionTags) : logger;
+		this.minIntervalMs = config.maxFps > 0 ? 1e3 / config.maxFps : 0;
+		this.outputMode = NodeAvDecoderSession.resolveOutputMode(config.outputFormat);
+		this.hwaccelPref = options?.hwaccel ?? "auto";
+		this.hwaccelResolver = options?.hwaccelResolver ?? null;
+		this.frameSink = options?.frameSink ?? "callback";
+		this.nodeId = options?.nodeId ?? "local";
+	}
+	/**
+	* The shared-memory ring sink for this stream, or `null` before the first
+	* `'shm'`-mode frame lazily creates it. Exposed so the owning addon can
+	* surface ring stats via `decoder.getShmStats`.
+	*/
+	get frameRingSinkOrNull() {
+		return this.frameRingSink;
+	}
+	/**
+	* Lazily build the shared-memory ring sink for this stream. The segment
+	* itself is still created lazily by the sink on its first `writeFrame`,
+	* once the decoded geometry is known.
+	*/
+	ensureFrameRingSink() {
+		if (this.frameRingSink === null) {
+			const seedParts = [];
+			if (typeof this.config.deviceId === "number") seedParts.push(String(this.config.deviceId));
+			if (typeof this.config.tag === "string" && this.config.tag.length > 0) seedParts.push(this.config.tag);
+			const seed = seedParts.length > 0 ? seedParts.join(":") : "anon";
+			this.frameRingSink = new DecoderFrameRingSink({
+				seed,
+				logger: this.logger,
+				nodeId: this.nodeId
+			});
+		}
+		return this.frameRingSink;
+	}
+	/**
+	* Resolve the backend preference list and try each one against
+	* node-av's HW context APIs. The first backend whose
+	* `HardwareDeviceContext.create()` succeeds gets attached to
+	* `codecCtx.hwDeviceCtx` + its hw pixel format registered via
+	* `setHardwarePixelFormat`. On any failure, falls through to the
+	* next backend; if all fail, returns with `activeHwAccel='none'`
+	* and the decoder runs in software on the same context.
+	*/
+	async tryAttachHwAccel(nav, C) {
+		if (!this.codecCtx) return;
+		if (this.hwaccelPref === "none") {
+			this.activeHwAccel = "none";
+			return;
+		}
+		const explicit = this.hwaccelPref === "auto" ? null : this.hwaccelPref;
+		const resolution = this.hwaccelResolver ? await this.hwaccelResolver.resolve(explicit) : explicit ? {
+			preferred: [explicit],
+			rationale: "explicit (no resolver)"
+		} : {
+			preferred: [],
+			rationale: "auto + no resolver → software"
+		};
+		if (resolution.preferred.length === 0) {
+			this.activeHwAccel = "none";
+			return;
+		}
+		for (const backend of resolution.preferred) {
+			const deviceType = backendToHwDeviceConst(backend, C);
+			const hwPixFmt = backendToHwPixFmt(backend, C);
+			if (!deviceType || !hwPixFmt) continue;
+			const device = new nav.HardwareDeviceContext();
+			const rc = device.create(deviceType);
+			if (rc < 0) {
+				this.logger.warn("node-av: hwaccel device create failed — trying next", { meta: {
+					backend,
+					rc
+				} });
+				device.free();
+				continue;
+			}
+			try {
+				this.codecCtx.hwDeviceCtx = device;
+				this.codecCtx.setHardwarePixelFormat(hwPixFmt);
+			} catch (err) {
+				this.logger.warn("node-av: hwaccel context attach failed — trying next", { meta: {
+					backend,
+					error: errMsg(err)
+				} });
+				device.free();
+				continue;
+			}
+			this.hwDevice = device;
+			this.activeHwAccel = backend;
+			return;
+		}
+		this.logger.warn("node-av: no hwaccel backend initialised — using software", { meta: {
+			attempted: resolution.preferred.join(","),
+			rationale: resolution.rationale
+		} });
+		this.activeHwAccel = "none";
+	}
+	/**
+	* Download a HW frame (format == hw pix fmt) into a SW frame so the
+	* rest of the pipeline (scaler, JPEG encoder, grayscale passthrough)
+	* handles it identically to the pure-software path. Uses the sync
+	* variant so the synchronous receive loop below doesn't need to be
+	* async-ified. Returns `null` on transfer failure, meaning the
+	* caller should drop the frame.
+	*/
+	transferHwFrame(hwFrame) {
+		if (this.activeHwAccel === "none" || !this.swTransferFrame) return hwFrame;
+		const rc = hwFrame.hwframeTransferDataSync(this.swTransferFrame, 0);
+		if (rc < 0) {
+			this.logger.warn("node-av: hwframeTransferData failed", { meta: { rc } });
+			return null;
+		}
+		return this.swTransferFrame;
+	}
+	/**
+	* Initialize the decoder pipeline on the first keyframe.
+	* After this returns, all hot-path methods are fully synchronous (except JPEG encode).
+	*/
+	async initDecoder() {
+		if (this.initialized || this.initializing || this.destroyed) return;
+		this.initializing = true;
+		try {
+			const nav = await getNodeAv();
+			const C = await getConstants();
+			this.EAGAIN = C.AVERROR_EAGAIN;
+			this.PIX_FMT_GRAY8 = C.AV_PIX_FMT_GRAY8;
+			this.PIX_FMT_RGB24 = C.AV_PIX_FMT_RGB24;
+			this.SWS_FAST_BILINEAR = C.SWS_FAST_BILINEAR;
+			if (this.outputMode === "jpeg") this.sharpFn = await getSharp();
+			nav.Log.setLevel(C.AV_LOG_FATAL);
+			const codecId = this.config.codec === "h265" || this.config.codec === "hevc" ? C.AV_CODEC_ID_HEVC : C.AV_CODEC_ID_H264;
+			this.parser = new nav.CodecParser();
+			this.parser.init(codecId);
+			const codec = nav.Codec.findDecoder(codecId);
+			if (!codec) {
+				this.logger.error("node-av: no decoder found", { meta: { codec: this.config.codec } });
+				return;
+			}
+			this.codecCtx = new nav.CodecContext();
+			this.codecCtx.allocContext3(codec);
+			if (this.config.width && this.config.height) {
+				this.codecCtx.width = this.config.width;
+				this.codecCtx.height = this.config.height;
+			}
+			this.codecCtx.threadCount = 1;
+			await this.tryAttachHwAccel(nav, C);
+			const ret = await this.codecCtx.open2(codec);
+			if (ret < 0) if (this.activeHwAccel !== "none") {
+				this.logger.warn("node-av: open2 failed with hwaccel — retrying in software", { meta: {
+					ret,
+					hwAccel: this.activeHwAccel
+				} });
+				this.hwDevice?.free();
+				this.hwDevice = null;
+				this.activeHwAccel = "none";
+				this.codecCtx = new nav.CodecContext();
+				this.codecCtx.allocContext3(codec);
+				if (this.config.width && this.config.height) {
+					this.codecCtx.width = this.config.width;
+					this.codecCtx.height = this.config.height;
+				}
+				this.codecCtx.threadCount = 1;
+				const retry = await this.codecCtx.open2(codec);
+				if (retry < 0) {
+					this.logger.error("node-av: failed to open decoder (sw fallback)", { meta: { ret: retry } });
+					return;
+				}
+			} else {
+				this.logger.error("node-av: failed to open decoder", { meta: { ret } });
+				return;
+			}
+			if (this.activeHwAccel !== "none") {
+				this.swTransferFrame = new nav.Frame();
+				this.swTransferFrame.alloc();
+			}
+			this.avPacket = new nav.Packet();
+			this.avPacket.alloc();
+			this.avFrame = new nav.Frame();
+			this.avFrame.alloc();
+			this.initialized = true;
+			this.logger.info("node-av push decoder initialized", { meta: {
+				codec: this.config.codec,
+				output: this.outputMode,
+				hwAccel: this.activeHwAccel
+			} });
+		} catch (err) {
+			this.logger.error("node-av init error", { meta: { error: errMsg(err) } });
+		} finally {
+			this.initializing = false;
+		}
+	}
+	/**
+	* Initialize the scaler after the first frame tells us the actual
+	* dimensions. Output pixel format: RGB24 for JPEG encoding, GRAY8
+	* for raw motion.
+	*
+	* Builds `scaler` + `dstFrame` on local variables and publishes
+	* them onto `this` in a single atomic step at the end. Captures
+	* `scalerEpoch` at entry; if `updateConfig` invalidated the scaler
+	* while this init was in flight (epoch mismatch), the locally
+	* built pair is disposed and discarded so the later init wins.
+	* Without the local-first approach, partial state (scaler set,
+	* dstFrame still null) could be observed by a concurrent
+	* `emitDecodedFrame` call.
+	*/
+	async initScaler(srcW, srcH, srcFmt) {
+		if (this.scalerInitializing) return;
+		this.scalerInitializing = true;
+		const myEpoch = this.scalerEpoch;
+		let localScaler = null;
+		let localDstFrame = null;
+		try {
+			const nav = await getNodeAv();
+			if (this.destroyed || myEpoch !== this.scalerEpoch) return;
+			const scale = this.config.scale > 1 ? this.config.scale : 1;
+			const maxW = Math.floor(640 / scale);
+			const outWidth = Math.min(srcW, maxW);
+			const outHeight = Math.round(outWidth * srcH / srcW);
+			const dstFmt = this.outputMode === "gray" ? this.PIX_FMT_GRAY8 : this.PIX_FMT_RGB24;
+			const fmtName = this.outputMode === "gray" ? "gray8" : "rgb24";
+			localScaler = new nav.SoftwareScaleContext();
+			localScaler.getContext(srcW, srcH, srcFmt, outWidth, outHeight, dstFmt, this.SWS_FAST_BILINEAR);
+			const ret = localScaler.initContext();
+			if (ret < 0) {
+				this.logger.error("node-av: sws_init_context failed", { meta: { ret } });
+				return;
+			}
+			localDstFrame = new nav.Frame();
+			localDstFrame.alloc();
+			localDstFrame.width = outWidth;
+			localDstFrame.height = outHeight;
+			localDstFrame.format = dstFmt;
+			const allocRet = localDstFrame.allocBuffer();
+			if (allocRet < 0) {
+				this.logger.error("node-av: dst frame allocBuffer failed", { meta: { ret: allocRet } });
+				return;
+			}
+			if (this.destroyed || myEpoch !== this.scalerEpoch) return;
+			this.scaler?.[Symbol.dispose]?.();
+			this.dstFrame?.[Symbol.dispose]?.();
+			this.scaler = localScaler;
+			this.dstFrame = localDstFrame;
+			this.outWidth = outWidth;
+			this.outHeight = outHeight;
+			localScaler = null;
+			localDstFrame = null;
+			this.logger.info("node-av scaler initialized", { meta: {
+				srcWidth: srcW,
+				srcHeight: srcH,
+				outWidth,
+				outHeight,
+				format: fmtName
+			} });
+		} catch (err) {
+			this.logger.error("Scaler init failed", { meta: { error: errMsg(err) } });
+		} finally {
+			localScaler?.[Symbol.dispose]?.();
+			localDstFrame?.[Symbol.dispose]?.();
+			this.scalerInitializing = false;
+		}
+	}
+	pushPacket(packet) {
+		if (this.destroyed) return;
+		this.inputPackets++;
+		if (!this.initialized && !this.initializing && packet.keyframe) {
+			this.initDecoder().then(() => {
+				if (this.initialized) this.decodeRawData(packet.data, packet.pts ?? Date.now());
+			}).catch((err) => {
+				this.logger.error("node-av init failed", { meta: { error: errMsg(err) } });
+			});
+			return;
+		}
+		if (!this.initialized) return;
+		this.decodeRawData(packet.data, packet.pts ?? Date.now());
+	}
+	decodeRawData(data, pts) {
+		if (!this.parser || !this.codecCtx || !this.avPacket || !this.avFrame) return;
+		const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+		const bigPts = BigInt(pts);
+		let offset = 0;
+		while (offset < buf.length) {
+			const remaining = buf.subarray(offset);
+			const consumed = this.parser.parse2(this.codecCtx, this.avPacket, remaining, bigPts, bigPts, offset);
+			if (consumed < 0) {
+				this.logger.warn("node-av parser error", { meta: { ret: consumed } });
+				break;
+			}
+			offset += consumed;
+			if (this.avPacket.size > 0) {
+				this.decodePacket();
+				this.avPacket.unref();
+			}
+		}
+	}
+	decodePacket() {
+		if (!this.codecCtx || !this.avFrame) return;
+		const sendRet = this.codecCtx.sendPacketSync(this.avPacket);
+		if (sendRet < 0 && sendRet !== this.EAGAIN) {
+			this.logger.warn("node-av sendPacket error", { meta: { ret: sendRet } });
+			return;
+		}
+		while (true) {
+			if (this.codecCtx.receiveFrameSync(this.avFrame) < 0) break;
+			const frame = this.transferHwFrame(this.avFrame);
+			if (!frame) continue;
+			this.emitDecodedFrame(frame);
+		}
+	}
+	emitDecodedFrame(frame) {
+		const now = performance.now();
+		if (this.minIntervalMs > 0 && now - this.lastEmitTime < this.minIntervalMs) {
+			this.droppedFrames++;
+			return;
+		}
+		if (!this.scaler && !this.scalerInitializing) {
+			this.initScaler(frame.width, frame.height, frame.format);
+			return;
+		}
+		if (!this.dstFrame || !this.scaler) return;
+		const decodeStart = performance.now();
+		if (this.frameSink === "shm" && this.outputMode !== "jpeg") {
+			this.scaleIntoRingSlot(frame, decodeStart);
+			return;
+		}
+		try {
+			this.dstFrame.makeWritable();
+			this.scaler.scaleFrameSync(this.dstFrame, frame);
+		} catch (err) {
+			this.logger.warn("node-av scale error", { meta: { error: errMsg(err) } });
+			return;
+		}
+		if (!this.firstFrameLogged) {
+			this.firstFrameLogged = true;
+			const channels = this.outputMode === "gray" ? 1 : 3;
+			const ls = this.dstFrame.linesize;
+			const buf = this.dstFrame.toBuffer();
+			this.logger.info("dstFrame after scale", { meta: {
+				phase: "frame-debug",
+				width: this.dstFrame.width,
+				height: this.dstFrame.height,
+				linesize: [
+					ls[0],
+					ls[1],
+					ls[2]
+				],
+				expectedStride: this.dstFrame.width * channels,
+				bufLen: buf.length,
+				expectedPacked: this.dstFrame.width * channels * this.dstFrame.height,
+				srcFormat: frame.format ?? "?"
+			} });
+			if (this.outputMode !== "gray") import("node:fs").then((fsModule) => {
+				import("node:path").then((pathModule) => {
+					const dumpPath = pathModule.join(process.cwd(), "camstack-data", "debug-frame-rgb24.raw");
+					fsModule.writeFileSync(dumpPath, buf);
+					this.logger.info("Dumped first RGB24 frame", { meta: {
+						phase: "frame-debug",
+						path: dumpPath,
+						bytes: buf.length
+					} });
+				}).catch(() => {});
+			}).catch(() => {});
+		}
+		const rawBuf = this.extractPackedBuffer(this.dstFrame);
+		if (this.outputMode === "jpeg") this.encodeAndEmitJpeg(rawBuf, decodeStart);
+		else if (this.outputMode === "rgb") this.emitRawFrame(rawBuf, "rgb", decodeStart);
+		else this.emitRawFrame(rawBuf, "gray", decodeStart);
+	}
+	/**
+	* Scale a decoded frame **directly into a shared-memory ring slot** — the
+	* zero write-side copy path (Phase 5 / D9 Task 7c).
+	*
+	* `beginFrame` reserves the slot (its seqlock open / odd — readers skip it);
+	* `SoftwareScaleContext.scaleSync` (the low-level `sws_scale` mapping) writes
+	* the packed pixels straight into the slot buffer with `linesize = width ×
+	* bpp` — no linesize padding, so there is nothing to strip and nothing to
+	* memcpy; `commitFrame` writes the metadata, closes the seqlock and publishes
+	* the slot. The decoded source planes feed `scaleSync` as `srcSlice` +
+	* `srcStride` (`frame.data` / `frame.linesize`).
+	*
+	* Used only for raw output formats (rgb/bgr/gray). The jpeg path keeps the
+	* `dstFrame` + sharp encode route because sharp must consume an RGB buffer
+	* before the final (variable-length) jpeg bytes exist.
+	*/
+	scaleIntoRingSlot(frame, decodeStart) {
+		if (!this.scaler) return;
+		const format = this.outputMode === "gray" ? "gray" : "rgb";
+		const channels = this.outputMode === "gray" ? 1 : 3;
+		const sink = this.ensureFrameRingSink();
+		const reserved = sink.beginFrame(this.outWidth, this.outHeight, format);
+		if (reserved === null) {
+			this.droppedFrames++;
+			return;
+		}
+		const srcPlanes = frame.data;
+		if (!srcPlanes || srcPlanes.length === 0) {
+			sink.abortFrame(reserved.slot);
+			this.droppedFrames++;
+			return;
+		}
+		const dstStride = this.outWidth * channels;
+		try {
+			const srcStrides = Array.from(frame.linesize).slice(0, srcPlanes.length);
+			this.scaler.scaleSync(Array.from(srcPlanes), srcStrides, 0, frame.height, [reserved.buffer], [dstStride]);
+		} catch (err) {
+			this.logger.warn("node-av scale-into-slot error", { meta: { error: errMsg(err) } });
+			sink.abortFrame(reserved.slot);
+			this.droppedFrames++;
+			return;
+		}
+		const decodeMs = performance.now() - decodeStart;
+		this.totalDecodeTimeMs += decodeMs;
+		this.outputFrames++;
+		this.lastEmitTime = performance.now();
+		if (!this.firstFrameLogged) {
+			this.firstFrameLogged = true;
+			this.logger.info("node-av: scaled directly into shm ring slot", { meta: {
+				phase: "frame-debug",
+				width: this.outWidth,
+				height: this.outHeight,
+				dstStride,
+				format
+			} });
+		}
+		if (this.outputFrames === 1 || this.outputFrames % 500 === 0) this.logger.info("node-av frame emitted", { meta: {
+			frameNumber: this.outputFrames,
+			width: this.outWidth,
+			height: this.outHeight,
+			format,
+			decodeMs,
+			sink: "shm",
+			subs: this.handleCallbacks.size
+		} });
+		const handle = sink.commitFrame(reserved.slot, {
+			width: this.outWidth,
+			height: this.outHeight,
+			format,
+			pts: performance.now(),
+			byteLength: dstStride * this.outHeight
+		});
+		if (handle === null) {
+			this.droppedFrames++;
+			return;
+		}
+		const delivered = {
+			handle,
+			timestamp: Date.now()
+		};
+		for (const cb of this.handleCallbacks) cb(delivered);
+	}
+	/**
+	* Extract packed pixel buffer from a decoded frame.
+	* FFmpeg's av_frame_get_buffer() may pad each row to alignment (32/64 bytes).
+	* Sharp and WASM consumers expect tightly-packed rows (stride = width * channels).
+	* If linesize matches expected stride, return the buffer directly (zero-copy).
+	*/
+	extractPackedBuffer(frame) {
+		const channels = this.outputMode === "gray" ? 1 : 3;
+		const expectedStride = frame.width * channels;
+		const actualStride = frame.linesize[0] ?? expectedStride;
+		const src = frame.data?.[0];
+		if (!src) return frame.toBuffer();
+		if (actualStride === expectedStride) return Buffer.from(src.buffer, src.byteOffset, expectedStride * frame.height);
+		const dst = Buffer.allocUnsafe(expectedStride * frame.height);
+		for (let y = 0; y < frame.height; y++) src.copy(dst, y * expectedStride, y * actualStride, y * actualStride + expectedStride);
+		return dst;
+	}
+	/**
+	* Encode RGB24 raw buffer as JPEG and emit.
+	*
+	* Drops the frame (and counts it) when `MAX_JPEG_INFLIGHT` encodes
+	* are already pending — prevents unbounded growth of the
+	* fire-and-forget promise chain when sharp cannot keep up with the
+	* decode rate.
+	*/
+	encodeAndEmitJpeg(rgb, decodeStart) {
+		if (!this.sharpFn) return;
+		if (this.jpegEncodeInFlight >= NodeAvDecoderSession.MAX_JPEG_INFLIGHT) {
+			this.droppedFrames++;
+			return;
+		}
+		this.jpegEncodeInFlight++;
+		this.sharpFn(rgb, { raw: {
+			width: this.outWidth,
+			height: this.outHeight,
+			channels: 3
+		} }).jpeg({
+			quality: 80,
+			mozjpeg: false
+		}).toBuffer().then((jpegBuf) => {
+			if (this.destroyed) return;
+			this.emitRawFrame(jpegBuf, "jpeg", decodeStart);
+		}).catch((err) => {
+			this.logger.warn("sharp jpeg encode error", { meta: { error: errMsg(err) } });
+		}).finally(() => {
+			this.jpegEncodeInFlight--;
+		});
+	}
+	emitRawFrame(data, format, decodeStart) {
+		const decodeMs = performance.now() - decodeStart;
+		this.totalDecodeTimeMs += decodeMs;
+		this.outputFrames++;
+		this.lastEmitTime = performance.now();
+		if (this.outputFrames === 1 || this.outputFrames % 500 === 0) this.logger.info("node-av frame emitted", { meta: {
+			frameNumber: this.outputFrames,
+			width: this.outWidth,
+			height: this.outHeight,
+			format,
+			decodeMs,
+			sink: this.frameSink,
+			subs: this.frameSink === "shm" ? this.handleCallbacks.size : this.frameCallbacks.size
+		} });
+		if (this.frameSink === "shm") {
+			this.emitShmFrame(data, format);
+			return;
+		}
+		const decodedFrame = {
+			data,
+			width: this.outWidth,
+			height: this.outHeight,
+			format,
+			timestamp: Date.now()
+		};
+		for (const cb of this.frameCallbacks) cb(decodedFrame);
+	}
+	/**
+	* Write a decoded frame into this stream's shared-memory ring and deliver
+	* the resulting `FrameHandle` to `onFrameHandle` subscribers. No pixel
+	* `Buffer` is handed to callbacks — consumers open the segment and read the
+	* pixels zero-copy via a `FrameRingReader`.
+	*/
+	emitShmFrame(data, format) {
+		const handle = this.ensureFrameRingSink().writeFrame(data, {
+			width: this.outWidth,
+			height: this.outHeight,
+			format,
+			pts: performance.now(),
+			byteLength: data.byteLength
+		});
+		if (handle === null) {
+			this.droppedFrames++;
+			return;
+		}
+		const frame = {
+			handle,
+			timestamp: Date.now()
+		};
+		for (const cb of this.handleCallbacks) cb(frame);
+	}
+	onFrame(callback) {
+		this.frameCallbacks.add(callback);
+		return () => {
+			this.frameCallbacks.delete(callback);
+		};
+	}
+	/**
+	* Subscribe to shared-memory frame handles. Fires only when the session was
+	* created with `frameSink: 'shm'`; in the legacy `'callback'` mode no
+	* handles are produced and this subscription never fires.
+	*/
+	onFrameHandle(callback) {
+		this.handleCallbacks.add(callback);
+		return () => {
+			this.handleCallbacks.delete(callback);
+		};
+	}
+	updateConfig(update) {
+		const prevFormat = this.config.outputFormat;
+		this.config = {
+			...this.config,
+			...update
+		};
+		if (update.maxFps !== void 0) this.minIntervalMs = update.maxFps > 0 ? 1e3 / update.maxFps : 0;
+		if (update.outputFormat !== void 0 && update.outputFormat !== prevFormat) {
+			const prevMode = this.outputMode;
+			this.outputMode = NodeAvDecoderSession.resolveOutputMode(update.outputFormat);
+			if (this.outputMode === prevMode) return;
+			this.scalerEpoch++;
+			if (this.scaler) {
+				this.scaler[Symbol.dispose]?.();
+				this.scaler = null;
+			}
+			if (this.dstFrame) {
+				this.dstFrame[Symbol.dispose]?.();
+				this.dstFrame = null;
+			}
+			if (this.outputMode === "jpeg" && !this.sharpFn) getSharp().then((fn) => {
+				this.sharpFn = fn;
+			}).catch(() => {});
+			this.logger.info("node-av: output format changed — scaler will reinit", { meta: {
+				from: prevFormat,
+				to: update.outputFormat,
+				mode: this.outputMode
+			} });
+		}
+	}
+	async destroy() {
+		if (this.destroyed) return;
+		this.destroyed = true;
+		this.frameCallbacks.clear();
+		this.handleCallbacks.clear();
+		this.frameRingSink?.destroy();
+		this.frameRingSink = null;
+		this.dstFrame?.[Symbol.dispose]?.();
+		this.avFrame?.[Symbol.dispose]?.();
+		this.avPacket?.[Symbol.dispose]?.();
+		this.scaler?.[Symbol.dispose]?.();
+		this.parser?.[Symbol.dispose]?.();
+		this.swTransferFrame?.[Symbol.dispose]?.();
+		this.codecCtx?.[Symbol.dispose]?.();
+		this.hwDevice?.free();
+		this.dstFrame = null;
+		this.avFrame = null;
+		this.avPacket = null;
+		this.scaler = null;
+		this.parser = null;
+		this.codecCtx = null;
+		this.swTransferFrame = null;
+		this.hwDevice = null;
+	}
+	getStats() {
+		const uptimeSec = Math.max((Date.now() - this.startTime) / 1e3, 1);
+		return {
+			inputFps: this.inputPackets / uptimeSec,
+			outputFps: this.outputFrames / uptimeSec,
+			avgDecodeTimeMs: this.outputFrames > 0 ? this.totalDecodeTimeMs / this.outputFrames : 0,
+			droppedFrames: this.droppedFrames
+		};
+	}
+	get isPullMode() {
+		return false;
+	}
+};
+//#endregion
+//#region src/decoder-nodeav/addon/index.ts
+var FRAME_BUFFER_CAPACITY = 32;
+var DecoderNodeAvAddon = class extends BaseAddon {
+	/**
+	* Sessions are stored as the concrete `NodeAvDecoderSession` (the only type
+	* this addon ever creates) so `getShmStats` can reach the per-session shm
+	* ring sink — `IDecoderSession` does not expose it.
+	*/
+	sessions = /* @__PURE__ */ new Map();
+	/** Pixel-frame buffers — populated only for `frameSink: 'callback'` sessions. */
+	frameBuffers = /* @__PURE__ */ new Map();
+	/** `FrameHandle` buffers — populated only for `frameSink: 'shm'` sessions. */
+	handleBuffers = /* @__PURE__ */ new Map();
+	unsubscribers = /* @__PURE__ */ new Map();
+	sessionMeta = /* @__PURE__ */ new Map();
+	/**
+	* Per-shm-segment `FrameRingReader` cache backing `getFrame`. Opens each
+	* named segment once and reuses the reader for every later handle on it;
+	* built in `onInitialize` (it needs the scoped logger) and closed in
+	* `onShutdown`.
+	*/
+	frameReaders = null;
+	/** Running `getFrame` hit/miss counters surfaced via `getShmStats`. */
+	getFrameHits = 0;
+	getFrameMisses = 0;
+	constructor() {
+		super(DEFAULT_DECODER_HWACCEL_CONFIG);
+	}
+	globalSettingsSchema() {
+		return this.schema({ sections: [{
+			id: "hwaccel",
+			title: "Hardware acceleration",
+			tab: "decoder",
+			description: "Backend used by node-av decoder sessions. \"Auto\" defers to the probed best; concrete backends force it. Changes apply to NEW sessions — existing sessions keep the backend they were created with.",
+			fields: [this.field({
+				type: "select",
+				key: "hwaccel",
+				label: "Preferred backend",
+				options: [...HWACCEL_OPTIONS],
+				default: "auto",
+				immediate: true
+			}), this.field({
+				type: "text",
+				key: "probedBestHwaccel",
+				label: "Probed best",
+				description: "Auto-detected best decoder backend on this host. Click the refresh icon to re-run the probe.",
+				readonlyField: true,
+				default: "",
+				actions: [{
+					action: "reprobe-hwaccel",
+					icon: "refresh-cw",
+					tooltip: "Re-probe hwaccel"
+				}]
+			})]
+		}] });
+	}
+	async onInitialize() {
+		this.ctx.logger.info("node-av decoder addon initialized");
+		this.frameReaders = new FrameRingReaderCache(this.ctx.logger);
+		if (!this.config.probedBestHwaccel) this.reprobeHwaccel().catch((err) => {
+			this.ctx.logger.warn("nodeav: auto-reprobe hwaccel failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		});
+		return [{
+			capability: decoderCapability,
+			provider: this
+		}];
+	}
+	/**
+	* Resolve the effective hwaccel backend for a new session. Reads
+	* this addon's own `hwaccel` setting first. `'auto'` defers to the
+	* session's local resolver (`ctx.kernel.hwaccel`) which probes the
+	* host and picks. No more orchestrator round-trip — decoder addon
+	* is self-sufficient for this setting as of phase 2d.
+	*/
+	resolveHwAccelPref() {
+		return this.config.hwaccel;
+	}
+	/**
+	* Re-run the platform probe on this host and persist the detected
+	* backend as `probedBestHwaccel`. The operator's `hwaccel` setting
+	* is intentionally left alone — the probe only updates the hint.
+	*/
+	async reprobeHwaccel() {
+		const resolver = this.ctx.kernel.hwaccel;
+		if (!resolver) {
+			this.ctx.logger.warn("reprobeHwaccel: no kernel hwaccel resolver — returning none");
+			await this.ctx.settings?.writeAddonStore({ probedBestHwaccel: "none" });
+			return { backend: "none" };
+		}
+		try {
+			const res = await resolver.resolve();
+			const backend = res.preferred[0] ?? "none";
+			await this.ctx.settings?.writeAddonStore({ probedBestHwaccel: backend });
+			this.ctx.logger.info("reprobeHwaccel: wrote probedBestHwaccel", { meta: {
+				backend,
+				rationale: res.rationale,
+				preferred: res.preferred
+			} });
+			return { backend };
+		} catch (err) {
+			this.ctx.logger.warn("reprobeHwaccel failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			await this.ctx.settings?.writeAddonStore({ probedBestHwaccel: "none" });
+			return { backend: "none" };
+		}
+	}
+	async supportsCodec(input) {
+		return [
+			"h264",
+			"h265",
+			"hevc"
+		].includes(input.codec.toLowerCase());
+	}
+	async getInfo() {
+		return {
+			id: "decoder-nodeav",
+			name: "Decoder (node-av)",
+			isPullMode: false,
+			priority: 10
+		};
+	}
+	/**
+	* The cluster node id of this decoder — the Moleculer nodeID (`hub`,
+	* `dev-agent-0`, …), not the addon id. Stamped into session-owned
+	* `FrameHandle`s so a downstream consumer routes `getFrame` to the node
+	* that holds the shm ring. A hierarchical broker nodeID (`hub/...`) is
+	* collapsed to the cluster-visible parent; in-process boot is left as-is.
+	* Mirrors the resolution `PipelineRunnerAddon.onInitialize` performs.
+	*/
+	resolveLocalNodeId() {
+		const raw = this.ctx.kernel.localNodeId ?? this.ctx.id;
+		return raw.includes("/") ? raw.split("/")[0] : raw;
+	}
+	async createSession(config) {
+		const sessionId = randomUUID();
+		const hwaccel = this.resolveHwAccelPref();
+		const { frameSink } = config;
+		const nodeId = this.resolveLocalNodeId();
+		const session = new NodeAvDecoderSession(config, this.ctx.logger, {
+			hwaccel,
+			hwaccelResolver: this.ctx.kernel.hwaccel,
+			frameSink,
+			nodeId
+		});
+		const unsub = frameSink === "shm" ? this.wireShmSink(sessionId, session) : this.wireCallbackSink(sessionId, session);
+		this.sessions.set(sessionId, session);
+		this.unsubscribers.set(sessionId, unsub);
+		this.sessionMeta.set(sessionId, {
+			codec: config.codec,
+			outputFormat: config.outputFormat,
+			createdAtMs: Date.now()
+		});
+		this.ctx.logger.info("node-av: created session", { meta: {
+			sessionId,
+			codec: config.codec,
+			hwaccelPref: hwaccel,
+			frameSink,
+			nodeId
+		} });
+		return {
+			sessionId,
+			nodeId
+		};
+	}
+	/**
+	* Subscribe a `'callback'` session's pixel frames into a per-session
+	* ring buffer drained by `pullFrames`.
+	*/
+	wireCallbackSink(sessionId, session) {
+		const ringBuffer = new RingBuffer(FRAME_BUFFER_CAPACITY);
+		this.frameBuffers.set(sessionId, ringBuffer);
+		return session.onFrame((frame) => {
+			const { format } = frame;
+			if (format !== "jpeg" && format !== "rgb" && format !== "bgr" && format !== "yuv420" && format !== "gray") return;
+			const arrayBuf = new ArrayBuffer(frame.data.byteLength);
+			new Uint8Array(arrayBuf).set(frame.data);
+			const capFrame = {
+				data: new Uint8Array(arrayBuf),
+				width: frame.width,
+				height: frame.height,
+				format,
+				timestamp: frame.timestamp
+			};
+			ringBuffer.push(capFrame);
+		});
+	}
+	/**
+	* Subscribe a `'shm'` session's `FrameHandle`s into a per-session ring
+	* buffer drained by `pullHandles`. No pixel bytes cross the cap boundary
+	* — the broker opens the named segment and reads the pixels zero-copy.
+	*/
+	wireShmSink(sessionId, session) {
+		const handleRing = new RingBuffer(FRAME_BUFFER_CAPACITY);
+		this.handleBuffers.set(sessionId, handleRing);
+		return session.onFrameHandle((frame) => {
+			handleRing.push(frame.handle);
+		});
+	}
+	async destroySession(input) {
+		const { sessionId } = input;
+		const session = this.sessions.get(sessionId);
+		if (!session) throw new Error(`decoder-nodeav: unknown sessionId ${sessionId}`);
+		const unsub = this.unsubscribers.get(sessionId);
+		if (unsub) unsub();
+		await session.destroy();
+		this.sessions.delete(sessionId);
+		this.frameBuffers.delete(sessionId);
+		this.handleBuffers.delete(sessionId);
+		this.unsubscribers.delete(sessionId);
+		this.sessionMeta.delete(sessionId);
+		this.ctx.logger.info("node-av: destroyed session", { meta: { sessionId } });
+	}
+	async listActiveSessions() {
+		const out = [];
+		for (const [sessionId, meta] of this.sessionMeta) out.push({
+			sessionId,
+			codec: meta.codec,
+			outputFormat: meta.outputFormat,
+			createdAtMs: meta.createdAtMs
+		});
+		return out;
+	}
+	async pushPacket(input) {
+		const session = this.sessions.get(input.sessionId);
+		if (!session) throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+		const rawData = input.packet.data;
+		const data = Buffer.isBuffer(rawData) ? rawData : rawData instanceof Uint8Array ? Buffer.from(rawData.buffer, rawData.byteOffset, rawData.byteLength) : Buffer.from(rawData);
+		session.pushPacket({
+			...input.packet,
+			data
+		});
+	}
+	async openStream(input) {
+		if (!this.sessions.get(input.sessionId)) throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+		input.url;
+	}
+	async pullFrames(input) {
+		if (!this.sessions.has(input.sessionId)) throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+		const ringBuffer = this.frameBuffers.get(input.sessionId);
+		if (!ringBuffer) return [];
+		return ringBuffer.drain(input.maxCount);
+	}
+	async pullHandles(input) {
+		if (!this.sessions.has(input.sessionId)) throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+		const handleRing = this.handleBuffers.get(input.sessionId);
+		if (!handleRing) return [];
+		return handleRing.drain(input.maxCount);
+	}
+	async updateConfig(input) {
+		const session = this.sessions.get(input.sessionId);
+		if (!session) throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+		session.updateConfig(input.config);
+	}
+	async getStats(input) {
+		const session = this.sessions.get(input.sessionId);
+		if (!session) throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+		return session.getStats();
+	}
+	/**
+	* Read back the pixels a `FrameHandle` refers to from this node's shm ring
+	* (Phase 5 / D9 downstream access). Returns `null` when the slot was
+	* already recycled (latest-wins drop) or the segment could not be opened.
+	* The reader cache opens each named segment once and reuses the reader.
+	*
+	* The reader hands back a `Buffer` view over its **reusable scratch
+	* buffer**, only valid until the next `read` on the same reader; the
+	* cap caller may keep the frame across reads, so the pixels are copied
+	* into a fresh detached `ArrayBuffer` here. This matches the existing
+	* callback-path copy in `wireCallbackSink`.
+	*/
+	async getFrame(input) {
+		const frame = this.frameReaders?.read(input.handle) ?? null;
+		if (!frame) {
+			this.getFrameMisses += 1;
+			return null;
+		}
+		this.getFrameHits += 1;
+		const arrayBuf = new ArrayBuffer(frame.data.byteLength);
+		new Uint8Array(arrayBuf).set(frame.data);
+		return {
+			data: new Uint8Array(arrayBuf),
+			width: frame.width,
+			height: frame.height,
+			format: frame.format,
+			timestamp: frame.timestamp
+		};
+	}
+	/**
+	* shm ring usage stats for a `frameSink: 'shm'` session — slot geometry,
+	* frames written, byte budget, plus this addon's running `getFrame`
+	* hit/miss counters. Returns `null` for an unknown session or one whose
+	* shm ring has not yet been armed by a first decoded frame.
+	*/
+	async getShmStats(input) {
+		const stats = this.sessions.get(input.sessionId)?.frameRingSinkOrNull?.getShmStats() ?? null;
+		if (!stats) return null;
+		return {
+			sessionId: input.sessionId,
+			...stats,
+			budgetMb: RING_BUDGET_MB,
+			getFrameHits: this.getFrameHits,
+			getFrameMisses: this.getFrameMisses
+		};
+	}
+	async onShutdown() {
+		this.ctx.logger.info("node-av decoder addon shutdown — destroying all sessions");
+		const destroyPromises = [];
+		for (const [sessionId, session] of this.sessions) {
+			const unsub = this.unsubscribers.get(sessionId);
+			if (unsub) unsub();
+			destroyPromises.push(session.destroy());
+		}
+		await Promise.all(destroyPromises);
+		this.sessions.clear();
+		this.frameBuffers.clear();
+		this.handleBuffers.clear();
+		this.unsubscribers.clear();
+		this.sessionMeta.clear();
+		this.frameReaders?.close();
+		this.frameReaders = null;
+	}
 };
-//# sourceMappingURL=index.mjs.map
+//#endregion
+export { DecoderFrameRingSink, DecoderNodeAvAddon, DecoderNodeAvAddon as default, NodeAvDecoderSession, makeSegmentName };