taglib-wasm 2.2.1 → 2.2.3

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/folder-api/album-corroborate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sibling corroboration for gated disc-folder names (taglib-ys7m split).
+ *
+ * Gated names (title-word markers, single-letter tokens, bonus, bare) are
+ * discs only when a sibling under the same parent confirms them — an
+ * unconditional disc sibling, or sibling numbering of their own (a folder
+ * never confirms itself). Side-letter tokens corroborate each other
+ * ("CD D" + "CD E").
+ */
+import type { DiscConfidence, DiscParse } from "./album-types.js";
+export declare const CONFIDENCE_RANK: Record<DiscConfidence, number>;
+export declare function corroborated(parse: DiscParse, siblings: string[]): boolean;
+//# sourceMappingURL=album-corroborate.d.ts.map

package/dist/src/folder-api/album-corroborate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"album-corroborate.d.ts","sourceRoot":"","sources":["../../../src/folder-api/album-corroborate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElE,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAI1D,CAAC;AAEF,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAoC1E"}

package/dist/src/folder-api/album-corroborate.js

@@ -0,0 +1,36 @@
+import { basename } from "../utils/path.js";
+import { parseDiscName } from "./folder-disc.js";
+const CONFIDENCE_RANK = {
+  low: 0,
+  medium: 1,
+  high: 2
+};
+function corroborated(parse, siblings) {
+  if (!parse.gated && parse.kind === "exact") return true;
+  if (siblings.length === 0) return false;
+  const siblingParses = siblings.map((s) => parseDiscName(basename(s))).filter((p) => p !== void 0);
+  const hasExactSibling = siblingParses.some(
+    (p) => !p.gated && p.kind === "exact"
+  );
+  const hasNumberedSibling = siblingParses.some(
+    (p) => p.number !== void 0
+  );
+  if (parse.number !== void 0 && hasNumberedSibling) return true;
+  if (!parse.gated && parse.kind === "embedded" && hasExactSibling) return true;
+  if (!parse.gated && parse.kind === "volume" && hasNumberedSibling) {
+    return true;
+  }
+  if (parse.sideLetter) {
+    return siblingParses.some((p) => p.sideLetter);
+  }
+  if (parse.kind === "bonus" || parse.kind === "bare") {
+    const numberedCount = siblingParses.filter((p) => p.number !== void 0).length;
+    if (numberedCount >= 2) return true;
+    if (parse.number !== void 0 && hasNumberedSibling) return true;
+  }
+  return false;
+}
+export {
+  CONFIDENCE_RANK,
+  corroborated
+};

package/dist/src/folder-api/album-discs.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Disc assembly and finalization (spec steps 6-7, taglib-ys7m split).
+ *
+ * Each file resolves to a disc number: the common tag value among its
+ * directory's files (missing abstains, disagreement falls back to the
+ * folder), else the folder evidence (own disc parse, ancestor, or flat
+ * filename prefix). Files resolving to the SAME number merge into one
+ * AlbumDisc, with tagDiscNumber recomputed over the merged set.
+ */
+import type { AlbumAccumulator, AlbumGroup } from "./album-types.js";
+/** Assemble discs per album, then sort discs and items (steps 6-7). */
+export declare function assembleDiscs(albums: Map<AlbumAccumulator["key"], AlbumAccumulator>): AlbumGroup[];
+//# sourceMappingURL=album-discs.d.ts.map

package/dist/src/folder-api/album-discs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"album-discs.d.ts","sourceRoot":"","sources":["../../../src/folder-api/album-discs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EACV,gBAAgB,EAEhB,UAAU,EAEX,MAAM,kBAAkB,CAAC;AAE1B,uEAAuE;AACvE,wBAAgB,aAAa,CAC3B,MAAM,EAAE,GAAG,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC,GACrD,UAAU,EAAE,CAoKd"}

package/dist/src/folder-api/album-discs.js

