@feralfile/cli 1.6.0 → 2.0.0

package/dist/src/main.js

@@ -1,54 +1,12 @@
 "use strict";
 /**
  * Main Flow Controller
- * Handles both deterministic and AI-driven playlist creation
+ * Builds DP-1 playlists deterministically from structured parameters.
  */
-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.SEND_SHORTCUT_PATTERN = void 0;
-exports.resolveSendShortcutDevice = resolveSendShortcutDevice;
-exports.resolveEffectiveDeviceName = resolveEffectiveDeviceName;
-exports.resolveSendPlaylistDeviceName = resolveSendPlaylistDeviceName;
-exports.sendPreparedPlaylistToDevice = sendPreparedPlaylistToDevice;
 exports.validateRequirements = validateRequirements;
 exports.applyPlaylistDefaults = applyPlaylistDefaults;
 exports.buildPlaylistDirect = buildPlaylistDirect;
-exports.buildPlaylist = buildPlaylist;
 // Suppress Ed25519 experimental warning immediately
 const originalEmitWarning = process.emitWarning;
 process.emitWarning = function (warning, type, ctor) {
@@ -60,83 +18,10 @@ process.emitWarning = function (warning, type, ctor) {
     }
     return originalEmitWarning.apply(this, [warning, type, ctor]);
 };
-const chalk_1 = __importDefault(require("chalk"));
-const readline = __importStar(require("readline"));
 const config_1 = require("./config");
