funoteka 0.1.0

package/dist/artist/credit.js

@@ -0,0 +1,95 @@
+/**
+ * An artist credit, read as a list.
+ *
+ * A collaboration is not one artist with punctuation in the name, and the
+ * collection says so constantly: `Cock E.S.P. + Thirdorgan`, `Merzbow & Cock
+ * E.S.P.`, `Aube / Cock E.S.P.` spread across 20 of the 24 Cock E.S.P folders.
+ * Reading them as a single name loses the collaboration; reading them as a list
+ * and throwing the string away loses the album when the reading is wrong.
+ *
+ * So neither is lost. Each entry carries the exact phrase that joined it to the
+ * entry before, which means the list rebuilds into the original string
+ * character for character. A split is a *reading* of a credit rather than a
+ * replacement for it, and an operator who disagrees with one can see exactly
+ * what was done and undo it.
+ *
+ * That is what makes "catch maximally" safe. And it needs to be, because two of
+ * these rules are provably wrong and will stay wrong:
+ *
+ *   - `Smell & Quim` is one artist. The rules split it. Nothing available to a
+ *     deterministic core can tell it apart from `Merzbow & Cock E.S.P.`, and
+ *     §2 of the design spec puts machine inference outside the core — so the
+ *     honest answer is to split it and be seen doing so.
+ *   - A **word** token matched anywhere rather than as a whole word is not a
+ *     near-miss, it is a disaster: `Extreme Noise Terror` becomes `E` +
+ *     `treme Noise Terror` the moment `x` is a bare token, and `The Nihilist
+ *     Spasm Band` becomes `The Nihilist Spasm B` + `and`. Both were measured on
+ *     the real sample before this rule was written.
+ */
+/**
+ * Symbols join wherever they appear, with whatever whitespace surrounds them.
+ *
+ * Unambiguous as characters: nobody spells an artist with a `;`. `&` is the
+ * risky one (`Smell & Quim`) and there is no way around that except to keep the
+ * original string on the row.
+ */
+const SYMBOLS = '&+/;×';
+/**
+ * Words join only when they stand alone — whitespace on both sides.
+ *
+ * The rule the measurement bought. `x` and `and` are far too common *inside*
+ * names to match as bare substrings, and `x` counts only in lower case:
+ * `Malcolm X` is a name, `Malcolm X and Xzibit` is a collaboration.
+ */
+const WORDS = ['featuring', 'feat\\.', 'ft\\.', 'vs\\.?', 'and', 'with', 'meets', 'x'];
+/**
+ * One pattern, two alternatives: a symbol with the whitespace around it, or a
+ * whole word with the whitespace that isolates it.
+ *
+ * The whitespace is captured *into* the match deliberately — it belongs to the
+ * phrase that joined the two artists, and dropping it is how a credit stops
+ * rebuilding into itself. Both branches therefore take the *run*, `\s+` and
+ * `\s*`, and not a single character: `A  and  B` has two spaces either side of
+ * the word, and a pattern that took one of each rebuilt it as `A and B` — which
+ * is what the module's promise of a character-for-character round trip turned
+ * out not to cover (task:2756).
+ */
+const JOINER = new RegExp(`\\s*([${SYMBOLS}])\\s*|\\s+(?:${WORDS.join('|')})\\s+`, 'g');
+/**
+ * Read a credit string as a list of artists and the phrases between them.
+ *
+ * Never throws and never loses its input: for every string with content on both
+ * sides of a joiner, `splitCredit(raw).map((e) => e.joinPhrase + e.name)
+ * .join('')` returns `raw`. Outer whitespace is the one exception, and
+ * deliberately so — a name with a leading space sorts wrongly forever.
+ */
+export function splitCredit(raw) {
+    const text = raw.trim();
+    const entries = [];
+    let at = 0;
+    // The phrase leading to the entry about to be pushed; empty before the first.
+    let phrase = '';
+    JOINER.lastIndex = 0;
+    for (let match = JOINER.exec(text); match !== null; match = JOINER.exec(text)) {
+        const start = match.index;
+        const after = start + match[0].length;
+        const name = text.slice(at, start).trim();
+        // A joiner with nothing before it (`& x`) or nothing after it (`a +`) is
+        // not joining two artists — it is part of one name. Splitting there would
+        // produce an empty name and break the round-trip on precisely the
+        // malformed input that most needs to survive intact.
+        if (name === '' || text.slice(after).trim() === '')
+            continue;
+        entries.push({ name, joinPhrase: phrase });
+        phrase = match[0];
+        at = after;
+    }
+    if (entries.length === 0) {
+        // Either the whole thing is one name, or it is empty.
+        return text === '' ? [] : [{ name: text, joinPhrase: '' }];
+    }
+    const tail = text.slice(at).trim();
+    if (tail !== '')
+        entries.push({ name: tail, joinPhrase: phrase });
+    return entries;
+}