@@ -0,0 +1,122 @@
+import { dirname } from "./folder-disc.js";
+function assembleDiscs(albums) {
+  const groups = [];
+  for (const acc of albums.values()) {
+    const dirTagCommon = /* @__PURE__ */ new Map();
+    const resolvedByFile = /* @__PURE__ */ new Map();
+    for (const item of acc.items) {
+      const dir = dirname(item.path);
+      if (!dirTagCommon.has(dir)) {
+        const tagged = acc.items.filter((i) => dirname(i.path) === dir).map((i) => i.tags.discNumber).filter((d) => d !== void 0 && d > 0);
+        dirTagCommon.set(
+          dir,
+          tagged.length > 0 && tagged.every((d) => d === tagged[0]) ? tagged[0] : void 0
+        );
+      }
+      const evidence = acc.evidence.get(item.path);
+      const tagCommon = dirTagCommon.get(dir);
+      resolvedByFile.set(
+        item.path,
+        tagCommon ?? evidence?.folderDiscNumber
+      );
+    }
+    const discs = /* @__PURE__ */ new Map();
+    const order = [];
+    const noEvidenceItems = [];
+    for (const item of acc.items) {
+      const evidence = acc.evidence.get(item.path);
+      if (evidence === void 0) {
+        noEvidenceItems.push(item);
+        continue;
+      }
+      const resolved = resolvedByFile.get(item.path);
+      const discKey = resolved === void 0 ? `dir:${dirname(item.path)}` : String(resolved);
+      let disc = discs.get(discKey);
+      if (!disc) {
+        disc = {
+          discNumber: resolved,
+          totalDiscs: evidence.total,
+          folderDiscNumber: evidence.folderDiscNumber,
+          folderDiscTitle: evidence.folderDiscTitle,
+          tagDiscNumber: void 0,
+          confidence: evidence.confidence,
+          items: []
+        };
+        discs.set(discKey, disc);
+        order.push(discKey);
+      }
+      disc.items.push(item);
+    }
+    if (noEvidenceItems.length > 0) {
+      const numbered = [...discs.values()].filter((d) => d.folderDiscNumber !== void 0).sort((a, b) => a.folderDiscNumber - b.folderDiscNumber);
+      if (numbered.length > 0) {
+        numbered[0].items.push(...noEvidenceItems);
+      } else {
+        const key = "dir:__none__";
+        let disc = discs.get(key);
+        if (!disc) {
+          disc = {
+            discNumber: void 0,
+            totalDiscs: void 0,
+            folderDiscNumber: void 0,
+            folderDiscTitle: void 0,
+            tagDiscNumber: void 0,
+            confidence: "high",
+            items: []
+          };
+          discs.set(key, disc);
+          order.push(key);
+        }
+        disc.items.push(...noEvidenceItems);
+      }
+    }
+    for (const disc of discs.values()) {
+      const tagged = disc.items.map((i) => i.tags.discNumber).filter((d) => d !== void 0 && d > 0);
+      const common = tagged.length > 0 && tagged.every((d) => d === tagged[0]) ? tagged[0] : void 0;
+      disc.tagDiscNumber = common;
+      disc.discNumber = common ?? disc.folderDiscNumber;
+      for (const item of disc.items) item.discNumber = disc.discNumber;
+    }
+    const albumTaggedTotals = acc.items.map((i) => i.tags.totalDiscs).filter((t) => t !== void 0 && t > 0);
+    const commonTotal = albumTaggedTotals.length > 0 && albumTaggedTotals.every((t) => t === albumTaggedTotals[0]) ? albumTaggedTotals[0] : void 0;
+    const ofN = [...discs.values()].map((d) => d.totalDiscs).find(
+      (t) => t !== void 0
+    );
+    const maxSibling = [...discs.values()].map((d) => d.discNumber).filter((n) => n !== void 0).reduce((a, b) => Math.max(a, b), 0) || void 0;
+    for (const disc of discs.values()) {
+      disc.totalDiscs = commonTotal ?? ofN ?? maxSibling;
+    }
+    const sortedDiscs = [...discs.values()].sort((a, b) => {
+      const an = a.discNumber === void 0 ? -1 : a.discNumber;
+      const bn = b.discNumber === void 0 ? -1 : b.discNumber;
+      if (an !== bn) return an - bn;
+      return (a.folderDiscTitle ?? "").localeCompare(b.folderDiscTitle ?? "");
+    });
+    for (const disc of sortedDiscs) {
+      disc.items.sort((a, b) => {
+        const at = a.tags.track ?? Infinity;
+        const bt = b.tags.track ?? Infinity;
+        if (at !== bt) return at - bt;
+        return a.path.localeCompare(b.path);
+      });
+    }
+    const flags = acc.items.map((i) => i.tags.compilation).filter((c) => c !== void 0);
+    const compilation = flags.length > 0 && flags.every((f) => f === flags[0]) ? flags[0] : void 0;
+    const albumDirs = new Set(acc.items.map((i) => i.albumDir));
+    const directory = albumDirs.size === 1 ? [...albumDirs][0] : acc.directory;
+    groups.push({
+      key: acc.key,
+      albumArtist: acc.albumArtist,
+      album: acc.album,
+      source: acc.source,
+      compilation,
+      directory,
+      discs: sortedDiscs,
+      items: sortedDiscs.flatMap((d) => d.items)
+    });
+  }
+  return groups;
+}
+export {
+  assembleDiscs
+};

