@ciphore/radiocli 0.2.3 → 0.2.5

package/dist/storage/store.js

@@ -1,43 +1,33 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { platformPaths } from '../platform/paths.js';
+import { assertStorageWritable } from '../platform/storage.js';
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { defaultReceiverStyle, receiverStyleNames, themeNames } from '../types.js';
 import { canonicalizeAlarmTime, canonicalizeIsoWeekdays, canonicalizeTimeZone } from '../alarms/schedule.js';
-import { backupBadFile } from '../providers/cache.js';
 import { migrateReceiverStyle } from '../ui/visualizers/receiver-style-registry.js';
-const stationSchema = z
-    .object({
-    id: z.string(),
-    provider: z.enum(['radio-browser', 'radio-garden', 'playlist']),
-    name: z.string(),
-    country: z.string().optional(),
-    countryCode: z.string().optional(),
-    state: z.string().optional(),
-    city: z.string().optional(),
-    language: z.string().optional(),
-    languageCodes: z.array(z.string()).optional(),
-    tags: z.array(z.string()),
-    codec: z.string().optional(),
-    bitrate: z.number().optional(),
-    homepage: z.string().optional(),
-    favicon: z.string().optional(),
-    streamUrl: z.string().optional(),
-    clickCount: z.number().optional(),
-    votes: z.number().optional(),
-    latitude: z.number().optional(),
-    longitude: z.number().optional(),
-    distanceKm: z.number().optional(),
-    hls: z.boolean().optional(),
-    lastCheckedOk: z.boolean().optional()
-});
+import { migrateStationIdentity } from './station-identity.js';
+import { stationSchema } from './station-schema.js';
+import { acquireFileLock } from './file-lock.js';
+import { replaceFileSync } from './replace-file.js';
 const defaultMediaKeys = {
     previous: [],
     playPause: [],
     next: []
 };
 const MAX_ALARMS = 500;
