taglib-wasm 2.2.2 → 2.3.0

package/dist/src/constants/properties.d.ts

@@ -299,7 +299,7 @@ export declare const PROPERTIES: {
     };
     readonly releaseType: {
         readonly key: "RELEASETYPE";
-        readonly description: "Release type (album, single, EP, compilation, ...). Multi-value (e.g. 'album' + 'EP'). TagLib 2.3.1 translates the RELEASETYPE key per format: ID3v2 TXXX 'MUSICBRAINZ ALBUM TYPE' (TagLib's description casing), MP4 freeform atom, APEv2 MUSICBRAINZ_ALBUMTYPE, ASF 'MusicBrainz/Album Type', Vorbis/Matroska raw RELEASETYPE";
+        readonly description: "Release type (album, single, EP, compilation, ...). Multi-value (e.g. 'album' + 'EP'). TagLib 2.3.2 translates the RELEASETYPE key per format: ID3v2 TXXX 'MUSICBRAINZ ALBUM TYPE' (TagLib's description casing), MP4 freeform atom, APEv2 MUSICBRAINZ_ALBUMTYPE, ASF 'MusicBrainz/Album Type', Vorbis/Matroska raw RELEASETYPE";
         readonly type: "string";
         readonly supportedFormats: readonly ["ID3v2", "MP4", "Vorbis", "APE", "ASF", "Matroska"];
         readonly mappings: {
@@ -313,7 +313,7 @@ export declare const PROPERTIES: {
     };
     readonly releaseCountry: {
         readonly key: "RELEASECOUNTRY";
-        readonly description: "Release country (ISO 3166-1 code, e.g. 'US'). TagLib 2.3.1 translates the RELEASECOUNTRY key per format: ID3v2 TXXX 'MUSICBRAINZ ALBUM RELEASE COUNTRY' (TagLib's description casing; an uppercase TXXX:RELEASECOUNTRY description also reads back), MP4 freeform atom 'MusicBrainz Album Release Country', APEv2 raw RELEASECOUNTRY, ASF 'MusicBrainz/Album Release Country', WAV ICNT, Vorbis/Matroska raw RELEASECOUNTRY";
+        readonly description: "Release country (ISO 3166-1 code, e.g. 'US'). TagLib 2.3.2 translates the RELEASECOUNTRY key per format: ID3v2 TXXX 'MUSICBRAINZ ALBUM RELEASE COUNTRY' (TagLib's description casing; an uppercase TXXX:RELEASECOUNTRY description also reads back), MP4 freeform atom 'MusicBrainz Album Release Country', APEv2 raw RELEASECOUNTRY, ASF 'MusicBrainz/Album Release Country', WAV ICNT, Vorbis/Matroska raw RELEASECOUNTRY";
         readonly type: "string";
         readonly supportedFormats: readonly ["ID3v2", "MP4", "Vorbis", "APE", "ASF", "Matroska", "WAV"];
         readonly mappings: {

package/dist/src/constants/specialized-properties.d.ts

@@ -61,7 +61,7 @@ export declare const SPECIALIZED_PROPERTIES: {
     };
     readonly releaseType: {
         readonly key: "RELEASETYPE";
-        readonly description: "Release type (album, single, EP, compilation, ...). Multi-value (e.g. 'album' + 'EP'). TagLib 2.3.1 translates the RELEASETYPE key per format: ID3v2 TXXX 'MUSICBRAINZ ALBUM TYPE' (TagLib's description casing), MP4 freeform atom, APEv2 MUSICBRAINZ_ALBUMTYPE, ASF 'MusicBrainz/Album Type', Vorbis/Matroska raw RELEASETYPE";
+        readonly description: "Release type (album, single, EP, compilation, ...). Multi-value (e.g. 'album' + 'EP'). TagLib 2.3.2 translates the RELEASETYPE key per format: ID3v2 TXXX 'MUSICBRAINZ ALBUM TYPE' (TagLib's description casing), MP4 freeform atom, APEv2 MUSICBRAINZ_ALBUMTYPE, ASF 'MusicBrainz/Album Type', Vorbis/Matroska raw RELEASETYPE";
         readonly type: "string";
         readonly supportedFormats: readonly ["ID3v2", "MP4", "Vorbis", "APE", "ASF", "Matroska"];
         readonly mappings: {
@@ -75,7 +75,7 @@ export declare const SPECIALIZED_PROPERTIES: {
     };
     readonly releaseCountry: {
         readonly key: "RELEASECOUNTRY";
-        readonly description: "Release country (ISO 3166-1 code, e.g. 'US'). TagLib 2.3.1 translates the RELEASECOUNTRY key per format: ID3v2 TXXX 'MUSICBRAINZ ALBUM RELEASE COUNTRY' (TagLib's description casing; an uppercase TXXX:RELEASECOUNTRY description also reads back), MP4 freeform atom 'MusicBrainz Album Release Country', APEv2 raw RELEASECOUNTRY, ASF 'MusicBrainz/Album Release Country', WAV ICNT, Vorbis/Matroska raw RELEASECOUNTRY";
+        readonly description: "Release country (ISO 3166-1 code, e.g. 'US'). TagLib 2.3.2 translates the RELEASECOUNTRY key per format: ID3v2 TXXX 'MUSICBRAINZ ALBUM RELEASE COUNTRY' (TagLib's description casing; an uppercase TXXX:RELEASECOUNTRY description also reads back), MP4 freeform atom 'MusicBrainz Album Release Country', APEv2 raw RELEASECOUNTRY, ASF 'MusicBrainz/Album Release Country', WAV ICNT, Vorbis/Matroska raw RELEASECOUNTRY";
         readonly type: "string";
         readonly supportedFormats: readonly ["ID3v2", "MP4", "Vorbis", "APE", "ASF", "Matroska", "WAV"];
         readonly mappings: {

package/dist/src/constants/specialized-properties.js

@@ -46,7 +46,7 @@ const SPECIALIZED_PROPERTIES = {
   },
   releaseType: {
     key: "RELEASETYPE",
-    description: "Release type (album, single, EP, compilation, ...). Multi-value (e.g. 'album' + 'EP'). TagLib 2.3.1 translates the RELEASETYPE key per format: ID3v2 TXXX 'MUSICBRAINZ ALBUM TYPE' (TagLib's description casing), MP4 freeform atom, APEv2 MUSICBRAINZ_ALBUMTYPE, ASF 'MusicBrainz/Album Type', Vorbis/Matroska raw RELEASETYPE",
+    description: "Release type (album, single, EP, compilation, ...). Multi-value (e.g. 'album' + 'EP'). TagLib 2.3.2 translates the RELEASETYPE key per format: ID3v2 TXXX 'MUSICBRAINZ ALBUM TYPE' (TagLib's description casing), MP4 freeform atom, APEv2 MUSICBRAINZ_ALBUMTYPE, ASF 'MusicBrainz/Album Type', Vorbis/Matroska raw RELEASETYPE",
     type: "string",
     supportedFormats: [
       "ID3v2",
@@ -64,7 +64,7 @@ const SPECIALIZED_PROPERTIES = {
   },
   releaseCountry: {
     key: "RELEASECOUNTRY",
-    description: "Release country (ISO 3166-1 code, e.g. 'US'). TagLib 2.3.1 translates the RELEASECOUNTRY key per format: ID3v2 TXXX 'MUSICBRAINZ ALBUM RELEASE COUNTRY' (TagLib's description casing; an uppercase TXXX:RELEASECOUNTRY description also reads back), MP4 freeform atom 'MusicBrainz Album Release Country', APEv2 raw RELEASECOUNTRY, ASF 'MusicBrainz/Album Release Country', WAV ICNT, Vorbis/Matroska raw RELEASECOUNTRY",
+    description: "Release country (ISO 3166-1 code, e.g. 'US'). TagLib 2.3.2 translates the RELEASECOUNTRY key per format: ID3v2 TXXX 'MUSICBRAINZ ALBUM RELEASE COUNTRY' (TagLib's description casing; an uppercase TXXX:RELEASECOUNTRY description also reads back), MP4 freeform atom 'MusicBrainz Album Release Country', APEv2 raw RELEASECOUNTRY, ASF 'MusicBrainz/Album Release Country', WAV ICNT, Vorbis/Matroska raw RELEASECOUNTRY",
     type: "string",
     supportedFormats: [
       "ID3v2",

package/dist/src/errors/base.d.ts

@@ -1,7 +1,22 @@
 /**
- * List of audio formats supported by TagLib-Wasm
+ * List of audio formats supported by TagLib-Wasm.
+ *
+ * The prose source of truth is the README's "Supported Formats" section; this
+ * list carries every `FileType` member except `"unknown"` (src/types/audio-
+ * formats.ts), plus the extension aliases files actually carry ("M4A", "MKA")
+ * — ASF is the container of the WMA flavour the README names.
+ *
+ * Public contract: the default `supportedFormats` on `UnsupportedFormatError`
+ * (src/errors/classes.ts), and part of that error's message.
+ *
+ * This is the formats the library can read, not a promise that both backends
+ * describe all of them identically. Measured 2026-09-18 (taglib-uat8):
+ * `getFormat()` answers every member on both backends, but on Emscripten
+ * `audioProperties().containerFormat` / `.codec` still report `"unknown"` for
+ * the formats the embind sniffer cannot place (APE, DSF, DSDIFF, MPC, SHN,
+ * MOD, S3M, IT, XM); their tags and the rest of their properties load.
  */
-export declare const SUPPORTED_FORMATS: readonly ["MP3", "MP4", "M4A", "FLAC", "OGG", "WAV", "MKA"];
+export declare const SUPPORTED_FORMATS: readonly ["MP3", "AAC", "MP4", "M4A", "FLAC", "OGG", "OPUS", "OggFLAC", "SPEEX", "WAV", "AIFF", "ASF", "APE", "DSF", "DSDIFF", "WV", "MPC", "TTA", "SHN", "MOD", "S3M", "IT", "XM", "MATROSKA", "MKA"];
 /**
  * Error codes for programmatic error handling
  */

package/dist/src/errors/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/errors/base.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,iBAAiB,6DAQpB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,gBAAgB,GAChB,gBAAgB,GAChB,oBAAoB,GACpB,gBAAgB,GAChB,UAAU,GACV,QAAQ,GACR,aAAa,GACb,aAAa,GACb,aAAa,GACb,WAAW,CAAC;AAEhB;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAQlB,IAAI,EAAE,eAAe;aAErB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IATnD;;;;;OAKG;gBAEe,IAAI,EAAE,eAAe,EACrC,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAMpD"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/errors/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB,wMA0BpB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,gBAAgB,GAChB,gBAAgB,GAChB,oBAAoB,GACpB,gBAAgB,GAChB,UAAU,GACV,QAAQ,GACR,aAAa,GACb,aAAa,GACb,aAAa,GACb,WAAW,CAAC;AAEhB;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAQlB,IAAI,EAAE,eAAe;aAErB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IATnD;;;;;OAKG;gBAEe,IAAI,EAAE,eAAe,EACrC,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAMpD"}

package/dist/src/errors/base.js

@@ -3,11 +3,29 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 const SUPPORTED_FORMATS = [
   "MP3",
+  "AAC",
   "MP4",
   "M4A",
   "FLAC",
   "OGG",
+  "OPUS",
+  "OggFLAC",
+  "SPEEX",
   "WAV",
+  "AIFF",
+  "ASF",
+  "APE",
+  "DSF",
+  "DSDIFF",
+  "WV",
+  "MPC",
+  "TTA",
+  "SHN",
+  "MOD",
+  "S3M",
+  "IT",
+  "XM",
+  "MATROSKA",
   "MKA"
 ];
 class TagLibError extends Error {

package/dist/src/runtime/detector.d.ts

@@ -7,6 +7,21 @@ export interface RuntimeDetectionResult {
     supportsStreaming: boolean;
     performanceTier: 1 | 2 | 3;
 }
+/**
+ * The pure per-environment backend configuration. `detectRuntime()` is the
+ * only sniffer in the codebase; every downstream decision (backend choice,
+ * PlatformIO creation, WASI availability) derives from this table so it can
+ * be exercised with synthetic environments instead of real runtimes
+ * (taglib-2b4).
+ */
+export interface EnvironmentProfile {
+    wasmType: WasmBinaryType;
+    supportsFilesystem: boolean;
+    supportsStreaming: boolean;
+    performanceTier: 1 | 2 | 3;
+}
+/** Pure environment -> backend configuration lookup (taglib-2b4). */
+export declare function environmentProfile(env: RuntimeEnvironment): EnvironmentProfile;
 /**
  * Check if a Node.js version meets the minimum requirement (v22.6.0+).
  * Returns an error message string if the version is too old, or undefined if OK.
@@ -22,5 +37,5 @@ export declare function detectRuntime(): RuntimeDetectionResult;
  */
 export declare function supportsExnref(): boolean;
 export declare function getEnvironmentDescription(env: RuntimeEnvironment): string;
-export declare function canLoadWasmType(wasmType: WasmBinaryType): boolean;
+export declare function canLoadWasmType(wasmType: WasmBinaryType, env?: RuntimeEnvironment): boolean;
 //# sourceMappingURL=detector.d.ts.map

package/dist/src/runtime/detector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../../../src/runtime/detector.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,WAAW,GACX,UAAU,GACV,SAAS,GACT,iBAAiB,GACjB,QAAQ,GACR,YAAY,CAAC;AAEjB,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,YAAY,CAAC;AAEnD,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,kBAAkB,CAAC;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,eAAe,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CAC5B;AAOD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,GAAG,SAAS,CAepB;AAuCD,qFAAqF;AACrF,wBAAgB,MAAM,IAAI,OAAO,CAEhC;AAED,wBAAgB,aAAa,IAAI,sBAAsB,CA8EtD;AAWD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAMxC;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAmBzE;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAQjE"}
+{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../../../src/runtime/detector.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,WAAW,GACX,UAAU,GACV,SAAS,GACT,iBAAiB,GACjB,QAAQ,GACR,YAAY,CAAC;AAEjB,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,YAAY,CAAC;AAEnD,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,kBAAkB,CAAC;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,eAAe,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,cAAc,CAAC;IACzB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,eAAe,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CAC5B;AA+CD,qEAAqE;AACrE,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,kBAAkB,GACtB,kBAAkB,CAEpB;AAOD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,GAAG,SAAS,CAepB;AAuCD,qFAAqF;AACrF,wBAAgB,MAAM,IAAI,OAAO,CAEhC;AAED,wBAAgB,aAAa,IAAI,sBAAsB,CAuCtD;AAWD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAMxC;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAmBzE;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,cAAc,EACxB,GAAG,GAAE,kBAAgD,GACpD,OAAO,CAKT"}

package/dist/src/runtime/detector.js

@@ -1,3 +1,50 @@
+const ENVIRONMENT_PROFILES = {
+  "deno-wasi": {
+    wasmType: "wasi",
+    supportsFilesystem: true,
+    supportsStreaming: true,
+    performanceTier: 1
+  },
+  "node-wasi": {
+    wasmType: "wasi",
+    supportsFilesystem: true,
+    supportsStreaming: true,
+    performanceTier: 1
+  },
+  "bun-wasi": {
+    wasmType: "wasi",
+    supportsFilesystem: true,
+    supportsStreaming: true,
+    performanceTier: 1
+  },
+  browser: {
+    wasmType: "emscripten",
+    supportsFilesystem: false,
+    supportsStreaming: true,
+    performanceTier: 2
+  },
+  worker: {
+    wasmType: "emscripten",
+    supportsFilesystem: false,
+    supportsStreaming: true,
+    performanceTier: 2
+  },
+  cloudflare: {
+    wasmType: "emscripten",
+    supportsFilesystem: false,
+    supportsStreaming: false,
+    performanceTier: 3
+  },
+  "node-emscripten": {
+    wasmType: "emscripten",
+    supportsFilesystem: true,
+    supportsStreaming: true,
+    performanceTier: 3
+  }
+};
+function environmentProfile(env) {
+  return ENVIRONMENT_PROFILES[env];
+}
 const g = globalThis;
 const MIN_NODE_MAJOR = 22;
 const MIN_NODE_MINOR = 6;
@@ -38,73 +85,32 @@ function isDeno() {
 }
 function detectRuntime() {
   if (isDeno() && hasWASISupport()) {
-    return {
-      environment: "deno-wasi",
-      wasmType: "wasi",
-      supportsFilesystem: true,
-      supportsStreaming: true,
-      performanceTier: 1
-    };
+    return { environment: "deno-wasi", ...environmentProfile("deno-wasi") };
   }
   if (isBun()) {
-    return {
-      environment: "bun-wasi",
-      wasmType: "wasi",
-      supportsFilesystem: true,
-      supportsStreaming: true,
-      performanceTier: 1
-    };
+    return { environment: "bun-wasi", ...environmentProfile("bun-wasi") };
   }
   if (isNode() && hasWASISupport()) {
-    return {
-      environment: "node-wasi",
-      wasmType: "wasi",
-      supportsFilesystem: true,
-      supportsStreaming: true,
-      performanceTier: 1
-    };
+    return { environment: "node-wasi", ...environmentProfile("node-wasi") };
   }
   if (isBrowser()) {
-    return {
-      environment: "browser",
-      wasmType: "emscripten",
-      supportsFilesystem: false,
-      supportsStreaming: true,
-      performanceTier: 2
-    };
+    return { environment: "browser", ...environmentProfile("browser") };
   }
   if (isWebWorker()) {
-    return {
-      environment: "worker",
-      wasmType: "emscripten",
-      supportsFilesystem: false,
-      supportsStreaming: true,
-      performanceTier: 2
-    };
+    return { environment: "worker", ...environmentProfile("worker") };
   }
   if (isCloudflareWorker()) {
-    return {
-      environment: "cloudflare",
-      wasmType: "emscripten",
-      supportsFilesystem: false,
-      supportsStreaming: false,
-      performanceTier: 3
-    };
+    return { environment: "cloudflare", ...environmentProfile("cloudflare") };
   }
   if (isNode()) {
     return {
       environment: "node-emscripten",
-      wasmType: "emscripten",
-      supportsFilesystem: true,
-      supportsStreaming: true,
-      performanceTier: 3
+      ...environmentProfile("node-emscripten")
     };
   }
   return {
     environment: "browser",
-    wasmType: "emscripten",
-    supportsFilesystem: false,
-    supportsStreaming: true,
+    ...environmentProfile("browser"),
     performanceTier: 3
   };
 }
@@ -158,10 +164,9 @@ function getEnvironmentDescription(env) {
       return "Unknown environment";
   }
 }
-function canLoadWasmType(wasmType) {
-  const result = detectRuntime();
+function canLoadWasmType(wasmType, env = detectRuntime().environment) {
   if (wasmType === "wasi") {
-    return result.environment === "deno-wasi" || result.environment === "node-wasi" || result.environment === "bun-wasi";
+    return environmentProfile(env).wasmType === "wasi";
   }
   return true;
 }
@@ -169,6 +174,7 @@ export {
   canLoadWasmType,
   checkNodeVersion,
   detectRuntime,
+  environmentProfile,
   getEnvironmentDescription,
   isDeno,
   supportsExnref

package/dist/src/runtime/platform-io.d.ts

@@ -1,3 +1,4 @@
+import { type RuntimeEnvironment } from "./detector.js";
 export type PlatformIO = {
     readFile(path: string): Promise<Uint8Array>;
     writeFile(path: string, data: Uint8Array): Promise<void>;
@@ -11,6 +12,13 @@ export type PlatformIO = {
     }>;
     readPartial?: (path: string, headerSize: number, footerSize: number) => Promise<Uint8Array>;
 };
+/**
+ * Pure environment -> PlatformIO selection (taglib-2b4): each environment's
+ * factory is chosen without sniffing, so the routing is testable with a
+ * synthetic environment. Factories are lazy — nothing touches the runtime
+ * until a method is called, so calling this under any runtime is safe.
+ */
+export declare function createPlatformIOFor(env: RuntimeEnvironment): PlatformIO;
 export declare function getPlatformIO(): PlatformIO;
 /** @internal */
 export declare function _setPlatformIOForTesting(io: PlatformIO): void;

package/dist/src/runtime/platform-io.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform-io.d.ts","sourceRoot":"","sources":["../../../src/runtime/platform-io.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9C,OAAO,CACL,IAAI,EAAE,MAAM,GACX,cAAc,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC3E,WAAW,CAAC,EAAE,CACZ,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,UAAU,CAAC,CAAC;CAC1B,CAAC;AA0LF,wBAAgB,aAAa,IAAI,UAAU,CAyB1C;AAED,gBAAgB;AAChB,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI,CAE7D;AAED,gBAAgB;AAChB,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}
+{"version":3,"file":"platform-io.d.ts","sourceRoot":"","sources":["../../../src/runtime/platform-io.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEvE,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9C,OAAO,CACL,IAAI,EAAE,MAAM,GACX,cAAc,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC3E,WAAW,CAAC,EAAE,CACZ,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,UAAU,CAAC,CAAC;CAC1B,CAAC;AA0LF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,kBAAkB,GAAG,UAAU,CAgBvE;AAED,wBAAgB,aAAa,IAAI,UAAU,CAM1C;AAED,gBAAgB;AAChB,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI,CAE7D;AAED,gBAAgB;AAChB,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/dist/src/runtime/platform-io.js

@@ -152,27 +152,26 @@ function createBunIO() {
     }
   };
 }
-function getPlatformIO() {
-  if (platformIO) return platformIO;
-  const runtime = detectRuntime();
-  switch (runtime.environment) {
+function createPlatformIOFor(env) {
+  switch (env) {
     case "deno-wasi":
-      platformIO = createDenoIO();
-      break;
+      return createDenoIO();
     case "bun-wasi":
-      platformIO = createBunIO();
-      break;
+      return createBunIO();
     case "node-wasi":
     case "node-emscripten":
-      platformIO = createNodeIO();
-      break;
+      return createNodeIO();
     default:
       throw new EnvironmentError(
-        runtime.environment,
+        env,
         "does not support filesystem operations",
         "filesystem access"
       );
   }
+}
+function getPlatformIO() {
+  if (platformIO) return platformIO;
+  platformIO = createPlatformIOFor(detectRuntime().environment);
   return platformIO;
 }
 function _setPlatformIOForTesting(io) {
@@ -184,5 +183,6 @@ function _resetPlatformIO() {
 export {
   _resetPlatformIO,
   _setPlatformIOForTesting,
+  createPlatformIOFor,
   getPlatformIO
 };

package/dist/src/runtime/unified-loader/module-selection.d.ts

@@ -1,6 +1,6 @@
 import { type RuntimeDetectionResult } from "../detector.js";
 import type { UnifiedLoaderOptions } from "./types.js";
 export declare function selectWasmType(runtime: RuntimeDetectionResult, options: UnifiedLoaderOptions): "wasi" | "emscripten";
-export declare function isWasiAvailable(): boolean;
-export declare function getRecommendedConfig(): UnifiedLoaderOptions;
+export declare function isWasiAvailable(runtime?: RuntimeDetectionResult): boolean;
+export declare function getRecommendedConfig(runtime?: RuntimeDetectionResult): UnifiedLoaderOptions;
 //# sourceMappingURL=module-selection.d.ts.map

package/dist/src/runtime/unified-loader/module-selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module-selection.d.ts","sourceRoot":"","sources":["../../../../src/runtime/unified-loader/module-selection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,oBAAoB,GAC5B,MAAM,GAAG,YAAY,CAqBvB;AAED,wBAAgB,eAAe,IAAI,OAAO,CAGzC;AAED,wBAAgB,oBAAoB,IAAI,oBAAoB,CAoB3D"}
+{"version":3,"file":"module-selection.d.ts","sourceRoot":"","sources":["../../../../src/runtime/unified-loader/module-selection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,oBAAoB,GAC5B,MAAM,GAAG,YAAY,CAqBvB;AAED,wBAAgB,eAAe,CAC7B,OAAO,GAAE,sBAAwC,GAChD,OAAO,CAET;AAED,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,sBAAwC,GAChD,oBAAoB,CAqBtB"}

package/dist/src/runtime/unified-loader/module-selection.js

@@ -14,19 +14,17 @@ function selectWasmType(runtime, options) {
   }
   return "emscripten";
 }
-function isWasiAvailable() {
-  const runtime = detectRuntime();
+function isWasiAvailable(runtime = detectRuntime()) {
   return runtime.wasmType === "wasi" && runtime.supportsFilesystem;
 }
-function getRecommendedConfig() {
-  const runtime = detectRuntime();
+function getRecommendedConfig(runtime = detectRuntime()) {
   if (runtime.environment === "browser") {
     return {
       forceWasmType: "emscripten",
       disableOptimizations: false
     };
   }
-  if (runtime.supportsFilesystem) {
+  if (runtime.wasmType === "wasi" && runtime.supportsFilesystem) {
     return {
       forceWasmType: "wasi",
       disableOptimizations: false

package/dist/src/runtime/wasi-adapter/adapter.d.ts

@@ -4,7 +4,7 @@
  * Adapts a WASI module interface to the TagLibModule interface,
  * providing Emscripten-compatible memory access and string operations.
  */
-import type { FileHandle, TagLibModule } from "../../wasm.js";
+import type { FileHandle, TagLibModule, WasmFileHandle } from "../../wasm.js";
 import type { WasiModule } from "../wasmer-sdk-loader/types.js";
 export declare class WasiToTagLibAdapter implements TagLibModule {
     private readonly wasi;
@@ -27,6 +27,18 @@ export declare class WasiToTagLibAdapter implements TagLibModule {
     stringToUTF8(str: string, ptr: number, maxBytes: number): number;
     lengthBytesUTF8(str: string): number;
     createFileHandle(): FileHandle;
+    /**
+     * The WASI host module this adapter wraps. Path mode's content gate
+     * (taglib-j9ld) needs the host's own detector and its WASI→host path
+     * resolution, neither of which belongs on the shared `TagLibModule` surface
+     * every backend implements.
+     */
+    get hostModule(): WasiModule;
+    /**
+     * The gated path open: `WasiFileHandle.loadFromPath` plus the content check a
+     * path needs where a buffer would be refused outright (see `path-open.ts`).
+     */
+    loadAudioPath(wasiPath: string, displayPath: string): Promise<WasmFileHandle>;
     version(): string;
     addFunction(_func: any): number;
     removeFunction(_ptr: number): void;

package/dist/src/runtime/wasi-adapter/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../src/runtime/wasi-adapter/adapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAKhE,qBAAa,mBAAoB,YAAW,YAAY;IACtD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;gBAEtB,UAAU,EAAE,UAAU;IAKlC,UAAU,EAMM,UAAU,UAAU,CAAC;IAErC,IAAI,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAEzB;IAED,IAAI,KAAK,IAAI,SAAS,CAErB;IAED,IAAI,MAAM,IAAI,UAAU,CAEvB;IAED,IAAI,MAAM,IAAI,UAAU,CAEvB;IAED,IAAI,MAAM,IAAI,UAAU,CAEvB;IAED,IAAI,OAAO,IAAI,WAAW,CAEzB;IAED,IAAI,OAAO,IAAI,WAAW,CAEzB;IAED,IAAI,OAAO,IAAI,YAAY,CAE1B;IAED,IAAI,OAAO,IAAI,YAAY,CAE1B;IAED,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI7B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAe9C,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAOjC,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAQhE,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAIpC,gBAAgB,IAAI,UAAU;IAI9B,OAAO,IAAI,MAAM;IAIjB,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM;IAM/B,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAMlC,KAAK,CACH,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,SAAS,EAAE,MAAM,EAAE,GAClB,GAAG;IAMN,KAAK,CACH,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,SAAS,EAAE,MAAM,EAAE,EACnB,KAAK,EAAE,GAAG,EAAE,GACX,GAAG;CAKP"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../src/runtime/wasi-adapter/adapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAMhE,qBAAa,mBAAoB,YAAW,YAAY;IACtD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;gBAEtB,UAAU,EAAE,UAAU;IAKlC,UAAU,EAMM,UAAU,UAAU,CAAC;IAErC,IAAI,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAEzB;IAED,IAAI,KAAK,IAAI,SAAS,CAErB;IAED,IAAI,MAAM,IAAI,UAAU,CAEvB;IAED,IAAI,MAAM,IAAI,UAAU,CAEvB;IAED,IAAI,MAAM,IAAI,UAAU,CAEvB;IAED,IAAI,OAAO,IAAI,WAAW,CAEzB;IAED,IAAI,OAAO,IAAI,WAAW,CAEzB;IAED,IAAI,OAAO,IAAI,YAAY,CAE1B;IAED,IAAI,OAAO,IAAI,YAAY,CAE1B;IAED,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI7B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAe9C,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAOjC,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAQhE,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAIpC,gBAAgB,IAAI,UAAU;IAI9B;;;;;OAKG;IACH,IAAI,UAAU,IAAI,UAAU,CAE3B;IAED;;;OAGG;IACH,aAAa,CACX,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,cAAc,CAAC;IAI1B,OAAO,IAAI,MAAM;IAIjB,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM;IAM/B,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAMlC,KAAK,CACH,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,SAAS,EAAE,MAAM,EAAE,GAClB,GAAG;IAMN,KAAK,CACH,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,SAAS,EAAE,MAAM,EAAE,EACnB,KAAK,EAAE,GAAG,EAAE,GACX,GAAG;CAKP"}

package/dist/src/runtime/wasi-adapter/adapter.js

@@ -4,6 +4,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 import { WasmerExecutionError } from "../wasmer-sdk-loader/types.js";
 import { MemoryError } from "../../errors/classes.js";
 import { WasiFileHandle } from "./file-handle.js";
+import { openAudioPath } from "./path-open.js";
 class WasiToTagLibAdapter {
   constructor(wasiModule) {
     __publicField(this, "wasi");
@@ -84,6 +85,22 @@ class WasiToTagLibAdapter {
   createFileHandle() {
     return new WasiFileHandle(this.wasi);
   }
+  /**
+   * The WASI host module this adapter wraps. Path mode's content gate
+   * (taglib-j9ld) needs the host's own detector and its WASI→host path
+   * resolution, neither of which belongs on the shared `TagLibModule` surface
+   * every backend implements.
+   */
+  get hostModule() {
+    return this.wasi;
+  }
+  /**
+   * The gated path open: `WasiFileHandle.loadFromPath` plus the content check a
+   * path needs where a buffer would be refused outright (see `path-open.ts`).
+   */
+  loadAudioPath(wasiPath, displayPath) {
+    return openAudioPath(this, wasiPath, displayPath);
+  }
   version() {
     return this.wasi.tl_version();
   }

package/dist/src/runtime/wasi-adapter/audio-properties.d.ts

@@ -8,7 +8,10 @@
 import type { AudioProperties } from "../../types.js";
 /** The audio-properties block of the C++ snapshot, null when absent. */
 export declare function getAudioProperties(tagData: Record<string, unknown> | null): AudioProperties | null;
-/** OGG codec sniffing: "OpusHead" in the first page payload, else OGG. */
+/**
+ * OGG codec sniffing from the first page payload: "OpusHead" (Opus),
+ * 0x7F"FLAC" (FLAC-in-Ogg), "Speex   " (Speex), else Ogg Vorbis ("OGG").
+ */
 export declare function detectOggCodec(fileData: Uint8Array): string;
 /**
  * Format detection: container-based first (works for path and buffer modes),

package/dist/src/runtime/wasi-adapter/audio-properties.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audio-properties.d.ts","sourceRoot":"","sources":["../../../../src/runtime/wasi-adapter/audio-properties.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAEV,eAAe,EAEhB,MAAM,gBAAgB,CAAC;AAexB,wEAAwE;AACxE,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GACtC,eAAe,GAAG,IAAI,CA4BxB;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAe3D;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACvC,QAAQ,EAAE,UAAU,GAAG,IAAI,GAC1B,MAAM,CAuDR;AAED,4EAA4E;AAC5E,wBAAgB,KAAK,CACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACvC,QAAQ,EAAE,UAAU,GAAG,IAAI,GAC1B,OAAO,CAYT"}
+{"version":3,"file":"audio-properties.d.ts","sourceRoot":"","sources":["../../../../src/runtime/wasi-adapter/audio-properties.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAEV,eAAe,EAEhB,MAAM,gBAAgB,CAAC;AA6CxB,wEAAwE;AACxE,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GACtC,eAAe,GAAG,IAAI,CA4BxB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAsB3D;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACvC,QAAQ,EAAE,UAAU,GAAG,IAAI,GAC1B,MAAM,CAyDR;AAED,4EAA4E;AAC5E,wBAAgB,KAAK,CACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACvC,QAAQ,EAAE,UAAU,GAAG,IAAI,GAC1B,OAAO,CAYT"}

package/dist/src/runtime/wasi-adapter/audio-properties.js

@@ -1,15 +1,30 @@
 const CONTAINER_TO_FORMAT = {
   MP3: "MP3",
+  ADTS: "AAC",
   MP4: "MP4",
   FLAC: "FLAC",
   OGG: "OGG",
   WAV: "WAV",
   AIFF: "AIFF",
+  ASF: "ASF",
+  APE: "APE",
+  DSF: "DSF",
+  DSDIFF: "DSDIFF",
   WavPack: "WV",
+  MPC: "MPC",
   TTA: "TTA",
-  ASF: "ASF",
+  Shorten: "SHN",
+  MOD: "MOD",
+  S3M: "S3M",
+  IT: "IT",
+  XM: "XM",
   Matroska: "MATROSKA"
 };
+const OGG_CODEC_TO_FORMAT = {
+  Opus: "OPUS",
+  FLAC: "OggFLAC",
+  Speex: "SPEEX"
+};
 function getAudioProperties(tagData) {
   if (!tagData || !("sampleRate" in tagData)) return null;
   const d = tagData;
@@ -38,17 +53,20 @@ function detectOggCodec(fileData) {
   if (segCount === void 0) return "OGG";
   const payloadStart = 27 + segCount;
   if (fileData.length < payloadStart + 8) return "OGG";
-  const sig = String.fromCharCode(
-    ...fileData.slice(payloadStart, payloadStart + 8)
-  );
-  if (sig === "OpusHead") return "OPUS";
+  const sig = fileData.slice(payloadStart, payloadStart + 8);
+  const text = String.fromCharCode(...sig);
+  if (text === "OpusHead") return "OPUS";
+  if (sig[0] === 127 && sig[1] === 70 && sig[2] === 76 && sig[3] === 65 && sig[4] === 67) return "OggFLAC";
+  if (text === "Speex   ") return "SPEEX";
   return "OGG";
 }
 function getFormat(tagData, fileData) {
   const container = tagData?.containerFormat;
   if (container) {
     const codec = tagData?.codec;
-    if (container === "OGG" && codec === "Opus") return "OPUS";
+    if (container === "OGG" && codec && OGG_CODEC_TO_FORMAT[codec]) {
+      return OGG_CODEC_TO_FORMAT[codec];
+    }
     if (CONTAINER_TO_FORMAT[container]) return CONTAINER_TO_FORMAT[container];
   }
   if (!fileData || fileData.length < 8) return "unknown";

package/dist/src/runtime/wasi-adapter/path-open.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The gated path open for the WASI backend: `WasiFileHandle.loadFromPath` plus
+ * the content check a path needs and a buffer does not.
+ *
+ * `read_from_path` resolves the file class by *extension* first, and upstream's
+ * `MPEG::File` reports itself valid for any bytes at all (its `read()` never
+ * clears validity, `lib/taglib/taglib/mpeg/mpegfile.cpp`), so `junk.mp3` opens
+ * where the same bytes in a buffer are refused. Two independent signals say
+ * whether anything was really there, in cost order:
+ *
+ * 1. {@link statesAudioProperties} — whether the parse read an audio property
+ *    out of the file. No extra I/O: the snapshot is what the open already
+ *    produced. A file that states a sample rate is audio TagLib read, whatever
+ *    its head looks like — which is how an MP3 behind a 4 KiB or 70 KiB APEv2
+ *    tag (this repo's own corpus shapes, tests/media-checksum-corpus.test.ts)
+ *    stays readable even though neither detector can see the frames behind the
+ *    tag.
+ * 2. {@link hasRecognizableHead} — whether the head is content the boundary's
+ *    detector knows, or opens as a buffer. This is what saves a file whose
+ *    properties are legitimately absent (`lib/taglib/tests/data/segfault.wav`
+ *    is 30 bytes of `RIFF`/`WAVE`; `tests/test-files/mp4/synth-multi-mdat.mp4`
+ *    has `ftyp` and no `moov`) and every tag-only file, whose head *is* its tag:
+ *    content is recognizable even when there is nothing to measure.
+ *
+ * A path is refused only when *both* say nothing — a zero-length file, junk
+ * bytes behind an audio extension. That is the shape of every refusal in this
+ * repo's and upstream's corpora (163 fixtures, swept by
+ * `tests/checksum-input-contract.test.ts`), and neither signal can refuse a file
+ * the buffer form accepts: every detector rule is head-based (MOD's signature at
+ * offset 1080 is the deepest, and the window clears it), the ID3v2 rule answers
+ * "MP3" rather than giving up when the tag runs past the window
+ * (`src/capi/taglib_boundary.c`, `tl_detect_format`), and a head that opens as a
+ * buffer *is* the buffer form's own verdict.
+ *
+ * The one asymmetry that survives is upstream's deliberately corrupt fixtures
+ * whose bytes still yield a property (`garbage.mp3`, `sv4_header.mpc`,
+ * `sv5_header.mpc`, `stripped.xm`): TagLib reads a header out of them, so the
+ * path form keeps accepting them exactly as it did before this change, while the
+ * buffer form's narrower magic rules refuse them. Nothing in the C detector can
+ * place SV4/SV5 MPC or junk-with-a-frame-header — see taglib-uat8 for that
+ * reachability gap — and refusing them here would mean refusing files the parse
+ * did read.
+ */
+import type { FileHandle, WasmFileHandle } from "../../wasm.js";
+import type { WasiModule } from "../wasmer-sdk-loader/types.js";
+/** The WASI backend this open runs on: its host module (where the detector and
+ * the WASI→host path resolution live, `WasiToTagLibAdapter.hostModule`) and its
+ * handle factory. */
+export interface PathOpenHost {
+    readonly hostModule: WasiModule;
+    createFileHandle(): FileHandle;
+}
+/**
+ * Load an audio file by path, verifying that its content is audio.
+ *
+ * Every failure the caller can act on is distinct: `FileOperationError` for a
+ * path the host does not have (what the buffer form's own stat answers, so a
+ * typo reads the same on both backends), `InvalidFormatError` for a zero-byte
+ * file (see below) and for content the boundary could not resolve as audio, and
+ * the wasm-level errors unchanged. Either content signal above suffices; both
+ * saying nothing is a refusal.
+ *
+ * The returned handle is the library-owned one (the WASI brand asserted here,
+ * the WASI equivalent of `wrapEmbindHandle`), destroyed on any failure — the
+ * caller's `AudioFile` takes it over on success.
+ */
+export declare function openAudioPath(backend: PathOpenHost, wasiPath: string, displayPath: string): Promise<WasmFileHandle>;
+//# sourceMappingURL=path-open.d.ts.map

package/dist/src/runtime/wasi-adapter/path-open.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-open.d.ts","sourceRoot":"","sources":["../../../../src/runtime/wasi-adapter/path-open.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAqBhE;;qBAEqB;AACrB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,gBAAgB,IAAI,UAAU,CAAC;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,cAAc,CAAC,CA0CzB"}