@feralfile/cli 1.1.1

package/dist/src/utilities/playlist-send.js

@@ -0,0 +1,260 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confirmPlaylistForSending = confirmPlaylistForSending;
+const chalk_1 = __importDefault(require("chalk"));
+const playlist_source_1 = require("./playlist-source");
+/**
+ * Get available FF1 devices from config
+ *
+ * @returns {Promise<Array>} Array of device objects
+ */
+async function getAvailableDevices() {
+    try {
+        const configModule = (await Promise.resolve().then(() => __importStar(require('../config'))));
+        const getFF1DeviceConfig = configModule.getFF1DeviceConfig ||
+            (configModule.default && configModule.default.getFF1DeviceConfig) ||
+            configModule.default;
+        if (typeof getFF1DeviceConfig !== 'function') {
+            return [];
+        }
+        const deviceConfig = getFF1DeviceConfig();
+        if (deviceConfig.devices && Array.isArray(deviceConfig.devices)) {
+            return deviceConfig.devices
+                .filter((d) => d && d.host)
+                .map((d) => ({
+                name: d.name || d.host,
+                host: d.host,
+            }));
+        }
+    }
+    catch (error) {
+        if (process.env.DEBUG) {
+            console.log(chalk_1.default.dim(`[DEBUG] Error loading devices: ${error.message}`));
+        }
+        // Silently fail if config can't be loaded
+    }
+    return [];
+}
+/**
+ * Confirm playlist file path and validate the playlist
+ *
+ * Reads the playlist file, runs parse/structure validation (same as `validate`),
+ * and returns confirmation result for user review. Does not verify signatures.
+ *
+ * @param {string} filePath - Playlist file path or URL
+ * @param {string} [deviceName] - Device name (optional)
+ * @returns {Promise<PlaylistSendConfirmation>} Validation result
+ */
+async function confirmPlaylistForSending(filePath, deviceName) {
+    const defaultPath = './playlist.json';
+    const resolvedPath = filePath || defaultPath;
+    // Convert string "null" to undefined (in case model passes it literally)
+    const actualDeviceName = deviceName === 'null' || deviceName === '' ? undefined : deviceName;
+    if (process.env.DEBUG) {
+        console.error(chalk_1.default.dim(`[DEBUG] confirmPlaylistForSending called with: filePath="${filePath}", deviceName="${deviceName}" -> "${actualDeviceName}"`));
+    }
+    try {
+        // Load playlist from file or URL
+        console.log(chalk_1.default.cyan(`Playlist source: ${resolvedPath}`));
+        let playlist;
+        let fileExists = false;
+        let loadedFrom = 'file';
+        try {
+            const loaded = await (0, playlist_source_1.loadPlaylistSource)(resolvedPath);
+            playlist = loaded.playlist;
+            fileExists = loaded.sourceType === 'file';
+            loadedFrom = loaded.sourceType;
+            console.log(chalk_1.default.green(`Loaded from ${loadedFrom}: ${resolvedPath}`));
+        }
+        catch (error) {
+            const message = error.message;
+            const isUrl = (0, playlist_source_1.isPlaylistSourceUrl)(resolvedPath);
+            if (isUrl) {
+                return {
+                    success: false,
+                    filePath: resolvedPath,
+                    fileExists: false,
+                    playlistValid: false,
+                    error: `Could not load playlist URL: ${resolvedPath}`,
+                    message: `${message}\n\nHint:\n  • Check the URL is reachable\n  • Confirm it returns JSON\n  • Use "send ./path/to/playlist.json" for local files`,
+                };
+            }
+            if (message.includes('Invalid JSON in')) {
+                return {
+                    success: false,
+                    filePath: resolvedPath,
+                    fileExists: true,
+                    playlistValid: false,
+                    error: message,
+                    message: `${message}\n\nHint:\n  • Check the JSON payload is valid DP-1 format\n  • Check local path points to a playlist file`,
+                };
+            }
+            return {
+                success: false,
+                filePath: resolvedPath,
+                fileExists: false,
+                playlistValid: false,
+                error: `Playlist file not found at ${resolvedPath}`,
+                message: `Could not find playlist file. Try:\n  • Run a playlist build first\n  • Check the file path is correct\n  • Use "send ./path/to/playlist.json"`,
+            };
+        }
+        if (!playlist) {
+            return {
+                success: false,
+                filePath: resolvedPath,
+                fileExists,
+                playlistValid: false,
+                error: `Playlist source is empty: ${loadedFrom}`,
+            };
+        }
+        // Parse / structure validation only (same as `validate`; use `verify` CLI for signatures)
+        console.log(chalk_1.default.cyan('Validation'));
+        // Dynamic import to avoid circular dependency
+        const { validatePlaylist } = await Promise.resolve().then(() => __importStar(require('./playlist-verifier')));
+        const validateResult = await validatePlaylist(playlist);
+        if (!validateResult.valid) {
+            console.log(chalk_1.default.red('Playlist validation failed'));
+            const detailLines = validateResult.details?.map((d) => `  • ${d.path}: ${d.message}`).join('\n') ||
+                validateResult.error;
+            const detailPaths = validateResult.details?.map((d) => d.path) || [];
+            const hints = [];
+            if (detailPaths.some((path) => path.includes('signature'))) {
+                hints.push('Add `playlist.privateKey` (or `PLAYLIST_PRIVATE_KEY`) and rebuild the playlist to include signatures.');
+            }
+            if (detailPaths.some((path) => path.includes('defaults.display.margin'))) {
+                hints.push('Rebuild the playlist with the latest CLI defaults (margin must be numeric).');
+            }
+            const hintText = hints.length > 0 ? `\n\nHint:\n${hints.map((h) => `  • ${h}`).join('\n')}` : '';
+            return {
+                success: false,
+                filePath: resolvedPath,
+                fileExists: true,
+                playlistValid: false,
+                playlist,
+                deviceName: actualDeviceName,
+                error: `Playlist is invalid: ${validateResult.error}`,
+                message: `This playlist doesn't match DP-1 specification.\n\nErrors:\n${detailLines}${hintText}`,
+            };
+        }
+        console.log(chalk_1.default.green('Valid DP-1 playlist'));
+        // Display confirmation details
+        const itemCount = playlist.items?.length || 0;
+        const title = playlist.title || 'Untitled';
+        // Handle device selection
+        let selectedDevice = actualDeviceName;
+        let needsDeviceSelection = false;
+        let availableDevices = [];
+        if (!selectedDevice) {
+            // Get available devices
+            availableDevices = await getAvailableDevices();
+            if (process.env.DEBUG) {
+                console.error(chalk_1.default.dim(`[DEBUG] selectedDevice is null/undefined`));
+                console.error(chalk_1.default.dim(`[DEBUG] Available devices found: ${availableDevices.length}`));
+                availableDevices.forEach((d) => {
+                    console.error(chalk_1.default.dim(`[DEBUG] Device: ${d.name} (${d.host})`));
+                });
+            }
+            if (availableDevices.length === 0) {
+                return {
+                    success: false,
+                    filePath: resolvedPath,
+                    fileExists: true,
+                    playlistValid: true,
+                    playlist,
+                    error: 'No FF1 devices configured',
+                    message: `No FF1 devices found in your configuration.\n\nPlease add devices to your config.json:\n{\n  "devices": [{\n    "name": "Living Room",\n    "host": "192.168.1.100"\n  }]\n}`,
+                };
+            }
+            else if (availableDevices.length === 1) {
+                // Auto-select single device
+                selectedDevice = availableDevices[0].name || availableDevices[0].host;
+                console.log(chalk_1.default.cyan(`Device: ${selectedDevice} (auto)`));
+            }
+            else {
+                // Multiple devices - need user to choose
+                needsDeviceSelection = true;
+            }
+        }
+        console.log();
+        console.log(chalk_1.default.bold('Send Summary'));
+        console.log(chalk_1.default.dim(`  Title: ${title}`));
+        console.log(chalk_1.default.dim(`  Items: ${itemCount}`));
+        if (selectedDevice) {
+            console.log(chalk_1.default.dim(`  Device: ${selectedDevice}`));
+        }
+        else if (availableDevices.length > 1) {
+            console.log(chalk_1.default.dim('  Device: select one'));
+        }
+        console.log();
+        // If multiple devices, return needsDeviceSelection flag
+        if (needsDeviceSelection) {
+            return {
+                success: false,
+                filePath: resolvedPath,
+                fileExists: true,
+                playlistValid: true,
+                playlist,
+                needsDeviceSelection: true,
+                availableDevices,
+                error: 'Multiple devices available - please choose one',
+                message: `Which device would you like to display on?\n\nAvailable devices:\n${availableDevices.map((d, i) => `  ${i + 1}. ${d.name || d.host}`).join('\n')}\n\nSay: "send to [device name]" or "send to device 1"`,
+            };
+        }
+        return {
+            success: true,
+            filePath: resolvedPath,
+            fileExists: true,
+            playlistValid: true,
+            playlist,
+            deviceName: selectedDevice,
+            message: `Ready to send "${title}" (${itemCount} items) to ${selectedDevice}!`,
+        };
+    }
+    catch (error) {
+        const errorMsg = error.message;
+        console.log(chalk_1.default.red(`Error: ${errorMsg}`));
+        return {
+            success: false,
+            filePath: resolvedPath,
+            fileExists: false,
+            playlistValid: false,
+            error: errorMsg,
+        };
+    }
+}

