@mediaway/ffi 0.1.6 → 0.2.1

package/dist/container-replay.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Replay ring + MP4 payload placements (adr/container/0009-replay-ring-c-abi.md).
+ *
+ * Split out of index.ts, which sits under the workspace's 1000-line source cap. This module
+ * imports only leaf modules (koffi, loader), never index.ts, so there is no import cycle:
+ * index.ts calls {@link createReplayBindings} once, after it has defined `MwRational` and
+ * `MwPacketView`, whose koffi names the signatures below refer to.
+ */
+import { type TypeObject } from "koffi";
+/** `mediaway_replay_payload_kind_t`. */
+export declare const REPLAY_PAYLOAD_BYTES = 0;
+export declare const REPLAY_PAYLOAD_STORED = 1;
+/** `mediaway_replay_ring_config_t`. */
+export interface RawReplayRingConfig {
+    anchor_stream_id: number;
+    anchor_time_base: {
+        num: bigint | number;
+        den: number;
+    };
+    window_ms: bigint | number;
+    max_bytes: bigint | number;
+    payload_kind: number;
+}
+/** `mediaway_packet_meta_t`. */
+export interface RawPacketMeta {
+    stream_id: number;
+    pts: bigint | number;
+    dts: bigint | number;
+    duration: bigint | number;
+    is_keyframe: boolean;
+    is_discard: boolean;
+}
+/** `mediaway_stored_payload_t`. */
+export interface RawStoredPayload {
+    file: number;
+    offset: bigint | number;
+    len: number;
+}
+/** `mediaway_replay_clip_entry_t`. `payload` is BORROWED from the clip. */
+export interface RawReplayClipEntry {
+    stream_id: number;
+    pts: bigint;
+    dts: bigint;
+    duration: bigint;
+    is_keyframe: boolean;
+    is_discard: boolean;
+    payload_kind: number;
+    payload: unknown;
+    payload_len: number;
+    stored_file: number;
+    stored_offset: bigint;
+    stored_len: number;
+}
+/** `mediaway_placement_t`. */
+export interface RawPlacement {
+    track_id: number;
+    dts: bigint;
+    offset: bigint;
+    len: number;
+}
+/**
+ * Declare the replay structs and bind the functions.
+ *
+ * `rational` is index.ts's `MwRational` (the struct is registered there once; koffi rejects a
+ * second definition under the same name).
+ */
+export declare function createReplayBindings(rational: TypeObject): {
+    structs: {
+        MwReplayRingConfig: TypeObject;
+        MwPacketMeta: TypeObject;
+        MwStoredPayload: TypeObject;
+        MwReplayClipEntry: TypeObject;
+        MwPlacement: TypeObject;
+    };
+    ringCreate: import("koffi").Callable;
+    ringAddStream: import("koffi").Callable;
+    ringPush: import("koffi").Callable;
+    ringPushStored: import("koffi").Callable;
+    ringSpanMs: import("koffi").Callable;
+    ringClipLast: import("koffi").Callable;
+    ringClose: import("koffi").Callable;
+    clipPacketCount: import("koffi").Callable;
+    clipDurationMs: import("koffi").Callable;
+    clipPacketAt: import("koffi").Callable;
+    clipFree: import("koffi").Callable;
+    muxerCreateWithPlacements: import("koffi").Callable;
+    muxerPollPlacements: import("koffi").Callable;
+    placementsFree: import("koffi").Callable;
+};
+/**
+ * `sizeof` and member offsets of the replay structs as koffi lays them out, for the test that
+ * pins them against a gcc probe of the real header.
+ */
+export declare function replayLayout(structs: ReturnType<typeof createReplayBindings>["structs"]): {
+    replayRingConfig: {
+        size: number;
+        offsets: {
+            [k: string]: number;
+        };
+    };
+    packetMeta: {
+        size: number;
+        offsets: {
+            [k: string]: number;
+        };
+    };
+    storedPayload: {
+        size: number;
+        offsets: {
+            [k: string]: number;
+        };
+    };
+    replayClipEntry: {
+        size: number;
+        offsets: {
+            [k: string]: number;
+        };
+    };
+    placement: {
+        size: number;
+        offsets: {
+            [k: string]: number;
+        };
+    };
+};

package/dist/container-replay.js