package/dist/src/folder-api/album-grouping.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Pure album grouping over a FolderScanResult (2026-08-03 spec).
+ *
+ * Given a folder scan, produce albums with disc subdivisions, using embedded
+ * tags as authority and folder/filename structure as evidence. Synchronous,
+ * runtime-agnostic, no wasm, no I/O: everything the algorithm needs arrives
+ * in the scan result (tags, paths, statuses). taglib-ys7m split: disc
+ * recognition lives in folder-disc.ts, identity in album-identity.ts, disc
+ * assembly in album-discs.ts, types in album-types.ts.
+ *
+ * Model contract (invariants, enforced by tests):
+ *   1. Every ok item appears exactly once across albums[*].items, singles,
+ *      and unmatched; errors is disjoint.
+ *   2. discs >= 1 per album; items >= 1 per disc.
+ *   3. discNumber === tagDiscNumber ?? folderDiscNumber on every disc.
+ *   4. key is stable for identical input.
+ *   5. Every item's albumDir/discNumber match the disc it was assigned to.
+ *   6. compilation is true/false only under full tag agreement, else undefined.
+ *   7. singles holds exactly the ok items whose resolved album has one file.
+ */
+import type { FolderScanResult } from "./types.js";
+import type { AlbumGroupingResult, GroupAlbumsOptions } from "./album-types.js";
+export declare function groupAlbums(result: FolderScanResult, options?: GroupAlbumsOptions): AlbumGroupingResult;
+//# sourceMappingURL=album-grouping.d.ts.map

package/dist/src/folder-api/album-grouping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"album-grouping.d.ts","sourceRoot":"","sources":["../../../src/folder-api/album-grouping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAEV,mBAAmB,EAInB,kBAAkB,EAEnB,MAAM,kBAAkB,CAAC;AA0I1B,wBAAgB,WAAW,CACzB,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,kBAAuB,GAC/B,mBAAmB,CAuCrB"}

package/dist/src/folder-api/album-grouping.js

