@camstack/shm-ring 0.1.2

package/dist/index.js

@@ -0,0 +1,655 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_module = require("node:module");
+let node_url = require("node:url");
+let node_path = require("node:path");
+let _camstack_types = require("@camstack/types");
+//#region src/native.ts
+/**
+* Typed wrapper over the `shm_ring` N-API addon.
+*
+* The addon maps/unmaps a named OS shared-memory segment and hands JS a
+* zero-copy `Buffer` over the mapping. The ring/seqlock logic lives in
+* `frame-ring.ts` (Task 2) — this module is purely the segment plumbing.
+*/
+var require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
+var here = (0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
+/**
+* `node-gyp-build` resolves a prebuilt binary if one exists, otherwise the
+* locally compiled `build/Release/shm_ring.node`. Pointed at the package root
+* (one level above `dist/` / `src/`) so both layouts resolve.
+*/
+function loadAddon() {
+	const addon = require$1("node-gyp-build")((0, node_path.dirname)(here));
+	if (!isShmAddon(addon)) throw new Error("@camstack/shm-ring: native addon did not expose the expected surface");
+	return addon;
+}
+function hasFunction(value, key) {
+	return typeof Reflect.get(value, key) === "function";
+}
+function isShmAddon(value) {
+	if (typeof value !== "object" || value === null) return false;
+	return hasFunction(value, "create") && hasFunction(value, "open") && hasFunction(value, "close") && hasFunction(value, "unlink");
+}
+var addon = loadAddon();
+function wrap(name, native) {
+	let closed = false;
+	let unlinked = false;
+	return {
+		buffer: native.buffer,
+		close() {
+			if (closed) return;
+			closed = true;
+			addon.close(native.handle);
+		},
+		unlink() {
+			if (unlinked) return;
+			unlinked = true;
+			addon.unlink(name);
+		}
+	};
+}
+/**
+* Create a new named shared-memory segment of `byteLength` bytes and map it.
+* The segment is zero-filled. Fails if a segment with this name already exists.
+*/
+function createSegment(name, byteLength) {
+	return wrap(name, addon.create(name, byteLength));
+}
+/**
+* Map an existing named shared-memory segment. `byteLength` must match (or be
+* smaller than) the size the segment was created with. Throws if the segment
+* does not exist.
+*/
+function openSegment(name, byteLength) {
+	return wrap(name, addon.open(name, byteLength));
+}
+/**
+* Remove a segment name from the OS namespace without holding a mapping.
+* Convenience for cleanup paths that never mapped the segment themselves.
+*/
+function unlinkSegment(name) {
+	addon.unlink(name);
+}
+//#endregion
+//#region src/frame-ring.ts
+/** Header slot indices in the `Int32Array` header view. */
+var HDR_SLOT_COUNT = 0;
+var HDR_SLOT_BYTE_LENGTH = 1;
+var HDR_WRITE_INDEX = 2;
+/** Fixed header fields before the per-slot `seq[]` array begins. */
+var HDR_FIXED_FIELDS = 3;
+/** Bytes of metadata reserved per slot (24 used + 8 padding → 8-byte aligned). */
+var SLOT_META_BYTES = 32;
+var META_OFF_WIDTH = 0;
+var META_OFF_HEIGHT = 4;
+var META_OFF_FORMAT = 8;
+var META_OFF_BYTE_LENGTH = 12;
+var META_OFF_PTS = 16;
+/**
+* Stable integer codes for `FrameFormat` — metadata stores the index, not the
+* string, so a slot's metadata is a fixed-width struct. Append-only: never
+* reorder or remove an entry, or existing segments would mis-decode.
+*/
+var FRAME_FORMAT_CODES = [
+	"jpeg",
+	"rgb",
+	"bgr",
+	"yuv420",
+	"gray"
+];
+function encodeFormat(format) {
+	const code = FRAME_FORMAT_CODES.indexOf(format);
+	if (code < 0) throw new Error(`FrameRing: unknown frame format "${format}"`);
+	return code;
+}
+function decodeFormat(code) {
+	const format = FRAME_FORMAT_CODES[code];
+	if (format === void 0) throw new Error(`FrameRing: unknown frame format code ${code}`);
+	return format;
+}
+/** Round `value` up to the next multiple of `align` (a power of two). */
+function alignUp(value, align) {
+	return Math.ceil(value / align) * align;
+}
+/** Compute the geometry of a ring with the given slot count and slot size. */
+function computeGeometry(slotCount, slotByteLength) {
+	if (!Number.isInteger(slotCount) || slotCount <= 0) throw new Error(`FrameRing: slotCount must be a positive integer, got ${slotCount}`);
+	if (!Number.isInteger(slotByteLength) || slotByteLength <= 0) throw new Error(`FrameRing: slotByteLength must be a positive integer, got ${slotByteLength}`);
+	const headerBytes = alignUp((HDR_FIXED_FIELDS + slotCount) * 4, 8);
+	const metaOffset = headerBytes;
+	const pixelsOffset = alignUp(metaOffset + slotCount * SLOT_META_BYTES, 8);
+	return {
+		slotCount,
+		slotByteLength,
+		headerBytes,
+		metaOffset,
+		pixelsOffset,
+		totalBytes: pixelsOffset + slotCount * slotByteLength
+	};
+}
+/**
+* Total byte length a segment must have to hold a `slotCount`-slot ring with
+* `slotByteLength`-byte pixel slots. The decoder uses this to size the
+* shared-memory segment before constructing a `FrameRingWriter` over it.
+*/
+function computeSegmentSize(slotCount, slotByteLength) {
+	return computeGeometry(slotCount, slotByteLength).totalBytes;
+}
+/**
+* Slot-count bounds for a per-resolution ring. {@link deriveSlotCount} clamps
+* the budget-derived count into `[MIN_RING_SLOTS, MAX_RING_SLOTS]`:
+*  - `MIN` keeps a tiny floor even when one frame nearly exhausts the budget
+*    (a 4K RGB frame is ~24.9 MB — a 128 MB budget yields only ~5 raw slots);
+*  - `MAX` caps the ring for small frames so a 360p stream does not allocate
+*    hundreds of slots' worth of shared memory it will never use latest-wins.
+*/
+var MIN_RING_SLOTS = 6;
+var MAX_RING_SLOTS = 64;
+/**
+* Slot count for a ring, derived from a per-ring shared-memory budget.
+*
+* `budgetBytes` is the shared memory a single stream's ring may consume; the
+* raw count is `floor(budgetBytes / slotByteLength)`, clamped into
+* `[MIN_RING_SLOTS, MAX_RING_SLOTS]`. Live video is latest-wins, so the slot
+* count only needs to absorb the writer-commit / reader-read window — the
+* budget trades shared-memory footprint against that window per resolution.
+*/
+function deriveSlotCount(budgetBytes, slotByteLength) {
+	const raw = Math.floor(budgetBytes / slotByteLength);
+	return Math.min(64, Math.max(6, raw));
+}
+/**
+* Bytes per pixel for each packed decode format a frame ring slot can hold.
+*
+* This is the single source of truth shared by the decoder write side
+* (`DecoderFrameRingSink`) and every consumer read side
+* (`FrameRingReaderCache`): if the two computed different values, a reader
+* would mis-map the shared-memory segment and read corrupt pixels.
+*
+* `jpeg` has no fixed bytes-per-pixel — `computeSlotByteLength` short-circuits
+* it to the equivalent RGB24 raster before this is ever consulted, so the `3`
+* here is only a safe placeholder for exhaustiveness over `FrameFormat`.
+*/
+function bytesPerPixel(format) {
+	switch (format) {
+		case "gray": return 1;
+		case "rgb":
+		case "bgr": return 3;
+		case "yuv420": return 2;
+		case "jpeg": return 3;
+	}
+}
+/**
+* Per-slot byte capacity for a frame of the given geometry — the single source
+* of truth for both the decoder write side and the consumer read side.
+*
+* For raw formats this is exactly `width × height × bpp`. For `jpeg` (variable
+* length) the slot is sized to the equivalent RGB24 raster — a JPEG is always
+* far smaller than its source raster, so an RGB24-sized slot is a safe upper
+* bound. Note: this upper bound holds only while the JPEG encoder is pinned to
+* its current quality (~80). A near-lossless quality setting can produce a
+* JPEG that exceeds the RGB24 byte count; if quality is raised significantly,
+* this slot size must be revisited.
+*/
+function computeSlotByteLength(width, height, format) {
+	if (format === "jpeg") return width * height * 3;
+	return width * height * bytesPerPixel(format);
+}
+/**
+* Shared geometry + typed views over a segment buffer. The header is an
+* `Int32Array` so `Atomics` ops apply directly; metadata and pixels are read
+* and written through `DataView` / `Buffer` slices.
+*/
+var FrameRingBase = class {
+	segment;
+	shmId;
+	geometry;
+	/** `Int32Array` over the header — slotCount, slotByteLength, writeIndex, seq[]. */
+	header;
+	view;
+	constructor(segment, shmId, slotCount, slotByteLength) {
+		this.segment = segment;
+		this.shmId = shmId;
+		this.geometry = computeGeometry(slotCount, slotByteLength);
+		if (segment.byteLength < this.geometry.totalBytes) throw new Error(`FrameRing: segment is ${segment.byteLength} bytes, need ${this.geometry.totalBytes} for ${slotCount}×${slotByteLength}`);
+		const headerInts = HDR_FIXED_FIELDS + slotCount;
+		this.header = new Int32Array(segment.buffer, segment.byteOffset, headerInts);
+		this.view = new DataView(segment.buffer, segment.byteOffset, segment.byteLength);
+	}
+	/** Header index of `seq[slot]`. */
+	seqIndex(slot) {
+		return HDR_FIXED_FIELDS + slot;
+	}
+	/** Byte offset of slot `slot`'s metadata struct. */
+	metaOffsetOf(slot) {
+		return this.geometry.metaOffset + slot * SLOT_META_BYTES;
+	}
+	/** Byte offset of slot `slot`'s pixel region. */
+	pixelOffsetOf(slot) {
+		return this.geometry.pixelsOffset + slot * this.geometry.slotByteLength;
+	}
+};
+/**
+* The single writer for a ring. Constructed by whoever owns the segment (the
+* decoder). On construction it stamps `slotCount` / `slotByteLength` into the
+* header so a reader opening the same segment can self-describe.
+*/
+var FrameRingWriter = class extends FrameRingBase {
+	/** Slot index of an in-flight `beginWrite()`, or `null` when idle. */
+	pendingSlot = null;
+	/** Cluster node id stamped into every `FrameHandle` this writer produces. */
+	nodeId;
+	constructor(segment, shmId, slotCount, slotByteLength, nodeId) {
+		super(segment, shmId, slotCount, slotByteLength);
+		this.nodeId = nodeId;
+		Atomics.store(this.header, HDR_SLOT_COUNT, slotCount);
+		Atomics.store(this.header, HDR_SLOT_BYTE_LENGTH, slotByteLength);
+	}
+	/** The number of slots in this ring — derived per-resolution from the budget. */
+	get slotCount() {
+		return this.geometry.slotCount;
+	}
+	/** The slot the next `writeFrame` / `beginFrame` will target. */
+	targetSlot() {
+		return Atomics.load(this.header, HDR_WRITE_INDEX) % this.geometry.slotCount;
+	}
+	/**
+	* Open the seqlock on the next slot and hand the caller a writable view
+	* directly over that slot's pixel region — the **scatter-write** entry point.
+	*
+	* The seqlock contract (see {@link FrameSlotWrite}): this bumps the slot's
+	* `seq` to **odd** (write in progress), so a concurrent reader skips the slot
+	* for the entire fill window. The caller fills `buffer` in place — there is
+	* NO intermediate copy: a producer (the node-av scaler) writes its packed
+	* output straight into the mapped segment — then MUST call
+	* {@link commitFrame} with the returned `slot` to publish the frame.
+	*
+	* Exactly one `beginFrame` may be open per writer at a time.
+	*/
+	beginFrame() {
+		if (this.pendingSlot !== null) throw new Error("FrameRingWriter: a frame write is already in progress");
+		const slot = this.targetSlot();
+		Atomics.add(this.header, this.seqIndex(slot), 1);
+		this.pendingSlot = slot;
+		const pixelOffset = this.pixelOffsetOf(slot);
+		return {
+			slot,
+			buffer: this.segment.subarray(pixelOffset, pixelOffset + this.geometry.slotByteLength)
+		};
+	}
+	/**
+	* Close the seqlock opened by {@link beginFrame}: write the metadata, bump
+	* `seq` back to **even** (committed) and advance `writeIndex` so readers see
+	* this slot as the latest. Returns the published frame's `FrameHandle`.
+	*
+	* `slot` must be the value from the matching `beginFrame`'s
+	* {@link FrameSlotWrite}. The pixels are assumed already filled in place by
+	* the caller (the scatter-write contract) — `commitFrame` copies nothing.
+	*/
+	commitFrame(slot, meta) {
+		if (this.pendingSlot === null) throw new Error("FrameRingWriter: commitFrame called without beginFrame");
+		if (slot !== this.pendingSlot) throw new Error(`FrameRingWriter: commitFrame slot ${slot} does not match the in-progress beginFrame slot ${this.pendingSlot}`);
+		const { slotByteLength } = this.geometry;
+		if (meta.byteLength > slotByteLength) throw new Error(`FrameRingWriter: frame is ${meta.byteLength} bytes, slot capacity is ${slotByteLength}`);
+		this.pendingSlot = null;
+		const metaOffset = this.metaOffsetOf(slot);
+		this.view.setInt32(metaOffset + META_OFF_WIDTH, meta.width, true);
+		this.view.setInt32(metaOffset + META_OFF_HEIGHT, meta.height, true);
+		this.view.setInt32(metaOffset + META_OFF_FORMAT, encodeFormat(meta.format), true);
+		this.view.setInt32(metaOffset + META_OFF_BYTE_LENGTH, meta.byteLength, true);
+		this.view.setFloat64(metaOffset + META_OFF_PTS, meta.pts, true);
+		const committedSeq = Atomics.add(this.header, this.seqIndex(slot), 1) + 1;
+		Atomics.add(this.header, HDR_WRITE_INDEX, 1);
+		return {
+			shmId: this.shmId,
+			slot,
+			seq: committedSeq,
+			width: meta.width,
+			height: meta.height,
+			format: meta.format,
+			pts: meta.pts,
+			byteLength: meta.byteLength,
+			nodeId: this.nodeId,
+			slotCount: this.geometry.slotCount
+		};
+	}
+	/**
+	* Abandon the seqlock opened by {@link beginFrame} **without publishing the
+	* slot** — the degenerate-path counterpart of {@link commitFrame}.
+	*
+	* `beginFrame` has bumped the slot's `seq` to **odd**. A caller that opened a
+	* slot but then could not fill it with valid pixels (the producer failed, or
+	* there were no source planes) MUST NOT `commitFrame` — that would close the
+	* seqlock over uninitialised / stale shared-memory bytes and advance
+	* `writeIndex`, so a reader would see those garbage bytes as a real, latest
+	* frame. `abortFrame` instead:
+	*
+	*   1. bumps `seq` from odd back to **even** — the slot is not left stuck
+	*      odd, so the writer can reuse it on a later cycle;
+	*   2. does **NOT** advance `writeIndex` — `readLatest` therefore never
+	*      surfaces this slot as the latest (the prior latest stays latest);
+	*   3. returns no `FrameHandle` — nothing is handed downstream.
+	*
+	* The slot's pixel bytes after `abortFrame` are **undefined** (whatever was
+	* there before, or a half-written producer output) — but that is harmless
+	* because no consumer ever sees the slot as committed: `readLatest` skips it
+	* (writeIndex did not move) and any handle that happened to point at this
+	* slot from an earlier commit sees the changed `seq` and is correctly
+	* rejected by `readHandle`'s seq check.
+	*
+	* `slot` must be the value from the matching `beginFrame` — validated
+	* exactly as {@link commitFrame} does.
+	*/
+	abortFrame(slot) {
+		if (this.pendingSlot === null) throw new Error("FrameRingWriter: abortFrame called without beginFrame");
+		if (slot !== this.pendingSlot) throw new Error(`FrameRingWriter: abortFrame slot ${slot} does not match the in-progress beginFrame slot ${this.pendingSlot}`);
+		this.pendingSlot = null;
+		Atomics.add(this.header, this.seqIndex(slot), 1);
+	}
+	/**
+	* Publish one frame from a caller-provided pixel `Buffer` — the convenience
+	* wrapper over the scatter-write {@link beginFrame} / {@link commitFrame}
+	* pair: it opens the slot, copies `pixels` into it, then commits.
+	*
+	* Prefer the `beginFrame` / `commitFrame` pair when the pixels can be
+	* produced directly into the slot (the node-av scaler scattering its packed
+	* output into the mapped segment) — that path has zero write-side copy.
+	* `writeFrame` keeps the single-call form for callers that already hold a
+	* detached pixel `Buffer`.
+	*/
+	writeFrame(pixels, meta) {
+		if (pixels.byteLength < meta.byteLength) throw new Error(`FrameRingWriter: pixels buffer (${pixels.byteLength} bytes) shorter than meta.byteLength (${meta.byteLength})`);
+		const { slot, buffer } = this.beginFrame();
+		buffer.set(pixels.subarray(0, meta.byteLength));
+		return this.commitFrame(slot, meta);
+	}
+};
+/**
+* A reader for a ring. Many readers may share a segment concurrently with the
+* single writer. Every read is a seqlock read — a torn or recycled slot is
+* dropped (returns `null`), never returned as garbage pixels.
+*/
+var FrameRingReader = class extends FrameRingBase {
+	/**
+	* The reusable per-reader scratch buffer the seqlock-validated pixels are
+	* copied into — see the `FrameRead` doc comment for the borrow contract.
+	*
+	* Sized to `slotByteLength` on construction (the segment's stamped slot
+	* capacity) and lazily grown if a slot ever reports a larger `byteLength`.
+	* Reusing one buffer per reader replaces the per-read `Buffer.allocUnsafe` —
+	* the D9 perf gate's regression (Task 7b): a fresh ~5.93 MB allocation per
+	* 1080p frame churned ~1.39 GB/s and stalled on GC. The single memcpy stays
+	* (it IS the seqlock safety copy); only the allocation is removed.
+	*/
+	scratch;
+	/**
+	* Cluster node id of the node that OWNS this segment (i.e. the writer's
+	* node — the node whose shared memory physically holds the ring), stamped
+	* into every `FrameHandle` this reader produces. `FrameHandle.nodeId` always
+	* identifies the segment-owning node, never the reading node, so callers
+	* pass the writer's node id here (e.g. `FrameRingReaderCache` passes
+	* `handle.nodeId` straight through).
+	*/
+	nodeId;
+	constructor(segment, shmId, slotCount, slotByteLength, nodeId) {
+		super(segment, shmId, slotCount, slotByteLength);
+		this.nodeId = nodeId;
+		this.scratch = Buffer.allocUnsafe(slotByteLength);
+	}
+	/**
+	* Return the reader's scratch buffer as a view of exactly `byteLength` bytes,
+	* growing the backing buffer first if a slot ever exceeds the stamped slot
+	* capacity (defensive — `slotByteLength` should always bound `byteLength`).
+	*/
+	scratchFor(byteLength) {
+		if (byteLength > this.scratch.byteLength) this.scratch = Buffer.allocUnsafe(byteLength);
+		return this.scratch.subarray(0, byteLength);
+	}
+	/**
+	* Read the latest committed frame, latest-wins. Returns `null` when the ring
+	* is empty (no frame ever published) or the latest slot is mid-write /
+	* recycled (a slow reader simply drops that frame and retries next tick).
+	*
+	* The returned `FrameRead.pixels` is **borrowed** from this reader's reusable
+	* scratch buffer — valid only until this reader's next read. A consumer that
+	* retains it past the next read MUST copy. See the `FrameRead` doc comment.
+	*/
+	readLatest() {
+		const writeIndex = Atomics.load(this.header, HDR_WRITE_INDEX);
+		if (writeIndex === 0) return null;
+		const slot = (writeIndex - 1) % this.geometry.slotCount;
+		return this.seqlockRead(slot, null);
+	}
+	/**
+	* Read the exact frame a `FrameHandle` refers to. Returns `null` when the
+	* slot has been recycled (its committed `seq` no longer matches `handle.seq`)
+	* or is mid-write — i.e. the frame is gone, not torn.
+	*
+	* The returned `FrameRead.pixels` is **borrowed** from this reader's reusable
+	* scratch buffer — valid only until this reader's next read. A consumer that
+	* retains it past the next read MUST copy. See the `FrameRead` doc comment.
+	*/
+	readHandle(handle) {
+		if (handle.shmId !== this.shmId) throw new Error(`FrameRingReader: handle is for segment "${handle.shmId}", this reader is on "${this.shmId}"`);
+		if (handle.slot < 0 || handle.slot >= this.geometry.slotCount) return null;
+		return this.seqlockRead(handle.slot, handle.seq);
+	}
+	/**
+	* The seqlock read of a single slot.
+	*
+	* `expectedSeq` is the committed seq a `readHandle` caller demands; pass
+	* `null` for `readLatest`, which accepts whatever even seq it finds.
+	*/
+	seqlockRead(slot, expectedSeq) {
+		const seqIdx = this.seqIndex(slot);
+		const s1 = Atomics.load(this.header, seqIdx);
+		if ((s1 & 1) !== 0) return null;
+		if (expectedSeq !== null && s1 !== expectedSeq) return null;
+		const metaOffset = this.metaOffsetOf(slot);
+		const width = this.view.getInt32(metaOffset + META_OFF_WIDTH, true);
+		const height = this.view.getInt32(metaOffset + META_OFF_HEIGHT, true);
+		const formatCode = this.view.getInt32(metaOffset + META_OFF_FORMAT, true);
+		const byteLength = this.view.getInt32(metaOffset + META_OFF_BYTE_LENGTH, true);
+		const pts = this.view.getFloat64(metaOffset + META_OFF_PTS, true);
+		if (byteLength < 0 || byteLength > this.geometry.slotByteLength) return null;
+		const pixelOffset = this.pixelOffsetOf(slot);
+		const pixels = this.scratchFor(byteLength);
+		this.segment.copy(pixels, 0, pixelOffset, pixelOffset + byteLength);
+		if (s1 !== Atomics.load(this.header, seqIdx)) return null;
+		let format;
+		try {
+			format = decodeFormat(formatCode);
+		} catch {
+			return null;
+		}
+		return {
+			pixels,
+			meta: {
+				width,
+				height,
+				format,
+				pts,
+				byteLength
+			},
+			handle: {
+				shmId: this.shmId,
+				slot,
+				seq: s1,
+				width,
+				height,
+				format,
+				pts,
+				byteLength,
+				nodeId: this.nodeId,
+				slotCount: this.geometry.slotCount
+			}
+		};
+	}
+	/**
+	* Read the latest committed frame **zero-copy** — `FrameView.pixels` is a
+	* `subarray` over the shared mapping, no memcpy. The caller MUST process it
+	* synchronously and then call `validate()`; see the `FrameView` contract.
+	* Returns `null` when the ring is empty or the latest slot is mid-write.
+	*/
+	readLatestView() {
+		const writeIndex = Atomics.load(this.header, HDR_WRITE_INDEX);
+		if (writeIndex === 0) return null;
+		const slot = (writeIndex - 1) % this.geometry.slotCount;
+		return this.seqlockReadView(slot, null);
+	}
+	/**
+	* Read the frame a `FrameHandle` refers to **zero-copy** — `FrameView.pixels`
+	* is a `subarray` over the shared mapping, no memcpy. The caller MUST process
+	* it synchronously and then call `validate()`; see the `FrameView` contract.
+	* Returns `null` when the slot is recycled (seq mismatch) or mid-write.
+	*/
+	readHandleView(handle) {
+		if (handle.shmId !== this.shmId) throw new Error(`FrameRingReader: handle is for segment "${handle.shmId}", this reader is on "${this.shmId}"`);
+		if (handle.slot < 0 || handle.slot >= this.geometry.slotCount) return null;
+		return this.seqlockReadView(handle.slot, handle.seq);
+	}
+	/**
+	* The zero-copy half of the seqlock read: validate the opening seqlock, then
+	* return a `subarray` over the slot plus a `validate()` closure that re-reads
+	* the seqlock. No pixel copy — the consumer owns the closing recheck.
+	*/
+	seqlockReadView(slot, expectedSeq) {
+		const seqIdx = this.seqIndex(slot);
+		const s1 = Atomics.load(this.header, seqIdx);
+		if ((s1 & 1) !== 0) return null;
+		if (expectedSeq !== null && s1 !== expectedSeq) return null;
+		const metaOffset = this.metaOffsetOf(slot);
+		const width = this.view.getInt32(metaOffset + META_OFF_WIDTH, true);
+		const height = this.view.getInt32(metaOffset + META_OFF_HEIGHT, true);
+		const formatCode = this.view.getInt32(metaOffset + META_OFF_FORMAT, true);
+		const byteLength = this.view.getInt32(metaOffset + META_OFF_BYTE_LENGTH, true);
+		const pts = this.view.getFloat64(metaOffset + META_OFF_PTS, true);
+		if (byteLength < 0 || byteLength > this.geometry.slotByteLength) return null;
+		let format;
+		try {
+			format = decodeFormat(formatCode);
+		} catch {
+			return null;
+		}
+		const pixelOffset = this.pixelOffsetOf(slot);
+		const pixels = this.segment.subarray(pixelOffset, pixelOffset + byteLength);
+		const meta = {
+			width,
+			height,
+			format,
+			pts,
+			byteLength
+		};
+		const handle = {
+			shmId: this.shmId,
+			slot,
+			seq: s1,
+			width,
+			height,
+			format,
+			pts,
+			byteLength,
+			nodeId: this.nodeId,
+			slotCount: this.geometry.slotCount
+		};
+		const validate = () => Atomics.load(this.header, seqIdx) === s1;
+		return {
+			pixels,
+			meta,
+			handle,
+			validate
+		};
+	}
+};
+//#endregion
+//#region src/frame-ring-reader-cache.ts
+/**
+* Opens (and caches) a `FrameRingReader` per `shmId` and reads the pixels a
+* `FrameHandle` refers to. Single-consumer — one cache per frame subscription.
+*/
+var FrameRingReaderCache = class {
+	rings = /* @__PURE__ */ new Map();
+	logger;
+	closed = false;
+	constructor(logger) {
+		this.logger = logger;
+	}
+	/**
+	* Read the pixels a `FrameHandle` refers to and return them as a
+	* `DecodedFrame`. Returns `null` when the ring slot was recycled before the
+	* read (a dropped frame) or the segment could not be opened.
+	*/
+	read(handle) {
+		if (this.closed) return null;
+		const ring = this.ringFor(handle);
+		if (!ring) return null;
+		let frame;
+		try {
+			frame = ring.reader.readHandle(handle);
+		} catch (err) {
+			this.logger?.warn("frame-ring reader: readHandle failed", { meta: {
+				shmId: handle.shmId,
+				error: (0, _camstack_types.errMsg)(err)
+			} });
+			return null;
+		}
+		if (!frame) return null;
+		return {
+			data: frame.pixels,
+			width: frame.meta.width,
+			height: frame.meta.height,
+			format: frame.meta.format,
+			timestamp: frame.meta.pts
+		};
+	}
+	/** Close every cached segment. Idempotent. */
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		for (const [shmId, ring] of this.rings) try {
+			ring.segment.close();
+		} catch (err) {
+			this.logger?.warn("frame-ring reader: segment close failed", { meta: {
+				shmId,
+				error: (0, _camstack_types.errMsg)(err)
+			} });
+		}
+		this.rings.clear();
+	}
+	/** Get the cached reader for a handle's segment, opening it on first use. */
+	ringFor(handle) {
+		const cached = this.rings.get(handle.shmId);
+		if (cached) return cached;
+		const slotByteLength = computeSlotByteLength(handle.width, handle.height, handle.format);
+		try {
+			const segment = openSegment(handle.shmId, computeSegmentSize(handle.slotCount, slotByteLength));
+			const ring = {
+				segment,
+				reader: new FrameRingReader(segment.buffer, handle.shmId, handle.slotCount, slotByteLength, handle.nodeId)
+			};
+			this.rings.set(handle.shmId, ring);
+			return ring;
+		} catch (err) {
+			this.logger?.warn("frame-ring reader: openSegment failed", { meta: {
+				shmId: handle.shmId,
+				error: (0, _camstack_types.errMsg)(err)
+			} });
+			return null;
+		}
+	}
+};
+//#endregion
+exports.FrameRingReader = FrameRingReader;
+exports.FrameRingReaderCache = FrameRingReaderCache;
+exports.FrameRingWriter = FrameRingWriter;
+exports.MAX_RING_SLOTS = MAX_RING_SLOTS;
+exports.MIN_RING_SLOTS = MIN_RING_SLOTS;
+exports.bytesPerPixel = bytesPerPixel;
+exports.computeSegmentSize = computeSegmentSize;
+exports.computeSlotByteLength = computeSlotByteLength;
+exports.createSegment = createSegment;
+exports.deriveSlotCount = deriveSlotCount;
+exports.openSegment = openSegment;
+exports.unlinkSegment = unlinkSegment;
+
+//# sourceMappingURL=index.js.map