package/dist/artist/folder.js

@@ -0,0 +1,65 @@
+import { artistName } from "./name.js";
+import { rootBasenameOf } from "../util/names.js";
+/**
+ * The artist folder above `albumRelPath`, or null when there is none.
+ *
+ * Null is the ordinary answer, not a failure: most albums in a loose collection
+ * have no artist folder at all, and a null folder is simply not evidence. The
+ * caller must not read it as "a different artist" — see `applyArtists`, where a
+ * key splits only when two or more *real* folders disagree.
+ */
+export function artistFolderOf(input) {
+    const { albumRelPath, rootPath, key } = input;
+    // An empty key means "not a name" (see `artistName`), and it would match the
+    // first folder whose own name is also not a name — `The`, say — inventing an
+    // artist folder out of nothing. The caller already refuses empty keys; this is
+    // the guard that keeps the refusal from having to be repeated.
+    if (key === '')
+        return null;
+    // An album that *is* the root has no folder above it. The root is its own
+    // folder here, and a record's folder is never its artist's.
+    if (albumRelPath === '')
+        return null;
+    // The root first: it is the outermost folder there is, and `Downloads\Кино`
+    // is a real artist folder (wiki:3519). Its name has to be read
+    // separator-agnostically — on Windows the stored path is backslashed.
+    const rootName = rootBasenameOf(rootPath);
+    if (artistName(rootName).key === key) {
+        return { id: `${rootPath}:`, rootPath, relPath: '' };
+    }
+    const parts = albumRelPath.split('/');
+    // Shallowest first. Bounding at `i < parts.length` is what keeps the album's
+    // own folder — the last segment — out of the running: the deepest candidate
+    // is its parent.
+    for (let i = 1; i < parts.length; i += 1) {
+        const name = parts[i - 1] ?? '';
+        if (artistName(name).key === key) {
+            const relPath = parts.slice(0, i).join('/');
+            return { id: `${rootPath}:${relPath}`, rootPath, relPath };
+        }
+    }
+    return null;
+}
+/**
+ * The merge key for the `index`-th artist folder of one name.
+ *
+ * The first folder keeps the bare key — for the overwhelming majority of
+ * artists there is only one folder anyway, and `nirvana` is a better key to read
+ * in a dump than `nirvana#1`. The rest are numbered in the order the caller
+ * sorted them, so a folder added ahead of an existing one takes the bare key and
+ * the one behind it moves to the next number. Nothing corrupts when that
+ * happens — albums and credits are re-resolved through the new keys every run —
+ * but a reader who knew a row as `nirvana#2` last time may find it elsewhere.
+ *
+ * A suffixed key can never collide with a bare one, though not for the obvious
+ * reason. `#` *does* survive into a key: `artistName` falls back to the raw
+ * lowercased name for a name with no letter or digit in it, so an artist called
+ * `#` keys to `#`. The invariant is narrower and holds regardless — a key
+ * containing `#` has no letter or digit anywhere in it (that is the only route
+ * to the fallback), while a suffixed key always ends in one. A name reading
+ * `nirvana#2` folds to `nirvana 2`, and `##2` folds to `2`, so neither can
+ * produce a suffixed key. The two sets are disjoint by construction.
+ */
+export function qualifiedKey(key, index) {
+    return index === 0 ? key : `${key}#${index + 1}`;
+}