-const logger = __importStar(require("./logger"));
-// Lazy load utilities and orchestrator to avoid circular dependencies
+// Lazy load utilities to avoid circular dependencies
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const getUtilities = () => require('./utilities');
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const getIntentParser = () => require('./intent-parser');
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const getAIOrchestrator = () => require('./ai-orchestrator');
-/**
- * Regex that matches the inline "send last / send playlist / send to <device>"
- * shortcut inside the chat flow. Exported for testing.
- */
-exports.SEND_SHORTCUT_PATTERN = /^send(?:\s+(?:last|playlist|the playlist))?(?:\s+to\s+(.+))?$/i;
-/**
- * Extract the target device from a sendMatch result, falling back to the CLI
- * --device flag. Exported for testing.
- */
-function resolveSendShortcutDevice(match, cliDefault) {
-    return match[1]?.trim() || cliDefault;
-}
-/**
- * Resolve the effective device name for a send operation.
- * The intent (from NL parsing) takes precedence; CLI flag is the fallback.
- * Exported for testing.
- */
-function resolveEffectiveDeviceName(fromIntent, fromCLI) {
-    return fromIntent || fromCLI;
-}
-/**
- * Sanitize and resolve the device name for the direct send_playlist action path.
- *
- * The intent parser can emit literal "null" or "" as a device name string; these
- * must be treated as absent so the CLI --device fallback is used instead.
- * Exported for testing — mirrors the sanitization in confirmPlaylistForSending().
- */
-function resolveSendPlaylistDeviceName(intentDeviceName, cliDeviceName) {
-    const sanitized = intentDeviceName === 'null' ||
-        intentDeviceName === '' ||
-        intentDeviceName === null ||
-        intentDeviceName === undefined
-        ? undefined
-        : intentDeviceName;
-    return resolveEffectiveDeviceName(sanitized, cliDeviceName);
-}
-/**
- * Verify a playlist for device delivery and send it using the supplied transport.
- *
- * This helper keeps the send branches in `buildPlaylist` testable without
- * duplicating the verification and transport wiring in tests.
- */
-async function sendPreparedPlaylistToDevice(playlist, deps) {
-    const verificationResult = await deps.verifyPlaylist(playlist);
-    if (!verificationResult.valid) {
-        return {
-            success: false,
-            error: verificationResult.error || 'Failed to verify playlist before sending',
-            playlist: null,
-        };
-    }
-    const sendResult = await deps.sendToDevice(playlist, deps.resolveDeviceName());
-    if (sendResult.success) {
-        return {
-            success: true,
-            playlist,
-            deviceName: sendResult.deviceName,
-            device: sendResult.device,
-        };
-    }
-    return {
-        success: false,
-        error: sendResult.error || 'Failed to send playlist',
-        playlist: null,
-    };
-}
 /**
  * Validate and apply constraints to requirements
  *
@@ -242,7 +127,6 @@ function applyPlaylistDefaults(settings = {}) {
 }
 /**
  * Build playlist deterministically from structured parameters
- * Path 1: Direct execution (no AI)
  *
  * @param {Object} params - Playlist parameters
  * @param {Array<Object>} params.requirements - Array of requirements
@@ -261,246 +145,3 @@ async function buildPlaylistDirect(params, options = {}) {
     utilities.initializeUtilities(config);
     return await utilities.buildPlaylistDirect({ requirements, playlistSettings }, options);
 }
-/**
- * Build playlist from natural language request
- * Path 2: AI-driven execution (intent parser → AI orchestrator → utilities)
- *
- * @param {string} userRequest - Natural language request
- * @param {Object} options - Options
- * @param {boolean} [options.verbose=false] - Verbose output
- * @param {string} [options.outputPath='playlist.json'] - Output path
- * @param {string} [options.modelName] - AI model to use
- * @param {boolean} [options.interactive=true] - Interactive mode (allow clarification prompts)
- * @returns {Promise<Object>} Result with playlist
- */
-async function buildPlaylist(userRequest, options = {}) {
-    const { verbose = false, outputPath = 'playlist.json', modelName, interactive = true, deviceName: defaultDeviceName, } = options;
-    // Enable verbose logging if requested
-    if (verbose) {
-        logger.setVerbose(true);
-    }
-    // Initialize utilities with config (indexer endpoint, API key, etc.)
-    const utilities = getUtilities();
-    const config = (0, config_1.getConfig)();
-    utilities.initializeUtilities(config);
-    try {
-        const trimmedRequest = userRequest.trim();
-        const sendMatch = trimmedRequest.match(/^send(?:\s+(?:last|playlist|the playlist))?(?:\s+to\s+(.+))?$/i);
-        if (sendMatch) {
-            const deviceName = sendMatch[1]?.trim() || defaultDeviceName;
-            const { confirmPlaylistForSending } = await Promise.resolve().then(() => __importStar(require('./utilities/playlist-send')));
-            const { verifyPlaylist } = await Promise.resolve().then(() => __importStar(require('./utilities/playlist-verifier')));
-            const confirmation = await confirmPlaylistForSending(outputPath, deviceName);
-            if (!confirmation.success) {
-                if (confirmation.message) {
-                    console.log(chalk_1.default.red(`\n${confirmation.message}`));
-                }
-                return {
-                    success: false,
-                    error: confirmation.error || 'Failed to prepare playlist for sending',
-                    action: 'send_playlist',
-                    playlist: null,
-                };
-            }
-            const sendResult = await sendPreparedPlaylistToDevice(confirmation.playlist, {
-                verifyPlaylist,
-                sendToDevice: utilities.sendToDevice,
-                resolveDeviceName: () => confirmation.deviceName,
-            });
-            if (sendResult.success) {
-                console.log(chalk_1.default.green('\nPlaylist sent'));
-                if (sendResult.deviceName) {
-                    console.log(chalk_1.default.dim(`  Device: ${sendResult.deviceName}`));
-                }
-                console.log();
-                return {
-                    success: true,
-                    playlist: sendResult.playlist,
-                    action: 'send_playlist',
-                };
-            }
-            console.log();
-            console.error(chalk_1.default.red('Send failed'));
-            if (sendResult.error) {
-                console.error(chalk_1.default.red(`  ${sendResult.error}`));
-            }
-            return {
-                success: false,
-                error: sendResult.error || 'Failed to send playlist',
-                playlist: null,
-                action: 'send_playlist',
-            };
-        }
-        // STEP 1: INTENT PARSER
-        // Parse user intent into structured requirements
-        const { processIntentParserRequest } = getIntentParser();
-        let intentParserResult = await processIntentParserRequest(userRequest, {
-            modelName,
-            defaultDeviceName,
-        });
-        // Handle interactive clarification loop
-        while (intentParserResult.needsMoreInfo) {
-            if (!interactive) {
-                // Non-interactive mode: cannot ask for clarification
-                console.error(chalk_1.default.red('\nNeed more information, but running in non-interactive mode. Provide a complete request.'));
-                if (intentParserResult.question) {
-                    console.error(chalk_1.default.yellow('\nQuestion: ') + intentParserResult.question);
-                }
-                process.exit(1);
-            }
-            // Ask user for clarification
-            const rl = readline.createInterface({
-                input: process.stdin,
-                output: process.stdout,
-            });
-            // Display the AI's question before asking for input
-            if (intentParserResult.question) {
-                console.log(chalk_1.default.cyan('\n') + intentParserResult.question);
-            }
-            const userResponse = await new Promise((resolve) => {
-                rl.question(chalk_1.default.yellow('Your response: '), (answer) => {
-                    rl.close();
-                    resolve(answer.trim());
-                });
-            });
-            if (!userResponse) {
-                console.error(chalk_1.default.red('\nNo response provided. Exiting.'));
-                process.exit(1);
-            }
-            console.log();
-            // Continue intent parser conversation
-            intentParserResult = await processIntentParserRequest(userResponse, {
-                modelName,
-                defaultDeviceName,
-                conversationContext: {
-                    messages: intentParserResult.messages,
-                },
-            });
-        }
-        if (!intentParserResult.approved) {
-            console.error(chalk_1.default.red('\nRequest not approved by intent parser'));
-            return null;
-        }
-        const params = intentParserResult.params;
-        // NOTE: do NOT merge defaultDeviceName into playlistSettings here.
-        // buildPlaylistDirect (src/utilities/index.js) sends whenever
-        // playlistSettings.deviceName is defined, so setting it here would turn
-        // every build-only `chat --device` invocation into an implicit network send.
-        // The CLI --device flag is used only in the two explicit send paths below
-        // (sendMatch shortcut and send_playlist action) via resolveEffectiveDeviceName.
-        // Check if this is a send_playlist action
-        if (params && params.action === 'send_playlist') {
-            // Handle playlist sending directly
-            const sendParams = params;
-            const utilities = getUtilities();
-            const { verifyPlaylist } = await Promise.resolve().then(() => __importStar(require('./utilities/playlist-verifier')));
-            console.log();
-            console.log(chalk_1.default.cyan('Sending to device'));
-            const sendResult = await sendPreparedPlaylistToDevice(sendParams.playlist, {
-                verifyPlaylist,
-                sendToDevice: utilities.sendToDevice,
-                resolveDeviceName: () => resolveSendPlaylistDeviceName(sendParams.deviceName, defaultDeviceName),
-            });
-            if (!sendResult.success) {
-                console.log();
-                console.error(chalk_1.default.red('Send failed'));
-                if (sendResult.error) {
-                    console.error(chalk_1.default.red(`  ${sendResult.error}`));
-                }
-                return {
-                    success: false,
-                    error: sendResult.error || 'Failed to send playlist',
-                    playlist: null,
-                    action: 'send_playlist',
-                };
-            }
-            console.log(chalk_1.default.green('\nPlaylist sent'));
-            if (sendResult.deviceName) {
-                console.log(chalk_1.default.dim(`  Device: ${sendResult.deviceName}`));
-            }
-            console.log();
-            return {
-                success: true,
-                playlist: sendResult.playlist,
-                action: 'send_playlist',
-            };
-        }
-        // Check if this is a publish_playlist action
-        if (params && params.action === 'publish_playlist') {
-            // Publishing was already handled by intent parser, just return the result
-            const publishParams = params;
-            if (publishParams.success) {
-                return {
-                    success: true,
-                    action: 'publish_playlist',
-                    playlistId: publishParams.playlistId,
-                    feedServer: publishParams.feedServer,
-                };
-            }
-            else {
-                return {
-                    success: false,
-                    error: publishParams.error,
-                    action: 'publish_playlist',
-                };
-            }
-        }
-        // STEP 2: AI ORCHESTRATOR (Function Calling)
-        // AI orchestrates function calls to build playlist
-        const { buildPlaylistWithAI } = getAIOrchestrator();
-        let result = await buildPlaylistWithAI(params, {
-            modelName,
-            verbose,
-            outputPath,
-            interactive,
-            defaultDeviceName,
-        });
-        // Handle confirmation loop in interactive mode
-        while (result.needsConfirmation && interactive) {
-            console.log(chalk_1.default.yellow('\n' + result.question));
-            console.log();
-            const rl = readline.createInterface({
-                input: process.stdin,
-                output: process.stdout,
-            });
-            const userResponse = await new Promise((resolve) => {
-                rl.question(chalk_1.default.cyan('Your response: '), (answer) => {
-                    rl.close();
-                    resolve(answer.trim());
-                });
-            });
-            if (!userResponse) {
-                console.error(chalk_1.default.red('\nNo response provided. Canceling.'));
-                return null;
-            }
-            console.log();
-            // Continue orchestrator with user's response
-            result = await buildPlaylistWithAI(result.params, {
-                modelName,
-                verbose,
-                outputPath,
-                interactive,
-                defaultDeviceName,
-                conversationContext: {
-                    messages: result.messages,
-                    userResponse,
-                },
-            });
-        }
-        // If no playlist was built, display the AI's message
-        if (!result.playlist && result.message) {
-            console.log(chalk_1.default.yellow('\n' + result.message));
-        }
-        else if (!result.playlist && result.error) {
-            console.error(chalk_1.default.red('\n' + result.error));
-        }
-        return result;
-    }
-    catch (error) {
-        console.error(chalk_1.default.red('\nError:'), error.message);
-        if (verbose) {
-            console.error(chalk_1.default.dim(error.stack));
-        }
-        throw error;
-    }
-}