@@ -0,0 +1,118 @@
+import { basename } from "../utils/path.js";
+import { dirname } from "./folder-disc.js";
+import { baseConfidence, parseDiscName } from "./folder-disc.js";
+import { CONFIDENCE_RANK, corroborated } from "./album-corroborate.js";
+import { buildAlbumIdentity } from "./album-identity.js";
+import { assembleDiscs } from "./album-discs.js";
+function flatPrefix(filename) {
+  const separated = filename.match(/^(\d{1,2})[\s._-](\d{1,2})/);
+  if (separated) return { disc: parseInt(separated[1], 10), form: "separated" };
+  const compact = filename.match(/^(\d)(\d{2})(?:\D|$)/);
+  if (compact) return { disc: parseInt(compact[1], 10), form: "compact" };
+  return void 0;
+}
+function normalizeOk(result) {
+  const okItems = [];
+  const errors = [];
+  for (const item of result.items) {
+    if (item.status === "ok") {
+      okItems.push({ path: item.path, tags: item.tags, metadata: item });
+    } else {
+      errors.push({ path: item.path, error: item.error });
+    }
+  }
+  return { okItems, errors };
+}
+function buildTree(okItems) {
+  const tree = /* @__PURE__ */ new Map();
+  for (const item of okItems) {
+    const dir = dirname(item.path);
+    let node = tree.get(dir);
+    if (!node) {
+      node = { files: [], parent: dirname(dir) };
+      tree.set(dir, node);
+    }
+    node.files.push(item);
+  }
+  return tree;
+}
+function confirmDiscs(tree, minRank) {
+  const confirmedDiscs = /* @__PURE__ */ new Map();
+  for (const [dir, node] of tree) {
+    if (node.files.length === 0) continue;
+    const parse = parseDiscName(basename(dir));
+    if (!parse) continue;
+    const siblings = [...tree.keys()].filter(
+      (d) => d !== dir && dirname(d) === dirname(dir)
+    );
+    const corroboratedBySiblings = corroborated(parse, siblings);
+    let confidence = parse.gated ? "low" : baseConfidence(parse);
+    if (parse.gated) {
+      if (!corroboratedBySiblings) continue;
+    } else if (parse.kind === "bonus" || parse.kind === "bare") {
+      if (!corroboratedBySiblings) continue;
+    } else if (corroboratedBySiblings) {
+      confidence = "high";
+    }
+    if (CONFIDENCE_RANK[confidence] < minRank) continue;
+    confirmedDiscs.set(dir, { parse, confidence });
+  }
+  return confirmedDiscs;
+}
+function flatSubdivisions(tree, confirmedDiscs, useFlatPrefixes) {
+  const flat = /* @__PURE__ */ new Map();
+  if (!useFlatPrefixes) return flat;
+  for (const [dir, node] of tree) {
+    if (node.files.length === 0 || confirmedDiscs.has(dir)) continue;
+    const byFile = /* @__PURE__ */ new Map();
+    const forms = /* @__PURE__ */ new Set();
+    for (const item of node.files) {
+      const prefix = flatPrefix(basename(item.path));
+      if (prefix) {
+        byFile.set(item.path, prefix.disc);
+        forms.add(prefix.form);
+      }
+    }
+    if (byFile.size < 2) continue;
+    const distinct = [...new Set(byFile.values())].sort((a, b) => a - b);
+    const allCompact = forms.size === 1 && forms.has("compact");
+    const plausible = allCompact ? distinct.every((d) => d >= 1 && d <= distinct.length) : true;
+    if (plausible) flat.set(dir, byFile);
+  }
+  return flat;
+}
+function groupAlbums(result, options = {}) {
+  const minRank = CONFIDENCE_RANK[options.minFolderConfidence ?? "low"];
+  const useFlatPrefixes = options.flatDiscPrefixes ?? true;
+  const useFolderFallback = options.folderFallback ?? true;
+  const { okItems, errors } = normalizeOk(result);
+  if (okItems.length === 0) {
+    return { albums: [], singles: [], unmatched: [], errors };
+  }
+  const tree = buildTree(okItems);
+  const confirmedDiscs = confirmDiscs(tree, minRank);
+  const flat = flatSubdivisions(tree, confirmedDiscs, useFlatPrefixes);
+  const { albums, unmatched } = buildAlbumIdentity(
+    okItems,
+    confirmedDiscs,
+    flat,
+    { scanRoot: options.scanRoot, useFolderFallback }
+  );
+  const groups = assembleDiscs(albums);
+  const albumsOut = [];
+  const singles = [];
+  for (const group of groups) {
+    if (group.items.length === 1) {
+      singles.push(group.items[0]);
+    } else {
+      albumsOut.push(group);
+    }
+  }
+  albumsOut.sort(
+    (a, b) => (a.albumArtist ?? "").localeCompare(b.albumArtist ?? "") || (a.album ?? "").localeCompare(b.album ?? "")
+  );
+  return { albums: albumsOut, singles, unmatched, errors };
+}
+export {
+  groupAlbums
+};