package/dist/artist/name.js

@@ -0,0 +1,205 @@
+/**
+ * One artist, however many ways the collection spells them.
+ *
+ * `The Cure`, `Cure, The` and `cure` are one artist, and a library that lists
+ * them three times has failed at the only thing it promised. So names are
+ * reduced to a key, and the key is what merges.
+ *
+ * But merging is a claim, and some claims are guesses. The module therefore
+ * answers at *two* levels, and the gap between them is the point:
+ *
+ *   - `folded` normalises only what is obviously the same record — case,
+ *     punctuation, whitespace, the definite article, and the accents a tag
+ *     loses on its way through a ripper.
+ *   - `key` goes further and also drops a disambiguator, because `Nirvana (UK)`
+ *     and `Nirvana` would otherwise never merge.
+ *
+ * Two names that fold to the same thing are the same artist, plainly. Two that
+ * fold *differently* and still share a key were merged by discarding something
+ * a human wrote on purpose — and that is exactly the merge worth flagging
+ * rather than performing in silence (requirements:39 §6).
+ */
+/**
+ * `’` for `'` and the typographic dashes for `-`.
+ *
+ * Rippers write all of these, and a key that treats `N’Ko` and `N'Ko` as two
+ * artists is not doing its job. Whitespace is collapsed here rather than at
+ * each use, since every path below assumes single spaces.
+ */
+function tidy(raw) {
+    return raw
+        .replace(/[‘’ʼ]/g, "'")
+        .replace(/[“”]/g, '"')
+        .replace(/[–—]/g, '-')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+const LEADING_ARTICLE = /^the\s+/i;
+const TRAILING_ARTICLE = /,\s*the$/i;
+/** A name that is nothing but the article — not an artist, and not a key. */
+const ONLY_ARTICLE = /^the$/i;
+/**
+ * Remove the definite article, from whichever end a ripper put it.
+ *
+ * Only `the`: it is the one article that gets inverted in practice, and
+ * stripping `a`/`an` would merge `A Perfect Circle` with a hypothetical
+ * `Perfect Circle` on no evidence at all.
+ */
+function dropArticle(name) {
+    if (ONLY_ARTICLE.test(name))
+        return '';
+    if (LEADING_ARTICLE.test(name))
+        return name.replace(LEADING_ARTICLE, '');
+    if (TRAILING_ARTICLE.test(name))
+        return name.replace(TRAILING_ARTICLE, '');
+    return name;
+}
+/**
+ * Letters, digits and combining marks survive; everything else becomes a
+ * separator.
+ *
+ * Unicode-aware on purpose — `Кино` has to come out the other side intact, and
+ * `\w` would not manage it. `\p{M}` survives *here* so that a mark stays part
+ * of its letter instead of becoming a separator: `foldName` below is where it
+ * is dropped, deliberately, and a mark turned into a space first would leave
+ * `bj rk` behind and merge nothing.
+ */
+function stripPunctuation(name) {
+    return name.replace(/[^\p{L}\p{N}\p{M}]+/gu, ' ').trim();
+}
+/**
+ * A dot inside a word belongs to the word, not between two of them.
+ *
+ * `Cock E.S.P.` and `Cock Esp` are one act, and this collection holds both
+ * spellings — twelve albums under the first, two under the second, and no flag
+ * between them, because the fold turned the acronym's dots into spaces and left
+ * `cock e s p` standing beside `cock esp`. An initialism is written with its
+ * dots in some places and without them in others; dropping them is the same
+ * class of normalisation as case, and it is what makes the two one key.
+ *
+ * Only a dot with something other than a space after it. `Dr. Dre` and
+ * `St. Vincent` keep the space their dot was standing in, and a dot at the end
+ * of a name is turned into a separator by the fold below either way.
+ */
+function closeAcronymDots(name) {
+    return name.replace(/\.(?=\S)/g, '');
+}
+/**
+ * The key a name folds to, with its accents gone.
+ *
+ * `Röyksopp` and `Royksopp` are one artist, and so are `Sigur Rós` and `Sigur
+ * Ros` — measured over the live collection, where those two pairs are the only
+ * names this merges and nothing else in it moves.
+ *
+ * The claim is about the collection rather than about Unicode: an unaccented
+ * spelling is nearly always a tag that lost its accent, not a name written
+ * differently on purpose. Nobody types `Royksopp` deliberately, and the
+ * opposite case — a collector who meant the plain spelling and got the accented
+ * one — costs a letter rather than a record.
+ *
+ * Decomposing before the marks come off is what keeps the two writings of one
+ * letter together: `ö` is a single code point in a tag and `o` plus U+0308 in a
+ * tree ripped on macOS, and both have to fold the same way. It is also what
+ * lets `Bjork`, carrying no mark at all, join them.
+ *
+ * What it costs: a mark that carries meaning goes with the rest. Cyrillic loses
+ * `й` to `и` and `ё` to `е`, so two names differing only there — and they are
+ * two names — would fold together. Nothing in this collection does, and the
+ * alternative is a library that lists `Röyksopp` twice.
+ */
+function foldName(name) {
+    const folded = stripPunctuation(closeAcronymDots(dropArticle(name).toLowerCase()));
+    return folded.normalize('NFD').replace(/\p{M}/gu, '');
+}
+/** `(UK)`, `[US]` — a human marking which of several same-named artists this is. */
+const BRACKETED = /[([][^)\]]*[)\]]/g;
+function stripDisambiguators(name) {
+    const found = [];
+    // Whitespace is collapsed, not merely left behind. Removing `(UK)` from
+    // `Cure, The (UK)` otherwise leaves a trailing space, and the article
+    // pattern — anchored at the end — stops matching, so the name keys as
+    // `cure the` while `Cure, The` keys as `cure`. One artist, two rows, which is
+    // the whole failure this module exists to prevent.
+    const cleaned = name
+        .replace(BRACKETED, (match) => {
+        const inner = match.slice(1, -1).trim();
+        if (inner !== '')
+            found.push(inner);
+        return ' ';
+    })
+        .replace(/\s+/g, ' ')
+        .trim();
+    // A name written *entirely* in brackets is the name, and the bracket has
+    // nothing left to qualify. `[LINKIN PARK]` is how a file states the artist —
+    // not a qualifier of one — and stripping it anyway left an empty name, which
+    // the key reads as "not a name". So one act the collection writes two ways
+    // became two identities, one of them nameless: thirteen records of
+    // `Linkin Park Japan CD` state `[LINKIN PARK]` on some tracks and
+    // `Linkin Park` on the rest, the stage found no name every track states, and
+    // they carried no album artist at all (task:2837).
+    if (cleaned === '' && found.length > 0)
+        return { name: found[0], stripped: null };
+    return { name: cleaned, stripped: found.length === 0 ? null : found.join('; ') };
+}
+/**
+ * Sort key: `The Cure` files under C.
+ *
+ * A name already written inverted (`Cure, The`) is left as it is — inverting
+ * it again would produce `The, Cure, The`.
+ */
+function sortKeyOf(name) {
+    if (!LEADING_ARTICLE.test(name))
+        return name;
+    return `${name.replace(LEADING_ARTICLE, '')}, The`;
+}
+/** Anything that could be a word. `The` has it; `!!!` does not. */
+function hasWordChar(name) {
+    return /[\p{L}\p{N}]/u.test(name);
+}
+export function artistName(raw) {
+    const name = tidy(raw);
+    const disambiguated = stripDisambiguators(name);
+    // An empty key means "not a name", and folding alone cannot tell the two
+    // cases apart: `The` folds to nothing because it is not a name, while `!!!`
+    // and `∆` fold to nothing because they are names written in symbols. Both
+    // are real artists, and giving them one shared empty key would merge every
+    // symbol-only act into a single nonexistent row.
+    const foldedDisambiguated = foldName(disambiguated.name);
+    const key = foldedDisambiguated !== '' || hasWordChar(name) ? foldedDisambiguated : name.toLowerCase();
+    return {
+        name,
+        folded: foldName(name),
+        key,
+        sortKey: sortKeyOf(name),
+        stripped: disambiguated.stripped,
+    };
+}
+/**
+ * The artist a folder's name belongs to, or null.
+ *
+ * The rule `shelf-name.ts` spells out, read the other way round. There a shelf's
+ * name is the artist's name *plus* something and the something is subtracted to
+ * name the record; here the same fact gathers the artist — a folder whose name
+ * opens with an artist's key is that artist's.
+ *
+ * The longest key wins, not the first: `Röyksopp Discography` opens with
+ * `Röyksopp`, and a shorter artist called `Röy` would otherwise take it.
+ *
+ * A separator has to follow, or `S` claims `Slipknot`. The same guard
+ * `shelf-name.ts` puts on the subtraction, for the same reason and from the
+ * same measurement.
+ */
+export function artistOwning(folderName, keys) {
+    const folderKey = artistName(folderName).key;
+    if (folderKey === '')
+        return null;
+    let best = null;
+    for (const key of keys) {
+        if (key === '')
+            continue;
+        const fits = folderKey === key || folderKey.startsWith(`${key} `);
+        if (fits && (best === null || key.length > best.length))
+            best = key;
+    }
+    return best;
+}