package/dist/src/utilities/ff1-device.js

@@ -38,11 +38,16 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isTransientDeviceNetworkError = isTransientDeviceNetworkError;
+exports.parseRetryAfterMs = parseRetryAfterMs;
 exports.sendPlaylistToDevice = sendPlaylistToDevice;
 const logger = __importStar(require("../logger"));
 const ff1_compatibility_1 = require("./ff1-compatibility");
 const SEND_RETRY_ATTEMPTS = 3;
 const SEND_RETRY_BASE_DELAY_MS = 750;
+const RATE_LIMIT_STATUS = 429;
+// Cap how long a device-supplied Retry-After can stall the CLI, so a buggy or
+// hostile device cannot pin a command for minutes/hours.
+const MAX_RETRY_DELAY_MS = 30_000;
 /**
  * Sleep for a short duration before retrying transient network errors.
  *
@@ -96,6 +101,36 @@ function isTransientDeviceNetworkError(error) {
         : undefined;
     return Boolean(causeCode && networkCodes.has(causeCode));
 }
+/**
+ * parseRetryAfterMs converts an HTTP `Retry-After` header into milliseconds.
+ *
+ * Supports both forms from RFC 7231: a delta-seconds integer (e.g. "5") and an
+ * HTTP-date (e.g. "Wed, 21 Oct 2025 07:28:00 GMT"). Returns undefined when the
+ * header is absent or unparseable, so callers can fall back to their own
+ * backoff. A past date clamps to 0 (retry immediately).
+ *
+ * @param {string | null | undefined} headerValue - Raw Retry-After header value
+ * @returns {number | undefined} Delay in milliseconds, or undefined if unknown
+ */
+function parseRetryAfterMs(headerValue) {
+    if (!headerValue) {
+        return undefined;
+    }
+    const trimmed = headerValue.trim();
+    if (/^\d+$/.test(trimmed)) {
+        return Number(trimmed) * 1000;
+    }
+    // A valid HTTP-date always contains letters (month/day names, or the ISO
+    // 'T'/'Z'). Requiring one rejects bare numeric junk (e.g. "-5", "5.5") that
+    // Date.parse would otherwise misinterpret as a date.
+    if (/[a-zA-Z]/.test(trimmed)) {
+        const dateMs = Date.parse(trimmed);
+        if (!Number.isNaN(dateMs)) {
+            return Math.max(0, dateMs - Date.now());
+        }
+    }
+    return undefined;
+}
 /**
  * Send a DP1 playlist to an FF1 device using the cast API
  *
@@ -185,6 +220,17 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
                     headers,
                     body: JSON.stringify(requestBody),
                 });
+                // The device sheds bursts of commands with HTTP 429 to protect itself.
+                // Treat it as transient: honor Retry-After when present, otherwise back
+                // off, and retry within the bounded attempt budget.
+                if (response.status === RATE_LIMIT_STATUS && attempt < SEND_RETRY_ATTEMPTS) {
+                    const retryAfterMs = parseRetryAfterMs(response.headers.get('retry-after'));
+                    const retryDelay = Math.min(retryAfterMs ?? SEND_RETRY_BASE_DELAY_MS * attempt, MAX_RETRY_DELAY_MS);
+                    logger.warn(`Device rate-limited the command (attempt ${attempt}/${SEND_RETRY_ATTEMPTS}); retrying in ${retryDelay}ms`);
+                    response = null;
+                    await waitForRetry(retryDelay);
+                    continue;
+                }
                 break;
             }
             catch (error) {
@@ -212,6 +258,15 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
             const errorText = await response.text();
             logger.error(`Failed to cast to device: ${response.status} ${response.statusText}`);
             logger.debug(`Error details: ${errorText}`);
+            if (response.status === RATE_LIMIT_STATUS) {
+                const deviceLabel = device.name || device.host;
+                return {
+                    success: false,
+                    error: `Device "${deviceLabel}" is busy and rate-limited the command`,
+                    details: 'The Art Computer is shedding a burst of commands to protect itself. ' +
+                        'Wait a few seconds and try again.',
+                };
+            }
             return {
                 success: false,
                 error: `Device returned error ${response.status}: ${response.statusText}`,

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

@@ -21,18 +21,43 @@ function isTimeBasedMedia(mimeType, sourceUrl) {
     const candidates = [String(mimeType || '').toLowerCase(), detectMimeType(sourceUrl)];
     return candidates.some((mime) => mime.startsWith('video/') || mime.startsWith('audio/'));
 }
+/**
+ * isInteractiveWeb reports whether an item is an interactive web page (HTML).
+ *
+ * Such sources have no intrinsic runtime AND no end-of-stream event, so they
+ * are timed differently from both video/audio (which end) and static images
+ * (which need a display duration): they play open-ended. The FF1 player
+ * renders these in a sandboxed iframe.
+ *
+ * Mirrors isTimeBasedMedia's two-signal approach: an explicit `text/html`
+ * MIME hint or a `.html`/`.htm` URL extension qualifies.
+ *
+ * @param {string} [mimeType] - MIME type hint, if any
+ * @param {string} [sourceUrl] - Item source URL, used as an extension fallback
+ * @returns {boolean} True when the source is an interactive HTML page
+ */
+function isInteractiveWeb(mimeType, sourceUrl) {
+    const candidates = [String(mimeType || '').toLowerCase(), detectMimeType(sourceUrl)];
+    return candidates.some((mime) => mime.startsWith('text/html'));
+}
 /**
  * applyItemTiming sets a DP1 item's playback timing per DP-1 §4.1.
  *
  * Invariant this function owns: an explicit numeric `duration` always wins
- * and is stamped as-is. When `duration` is undefined/null ("auto"), a
- * time-based source (video/audio) gets NO duration and `display.loop: false`,
- * so a conformant player MUST advance at end-of-stream — the media plays its
- * natural length. Static and code-based sources fall back to the configured
- * `defaultDuration` because they have no intrinsic runtime to play out.
+ * and is stamped as-is. When `duration` is undefined/null ("auto"):
+ *   - a time-based source (video/audio) gets NO duration and
+ *     `display.loop: false`, so a conformant player MUST advance at
+ *     end-of-stream — the media plays its natural length;
+ *   - an interactive web page (HTML) gets NO duration either, but for the
+ *     opposite reason: it has no end-of-stream event, so a conformant player
+ *     parks on it indefinitely (the generative/interactive art keeps running);
+ *   - static and code-based sources fall back to the configured
+ *     `defaultDuration` because they have no intrinsic runtime to play out.
  *
  * Do not re-introduce an unconditional duration here: stamping a default on
- * video items silently truncates or pads them (the bug this fixed).
+ * video items silently truncates or pads them, and stamping one on an HTML
+ * page cuts the artwork off and restarts it every `defaultDuration` seconds
+ * (the bugs this guards against).
  *
  * @param {Object} item - DP1 playlist item (mutated in place)
  * @param {Object} mediaHints - Media signals for the time-based check
@@ -50,6 +75,11 @@ function applyItemTiming(item, mediaHints = {}, duration) {
         item.display = { ...(item.display || {}), loop: false };
         return item;
     }
+    if (isInteractiveWeb(mediaHints.mimeType, mediaHints.sourceUrl)) {
+        // No duration: an open-ended interactive page should play until the
+        // playlist advances for another reason, not on a fixed timer.
+        return item;
+    }
     item.duration = getDefaultStaticDuration();
     return item;
 }
@@ -496,20 +526,24 @@ function validateDP1Playlist(playlist) {
     };
 }
 /**
- * Detect MIME type from URL or file extension
+ * Detect MIME type from a URL or file extension.
  *
- * Analyzes URL to determine appropriate MIME type for media content.
- * Supports images, videos, audio, and 3D models.
+ * Maps known media/web extensions to a MIME type. Returns '' (empty) when the
+ * extension is unknown or absent — the type is genuinely undetermined, and
+ * callers decide the fallback. (Do NOT default to 'image/png': that silently
+ * misclassified HTML pages and extensionless URLs as static images, stamping
+ * them with a display duration that cut interactive artworks off.)
  *
- * @param {string} url - Media URL
- * @returns {string} MIME type
+ * @param {string} url - Media or page URL
+ * @returns {string} MIME type, or '' when undetermined
  * @example
- * const mimeType = detectMimeType('https://example.com/image.png');
- * // Returns: 'image/png'
+ * detectMimeType('https://example.com/image.png'); // 'image/png'
+ * detectMimeType('https://example.com/art.html');  // 'text/html'
+ * detectMimeType('https://example.com/output/abc'); // ''
  */
 function detectMimeType(url) {
     if (!url) {
-        return 'image/png';
+        return '';
     }
     const extension = url.split('.').pop()?.toLowerCase().split('?')[0];
     const mimeTypes = {
@@ -519,6 +553,8 @@ function detectMimeType(url) {
         gif: 'image/gif',
         webp: 'image/webp',
         svg: 'image/svg+xml',
+        html: 'text/html',
+        htm: 'text/html',
         mp4: 'video/mp4',
         webm: 'video/webm',
         mp3: 'audio/mpeg',
@@ -526,7 +562,7 @@ function detectMimeType(url) {
         glb: 'model/gltf-binary',
         gltf: 'model/gltf+json',
     };
-    return mimeTypes[extension] || 'image/png';
+    return mimeTypes[extension] || '';
 }
 /**
  * Build a single DP1 playlist item from a URL
@@ -584,7 +620,13 @@ function buildUrlItem(url, duration, options = {}) {
             margin: 0,
         },
     };
-    return applyItemTiming(item, { sourceUrl, mimeType: options.mimeType }, duration);
+    // A URL handed to `play` that isn't a recognized media file is treated as an
+    // interactive web page: the FF1 renders unknown URLs in a sandboxed iframe,
+    // so an explicit caller hint aside, "unknown" means web, not static image.
+    // This routes such items through the open-ended (no-duration) timing path
+    // instead of the static-image default.
+    const mimeHint = options.mimeType || (detectMimeType(sourceUrl) === '' ? 'text/html' : undefined);
+    return applyItemTiming(item, { sourceUrl, mimeType: mimeHint }, duration);
 }
 module.exports = {
     convertTokenToDP1Item,
@@ -595,6 +637,7 @@ module.exports = {
     validateDP1Playlist,
     detectMimeType,
     isTimeBasedMedia,
+    isInteractiveWeb,
     applyItemTiming,
     buildUrlItem,
 };

package/docs/CONFIGURATION.md

@@ -21,35 +21,10 @@ npm run dev -- config show
 
 ## Top‑level fields
 
-- **defaultModel** (string)
-  - The default AI model key to use. Must match a key under `models`.
-  - Used by orchestration to pick API, timeouts, and model identifier.
-
 - **defaultDuration** (number, seconds)
   - Default per‑item display duration for media without an intrinsic runtime (images, code-based works). Falls back to 10s when unset.
   - Does NOT apply to video/audio items: with no explicit duration those are emitted without `duration` and with `display.loop: false`, so a DP-1 player advances at end-of-stream (§4.1) — the media plays its natural length.
 
-## models
-
-Each key under `models` defines a model configuration used by the AI orchestrator.
-
-- `<modelName>.apiKey` (string): API key for the provider.
-- `<modelName>.baseURL` (string): Base API URL.
-- `<modelName>.model` (string): Model identifier (e.g., `grok-beta`, `gpt-4o`).
-- `<modelName>.availableModels` (string[], optional): Display/help only.
-- `<modelName>.timeout` (number, ms): HTTP timeout for requests.
-- `<modelName>.maxRetries` (number): Retry count for requests.
-- `<modelName>.temperature` (number): Generation temperature.
-- `<modelName>.maxTokens` (number): Token cap.
-- `<modelName>.supportsFunctionCalling` (boolean): Must be true; otherwise the CLI rejects the model.
-
-Environment variable helpers:
-
-- Anthropic (Claude): `ANTHROPIC_API_KEY`
-- Grok: `GROK_API_KEY`, `GROK_MODEL`, `GROK_API_BASE_URL`
-- OpenAI: `OPENAI_API_KEY`
-- Gemini: `GEMINI_API_KEY`
-
 ## browser
 
 Optional settings used where headless/browser‑like behavior is needed.
@@ -182,15 +157,6 @@ Minimal `config.json` example (selected fields):
 
 ```json
 {
-  "defaultModel": "claude",
-  "models": {
-    "claude": {
-      "apiKey": "sk-ant-your-api-key-here",
-      "baseURL": "https://api.anthropic.com/v1/",
-      "model": "claude-sonnet-4-6",
-      "supportsFunctionCalling": true
-    }
-  },
   "defaultDuration": 10,
   "playlist": {
     "privateKey": "your_ed25519_private_key_hex_or_base64_here",