package/dist/src/folder-api/album-identity.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Album identity resolution (spec step 5, taglib-ys7m split).
+ *
+ * Tags are authority: key on normalized (albumArtist, album), folding generic
+ * album artists into an album-only key. Untagged files fall back to a folder
+ * walk, and folder-derived groups merge into matching tag-keyed groups.
+ */
+import type { AudioFileMetadata } from "./types.js";
+import type { AlbumAccumulator, AlbumGroupKey, DiscConfidence, DiscParse, OkItem } from "./album-types.js";
+type ConfirmedDiscs = Map<string, {
+    parse: DiscParse;
+    confidence: DiscConfidence;
+}>;
+export interface AlbumIdentity {
+    albums: Map<AlbumGroupKey, AlbumAccumulator>;
+    unmatched: AudioFileMetadata[];
+}
+/**
+ * Build the album map (spec step 5): tag-keyed groups first, folder fallback
+ * for untagged files, then mixed-folder merges into tag-keyed groups.
+ */
+export declare function buildAlbumIdentity(okItems: OkItem[], confirmedDiscs: ConfirmedDiscs, flatSubdivisions: Map<string, Map<string, number>>, options: {
+    scanRoot?: string | undefined;
+    useFolderFallback: boolean;
+}): AlbumIdentity;
+export {};
+//# sourceMappingURL=album-identity.d.ts.map

package/dist/src/folder-api/album-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"album-identity.d.ts","sourceRoot":"","sources":["../../../src/folder-api/album-identity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,SAAS,EAET,MAAM,EACP,MAAM,kBAAkB,CAAC;AAY1B,KAAK,cAAc,GAAG,GAAG,CACvB,MAAM,EACN;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,cAAc,CAAA;CAAE,CACjD,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,GAAG,CAAC,aAAa,EAAE,gBAAgB,CAAC,CAAC;IAC7C,SAAS,EAAE,iBAAiB,EAAE,CAAC;CAChC;AA6ED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EAAE,EACjB,cAAc,EAAE,cAAc,EAC9B,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAClD,OAAO,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,iBAAiB,EAAE,OAAO,CAAA;CAAE,GACrE,aAAa,CAmGf"}

package/dist/src/folder-api/album-identity.js