package/dist/artist/nfo.js

@@ -0,0 +1,101 @@
+/**
+ * What an artist's `.nfo` says about them.
+ *
+ * The collection keeps a note about an artist in the folder named for them —
+ * `The Cure/artist.nfo`, written by Jellyfin — and it is the only offline
+ * source of a biography this project has. The scan records `.nfo` files as
+ * files and never parses them: their text is not in the meta layer, so it is
+ * read out of the document at the point a client asks, which is what makes this
+ * a reader rather than a column.
+ *
+ * It is not an XML parser and does not pretend to be. The documents this
+ * collection holds are the ones Jellyfin writes, and this reads the two things
+ * about them that matter: a tag's text, and the five entities XML defines. A
+ * document that needed more than that would need a parser, and adding one
+ * before there is a document to justify it would be guessing at the shape of
+ * the problem.
+ */
+/** The text a document holds between one tag's opening and its closing. */
+function elementText(xml, tag) {
+    const open = `<${tag}>`;
+    const close = `</${tag}>`;
+    const from = xml.indexOf(open);
+    if (from === -1)
+        return null;
+    const to = xml.indexOf(close, from + open.length);
+    if (to === -1)
+        return null;
+    return xml.slice(from + open.length, to);
+}
+/** The last code point Unicode has, which is also the last XML allows. */
+const LAST_CODE_POINT = 0x10ffff;
+/** The surrogate range: a pair's halves, never a character on its own. */
+const SURROGATES = { from: 0xd800, to: 0xdfff };
+/**
+ * Whether a number names a character XML has — which is not every number
+ * Unicode does.
+ *
+ * `Char` is what the format permits in a document, and it excludes the
+ * surrogates (each is half of a pair) and everything past the last plane.
+ * `String.fromCodePoint` refuses only the second of those, so the first is
+ * checked here rather than left to it: a lone surrogate that reached the XML
+ * envelope would be a document no reader could parse.
+ */
+function isXmlChar(point) {
+    if (!Number.isInteger(point) || point < 0 || point > LAST_CODE_POINT)
+        return false;
+    return point < SURROGATES.from || point > SURROGATES.to;
+}
+/**
+ * The text with its entities resolved — `Siouxsie &amp; the Banshees` read as
+ * a client should show it.
+ *
+ * Named and numeric alike, because a document may spell an ampersand either
+ * way and both mean the same thing to a reader. Anything that is not an entity
+ * this reader can resolve is left exactly as it was written, and that includes
+ * a numeric one naming no XML character: `&#1114112;` is not a character, so
+ * there is nothing to resolve it to, and a bare `&` is not this reader's to
+ * fix. Leaving the text is also what keeps this total — a note read off disk
+ * is somebody else's file, and a malformed one must not be able to throw out
+ * of a pure reader that answers with text.
+ */
+function unescapeXml(text) {
+    return text.replace(/&(?:#(\d+)|#x([0-9a-fA-F]+)|(amp|lt|gt|quot|apos));/g, (whole, dec, hex, named) => {
+        if (dec !== undefined || hex !== undefined) {
+            const point = dec !== undefined ? Number(dec) : parseInt(hex ?? '', 16);
+            return isXmlChar(point) ? String.fromCodePoint(point) : whole;
+        }
+        switch (named) {
+            case 'amp':
+                return '&';
+            case 'lt':
+                return '<';
+            case 'gt':
+                return '>';
+            case 'quot':
+                return '"';
+            case 'apos':
+                return "'";
+            default:
+                return whole;
+        }
+    });
+}
+/**
+ * The artist's biography, or nothing when the document does not hold one.
+ *
+ * A document with no `<biography>` has no biography — an `<outline>` beside it
+ * is a summary and is not the same claim, so it is not offered in its place.
+ * Whitespace around the text is the document's layout rather than its content
+ * and goes; the lines inside it are the author's and stay.
+ *
+ * Empty is nothing. A caller that has to check for an empty string before
+ * showing it is a caller doing this reader's job.
+ */
+export function biographyOf(xml) {
+    const raw = elementText(xml, 'biography');
+    if (raw === null)
+        return null;
+    const text = unescapeXml(raw).trim();
+    return text === '' ? null : text;
+}