package/dist/src/utilities/playlist-signer.js

@@ -0,0 +1,204 @@
+/**
+ * Playlist Signing Utility.
+ * Uses the DP-1 v1.1.0 signing contract via the `dp1-js` package.
+ */
+const { getPlaylistConfig } = require('../config');
+const { isDp1PlaylistSigningRole } = require('./playlist-signing-role');
+/**
+ * Sign a playlist using the DP-1 signing API.
+ * The signed payload excludes any pre-existing signature fields so the output
+ * is stable across re-signing and matches the library's canonical digest.
+ *
+ * @param {Object} playlist - Playlist object without signature
+ * @param {string} [privateKeyBase64] - Ed25519 private key in hex or base64 format (optional, uses config if not provided)
+ * @param {string} [roleOverride] - DP-1 signing role override (optional, uses config if not provided)
+ * @returns {Promise<Object>} DP-1 signature envelope
+ * @throws {Error} If private key is invalid or signing fails
+ */
+async function signPlaylist(playlist, privateKeyBase64, roleOverride) {
+    // Get private key from config if not provided
+    let privateKey = privateKeyBase64;
+    if (!privateKey) {
+        const config = getPlaylistConfig();
+        privateKey = config.privateKey;
+    }
+    if (!privateKey) {
+        throw new Error('Private key is required for signing');
+    }
+    try {
+        const playlistToSign = { ...playlist };
+        delete playlistToSign.signature;
+        delete playlistToSign.signatures;
+        const dp1 = await loadDp1();
+        const raw = Buffer.from(JSON.stringify(playlistToSign));
+        const config = getPlaylistConfig();
+        const role = resolvePlaylistSigningRole(roleOverride || config.role);
+        if (typeof dp1.SignMultiEd25519 === 'function') {
+            return dp1.SignMultiEd25519(raw, privateKey, role, currentTimestamp());
+        }
+        throw new Error('dp1-js does not expose SignMultiEd25519');
+    }
+    catch (error) {
+        throw new Error(`Failed to sign playlist: ${error.message}`);
+    }
+}
+/**
+ * Verify a playlist signature with the DP-1 verification API.
+ *
+ * @param {Object} playlist - Playlist object with signature field
+ * @param {string} publicKeyHex - Ed25519 public key in hex format (with or without 0x prefix)
+ * @returns {Promise<boolean>} True if signature is valid, false otherwise
+ * @throws {Error} If verification process fails
+ */
+async function verifyPlaylist(playlist, publicKeyHex) {
+    if (!publicKeyHex) {
+        throw new Error('Public key is required for verification');
+    }
+    try {
+        const dp1 = await loadDp1();
+        const verifyFn = dp1.verifyPlaylist;
+        if (typeof verifyFn !== 'function') {
+            throw new Error('dp1-js does not expose verifyPlaylist');
+        }
+        const isValid = await verifyFn(playlist, publicKeyHex);
+        return isValid;
+    }
+    catch (error) {
+        throw new Error(`Failed to verify playlist signature: ${error.message}`);
+    }
+}
+/**
+ * Sign a playlist file
+ * Reads playlist from file, signs it, and writes back
+ *
+ * @param {string} playlistPath - Path to playlist JSON file
+ * @param {string} [privateKeyBase64] - Ed25519 private key in hex or base64 format (optional, uses config if not provided)
+ * @param {string} [outputPath] - Output path (optional, overwrites input if not provided)
+ * @returns {Promise<Object>} Result with signed playlist
+ * @returns {boolean} returns.success - Whether signing succeeded
+ * @returns {Object} [returns.playlist] - Signed playlist object
+ * @returns {string} [returns.error] - Error message if failed
+ */
+async function signPlaylistFile(playlistPath, privateKeyBase64, outputPath, roleOverride) {
+    const fs = require('fs');
+    const path = require('path');
+    try {
+        // Read playlist file
+        if (!fs.existsSync(playlistPath)) {
+            throw new Error(`Playlist file not found: ${playlistPath}`);
+        }
+        const playlistContent = fs.readFileSync(playlistPath, 'utf-8');
+        const playlist = JSON.parse(playlistContent);
+        const config = getPlaylistConfig();
+        const privateKey = privateKeyBase64 || config.privateKey;
+        const role = resolvePlaylistSigningRole(roleOverride || config.role);
+        const validation = await validatePlaylistForSigning(playlist);
+        if (!validation.valid) {
+            throw new Error(`Playlist validation failed: ${validation.error}`);
+        }
+        const dp1 = await loadDp1();
+        if (!privateKey) {
+            throw new Error('Private key is required for signing');
+        }
+        const signedPlaylist = await buildSignedPlaylistEnvelope(playlist, privateKey, dp1, role);
+        const verification = await verifySignedPlaylistEnvelope(signedPlaylist, dp1);
+        if (!verification.valid) {
+            throw new Error(`Signed playlist verification failed: ${verification.error}`);
+        }
+        // Write to output file
+        const output = outputPath || playlistPath;
+        fs.writeFileSync(output, JSON.stringify(signedPlaylist, null, 2), 'utf-8');
+        console.log(`✓ Playlist signed and saved to: ${path.resolve(output)}`);
+        return {
+            success: true,
+            playlist: signedPlaylist,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message,
+        };
+    }
+}
+module.exports = {
+    signPlaylist,
+    verifyPlaylist,
+    signPlaylistFile,
+};
+function resolvePlaylistSigningRole(role) {
+    const candidate = typeof role === 'string' ? role.trim() : '';
+    const effectiveRole = candidate || 'agent';
+    if (!isDp1PlaylistSigningRole(effectiveRole)) {
+        throw new Error(`Unsupported DP-1 playlist signing role "${effectiveRole}". Expected one of: agent, feed, curator, institution, licensor`);
+    }
+    return effectiveRole;
+}
+async function validatePlaylistForSigning(playlist) {
+    const dp1 = await loadDp1();
+    const parseFn = dp1.parseDP1Playlist;
+    if (typeof parseFn !== 'function') {
+        throw new Error('dp1-js does not expose parseDP1Playlist');
+    }
+    const result = parseFn(playlist);
+    if (result && result.error) {
+        return { valid: false, error: result.error.message };
+    }
+    return { valid: true };
+}
+/**
+ * Produce a DP-1 v1.1.0 playlist object with a new multi-signature appended.
+ * The digest uses JSON with top-level `signature` and `signatures` removed (same
+ * as dp1-js/dp1-go §7.1); prior `signatures[]` entries are kept on the returned
+ * object so repeated `sign` runs accumulate endorsements instead of replacing them.
+ *
+ * @param {Object} playlist - Parsed playlist (may already include `signatures[]`)
+ * @param {string} privateKey - Private key material forwarded to dp1-js
+ * @param {Object} dp1 - Loaded dp1-js module
+ * @param {string} role - DP-1 signing role
+ * @returns {Promise<Object>} Playlist with legacy `signature` cleared and merged `signatures[]`
+ */
+async function buildSignedPlaylistEnvelope(playlist, privateKey, dp1, role) {
+    const playlistToSign = { ...playlist };
+    delete playlistToSign.signature;
+    delete playlistToSign.signatures;
+    const existingSignatures = Array.isArray(playlist.signatures)
+        ? playlist.signatures.filter((entry) => Boolean(entry))
+        : [];
+    if (typeof dp1.SignMultiEd25519 === 'function') {
+        const signature = await dp1.SignMultiEd25519(Buffer.from(JSON.stringify(playlistToSign)), privateKey, role, currentTimestamp());
+        return {
+            ...playlist,
+            signature: undefined,
+            signatures: [...existingSignatures, signature],
+        };
+    }
+    throw new Error('dp1-js does not expose SignMultiEd25519');
+}
+/**
+ * Verify a signed playlist envelope with dp1-js before it is persisted.
+ * The sign command must only write outputs that the same verifier path accepts;
+ * otherwise it can succeed while immediately generating a broken artifact.
+ *
+ * @param {Object} signedPlaylist - Playlist envelope with signatures attached
+ * @param {Object} dp1 - Loaded dp1-js module
+ * @returns {Promise<{ valid: boolean; error?: string }>} Verification result
+ */
+async function verifySignedPlaylistEnvelope(signedPlaylist, dp1) {
+    const verifyFn = dp1.verifyPlaylist;
+    if (typeof verifyFn !== 'function') {
+        throw new Error('dp1-js does not expose verifyPlaylist');
+    }
+    const isValid = await verifyFn(signedPlaylist);
+    if (!isValid) {
+        return { valid: false, error: 'signed playlist is not verifiable' };
+    }
+    return { valid: true };
+}
+/** Loads `dp1-js`; env overrides are not supported (see playlist-verifier). */
+async function loadDp1() {
+    return require('dp1-js');
+}
+function currentTimestamp() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}