@@ -0,0 +1,151 @@
+import { basename } from "../utils/path.js";
+import { dirname } from "./folder-disc.js";
+function normalizeKey(s) {
+  return s.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function isGenericAlbumArtist(albumArtist) {
+  if (!albumArtist || albumArtist.trim() === "") return true;
+  const n = normalizeKey(albumArtist);
+  return n === "various artists" || n === "va";
+}
+function evidenceFor(item, confirmedDiscs, flatSubdivisions) {
+  const dir = dirname(item.path);
+  const own = confirmedDiscs.get(dir);
+  if (own) {
+    return {
+      folderDiscNumber: own.parse.number,
+      total: own.parse.total,
+      folderDiscTitle: own.parse.discTitle,
+      confidence: own.confidence,
+      albumDir: dirname(dir)
+    };
+  }
+  let cursor = dirname(dir);
+  while (cursor !== void 0) {
+    const entry = confirmedDiscs.get(cursor);
+    if (entry) {
+      return {
+        folderDiscNumber: entry.parse.number,
+        total: entry.parse.total,
+        folderDiscTitle: entry.parse.discTitle,
+        confidence: entry.confidence,
+        albumDir: dirname(cursor)
+      };
+    }
+    const parent = dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  const flat = flatSubdivisions.get(dir)?.get(item.path);
+  if (flat !== void 0) {
+    return {
+      folderDiscNumber: flat,
+      total: void 0,
+      folderDiscTitle: void 0,
+      confidence: "medium",
+      albumDir: dir
+    };
+  }
+  return void 0;
+}
+function folderIdentity(dir, confirmedDiscs, scanRoot) {
+  const own = confirmedDiscs.get(dir);
+  if (!own) {
+    const title2 = basename(dir);
+    return title2 ? { title: title2, titleSource: dir } : void 0;
+  }
+  if (own.parse.title !== void 0) {
+    return { title: own.parse.title, titleSource: dirname(dir) };
+  }
+  const source = dirname(dir);
+  if (source === scanRoot || source === dir) return void 0;
+  const title = basename(source);
+  return title ? { title, titleSource: source } : void 0;
+}
+function buildAlbumIdentity(okItems, confirmedDiscs, flatSubdivisions, options) {
+  const albums = /* @__PURE__ */ new Map();
+  const unmatched = [];
+  for (const item of okItems) {
+    const dir = dirname(item.path);
+    const albumTag = item.tags.album?.[0]?.trim();
+    const albumArtistTag = item.tags.albumArtist?.[0]?.trim();
+    if (albumTag) {
+      const artistPart = isGenericAlbumArtist(albumArtistTag) ? "" : normalizeKey(albumArtistTag ?? "");
+      const key2 = `${artistPart}::${normalizeKey(albumTag)}`;
+      let acc2 = albums.get(key2);
+      if (!acc2) {
+        acc2 = {
+          key: key2,
+          album: albumTag,
+          albumArtist: isGenericAlbumArtist(albumArtistTag) ? void 0 : albumArtistTag,
+          source: "tags",
+          directory: void 0,
+          items: [],
+          evidence: /* @__PURE__ */ new Map()
+        };
+        albums.set(key2, acc2);
+      }
+      const evidence2 = evidenceFor(item, confirmedDiscs, flatSubdivisions);
+      acc2.evidence.set(item.path, evidence2);
+      acc2.items.push({
+        ...item.metadata,
+        albumDir: evidence2?.albumDir ?? dir,
+        discNumber: evidence2?.folderDiscNumber
+      });
+      continue;
+    }
+    if (!options.useFolderFallback) {
+      unmatched.push(item.metadata);
+      continue;
+    }
+    const identity = folderIdentity(dir, confirmedDiscs, options.scanRoot);
+    if (!identity) {
+      unmatched.push(item.metadata);
+      continue;
+    }
+    const key = `${identity.titleSource}::${normalizeKey(identity.title)}`;
+    let acc = albums.get(key);
+    if (!acc) {
+      acc = {
+        key,
+        album: identity.title,
+        albumArtist: void 0,
+        source: "folder",
+        directory: identity.titleSource,
+        items: [],
+        evidence: /* @__PURE__ */ new Map()
+      };
+      albums.set(key, acc);
+    }
+    const evidence = evidenceFor(item, confirmedDiscs, flatSubdivisions);
+    acc.evidence.set(item.path, evidence);
+    acc.items.push({
+      ...item.metadata,
+      albumDir: evidence?.albumDir ?? dir,
+      discNumber: evidence?.folderDiscNumber
+    });
+  }
+  for (const [key, acc] of [...albums]) {
+    if (acc.source === "tags") continue;
+    for (const other of albums.values()) {
+      if (other === acc || other.source !== "tags") continue;
+      if (normalizeKey(other.album) !== normalizeKey(acc.album)) continue;
+      const albumDir = acc.directory;
+      const sharesChain = albumDir !== void 0 && other.items.some((o) => {
+        const od = dirname(o.path);
+        return od === albumDir || od.startsWith(albumDir + "/");
+      });
+      if (!sharesChain) continue;
+      for (const item of acc.items) {
+        other.items.push(item);
+        other.evidence.set(item.path, acc.evidence.get(item.path));
+      }
+      albums.delete(key);
+      break;
+    }
+  }
+  return { albums, unmatched };
+}
+export {
+  buildAlbumIdentity
+};

package/dist/src/folder-api/{group-albums.d.ts → album-types.d.ts}

@@ -1,22 +1,9 @@
 /**
- * @fileoverview Pure album grouping over a FolderScanResult (2026-08-03 spec).
- *
- * Given a folder scan, produce albums with disc subdivisions, using embedded
- * tags as authority and folder/filename structure as evidence. Synchronous,
- * runtime-agnostic, no wasm, no I/O: everything the algorithm needs arrives
- * in the scan result (tags, paths, statuses).
- *
- * Model contract (invariants, enforced by tests):
- *   1. Every ok item appears exactly once across albums[*].items, singles,
- *      and unmatched; errors is disjoint.
- *   2. discs >= 1 per album; items >= 1 per disc.
- *   3. discNumber === tagDiscNumber ?? folderDiscNumber on every disc.
- *   4. key is stable for identical input.
- *   5. Every item's albumDir/discNumber match the disc it was assigned to.
- *   6. compilation is true/false only under full tag agreement, else undefined.
- *   7. singles holds exactly the ok items whose resolved album has one file.
+ * Types for pure album grouping (taglib-ys7m split). No runtime imports:
+ * every module in the disc-folder graph must stay Wasm-free (taglib-cd7b).
  */
-import type { AudioFileMetadata, FolderScanResult } from "./types.js";
+import type { AudioFileMetadata } from "./types.js";
+/** Opaque, stable album identity. */
 export type AlbumGroupKey = string & {
     __brand: "AlbumGroupKey";
 };
@@ -111,12 +98,54 @@ export interface DiscFolderInfo {
      * "high" inside groupAlbums. Gated names stay "low" even corroborated. */
     confidence: DiscConfidence;
 }
-/**
- * Recognize a directory name as a disc folder. Standalone — it only
- * classifies the name; it does not resolve the folder to its parent (use
- * the album result's per-file `albumDir` for that). Returns undefined for
- * non-disc names. Plain "Bonus" and "Extras" are never discs by name.
- */
-export declare function discFolderInfo(name: string): DiscFolderInfo | undefined;
-export declare function groupAlbums(result: FolderScanResult, options?: GroupAlbumsOptions): AlbumGroupingResult;
-//# sourceMappingURL=group-albums.d.ts.map
+export type DiscKind = "exact" | "embedded" | "volume" | "bonus" | "bare";
+export interface DiscParse {
+    kind: DiscKind;
+    /** Disc number when the name carries one. */
+    number: number | undefined;
+    /** "of N" total from "CD 1 of 2". */
+    total: number | undefined;
+    /** Title text before an embedded marker ("Album (Disc 1)" -> "Album"). */
+    title: string | undefined;
+    /** Trailing text after the number ("Bonus Tracks" from "Disc 2 (Bonus Tracks)"). */
+    discTitle: string | undefined;
+    /** True for title-word markers (tape/vinyl/cassette/lp/record) and
+     * single-letter number tokens: corroboration required, low confidence. */
+    gated: boolean;
+    /** True when the number token was a single letter ("CD D"): a side label,
+     * not a number — corroboration required (2026-08-04 feedback). */
+    sideLetter: boolean;
+    /** True when the number token was arabic digits ("CD1" vs "Disc One"). */
+    digit: boolean;
+}
+export interface OkItem {
+    path: string;
+    tags: AudioFileMetadata["tags"];
+    metadata: AudioFileMetadata;
+}
+export interface DirNode {
+    files: OkItem[];
+    parent: string | undefined;
+}
+/** Per-file disc evidence, resolved before tag merging. */
+export interface FileDiscEvidence {
+    /** Folder-derived disc number (own/ancestor parse or flat prefix). */
+    folderDiscNumber: number | undefined;
+    /** "of N" total from the folder name. */
+    total: number | undefined;
+    folderDiscTitle: string | undefined;
+    confidence: DiscConfidence;
+    /** The album directory attributed to this file. */
+    albumDir: string;
+}
+/** Accumulator for one album during identity and disc assembly. */
+export interface AlbumAccumulator {
+    key: AlbumGroupKey;
+    album: string;
+    albumArtist: string | undefined;
+    source: "tags" | "folder";
+    directory: string | undefined;
+    items: AlbumGroupItem[];
+    evidence: Map<string, FileDiscEvidence | undefined>;
+}
+//# sourceMappingURL=album-types.d.ts.map

package/dist/src/folder-api/album-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"album-types.d.ts","sourceRoot":"","sources":["../../../src/folder-api/album-types.ts"],"names":[],"mappings":"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"}