package/dist/artist/translit.js

@@ -0,0 +1,79 @@
+/**
+ * The Latin spellings a Cyrillic artist key may be written as.
+ *
+ * This table never merges anything. It exists so that two rows which are one
+ * name in two alphabets can be *named* to a reader (task:2675); the decision
+ * that they are the same artist is left to a human or to v1.5's MBID, because
+ * nothing on disk states it.
+ *
+ * The reason it cannot be a merge rule is the reason it is a list of schemes
+ * rather than one table. A `name_key` folds spellings that differ only in
+ * decoration — case, articles, punctuation — and folding is idempotent and
+ * reversible enough to trust. Cyrillic-to-Latin is not a fold: it is a mapping
+ * between scripts, it is many-to-many in both directions (`Кино` → `Kino`,
+ * `Kino` → `Кино` or `Кіно`), and the schemes disagree with one another
+ * (ГОСТ / BGN / ISO render `х` as `kh` or `h`, `я` as `ya` or `a`). A rule that
+ * asserted the identity would be choosing a scheme, and a wrong choice is
+ * silent: two bands that merely sound alike become one row, and no consumer
+ * downstream can see that it happened. Reporting a wrong pair costs a line.
+ */
+/**
+ * What rippers, Discogs and MusicBrainz actually write — the BGN/PCGN side of
+ * each disagreement. `х` is `kh`, `я` is `ya`.
+ */
+const PRACTICAL = {
+    а: 'a', б: 'b', в: 'v', г: 'g', д: 'd', е: 'e', ё: 'e', ж: 'zh', з: 'z',
+    и: 'i', й: 'y', к: 'k', л: 'l', м: 'm', н: 'n', о: 'o', п: 'p', р: 'r',
+    с: 's', т: 't', у: 'u', ф: 'f', х: 'kh', ц: 'ts', ч: 'ch', ш: 'sh',
+    щ: 'shch', ъ: '', ы: 'y', ь: '', э: 'e', ю: 'yu', я: 'ya',
+    і: 'i', ї: 'i', є: 'e', ґ: 'g',
+};
+/**
+ * The simplified side: one letter per letter, as an ASCII keyboard or a
+ * country-agnostic database tends to write it. It differs from `PRACTICAL` on
+ * `й` (`i`), `х` (`h`), `ц` (`c`), `щ` (`sh`), `ю` (`u`) and `я` (`a`).
+ */
+const SIMPLIFIED = {
+    ...PRACTICAL,
+    й: 'i', х: 'h', ц: 'c', щ: 'sh', ю: 'u', я: 'a',
+};
+const SCHEMES = [PRACTICAL, SIMPLIFIED];
+/**
+ * The property escape rather than a hand-written range: `Ѐ-ӿ` is the main
+ * block only, and would read the Cyrillic Supplement (U+0500–U+052F) as a name
+ * that is already Latin. `name.ts` asks the same question the same way.
+ */
+const CYRILLIC = /\p{Script=Cyrillic}/u;
+/** Whether a key holds a Cyrillic letter at all. */
+export function hasCyrillic(key) {
+    return CYRILLIC.test(key);
+}
+/**
+ * Every Latin key the schemes would write this one as, deduplicated. Empty when
+ * the key holds no Cyrillic letter — a Latin key is not a candidate for being
+ * the Latin side of a pair.
+ *
+ * The key is lowercased on entry: the schemes are written for lowercase
+ * Cyrillic, and a caller holding a display name rather than a key would
+ * otherwise get an answer that is still half Cyrillic (`Ха` → `Хa`).
+ *
+ * Characters no scheme maps — spaces, digits, the `#2` a split homonym carries
+ * — pass through unchanged, so `кино` and `кино#2` stay distinguishable. What a
+ * caller does with a qualified key is its own decision: the index is the row's
+ * position within *its own* key group, so `кино#2` and `kino#2` are second
+ * folders of two independently sorted groups and nothing makes them the same
+ * folder. Pairing them would assert a correspondence that does not exist.
+ */
+export function latinSpellingsOf(key) {
+    const lowered = key.toLowerCase();
+    if (!hasCyrillic(lowered))
+        return [];
+    const spellings = new Set();
+    for (const scheme of SCHEMES) {
+        let latin = '';
+        for (const letter of lowered)
+            latin += scheme[letter] ?? letter;
+        spellings.add(latin);
+    }
+    return [...spellings];
+}