package/dist/src/utilities/playlist-signing-role.js

@@ -0,0 +1,41 @@
+/**
+ * Supported DP-1 playlist signing roles.
+ *
+ * Keep this list aligned with the published dp1-js role constants so guided
+ * setup, config validation, and signing all agree on the same contract.
+ */
+const DP1_PLAYLIST_SIGNING_ROLES = Object.freeze([
+    'agent',
+    'feed',
+    'curator',
+    'institution',
+    'licensor',
+]);
+function isDp1PlaylistSigningRole(role) {
+    return typeof role === 'string' && DP1_PLAYLIST_SIGNING_ROLES.includes(role);
+}
+function formatUnsupportedPlaylistSigningRoleError(role) {
+    return `Unsupported DP-1 playlist signing role "${role}". Expected one of: ${DP1_PLAYLIST_SIGNING_ROLES.join(', ')}`;
+}
+function normalizeDp1PlaylistSigningRole(value, defaultRole = 'agent') {
+    const trimmedValue = typeof value === 'string' ? value.trim() : '';
+    if (trimmedValue) {
+        return trimmedValue;
+    }
+    const trimmedDefault = typeof defaultRole === 'string' ? defaultRole.trim() : '';
+    return trimmedDefault || 'agent';
+}
+function resolveDp1PlaylistSigningRole(role, fallbackRole = 'agent') {
+    const candidate = normalizeDp1PlaylistSigningRole(role, fallbackRole);
+    if (!isDp1PlaylistSigningRole(candidate)) {
+        throw new Error(formatUnsupportedPlaylistSigningRoleError(candidate));
+    }
+    return candidate;
+}
+module.exports = {
+    DP1_PLAYLIST_SIGNING_ROLES,
+    isDp1PlaylistSigningRole,
+    formatUnsupportedPlaylistSigningRoleError,
+    normalizeDp1PlaylistSigningRole,
+    resolveDp1PlaylistSigningRole,
+};