@@ -0,0 +1,102 @@
+/**
+ * Replay ring + MP4 payload placements (adr/container/0009-replay-ring-c-abi.md).
+ *
+ * Split out of index.ts, which sits under the workspace's 1000-line source cap. This module
+ * imports only leaf modules (koffi, loader), never index.ts, so there is no import cycle:
+ * index.ts calls {@link createReplayBindings} once, after it has defined `MwRational` and
+ * `MwPacketView`, whose koffi names the signatures below refer to.
+ */
+import koffi, {} from "koffi";
+import { containerLib } from "./loader.js";
+/** `mediaway_replay_payload_kind_t`. */
+export const REPLAY_PAYLOAD_BYTES = 0;
+export const REPLAY_PAYLOAD_STORED = 1;
+/**
+ * Declare the replay structs and bind the functions.
+ *
+ * `rational` is index.ts's `MwRational` (the struct is registered there once; koffi rejects a
+ * second definition under the same name).
+ */
+export function createReplayBindings(rational) {
+    const MwReplayRingConfig = koffi.struct("MwReplayRingConfig", {
+        anchor_stream_id: "uint32",
+        anchor_time_base: rational,
+        window_ms: "uint64",
+        max_bytes: "uint64",
+        payload_kind: "int32",
+    });
+    const MwPacketMeta = koffi.struct("MwPacketMeta", {
+        stream_id: "uint32",
+        pts: "int64",
+        dts: "int64",
+        duration: "uint64",
+        is_keyframe: "bool",
+        is_discard: "bool",
+    });
+    const MwStoredPayload = koffi.struct("MwStoredPayload", {
+        file: "uint32",
+        offset: "uint64",
+        len: "uint32",
+    });
+    const MwReplayClipEntry = koffi.struct("MwReplayClipEntry", {
+        stream_id: "uint32",
+        pts: "int64",
+        dts: "int64",
+        duration: "uint64",
+        is_keyframe: "bool",
+        is_discard: "bool",
+        payload_kind: "int32",
+        payload: "uint8_t *",
+        payload_len: "size_t",
+        stored_file: "uint32",
+        stored_offset: "uint64",
+        stored_len: "uint32",
+    });
+    const MwPlacement = koffi.struct("MwPlacement", {
+        track_id: "uint32",
+        dts: "int64",
+        offset: "uint64",
+        len: "uint32",
+    });
+    return {
+        structs: { MwReplayRingConfig, MwPacketMeta, MwStoredPayload, MwReplayClipEntry, MwPlacement },
+        ringCreate: containerLib.func("int mediaway_replay_ring_create(MwReplayRingConfig *config, _Out_ void **out_ring)"),
+        ringAddStream: containerLib.func("int mediaway_replay_ring_add_stream(void *ring, uint32_t stream_id, MwRational time_base)"),
+        ringPush: containerLib.func("int mediaway_replay_ring_push(void *ring, MwPacketView *packet)"),
+        ringPushStored: containerLib.func("int mediaway_replay_ring_push_stored(void *ring, MwPacketMeta *meta, MwStoredPayload *stored)"),
+        ringSpanMs: containerLib.func("int mediaway_replay_ring_span_ms(void *ring, _Out_ uint64_t *out_span_ms)"),
+        ringClipLast: containerLib.func("int mediaway_replay_ring_clip_last(void *ring, uint64_t span_ms, _Out_ void **out_clip, _Out_ bool *out_has)"),
+        ringClose: containerLib.func("void mediaway_replay_ring_close(void *ring)"),
+        clipPacketCount: containerLib.func("size_t mediaway_replay_clip_packet_count(void *clip)"),
+        clipDurationMs: containerLib.func("int mediaway_replay_clip_duration_ms(void *clip, _Out_ uint64_t *out_ms)"),
+        clipPacketAt: containerLib.func("int mediaway_replay_clip_packet_at(void *clip, size_t index, _Out_ MwReplayClipEntry *out_entry)"),
+        clipFree: containerLib.func("void mediaway_replay_clip_free(void *clip)"),
+        muxerCreateWithPlacements: containerLib.func("void *mediaway_muxer_create_with_placements()"),
+        muxerPollPlacements: containerLib.func("int mediaway_muxer_poll_placements(void *muxer, _Out_ MwPlacement **out_rows, _Out_ size_t *out_count)"),
+        placementsFree: containerLib.func("void mediaway_placements_free(MwPlacement *rows, size_t count)"),
+    };
+}
+/**
+ * `sizeof` and member offsets of the replay structs as koffi lays them out, for the test that
+ * pins them against a gcc probe of the real header.
+ */
+export function replayLayout(structs) {
+    const describe = (type, members) => ({
+        size: koffi.sizeof(type),
+        offsets: Object.fromEntries(members.map((m) => [m, koffi.offsetof(type, m)])),
+    });
+    return {
+        replayRingConfig: describe(structs.MwReplayRingConfig, [
+            "anchor_stream_id", "anchor_time_base", "window_ms", "max_bytes", "payload_kind",
+        ]),
+        packetMeta: describe(structs.MwPacketMeta, [
+            "stream_id", "pts", "dts", "duration", "is_keyframe", "is_discard",
+        ]),
+        storedPayload: describe(structs.MwStoredPayload, ["file", "offset", "len"]),
+        replayClipEntry: describe(structs.MwReplayClipEntry, [
+            "stream_id", "pts", "dts", "duration", "is_keyframe", "is_discard", "payload_kind",
+            "payload", "payload_len", "stored_file", "stored_offset", "stored_len",
+        ]),
+        placement: describe(structs.MwPlacement, ["track_id", "dts", "offset", "len"]),
+    };
+}