package/dist/bookmark/store.js

@@ -0,0 +1,54 @@
+/**
+ * Every bookmark, most recently moved first.
+ *
+ * Ordered by when it was last touched rather than by the song: a list of where
+ * somebody stopped is a list of the things they are in the middle of, and the
+ * one they are furthest into is the one they last listened to.
+ */
+export function bookmarks(db) {
+    return db
+        .prepare(`SELECT track_id    AS trackId,
+              position_ms AS positionMs,
+              comment     AS comment,
+              created_at  AS createdAt,
+              changed_at  AS changedAt
+         FROM bookmark
+        ORDER BY changed_at DESC, track_id`)
+        .all();
+}
+/**
+ * Put the mark on a song, or move the one that is there.
+ *
+ * `created_at` survives a second write and `changed_at` does not: moving a
+ * bookmark is not making one, and a client that shows "added" beside a list of
+ * bookmarks would be told something untrue about every mark its user has
+ * adjusted.
+ *
+ * **The comment is written as given, and a write that names none clears the
+ * one that was there** — which is the protocol's rule for this method and not
+ * the one playlists follow. `updatePlaylist` treats a missing song list as
+ * silence because a client renaming a playlist means to keep its songs; here
+ * the protocol says the bookmark "will be overwritten", and a client that
+ * updates the position and drops the comment has said what the mark now is.
+ * The difference is worth the sentence because the other rule is the one this
+ * project would reach for by habit.
+ */
+export function bookmark(db, trackId, positionMs, comment, at) {
+    db.prepare(`INSERT INTO bookmark (track_id, position_ms, comment, created_at, changed_at)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT (track_id) DO UPDATE SET
+       position_ms = excluded.position_ms,
+       comment     = excluded.comment,
+       changed_at  = excluded.changed_at`).run(trackId, positionMs, comment, at, at);
+}
+/**
+ * Take the mark off a song. Nothing to take off is not an error.
+ *
+ * One statement and no transaction around it, which is `playlist/store.ts`'s
+ * `remove` as well: a lone `DELETE` is its own transaction, and a `withTransaction`
+ * here would be a wrapper that says something is being kept together when
+ * nothing is.
+ */
+export function unbookmark(db, trackId) {
+    db.prepare('DELETE FROM bookmark WHERE track_id = ?').run(trackId);
+}