package/dist/src/utilities/playlist-source.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPlaylistSourceUrl = isPlaylistSourceUrl;
+exports.loadPlaylistSource = loadPlaylistSource;
+exports.resolvePlaySource = resolvePlaySource;
+const fs_1 = require("fs");
+// playlist-builder is still CommonJS; require keeps the interop simple.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { buildUrlItem, buildDP1Playlist } = require('./playlist-builder');
+/**
+ * Determine whether a playlist source is an HTTP(S) URL.
+ *
+ * @param {string} source - Playlist source value
+ * @returns {boolean} Whether the value parses as http:// or https:// URL
+ */
+function isPlaylistSourceUrl(source) {
+    const trimmed = source.trim();
+    if (!trimmed) {
+        return false;
+    }
+    try {
+        const parsed = new URL(trimmed);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Load a DP-1 playlist from a local file or hosted URL.
+ *
+ * @param {string} source - Playlist file path or URL
+ * @returns {Promise<LoadedPlaylist>} Loaded playlist payload with source metadata
+ * @throws {Error} When source is empty, cannot be loaded, or JSON is invalid
+ */
+async function loadPlaylistSource(source) {
+    const trimmedSource = source.trim();
+    if (!trimmedSource) {
+        throw new Error('Playlist source is required');
+    }
+    if (isPlaylistSourceUrl(trimmedSource)) {
+        const response = await fetch(trimmedSource);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch playlist URL: ${response.status} ${response.statusText}`);
+        }
+        let playlistText;
+        try {
+            playlistText = await response.text();
+        }
+        catch (error) {
+            throw new Error(`Failed to read playlist response from ${trimmedSource}: ${error.message}`);
+        }
+        try {
+            return {
+                playlist: JSON.parse(playlistText),
+                source: trimmedSource,
+                sourceType: 'url',
+            };
+        }
+        catch (error) {
+            throw new Error(`Invalid JSON from playlist URL ${trimmedSource}: ${error.message}`);
+        }
+    }
+    let fileText;
+    try {
+        fileText = await fs_1.promises.readFile(trimmedSource, 'utf-8');
+    }
+    catch (_error) {
+        throw new Error(`Playlist file not found at ${trimmedSource}`);
+    }
+    try {
+        return {
+            playlist: JSON.parse(fileText),
+            source: trimmedSource,
+            sourceType: 'file',
+        };
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON in ${trimmedSource}: ${error.message}`);
+    }
+}
+/**
+ * Resolve a `play` command argument to a playable source.
+ *
+ * Files are always treated as playlists. URLs are tried as playlists first;
+ * if loading fails (network, non-JSON, etc.), the URL is wrapped in a
+ * synthesized single-item playlist so direct media URLs still work.
+ *
+ * The "URL → playlist or media" path uses throw-and-fallback because there
+ * is no cheap way to distinguish a 200-OK media file from a malformed
+ * playlist response without trying to parse it. Keeping the fallback
+ * scoped to one helper means the play action no longer carries the
+ * `loadedAsPlaylist` boolean dance.
+ *
+ * @param source - User-supplied path or URL
+ * @param defaultDuration - Duration (seconds) for the synthesized media item
+ * @returns Resolved playlist + metadata describing how it was loaded
+ * @throws Error When `source` is empty, or is a non-URL file path that cannot be loaded
+ */
+async function resolvePlaySource(source, defaultDuration) {
+    const trimmed = source.trim();
+    if (!trimmed) {
+        throw new Error('Playlist source is required');
+    }
+    if (!isPlaylistSourceUrl(trimmed)) {
+        const loaded = await loadPlaylistSource(trimmed);
+        return {
+            kind: 'playlist',
+            playlist: loaded.playlist,
+            sourceType: loaded.sourceType,
+            source: loaded.source,
+        };
+    }
+    try {
+        const loaded = await loadPlaylistSource(trimmed);
+        return {
+            kind: 'playlist',
+            playlist: loaded.playlist,
+            sourceType: loaded.sourceType,
+            source: loaded.source,
+        };
+    }
+    catch {
+        const item = buildUrlItem(trimmed, defaultDuration);
+        const playlist = (await buildDP1Playlist({ items: [item], title: item.title }));
+        return { kind: 'media', playlist, source: trimmed };
+    }
+}