package/dist/index.d.ts

@@ -14,11 +14,12 @@
  *     `_free` — the public packages do this automatically.
  */
 import { type TypeObject } from "koffi";
-export declare function findLibrary(name: string): string;
-export declare const containerLib: import("koffi").LibraryHandle;
-export declare const pipelineLib: import("koffi").LibraryHandle;
-export declare const deviceLib: import("koffi").LibraryHandle;
-export declare const MwRational: TypeObject;
+import { findLibrary, containerLib, pipelineLib, deviceLib } from "./loader.js";
+import { MwRational } from "./rational.js";
+import { replayLayout } from "./container-replay.js";
+export * from "./container-replay.js";
+export { findLibrary, containerLib, pipelineLib, deviceLib, MwRational };
+export * from "./pipeline-v7.js";
 export declare const MwVideoTrackInfo: TypeObject;
 export declare const MwAudioTrackInfo: TypeObject;
 export declare const MwPacketView: TypeObject;
@@ -47,7 +48,6 @@ export declare const MwAudioStreamInfo: TypeObject;
 export declare const MwDecodePacketView: TypeObject;
 export declare const MwAutoVideoDecodeConfig: TypeObject;
 export declare const MwDecodedVideoFrame: TypeObject;
-export declare const MwAudioDecodeConfig: TypeObject;
 export declare const MwDecodedAudioFrame: TypeObject;
 export declare const container: {
     abiVersion: import("koffi").Callable;
@@ -136,6 +136,13 @@ export declare const container: {
     wavParse: import("koffi").Callable;
 };
 export declare const pipeline: {
+    sessionWriteFrameFromCameraCapture: import("koffi").Callable;
+    sessionWriteFrameFromDesktopCapture: import("koffi").Callable;
+    audioDecodeConfigAac: import("koffi").Callable;
+    sessionPollBytes: import("koffi").Callable;
+    encoderSupportAt: import("koffi").Callable;
+    encoderSupportFree: import("koffi").Callable;
+    decoderSupport: import("koffi").Callable;
     abiVersion: import("koffi").Callable;
     encConfigNew: import("koffi").Callable;
     encConfigH264: import("koffi").Callable;
@@ -169,8 +176,6 @@ export declare const pipeline: {
     audioDecodeSessionFlush: import("koffi").Callable;
     audioDecodeSessionClose: import("koffi").Callable;
     decodedAudioFrameFree: import("koffi").Callable;
-    sessionWriteFrameFromCameraCapture: import("koffi").Callable;
-    sessionWriteFrameFromDesktopCapture: import("koffi").Callable;
 };
 export declare const device: {
     abiVersion: import("koffi").Callable;
@@ -183,6 +188,8 @@ export declare const device: {
     cameraClose: import("koffi").Callable;
     cameraFrameFree: import("koffi").Callable;
     desktopConfigScreen: import("koffi").Callable;
+    desktopConfigWindow: import("koffi").Callable;
+    desktopBorderHidden: import("koffi").Callable;
     desktopOpen: import("koffi").Callable;
     desktopGeometry: import("koffi").Callable;
     desktopPollFrame: import("koffi").Callable;
@@ -201,6 +208,31 @@ export declare const device: {
     gpuDeviceHandle: import("koffi").Callable;
     gpuDeviceClose: import("koffi").Callable;
 };
+export declare const replay: {
+    structs: {
+        MwReplayRingConfig: TypeObject;
+        MwPacketMeta: TypeObject;
+        MwStoredPayload: TypeObject;
+        MwReplayClipEntry: TypeObject;
+        MwPlacement: TypeObject;
+    };
+    ringCreate: import("koffi").Callable;
+    ringAddStream: import("koffi").Callable;
+    ringPush: import("koffi").Callable;
+    ringPushStored: import("koffi").Callable;
+    ringSpanMs: import("koffi").Callable;
+    ringClipLast: import("koffi").Callable;
+    ringClose: import("koffi").Callable;
+    clipPacketCount: import("koffi").Callable;
+    clipDurationMs: import("koffi").Callable;
+    clipPacketAt: import("koffi").Callable;
+    clipFree: import("koffi").Callable;
+    muxerCreateWithPlacements: import("koffi").Callable;
+    muxerPollPlacements: import("koffi").Callable;
+    placementsFree: import("koffi").Callable;
+};
+/** koffi's sizeof/offsetof for the replay structs — pinned by test/replay-ring.test.ts. */
+export declare const replayStructLayout: () => ReturnType<typeof replayLayout>;
 /** Copy `len` bytes out of a koffi pointer/opaque handle. */
 export declare function copyBytes(ptr: unknown, len: number): Buffer;
 /**
@@ -337,6 +369,21 @@ export interface RawPipelineFrame {
 }
 /** `mediaway_gpu_device_handle_t` (Screen capture / GPU-input encode input,
  * mediaway_gpu_device_handle()'s output). */
+export interface RawDesktopConfig {
+    source_kind: number;
+    source_index: number;
+    time_base: RawRational;
+    gpu_device: RawGpuDeviceHandle;
+    window_handle: bigint | number;
+    cursor: number;
+    border: number;
+    dimensions: number;
+    region_x: number;
+    region_y: number;
+    region_width: number;
+    region_height: number;
+    region_enabled: boolean;
+}
 export interface RawGpuDeviceHandle {
     kind: number;
     native: number | bigint;
@@ -417,12 +464,14 @@ export interface RawDecodedVideoFrame {
     data: unknown;
     data_len: number;
 }
-/** `mediaway_audio_decode_config_t` (Opus only today). */
+/** `mediaway_audio_decode_config_t` (Opus or AAC; AAC needs `extra_data`, the ASC). */
 export interface RawAudioDecodeConfig {
     codec: number;
     sample_rate: number;
     channels: number;
     time_base: RawRational;
+    extra_data: unknown;
+    extra_data_len: number;
 }
 /** `mediaway_decoded_audio_frame_t` (audio decode session output; always F32). */
 export interface RawDecodedAudioFrame {

package/dist/index.js

@@ -14,63 +14,17 @@
  *     `_free` — the public packages do this automatically.
  */
 import koffi, {} from "koffi";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-// ── Library discovery ──────────────────────────────────────────────────────────
-// The cdylibs are Rust build artifacts, not installed system libraries. Search:
-//   1. $MEDIAWAY_FFI_DIR
-//   2. <this package>/native        (DLLs bundled at pack time — the npm distribution)
-//   3. <repo root>/target/x86_64-pc-windows-gnu/debug   (GNU toolchain, dev runs)
-//   4. <repo root>/target/debug                          (host/MSVC toolchain)
-//   5. cwd
-const here = path.dirname(fileURLToPath(import.meta.url));
-const repoRoot = path.resolve(here, "..", "..", "..", "..", "..");
-const searchDirs = [
-    process.env.MEDIAWAY_FFI_DIR ?? "",
-    path.resolve(here, "..", "native"),
-    path.join(repoRoot, "target", "x86_64-pc-windows-gnu", "debug"),
-    path.join(repoRoot, "target", "debug"),
-    process.cwd(),
-];
-export function findLibrary(name) {
-    for (const dir of searchDirs) {
-        if (!dir)
-            continue;
-        const candidate = path.join(dir, name);
-        if (fs.existsSync(candidate))
-            return candidate;
-    }
-    throw new Error(`cannot find ${name}; set $MEDIAWAY_FFI_DIR or build the -ffi crates`);
-}
-/**
- * cdylib filename Cargo produces for this platform. Windows and Linux only —
- * the workspace's own hardware/CI coverage is limited to those two (see
- * docs/ai/wiki/platform/order.md); macOS support is not claimed here since
- * it has never been built or run.
- */
-function libraryFilename() {
-    switch (process.platform) {
-        case "win32":
-            return "mediaway_ffi.dll";
-        case "linux":
-            return "libmediaway_ffi.so";
-        default:
-            throw new Error(`mediaway: unsupported platform ${process.platform} (Windows and Linux only)`);
-    }
-}
-function load(name) {
-    return koffi.load(findLibrary(name));
-}
-const libraryName = libraryFilename();
-export const containerLib = load(libraryName);
-export const pipelineLib = load(libraryName);
-export const deviceLib = load(libraryName);
+import { findLibrary, containerLib, pipelineLib, deviceLib } from "./loader.js";
+import { MwRational } from "./rational.js";
+// Pipeline ABI v7 (streaming bytes, AAC decode, capability probes) lives in its own module for
+// the 1000-line source cap. Importing it first also registers `MwAudioDecodeConfig`, which the
+// `pipeline` object's prototype strings below name.
+import { pipelineV7 } from "./pipeline-v7.js";
+import { createReplayBindings, replayLayout } from "./container-replay.js";
+export * from "./container-replay.js";
+export { findLibrary, containerLib, pipelineLib, deviceLib, MwRational };
+export * from "./pipeline-v7.js";
 // ── Structs (layouts mirror the headers exactly) ───────────────────────────────
-export const MwRational = koffi.struct("MwRational", {
-    num: "uint64",
-    den: "uint32",
-});
 export const MwVideoTrackInfo = koffi.struct("MwVideoTrackInfo", {
     id: "uint32",
     codec: "int32",
@@ -182,11 +136,22 @@ export const MwCameraFrame = koffi.struct("MwCameraFrame", {
     data: "uint8_t *",
     data_len: "size_t",
 });
+// Field order and widths mirror `mediaway_desktop_capture_config_t` in device.h
+// exactly (ADR-0005). Every field after `gpu_device` is zero-means-previous-behaviour.
 export const MwDesktopConfig = koffi.struct("MwDesktopConfig", {
     source_kind: "int32",
     source_index: "uint32",
     time_base: MwRational,
     gpu_device: MwGpuDeviceHandle,
+    window_handle: "uint64",
+    cursor: "int32", // 0 = excluded, 1 = included
+    border: "int32", // 0 = shown, 1 = hidden (Window only)
+    dimensions: "int32", // 0 = native, 1 = even-cropped (Window only)
+    region_x: "uint32",
+    region_y: "uint32",
+    region_width: "uint32",
+    region_height: "uint32",
+    region_enabled: "bool",
 });
 export const MwDesktopFrame = koffi.struct("MwDesktopFrame", {
     pts: "int64",
@@ -295,12 +260,7 @@ export const MwDecodedVideoFrame = koffi.struct("MwDecodedVideoFrame", {
     data: "uint8_t *", // owned
     data_len: "size_t",
 });
-export const MwAudioDecodeConfig = koffi.struct("MwAudioDecodeConfig", {
-    codec: "int32", // Opus only today
-    sample_rate: "uint32",
-    channels: "uint16",
-    time_base: MwRational,
-});
+// `MwAudioDecodeConfig` (Opus + AAC) is defined in pipeline-v7.ts.
 export const MwDecodedAudioFrame = koffi.struct("MwDecodedAudioFrame", {
     pts: "int64",
     duration: "uint64",
@@ -439,6 +399,8 @@ export const pipeline = {
     audioDecodeSessionFlush: pipelineLib.func("int mediaway_audio_decode_session_flush(void *session)"),
     audioDecodeSessionClose: pipelineLib.func("void mediaway_audio_decode_session_close(void *session)"),
     decodedAudioFrameFree: pipelineLib.func("void mediaway_decoded_audio_frame_free(MwDecodedAudioFrame *frame)"),
+    // ── ABI v7: streaming bytes, AAC decode config, capability probes (pipeline-v7.ts) ──
+    ...pipelineV7,
     // ── Capture-to-encode bridge (adr/pipeline/0005-capture-encode-bridge-c-abi.md) ──
     // Pushes one polled frame from a device.h capture handle straight into a
     // session — no intermediate MwCameraFrame/MwDesktopFrame, no extra copy.
@@ -457,6 +419,8 @@ export const device = {
     cameraClose: deviceLib.func("int mediaway_camera_capture_close(void *capture)"),
     cameraFrameFree: deviceLib.func("void mediaway_camera_frame_free(MwCameraFrame *frame)"),
     desktopConfigScreen: deviceLib.func("MwDesktopConfig mediaway_desktop_capture_config_screen(uint32_t output_index, MwRational time_base, MwGpuDeviceHandle gpu_device)"),
+    desktopConfigWindow: deviceLib.func("MwDesktopConfig mediaway_desktop_capture_config_window(uint64_t hwnd, MwRational time_base, MwGpuDeviceHandle gpu_device)"),
+    desktopBorderHidden: deviceLib.func("int mediaway_desktop_capture_border_hidden(void *capture, _Out_ bool *out_hidden)"),
     desktopOpen: deviceLib.func("int mediaway_desktop_capture_open(MwDesktopConfig *config, _Out_ void **out_capture)"),
     desktopGeometry: deviceLib.func("int mediaway_desktop_capture_geometry(void *capture, _Out_ uint32_t *out_width, _Out_ uint32_t *out_height)"),
     desktopPollFrame: deviceLib.func("int mediaway_desktop_capture_poll_frame(void *capture, _Out_ MwDesktopFrame *out_frame, _Out_ bool *out_has)"),
@@ -476,6 +440,12 @@ export const device = {
     gpuDeviceHandle: deviceLib.func("int mediaway_gpu_device_handle(void *device, _Out_ MwGpuDeviceHandle *out_handle)"),
     gpuDeviceClose: deviceLib.func("void mediaway_gpu_device_close(void *device)"),
 };
+// ── Replay ring + payload placements (adr/container/0009) ────────────────────
+// Declared in container-replay.ts (this file is near the 1000-line cap). Called here, after
+// `MwRational` and `MwPacketView` exist, because the signatures name them.
+export const replay = createReplayBindings(MwRational);
+/** koffi's sizeof/offsetof for the replay structs — pinned by test/replay-ring.test.ts. */
+export const replayStructLayout = () => replayLayout(replay.structs);
 // ── Copy helpers ───────────────────────────────────────────────────────────────
 /** Copy `len` bytes out of a koffi pointer/opaque handle. */
 export function copyBytes(ptr, len) {

package/dist/loader.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Native library discovery + koffi load for @mediaway/ffi.
+ *
+ * Split out of index.ts (ADR-0024, multi-platform binding distribution)
+ * once the added per-platform search-path logic pushed index.ts's struct/
+ * function-binding definitions past the workspace's 1000-line source cap.
+ */
+export declare function findLibrary(name: string): string;
+export declare const containerLib: import("koffi").LibraryHandle;
+export declare const pipelineLib: import("koffi").LibraryHandle;
+export declare const deviceLib: import("koffi").LibraryHandle;

package/dist/loader.js

@@ -0,0 +1,74 @@
+/**
+ * Native library discovery + koffi load for @mediaway/ffi.
+ *
+ * Split out of index.ts (ADR-0024, multi-platform binding distribution)
+ * once the added per-platform search-path logic pushed index.ts's struct/
+ * function-binding definitions past the workspace's 1000-line source cap.
+ */
+import koffi from "koffi";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// ── Library discovery ──────────────────────────────────────────────────────────
+// The cdylib is a Rust build artifact, not an installed system library.
+// Search:
+//   1. $MEDIAWAY_FFI_DIR
+//   2. <this package>/native/<platform>-<arch>   (libs for every platform
+//      bundled at pack time — the npm distribution; see § platform tag)
+//   3. <repo root>/target/x86_64-pc-windows-gnu/debug   (GNU toolchain, dev runs)
+//   4. <repo root>/target/debug                          (host/MSVC toolchain)
+//   5. cwd
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(here, "..", "..", "..", "..", "..");
+/**
+ * `os-arch` tag matching one of `native/<tag>`'s subdirectories (this
+ * package bundles every platform's prebuilt lib directly — see
+ * tools/scripts/copy-native-dlls.ts). Returns `undefined` for an
+ * unsupported platform/arch pair rather than throwing, so callers can still
+ * fall through to the other search dirs (e.g. `$MEDIAWAY_FFI_DIR` during
+ * local development on an unlisted arch).
+ */
+function platformTag() {
+    const os = process.platform === "win32" ? "win32" : process.platform === "linux" ? "linux"
+        : process.platform === "darwin" ? "darwin" : undefined;
+    const arch = process.arch === "x64" ? "x64" : process.arch === "arm64" ? "arm64" : undefined;
+    return os && arch ? `${os}-${arch}` : undefined;
+}
+const tag = platformTag();
+const searchDirs = [
+    process.env.MEDIAWAY_FFI_DIR ?? "",
+    tag ? path.resolve(here, "..", "native", tag) : "",
+    path.join(repoRoot, "target", "x86_64-pc-windows-gnu", "debug"),
+    path.join(repoRoot, "target", "debug"),
+    process.cwd(),
+];
+export function findLibrary(name) {
+    for (const dir of searchDirs) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, name);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    throw new Error(`cannot find ${name}; set $MEDIAWAY_FFI_DIR or build the -ffi crates`);
+}
+/** cdylib filename Cargo produces for this platform. */
+function libraryFilename() {
+    switch (process.platform) {
+        case "win32":
+            return "mediaway_ffi.dll";
+        case "linux":
+            return "libmediaway_ffi.so";
+        case "darwin":
+            return "libmediaway_ffi.dylib";
+        default:
+            throw new Error(`mediaway: unsupported platform ${process.platform}`);
+    }
+}
+function load(name) {
+    return koffi.load(findLibrary(name));
+}
+const libraryName = libraryFilename();
+export const containerLib = load(libraryName);
+export const pipelineLib = load(libraryName);
+export const deviceLib = load(libraryName);

package/dist/pipeline-v7.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pipeline ABI v7 additions — `crates/mediaway-ffi/adr/pipeline/0007-stream-bytes-aac-decode-
+ * support-probe.md`: streaming fMP4 bytes, AAC decode, and the capability probes.
+ *
+ * Split out of index.ts for the workspace's 1000-line source cap. It imports only leaf modules
+ * (`rational.ts`, `loader.ts`), never `index.ts`, so `index.ts` can re-export it without a cycle.
+ *
+ * Ownership (from `pipeline.h`):
+ *   - `mediaway_encode_session_poll_bytes` returns an OWNED buffer (release it with
+ *     `pipeline.bufferFree`); nothing ready is `NULL` / `0` and needs no free.
+ *   - `mediaway_encoder_support_at` returns an OWNED array; release it with
+ *     `mediaway_encoder_support_free`, passing back the same pointer and count.
+ *   - `mediaway_audio_decode_config_t.extra_data` is BORROWED, valid for `open()` only.
+ */
+/** `mediaway_audio_decode_config_t` — Opus passes `extra_data = NULL`, AAC the raw ASC. */
+export declare const MwAudioDecodeConfig: import("koffi").TypeObject;
+/** `mediaway_encoder_capability_t` — one backend row of `mediaway_encoder_support_at`. */
+export declare const MwEncoderCapability: import("koffi").TypeObject;
+/** `mediaway_encoder_capability_t` as decoded by koffi. */
+export interface RawEncoderCapability {
+    backend: number;
+    state: number;
+    path_class: number;
+}
+/** Codec numbers the probes and AAC decode accept (`mediaway_pipeline_codec_kind_t`). */
+export declare const PIPELINE_CODEC: {
+    readonly h264: 0;
+    readonly hevc: 1;
+    readonly av1: 2;
+    readonly vp9: 3;
+    readonly aac: 4;
+    readonly opus: 5;
+};
+export declare const pipelineV7: {
+    audioDecodeConfigAac: import("koffi").Callable;
+    sessionPollBytes: import("koffi").Callable;
+    encoderSupportAt: import("koffi").Callable;
+    encoderSupportFree: import("koffi").Callable;
+    decoderSupport: import("koffi").Callable;
+};
+/**
+ * Size and field offsets of a registered struct, for pinning a mirror against the C header's
+ * layout in a test. `fields` are read in the order given.
+ */
+export declare function structLayout(type: unknown, fields: readonly string[]): {
+    size: number;
+    offsets: Record<string, number>;
+};

package/dist/pipeline-v7.js

@@ -0,0 +1,54 @@
+/**
+ * Pipeline ABI v7 additions — `crates/mediaway-ffi/adr/pipeline/0007-stream-bytes-aac-decode-
+ * support-probe.md`: streaming fMP4 bytes, AAC decode, and the capability probes.
+ *
+ * Split out of index.ts for the workspace's 1000-line source cap. It imports only leaf modules
+ * (`rational.ts`, `loader.ts`), never `index.ts`, so `index.ts` can re-export it without a cycle.
+ *
+ * Ownership (from `pipeline.h`):
+ *   - `mediaway_encode_session_poll_bytes` returns an OWNED buffer (release it with
+ *     `pipeline.bufferFree`); nothing ready is `NULL` / `0` and needs no free.
+ *   - `mediaway_encoder_support_at` returns an OWNED array; release it with
+ *     `mediaway_encoder_support_free`, passing back the same pointer and count.
+ *   - `mediaway_audio_decode_config_t.extra_data` is BORROWED, valid for `open()` only.
+ */
+import koffi from "koffi";
+import { pipelineLib } from "./loader.js";
+import { MwRational } from "./rational.js";
+/** `mediaway_audio_decode_config_t` — Opus passes `extra_data = NULL`, AAC the raw ASC. */
+export const MwAudioDecodeConfig = koffi.struct("MwAudioDecodeConfig", {
+    codec: "int32", // Opus (5) or AAC (4)
+    sample_rate: "uint32",
+    channels: "uint16",
+    time_base: MwRational,
+    extra_data: "uint8_t *", // borrowed, open-call only; AAC's AudioSpecificConfig
+    extra_data_len: "size_t",
+});
+/** `mediaway_encoder_capability_t` — one backend row of `mediaway_encoder_support_at`. */
+export const MwEncoderCapability = koffi.struct("MwEncoderCapability", {
+    backend: "int32",
+    state: "int32",
+    path_class: "int32", // meaningful only when state == SUPPORTED
+});
+/** Codec numbers the probes and AAC decode accept (`mediaway_pipeline_codec_kind_t`). */
+export const PIPELINE_CODEC = { h264: 0, hevc: 1, av1: 2, vp9: 3, aac: 4, opus: 5 };
+export const pipelineV7 = {
+    audioDecodeConfigAac: pipelineLib.func("MwAudioDecodeConfig mediaway_audio_decode_config_aac(uint32_t sample_rate, uint16_t channels, MwRational time_base, uint8_t *extra_data, size_t extra_data_len)"),
+    sessionPollBytes: pipelineLib.func("int mediaway_encode_session_poll_bytes(void *session, _Out_ uint8_t **out_data, _Out_ size_t *out_len)"),
+    encoderSupportAt: pipelineLib.func("int mediaway_encoder_support_at(int codec, uint32_t width, uint32_t height, _Out_ void **out_rows, _Out_ size_t *out_count)"),
+    encoderSupportFree: pipelineLib.func("void mediaway_encoder_support_free(void *rows, size_t count)"),
+    decoderSupport: pipelineLib.func("int mediaway_decoder_support(int codec, _Out_ int *out_state)"),
+};
+/**
+ * Size and field offsets of a registered struct, for pinning a mirror against the C header's
+ * layout in a test. `fields` are read in the order given.
+ */
+export function structLayout(type, fields) {
+    // `type` stays `unknown` so callers can pass whatever `koffi.struct` returned; `koffi.d.ts`
+    // types the pair strictly (`TypeObject`), so narrow it once here.
+    const registered = type;
+    const offsets = {};
+    for (const field of fields)
+        offsets[field] = koffi.offsetof(registered, field);
+    return { size: koffi.sizeof(registered), offsets };
+}

package/dist/rational.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `mediaway_rational_t`, in a leaf module.
+ *
+ * Split out of index.ts so `pipeline-v7.ts` (which needs it to define struct layouts that
+ * embed a timebase) can import it without a cycle: index.ts imports pipeline-v7.ts, so
+ * pipeline-v7.ts must not import index.ts.
+ */
+export declare const MwRational: import("koffi").TypeObject;

package/dist/rational.js

@@ -0,0 +1,12 @@
+/**
+ * `mediaway_rational_t`, in a leaf module.
+ *
+ * Split out of index.ts so `pipeline-v7.ts` (which needs it to define struct layouts that
+ * embed a timebase) can import it without a cycle: index.ts imports pipeline-v7.ts, so
+ * pipeline-v7.ts must not import index.ts.
+ */
+import koffi from "koffi";
+export const MwRational = koffi.struct("MwRational", {
+    num: "uint64",
+    den: "uint32",
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediaway/ffi",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "Rust-based, lightweight, fast — Mediaway native C ABI bindings for Node.js — the shared DLL behind the @mediaway packages",
   "type": "module",
   "main": "./dist/index.js",