+// Keep the shared library readable by pre-scene releases whose background MCP
+// workers quarantine an entire library when they see an unfamiliar enum value.
+// Crossfade is the last style understood by those releases. New styles live in
+// a separate preference file that old writers never read or overwrite.
+const sharedLibraryReceiverStyles = new Set(receiverStyleNames.slice(0, receiverStyleNames.indexOf('crossfade') + 1));
+const receiverPreferenceSchema = z.object({
+    version: z.literal(1),
+    receiverStyle: z.preprocess(migrateReceiverStyle, z.enum(receiverStyleNames)),
+    libraryReceiverStyle: z.literal('ultracode')
+});
 const settingsSchema = z.object({
     theme: z.enum(themeNames).default('green'),
     receiverStyle: z.preprocess(migrateReceiverStyle, z.enum(receiverStyleNames).default(defaultReceiverStyle)),
@@ -48,6 +38,7 @@ const settingsSchema = z.object({
     shareDirectoryVotes: z.boolean().default(true),
     preferredBackend: z.enum(['auto', 'mpv', 'ffplay', 'vlc', 'airplay']).default('auto'),
     preferredAirPlayDevice: z.string().min(1).optional(),
+    linuxAirPlayEnabled: z.boolean().optional(),
     tuneTimeoutSeconds: z.number().min(3).max(45).default(12),
     skipBrokenStreams: z.boolean().default(true),
     mediaKeys: z
@@ -63,6 +54,7 @@ const settingsSchema = z.object({
     reduceMotion: z.boolean().default(false),
     mouseSupport: z.boolean().default(true),
     automaticUpdateChecks: z.boolean().default(true),
+    desktopMediaControls: z.enum(['auto', 'on', 'off']).default('auto'),
     agentControl: z.object({
         enabled: z.boolean().default(false),
         openUiOnPlay: z.boolean().default(true),
@@ -166,6 +158,10 @@ const librarySchema = z.object({
     }))
         .default([]),
     favorites: z.array(stationSchema).default([]),
+    presets: z.array(z.object({
+        name: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,39}$/),
+        station: stationSchema
+    })).max(200).default([]),
     imported: z.array(stationSchema).default([]),
     trackHistory: z
         .array(z.object({
@@ -234,16 +230,70 @@ export class JsonLibraryStore {
     state;
     idGenerator;
     now;
-    constructor(filePath = defaultStorePath(), options = {}) {
+    revision = '';
+    constructor(filePath = defaultLibraryPath(), options = {}) {
         this.filePath = filePath;
         this.idGenerator = options.idGenerator ?? randomUUID;
         this.now = options.now ?? (() => new Date());
+        this.revision = this.diskRevision();
         this.state = this.read();
+        // Normalize libraries saved by an earlier preview before any legacy
+        // background reader encounters its new enum value again.
+        if (!sharedLibraryReceiverStyles.has(this.state.settings.receiverStyle) && !existsSync(this.receiverPreferencePath()))
+            this.commit(this.state);
     }
     snapshot() {
+        this.refresh();
+        return this.cachedSnapshot();
+    }
+    cachedSnapshot() {
         return structuredClone(this.state);
     }
+    /** Refresh atomically replaced files without recovering a live listening session. */
+    refresh() {
+        const revision = this.diskRevision();
+        if (revision === this.revision)
+            return false;
+        const next = this.readForCurrentSession();
+        this.state = next;
+        this.revision = revision;
+        return true;
+    }
+    settings() {
+        this.refresh();
+        return structuredClone(this.state.settings);
+    }
+    diskRevision() {
+        return [this.filePath, this.receiverPreferencePath()].map(file => {
+            try {
+                const info = statSync(file, { bigint: true });
+                return `${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`;
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return 'missing';
+                throw storageError('read the RadioCLI library', error);
+            }
+        }).join('|');
+    }
+    savePreset(name, station) {
+        this.refresh();
+        const key = normalizePresetName(name);
+        const presets = this.state.presets ?? [];
+        if (presets.length >= 200 && !presets.some(preset => preset.name === key))
+            throw new Error('RadioCLI supports at most 200 station presets. Remove one with radiocli preset remove <name>.');
+        this.commit({ ...this.state, presets: [{ name: key, station }, ...presets.filter(preset => preset.name !== key)] });
+    }
+    removePreset(name) {
+        this.refresh();
+        const key = normalizePresetName(name);
+        const presets = this.state.presets ?? [];
+        if (!presets.some(preset => preset.name === key))
+            throw new Error(`No preset named ${key}. Run radiocli presets to see saved names.`);
+        this.commit({ ...this.state, presets: presets.filter(preset => preset.name !== key) });
+    }
     exportBackup(requestedPath) {
+        this.refresh();
         const targetPath = requestedPath?.trim()
             ? resolveUserPath(requestedPath)
             : resolve(process.cwd(), `radiocli-backup-${fileTimestamp(new Date())}.json`);
@@ -283,7 +333,9 @@ export class JsonLibraryStore {
                 ? `${this.filePath}.before-import-${fileTimestamp(new Date())}.bak`
                 : undefined;
             if (safetyBackupPath) {
-                writeJsonAtomically(safetyBackupPath, libraryStateForDisk(this.state));
+                // Another TUI or background player may have saved since this owner
+                // last refreshed. Preserve its latest data while holding the lock.
+                writeJsonAtomically(safetyBackupPath, libraryStateForDisk(this.read()));
             }
             this.write(importedState);
             this.state = importedState;
@@ -294,6 +346,7 @@ export class JsonLibraryStore {
         }
     }
     updateSettings(settings) {
+        this.refresh();
         return this.commit({
             ...this.state,
             settings: {
@@ -304,12 +357,13 @@ export class JsonLibraryStore {
         });
     }
     updateCheckState(updateCheck) {
+        this.refresh();
         return this.commit({ ...this.state, updateCheck });
     }
     addAlarm(input) {
         const release = acquireStoreLock(this.filePath);
         try {
-            const latestState = this.read();
+            const latestState = this.readForCurrentSession();
             if (latestState.alarms.length >= MAX_ALARMS) {
                 throw new Error(`RadioCLI supports at most ${MAX_ALARMS} alarms.`);
             }
@@ -351,7 +405,7 @@ export class JsonLibraryStore {
     removeAlarm(id) {
         const release = acquireStoreLock(this.filePath);
         try {
-            const latestState = this.read();
+            const latestState = this.readForCurrentSession();
             if (!latestState.alarms.some(alarm => alarm.id === id)) {
                 this.state = latestState;
                 return false;
@@ -373,10 +427,12 @@ export class JsonLibraryStore {
         }));
     }
     getAlarm(id) {
+        this.refresh();
         const alarm = this.state.alarms.find(item => item.id === id);
         return alarm ? structuredClone(alarm) : undefined;
     }
     listAlarms() {
+        this.refresh();
         return structuredClone(this.state.alarms);
     }
     recordAlarmOutcome(id, outcome, options = {}) {
@@ -408,6 +464,7 @@ export class JsonLibraryStore {
         }));
     }
     addRecent(station) {
+        this.refresh();
         const key = stationKey(station);
         const recent = [
             { station, playedAt: new Date().toISOString() },
@@ -418,9 +475,10 @@ export class JsonLibraryStore {
     // Persist the ICY track titles a station announces so "what was that song?"
     // is answerable later. Consecutive duplicates on the same station are skipped.
     recordTrack(station, title) {
+        this.refresh();
         const cleaned = title.trim();
         if (!cleaned) {
-            return this.snapshot();
+            return this.cachedSnapshot();
         }
         const key = stationKey(station);
         const last = this.state.trackHistory[0];
@@ -437,6 +495,7 @@ export class JsonLibraryStore {
     }
     // Most-recent-first search queries for up-arrow recall in the search box.
     addSearch(query) {
+        this.refresh();
         const cleaned = query.trim();
         if (!cleaned) {
             return this.snapshot();
@@ -445,6 +504,7 @@ export class JsonLibraryStore {
         return this.commit({ ...this.state, searchHistory });
     }
     startListeningSession(station, startedAt = new Date()) {
+        this.refresh();
         const finishedState = recoverActiveListeningSessionInState(this.state);
         const session = {
             id: `${startedAt.toISOString()}-${stationKey(station)}`,
@@ -461,6 +521,7 @@ export class JsonLibraryStore {
         });
     }
     checkpointActiveListeningSession(activeAt = new Date()) {
+        this.refresh();
         const active = this.state.activity.sessions[0];
         if (!active || active.endedAt) {
             return this.snapshot();
@@ -481,6 +542,7 @@ export class JsonLibraryStore {
         });
     }
     finishActiveListeningSession(endedAt = new Date()) {
+        this.refresh();
         const nextState = finishActiveListeningSessionInState(this.state, endedAt);
         if (nextState === this.state) {
             return this.snapshot();
@@ -488,6 +550,7 @@ export class JsonLibraryStore {
         return this.commit(nextState);
     }
     toggleFavorite(station) {
+        this.refresh();
         const key = stationKey(station);
         const exists = this.state.favorites.some(item => stationKey(item) === key);
         const favorites = exists
@@ -496,26 +559,36 @@ export class JsonLibraryStore {
         return this.commit({ ...this.state, favorites });
     }
     addImported(stations) {
-        const existing = new Map(this.state.imported.map(station => [stationKey(station), station]));
+        this.refresh();
+        const incoming = [];
+        const incomingKeys = new Set();
         for (const station of stations) {
-            existing.set(stationKey(station), station);
+            const key = stationKey(station);
+            if (incomingKeys.has(key))
+                continue;
+            incomingKeys.add(key);
+            incoming.push(station);
         }
         return this.commit({
             ...this.state,
-            imported: [...existing.values()].slice(0, 1000)
+            imported: [
+                ...incoming,
+                ...this.state.imported.filter(station => !incomingKeys.has(stationKey(station)))
+            ].slice(0, 1000)
         });
     }
     isFavorite(station) {
         if (!station) {
             return false;
         }
+        this.refresh();
         const key = stationKey(station);
         return this.state.favorites.some(item => stationKey(item) === key);
     }
     mutateAlarm(id, change) {
         const release = acquireStoreLock(this.filePath);
         try {
-            const latestState = this.read();
+            const latestState = this.readForCurrentSession();
             const existing = latestState.alarms.find(alarm => alarm.id === id);
             if (!existing) {
                 this.state = latestState;
@@ -535,37 +608,130 @@ export class JsonLibraryStore {
         }
     }
     read() {
-        if (!existsSync(this.filePath)) {
-            return defaultState();
+        let contents;
+        try {
+            contents = readFileSync(this.filePath, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return defaultState();
+            throw storageError('read the RadioCLI library', error);
         }
+        let state;
         try {
-            return migrateLibraryState(librarySchema.parse(JSON.parse(readFileSync(this.filePath, 'utf8'))));
+            state = migrateLibraryState(librarySchema.parse(JSON.parse(contents)));
         }
-        catch {
-            backupBadFile(this.filePath);
+        catch (error) {
+            if (error instanceof z.ZodError && error.issues.some(issue => issue.code === 'invalid_value' && issue.path.length === 2 &&
+                issue.path[0] === 'settings' && issue.path[1] === 'receiverStyle')) {
+                // Another running build may have saved a newer receiver. Its library
+                // is intact: never quarantine it or replace it with empty defaults.
+                throw new Error('The RadioCLI library uses a receiver style this process does not support. Restart RadioCLI and its MCP clients to load the updated styles.');
+            }
+            try {
+                assertStorageWritable(this.filePath);
+                renameSync(this.filePath, `${this.filePath}.bad-${Date.now()}-${randomUUID()}`);
+            }
+            catch (error) {
+                // Reset only after preserving the original bytes. A failed read never reaches here.
+                throw storageError('preserve the corrupt RadioCLI library', error);
+            }
             return defaultState();
         }
+        // A legacy writer can still change ordinary preferences and favorites. Its
+        // fallback style must not erase the selection saved by an updated process.
+        let preference;
+        try {
+            preference = readFileSync(this.receiverPreferencePath(), 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return state;
+            throw storageError('read the receiver preference', error);
+        }
+        const parsed = receiverPreferenceSchema.safeParse(JSON.parse(preference));
+        if (!parsed.success)
+            throw new Error('The RadioCLI receiver preference is unsupported or invalid. Restart RadioCLI and its MCP clients with the latest version. Your library has been preserved.');
+        if (state.settings.receiverStyle === parsed.data.libraryReceiverStyle)
+            state.settings.receiverStyle = parsed.data.receiverStyle;
+        return state;
+    }
+    receiverPreferencePath() { return `${this.filePath}.receiver.json`; }
+    readForCurrentSession() {
+        const next = this.read();
+        // Disk intentionally stores auto instead of reopening a receiver on launch.
+        // Within this owner, unrelated durable changes retain its selected output.
+        if (this.state.settings.preferredBackend === 'airplay' && next.settings.preferredBackend === 'auto') {
+            next.settings.preferredBackend = 'airplay';
+        }
+        return next;
     }
     commit(nextState) {
         const release = acquireStoreLock(this.filePath);
         try {
-            const latestState = this.read();
+            const latestState = this.readForCurrentSession();
             const mergedState = mergeLibraryChanges(this.state, latestState, nextState);
             this.write(mergedState);
             this.state = mergedState;
-            return this.snapshot();
+            return this.cachedSnapshot();
         }
         finally {
             release();
         }
     }
     write(state) {
-        mkdirSync(dirname(this.filePath), { recursive: true, mode: 0o700 });
-        writeJsonAtomically(this.filePath, libraryStateForDisk(state));
+        try {
+            assertStorageWritable(this.filePath);
+            mkdirSync(dirname(this.filePath), { recursive: true, mode: 0o700 });
+            const diskState = libraryStateForDisk(state);
+            const separateReceiver = !sharedLibraryReceiverStyles.has(state.settings.receiverStyle);
+            const preferencePath = this.receiverPreferencePath();
+            let previousPreference;
+            try {
+                previousPreference = readFileSync(preferencePath, 'utf8');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            const nextPreference = separateReceiver
+                ? `${JSON.stringify({ version: 1, receiverStyle: state.settings.receiverStyle, libraryReceiverStyle: 'ultracode' }, null, 2)}\n`
+                : undefined;
+            const preferenceChanged = previousPreference !== nextPreference;
+            if (preferenceChanged) {
+                if (nextPreference === undefined)
+                    rmSync(preferencePath);
+                else
+                    writeTextAtomically(preferencePath, nextPreference);
+            }
+            try {
+                writeJsonAtomically(this.filePath, separateReceiver
+                    ? { ...diskState, settings: { ...diskState.settings, receiverStyle: 'ultracode' } }
+                    : diskState);
+            }
+            catch (error) {
+                if (preferenceChanged) {
+                    if (previousPreference === undefined)
+                        rmSync(preferencePath, { force: true });
+                    else
+                        writeTextAtomically(preferencePath, previousPreference);
+                }
+                throw error;
+            }
+            try {
+                this.revision = this.diskRevision();
+            }
+            catch {
+                this.revision = '';
+            }
+        }
+        catch (error) {
+            throw storageError('write the RadioCLI library', error);
+        }
     }
 }
 export function stationKey(station) {
-    return `${station.provider}:${station.id}`;
+    return `${station.provider}:${migrateStationIdentity(station).id}`;
 }
 function finishActiveListeningSessionInState(state, endedAt) {
     const active = state.activity.sessions[0];
@@ -602,31 +768,21 @@ function recoverActiveListeningSessionInState(state) {
             : Date.now();
     return finishActiveListeningSessionInState(state, new Date(recoveredEnd));
 }
-function defaultStorePath() {
-    if (process.env.RADIOCLI_HOME) {
-        return join(process.env.RADIOCLI_HOME, 'radiocli.json');
-    }
-    if (process.env.RADIO_ATLAS_HOME) {
-        return join(process.env.RADIO_ATLAS_HOME, 'radio-atlas.json');
-    }
-    const currentPath = currentDefaultStorePath();
-    const legacyPath = legacyDefaultStorePath();
-    return existsSync(currentPath) || !existsSync(legacyPath) ? currentPath : legacyPath;
-}
-function currentDefaultStorePath() {
-    if (process.platform === 'darwin') {
-        return join(homedir(), 'Library', 'Application Support', 'radiocli', 'radiocli.json');
-    }
-    if (process.platform === 'win32') {
-        return join(process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming'), 'RadioCLI', 'radiocli.json');
-    }
-    return join(process.env.XDG_DATA_HOME ?? join(homedir(), '.local', 'share'), 'radiocli', 'radiocli.json');
-}
-function legacyDefaultStorePath() {
-    if (process.platform === 'darwin') {
-        return join(homedir(), 'Library', 'Application Support', 'radio-atlas', 'radio-atlas.json');
+export function defaultLibraryPath(options = {}) {
+    const { library, legacyLibrary } = platformPaths(options);
+    for (const filePath of [library, legacyLibrary]) {
+        try {
+            statSync(filePath);
+            return filePath;
+        }
+        catch (error) {
+            // A permission failure must not select an older library or empty defaults.
+            if (error.code !== 'ENOENT') {
+                throw storageError('read the RadioCLI library', error);
+            }
+        }
     }
-    return join(process.env.XDG_DATA_HOME ?? join(homedir(), '.local', 'share'), 'radio-atlas', 'radio-atlas.json');
+    return library;
 }
 function resolveUserPath(requestedPath) {
     const unquoted = requestedPath.trim().replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/, (_match, doubleQuoted, singleQuoted) => doubleQuoted ?? singleQuoted ?? '');
@@ -644,6 +800,7 @@ function defaultState() {
     return {
         recent: [],
         favorites: [],
+        presets: [],
         imported: [],
         trackHistory: [],
         searchHistory: [],
@@ -673,9 +830,32 @@ function defaultState() {
     };
 }
 function migrateLibraryState(state) {
+    const aliases = new Map();
+    const migrate = (station) => {
+        const next = migrateStationIdentity(station);
+        if (next.id !== station.id) {
+            const key = `${station.provider}:${station.id}`;
+            const targets = aliases.get(key) ?? new Set();
+            targets.add(stationKey(next));
+            aliases.set(key, targets);
+        }
+        return next;
+    };
+    const recent = state.recent.map(item => ({ ...item, station: migrate(item.station) }));
+    const favorites = state.favorites.map(migrate);
+    const imported = state.imported.map(migrate);
+    const presets = state.presets?.map(item => ({ ...item, station: migrate(item.station) }));
+    const sessions = state.activity.sessions.map(item => ({ ...item, station: migrate(item.station) }));
+    const alarms = state.alarms.map(alarm => normalizeAlarm({ ...alarm, station: migrate(alarm.station),
+        playback: { ...alarm.playback, ...(alarm.playback.fallbackStation ? { fallbackStation: migrate(alarm.playback.fallbackStation) } : {}) } }));
     return {
         ...state,
-        alarms: state.alarms.map(normalizeAlarm),
+        recent, favorites, imported, presets, alarms,
+        activity: { sessions },
+        trackHistory: state.trackHistory.map(item => {
+            const targets = aliases.get(item.stationKey);
+            return targets?.size === 1 ? { ...item, stationKey: [...targets][0] } : item;
+        }),
         settings: {
             ...state.settings,
             preferredBackend: state.settings.preferredBackend === 'airplay' ? 'auto' : state.settings.preferredBackend,
@@ -700,53 +880,98 @@ function libraryStateForDisk(state) {
         : state;
 }
 function writeJsonAtomically(filePath, value) {
-    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    writeTextAtomically(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+function writeTextAtomically(filePath, text) {
+    const tempPath = `${filePath}.tmp-${process.pid}-${randomUUID()}`;
     try {
-        writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
-        renameSync(tempPath, filePath);
-        if (process.platform !== 'win32') {
-            chmodSync(filePath, 0o600);
+        const fd = openSync(tempPath, 'wx', 0o600);
+        try {
+            writeFileSync(fd, text, 'utf8');
+            if (process.platform !== 'win32')
+                chmodSync(tempPath, 0o600);
+            fsyncSync(fd);
+        }
+        catch (error) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* Preserve the original persistence error. */ }
+            throw error;
         }
+        closeSync(fd);
+        replaceFileSync(tempPath, filePath);
     }
     catch (error) {
-        rmSync(tempPath, { force: true });
-        throw error;
-    }
-}
-function acquireStoreLock(filePath) {
-    const lockPath = `${filePath}.lock`;
-    mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
-    const deadline = Date.now() + 1000;
-    while (true) {
         try {
-            mkdirSync(lockPath, { mode: 0o700 });
-            return () => rmSync(lockPath, { recursive: true, force: true });
+            rmSync(tempPath, { force: true });
         }
-        catch (error) {
-            const code = error.code;
-            if (code !== 'EEXIST')
-                throw error;
+        catch { /* Preserve the original write failure. */ }
+        throw storageError('write RadioCLI data', error);
+    }
+    // Flush the replacement directory where supported. Once rename succeeds the
+    // transaction is committed: a directory-sync failure cannot roll it back or
+    // leave the caller's in-memory state describing the previous file. Windows
+    // and some network/removable filesystems do not support syncing directories.
+    let directoryFd;
+    try {
+        directoryFd = openSync(dirname(filePath), 'r');
+        fsyncSync(directoryFd);
+    }
+    catch { /* The file itself was flushed before replacement. */ }
+    finally {
+        if (directoryFd !== undefined)
             try {
-                if (Date.now() - statSync(lockPath).mtimeMs > 10_000) {
-                    rmSync(lockPath, { recursive: true, force: true });
-                    continue;
-                }
-            }
-            catch {
-                continue;
-            }
-            if (Date.now() >= deadline) {
-                throw new Error(`RadioCLI library is busy: ${filePath}`);
+                closeSync(directoryFd);
             }
-            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
-        }
+            catch { /* Already committed. */ }
+    }
+}
+function acquireStoreLock(filePath) {
+    const lockPath = `${filePath}.lock`;
+    try {
+        assertStorageWritable(filePath);
+        mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    }
+    catch (error) {
+        throw storageError('write the RadioCLI library', error);
+    }
+    try {
+        return acquireFileLock(lockPath);
     }
+    catch (error) {
+        throw storageError('lock the RadioCLI library', error);
+    }
+}
+class LibraryStorageError extends Error {
+    code;
+    errno;
+    constructor(operation, cause) {
+        const code = cause?.code;
+        const detail = typeof code === 'string' && /^[A-Z][A-Z0-9_]+$/.test(code) ? ` (${code})` : '';
+        super(code === 'EBUSY'
+            ? 'The RadioCLI library is busy. Retry after the other writer finishes, or set RADIOCLI_HOME to a private writable directory.'
+            : `Unable to ${operation}${detail}. Check storage permissions or set RADIOCLI_HOME to a private writable directory.`, { cause });
+        this.name = 'LibraryStorageError';
+        this.code = code;
+        this.errno = cause?.errno;
+    }
+}
+function storageError(operation, cause) {
+    return cause instanceof LibraryStorageError ? cause : new LibraryStorageError(operation, cause);
+}
+function normalizePresetName(name) {
+    const key = name.trim().toLowerCase();
+    if (!/^[a-z0-9][a-z0-9_-]{0,39}$/.test(key))
+        throw new Error('Preset names must be 1-40 letters, numbers, hyphens, or underscores, starting with a letter or number.');
+    return key;
 }
 function mergeLibraryChanges(base, disk, next) {
     return {
         recent: mergeKeyedChanges(base.recent, disk.recent, next.recent, item => stationKey(item.station), 50),
         favorites: mergeKeyedChanges(base.favorites, disk.favorites, next.favorites, stationKey, 200, true),
-        imported: mergeKeyedChanges(base.imported, disk.imported, next.imported, stationKey, 1000, true),
+        presets: mergeKeyedChanges(base.presets ?? [], disk.presets ?? [], next.presets ?? [], preset => preset.name, 200, true),
+        imported: mergeKeyedChanges(base.imported, disk.imported, next.imported, stationKey, 1000, true, true),
         trackHistory: mergeKeyedChanges(base.trackHistory, disk.trackHistory, next.trackHistory, item => `${item.at}:${item.stationKey}:${item.title}`, 100),
         searchHistory: mergeSearchHistory(base.searchHistory, disk.searchHistory, next.searchHistory),
         alarms: mergeKeyedChanges(base.alarms, disk.alarms, next.alarms, alarm => alarm.id, MAX_ALARMS, true),
@@ -768,15 +993,16 @@ function normalizeAlarm(alarm) {
         };
     return { ...alarm, schedule };
 }
-function mergeKeyedChanges(base, disk, next, keyFor, limit, applyRemovals = false) {
+function mergeKeyedChanges(base, disk, next, keyFor, limit, applyRemovals = false, applyOrderChanges = false) {
     const baseByKey = new Map(base.map(item => [keyFor(item), item]));
+    const basePositions = new Map(base.map((item, index) => [keyFor(item), index]));
     const nextKeys = new Set(next.map(keyFor));
     const removedKeys = applyRemovals
         ? new Set(base.map(keyFor).filter(key => !nextKeys.has(key)))
         : new Set();
-    const localChanges = next.filter(item => {
+    const localChanges = next.filter((item, index) => {
         const prior = baseByKey.get(keyFor(item));
-        return prior === undefined || !sameValue(prior, item);
+        return prior === undefined || !sameValue(prior, item) || applyOrderChanges && basePositions.get(keyFor(item)) !== index;
     });
     const changedKeys = new Set(localChanges.map(keyFor));
     return [