@feralfile/cli 3.0.0 → 4.0.0

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

@@ -37,21 +37,36 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isTransientDeviceNetworkError = isTransientDeviceNetworkError;
-exports.parseRetryAfterMs = parseRetryAfterMs;
+exports.parseRetryAfterMs = exports.isTransientDeviceNetworkError = void 0;
 exports.sendPlaylistToDevice = sendPlaylistToDevice;
+exports.publicControlCode = publicControlCode;
 const http_1 = require("./http");
 const logger = __importStar(require("../logger"));
 const config_1 = require("../config");
 const ff1_compatibility_1 = require("./ff1-compatibility");
 const ff1_relayer_1 = require("./ff1-relayer");
 const topic_store_1 = require("./topic-store");
+const secure_transport_1 = require("./control/secure-transport");
+const control_errors_1 = require("./control/control-errors");
+const device_network_1 = require("./device-network");
+Object.defineProperty(exports, "isTransientDeviceNetworkError", { enumerable: true, get: function () { return device_network_1.isTransientDeviceNetworkError; } });
+Object.defineProperty(exports, "parseRetryAfterMs", { enumerable: true, get: function () { return device_network_1.parseRetryAfterMs; } });
 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;
+// PUBLIC_CONTROL_CODES are the ff1-control-v1 §4.4 public errors a secured
+// FF1 can answer a plaintext cast with (LAN 401/403, relayer RPC message).
+const PUBLIC_CONTROL_CODES = new Set([
+    'bad_envelope',
+    'unknown_controller',
+    'bad_signature',
+    'enrollment_required',
+    'envelope_required',
+    'locked',
+]);
 /** Find an FF1 `ok` flag through the nested cast response envelopes. */
 function nestedCastOk(value) {
     if (!value || typeof value !== 'object') {
@@ -74,78 +89,6 @@ function waitForRetry(delayMs) {
         setTimeout(resolve, delayMs);
     });
 }
-/**
- * isTransientDeviceNetworkError returns true when a send failure is likely temporary.
- *
- * This classifier intentionally targets resolver and route-level failures that are
- * common on local mDNS/Wi-Fi environments. Permanent command errors should surface
- * immediately without retry loops.
- *
- * @param {unknown} error - Error thrown by fetch
- * @returns {boolean} True when retrying is likely to recover
- */
-function isTransientDeviceNetworkError(error) {
-    if (!(error instanceof Error)) {
-        return false;
-    }
-    const networkCodes = new Set([
-        'EHOSTUNREACH',
-        'ENETUNREACH',
-        'ENOTFOUND',
-        'EAI_AGAIN',
-        'ETIMEDOUT',
-        'ECONNREFUSED',
-        'ECONNRESET',
-    ]);
-    const message = error.message || '';
-    const messageLooksTransient = message.includes('fetch failed') ||
-        message.includes('getaddrinfo') ||
-        message.includes('EHOSTUNREACH') ||
-        message.includes('ENOTFOUND') ||
-        message.includes('ETIMEDOUT') ||
-        message.includes('network timeout') ||
-        message.includes('No route to host');
-    if (messageLooksTransient) {
-        return true;
-    }
-    const causeCode = error.cause &&
-        typeof error.cause === 'object' &&
-        'code' in error.cause &&
-        typeof error.cause.code === 'string'
-        ? error.cause.code
-        : 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
  *
@@ -186,6 +129,8 @@ async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
         getRelayerConfigFn: overrides.getRelayerConfigFn ?? config_1.getFF1RelayerConfig,
         waitFn: overrides.waitFn ?? waitForRetry,
         noticeFn: overrides.noticeFn ?? logger.always,
+        controllerStore: overrides.controllerStore,
+        nowFn: overrides.nowFn,
     };
     let device;
     try {
@@ -204,16 +149,30 @@ async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
             };
         }
         device = resolved.device;
+        // A stored controller file means this FF1 was paired under the control
+        // protocol (ff1-control-v1): every command goes as a secure envelope and
+        // the legacy plaintext path below is never used for it.
+        const secure = (0, secure_transport_1.findSecureController)(device, dependencies.controllerStore);
+        if (secure.failure) {
+            return { success: false, error: secure.failure.error, details: secure.failure.details };
+        }
         const compatibility = await (0, ff1_compatibility_1.assertFF1CommandCompatibility)(device, 'displayPlaylist', {
             fetchFn: dependencies.fetchFn,
+            controller: secure.record
+                ? { record: secure.record, deps: secureDeps(dependencies) }
+                : undefined,
         });
         if (!compatibility.compatible) {
             return {
                 success: false,
                 error: compatibility.error || 'FF1 OS does not support playlist casting',
-                details: compatibility.version ? `Detected version ${compatibility.version}` : undefined,
+                details: compatibility.details ??
+                    (compatibility.version ? `Detected version ${compatibility.version}` : undefined),
             };
         }
+        if (secure.record) {
+            return sendPlaylistSecurely(playlist, device, secure.record, dependencies);
+        }
         logger.info(`Sending playlist to FF1 device: ${device.host}`);
         const apiUrl = `${device.host}/api/cast`;
         // Wrap playlist in required structure
@@ -251,7 +210,7 @@ async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
                 // 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 retryAfterMs = (0, device_network_1.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;
@@ -291,7 +250,7 @@ async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
                 break;
             }
             catch (error) {
-                const shouldRetry = attempt < SEND_RETRY_ATTEMPTS && isTransientDeviceNetworkError(error);
+                const shouldRetry = attempt < SEND_RETRY_ATTEMPTS && (0, device_network_1.isTransientDeviceNetworkError)(error);
                 if (!shouldRetry) {
                     throw error;
                 }
@@ -320,6 +279,11 @@ async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
             const errorText = await response.text();
             logger.error(`Failed to cast to device: ${response.status} ${response.statusText}`);
             logger.debug(`Error details: ${errorText}`);
+            const publicCode = publicControlCode(response.status, errorText);
+            if (publicCode) {
+                const failure = (0, control_errors_1.describeControlCode)(publicCode, device.name || device.id || device.host);
+                return { success: false, error: failure.error, details: failure.details };
+            }
             if (response.status === RATE_LIMIT_STATUS) {
                 const deviceLabel = device.name || device.host;
                 return {
@@ -368,7 +332,7 @@ async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
     catch (error) {
         const errorMessage = error.message;
         logger.error(`Error sending playlist to device: ${errorMessage}`);
-        if (device && isTransientDeviceNetworkError(error)) {
+        if (device && (0, device_network_1.isTransientDeviceNetworkError)(error)) {
             const deviceLabel = device.name || device.host;
             return fallbackToRelayer({
                 playlist,
@@ -388,6 +352,117 @@ async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
         };
     }
 }
+/**
+ * secureDeps forwards the delivery seams to the secure transport.
+ *
+ * @param dependencies - Resolved delivery dependencies
+ * @returns Secure transport dependencies
+ */
+function secureDeps(dependencies) {
+    return {
+        fetchFn: dependencies.fetchFn,
+        getTopicIdFn: dependencies.getTopicIdFn,
+        getRelayerConfigFn: dependencies.getRelayerConfigFn,
+        waitFn: dependencies.waitFn,
+        noticeFn: dependencies.noticeFn,
+        controllerStore: dependencies.controllerStore,
+        nowFn: dependencies.nowFn,
+    };
+}
+/**
+ * sendPlaylistSecurely delivers displayPlaylist as a secure envelope with the
+ * same retry budget and LAN-then-relayer fallback as the plaintext path. The
+ * `req` is the unchanged plaintext request object (§3.3).
+ *
+ * @param playlist - DP-1 playlist
+ * @param device - Device with a stored controller record
+ * @param record - Enrolled controller record
+ * @param dependencies - Delivery seams
+ * @returns Send result
+ */
+async function sendPlaylistSecurely(playlist, device, record, dependencies) {
+    logger.info(`Sending playlist to FF1 device (secure): ${device.host}`);
+    const result = await (0, secure_transport_1.runSecureCommand)({
+        device: device,
+        record,
+        cmd: 'displayPlaylist',
+        req: { dp1_call: playlist, intent: { action: 'now_display' } },
+        relayerFallback: true,
+        retry: true,
+    }, secureDeps(dependencies));
+    const deviceName = device.name || device.host;
+    if (!result.success) {
+        return {
+            success: false,
+            error: result.error,
+            details: result.details,
+            transport: result.transport,
+        };
+    }
+    if (nestedCastOk(result.response) === false) {
+        return {
+            success: false,
+            error: `Device "${deviceName}" rejected the display command`,
+            details: JSON.stringify(result.response),
+            transport: result.transport,
+        };
+    }
+    const viaRelayer = result.transport === 'relayer';
+    return {
+        success: true,
+        device: device.host,
+        deviceName,
+        response: result.response,
+        message: viaRelayer
+            ? 'Playlist successfully sent through the FF1 relayer'
+            : 'Playlist successfully sent to FF1 device',
+        transport: result.transport,
+    };
+}
+/**
+ * publicControlCode extracts a control-protocol public error (§4.4) from a
+ * LAN 401/403, e.g. a secured FF1 refusing plaintext with
+ * `enrollment_required`. Other bodies return undefined.
+ *
+ * @param status - HTTP status
+ * @param body - Response text
+ * @returns The code, or undefined
+ */
+function publicControlCode(status, body) {
+    if (status !== 401 && status !== 403) {
+        return undefined;
+    }
+    try {
+        const code = JSON.parse(body)?.error?.code;
+        return typeof code === 'string' && PUBLIC_CONTROL_CODES.has(code) ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * plaintextRefusalCode finds a control-protocol refusal in a relayer reply:
+ * the flat plaintext denial `{ok:false,error:"<code>",command,message}` or the
+ * public-error shape `{error:{code}}`, at any of the relayer's nesting levels.
+ *
+ * @param response - Parsed relayer response
+ * @returns A §4.4 code, or undefined
+ */
+function plaintextRefusalCode(response) {
+    let current = response;
+    for (let depth = 0; depth < 3 && current && typeof current === 'object'; depth += 1) {
+        const record = current;
+        const error = record.error;
+        const code = record.ok === false && typeof error === 'string'
+            ? error
+            : error?.code;
+        if (typeof code === 'string' && PUBLIC_CONTROL_CODES.has(code)) {
+            return code;
+        }
+        current = record.message;
+    }
+    return undefined;
+}
 /**
  * Fall back to the relayer only after LAN reachability is exhausted.
  *
@@ -437,6 +512,14 @@ async function fallbackToRelayer(input) {
         playlist: input.playlist,
         fetchFn: input.dependencies.fetchFn,
     });
+    // A secured FF1 refuses a plaintext relayer cast it will not run
+    // (ff1-control-v1 §4.4/§7.2) with a flat `{ok:false,error:"<code>"}` RPC
+    // message; map it to pairing guidance instead of a bare rejection.
+    const refusal = plaintextRefusalCode(result.response);
+    if (refusal) {
+        const failure = (0, control_errors_1.describeControlCode)(refusal, input.device.name ?? input.device.id);
+        return { success: false, error: failure.error, details: failure.details, transport: 'relayer' };
+    }
     if (!result.success) {
         return {
             success: false,

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sendPlaylistViaRelayer = sendPlaylistViaRelayer;
+exports.sendCastViaRelayer = sendCastViaRelayer;
 const http_1 = require("./http");
 function nestedOk(value) {
     if (!value || typeof value !== 'object') {
@@ -27,6 +28,37 @@ function nestedOk(value) {
  * and JSON parsing errors.
  */
 async function sendPlaylistViaRelayer(input) {
+    const result = await sendCastViaRelayer({
+        ...input,
+        body: {
+            command: 'displayPlaylist',
+            request: {
+                dp1_call: input.playlist,
+                intent: { action: 'now_display' },
+            },
+        },
+    });
+    if (result.success && nestedOk(result.response) === false) {
+        return {
+            success: false,
+            error: 'FF1 rejected the relayer display command',
+            details: JSON.stringify(result.response),
+            response: result.response,
+        };
+    }
+    return result;
+}
+/**
+ * sendCastViaRelayer posts one cast body to the relayer topic endpoint and
+ * returns the parsed JSON response without interpreting the device's answer.
+ * It is shared by the legacy plaintext Play path and the secure `ff1Envelope`
+ * path (ff1-control-v1 §10: the envelope rides the same topic cast).
+ *
+ * @param input - Relayer endpoint, optional compatibility key, paired topic,
+ * cast body, and optional fetch implementation.
+ * @returns The parsed relayer response, or a structured failure.
+ */
+async function sendCastViaRelayer(input) {
     // Production default rides the shared deadline (#101 review).
     const fetchFn = input.fetchFn ?? http_1.defaultDeadlineFetch;
     let url;
@@ -53,13 +85,7 @@ async function sendPlaylistViaRelayer(input) {
             // the mobile request shape and topic query parameter.
             method: 'POST',
             headers,
-            body: JSON.stringify({
-                command: 'displayPlaylist',
-                request: {
-                    dp1_call: input.playlist,
-                    intent: { action: 'now_display' },
-                },
-            }),
+            body: JSON.stringify(input.body),
         });
     }
     catch (error) {
@@ -78,6 +104,7 @@ async function sendPlaylistViaRelayer(input) {
         return {
             success: false,
             error: `FF1 relayer returned HTTP ${response.status}`,
+            status: response.status,
             details: needsCompatibilityKey
                 ? 'This relayer deployment still requires its optional FF1_RELAYER_API_KEY compatibility gate.'
                 : bodyText || response.statusText,
@@ -96,12 +123,5 @@ async function sendPlaylistViaRelayer(input) {
             };
         }
     }
-    if (nestedOk(data) === false) {
-        return {
-            success: false,
-            error: 'FF1 rejected the relayer display command',
-            details: bodyText,
-        };
-    }
     return { success: true, response: data };
 }

package/dist/src/utilities/handoff-client.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TopicHandoffReceiver = void 0;
+exports.HandoffReceiver = void 0;
+exports.parseHandoffPayload = parseHandoffPayload;
 const http_1 = require("./http");
 const handoff_crypto_1 = require("./handoff-crypto");
 const DEFAULT_HANDOFF_URL = 'https://handoff.feralfile.com';
@@ -33,6 +34,19 @@ function parsePoll(value, channelId) {
     }
     return record;
 }
+/**
+ * parseHandoffPayload accepts a v1 topic handoff for the selected device and
+ * rejects everything else, including a retired v2 controller handoff.
+ *
+ * @param value - Decrypted handoff plaintext
+ * @param channelId - This receiver's channel
+ * @param expectedDeviceId - The configured device's stable ID
+ * @returns The validated payload
+ * @throws {Error} When the payload is for another channel or device, or malformed
+ */
+function parseHandoffPayload(value, channelId, expectedDeviceId) {
+    return parseTopicPayload(value, channelId, expectedDeviceId);
+}
 function parseTopicPayload(value, channelId, expectedDeviceId) {
     const payload = value;
     if (payload?.v !== 1 ||
@@ -48,8 +62,8 @@ function parseTopicPayload(value, channelId, expectedDeviceId) {
     }
     return payload;
 }
-/** One short-lived CLI-side channel waiting for a mobile topic transfer. */
-class TopicHandoffReceiver {
+/** One short-lived CLI-side channel waiting for a mobile topic handoff. */
+class HandoffReceiver {
     baseUrl;
     channelId;
     shortCode;
@@ -90,10 +104,10 @@ class TopicHandoffReceiver {
             channelId: created.channelId,
             minterPublicKeyJwk: publicKey,
         });
-        return new TopicHandoffReceiver(baseUrl, created.channelId, created.shortCode, verificationCode, created.expiresAt, created.minterToken, keyPair.privateKey, fetchFn);
+        return new HandoffReceiver(baseUrl, created.channelId, created.shortCode, verificationCode, created.expiresAt, created.minterToken, keyPair.privateKey, fetchFn);
     }
-    /** Poll until mobile sends a valid encrypted topic for the selected device. */
-    async receiveTopic(options) {
+    /** Poll until mobile sends a valid encrypted topic handoff for the selected device. */
+    async receiveHandoff(options) {
         const deadline = Date.now() + (options.maxWaitMs ?? 300_000);
         let afterSeq = 0;
         while (Date.now() <= deadline) {
@@ -117,11 +131,11 @@ class TopicHandoffReceiver {
                     seq: message.seq,
                     message,
                 });
-                return parseTopicPayload(plaintext, this.channelId, options.expectedDeviceId);
+                return parseHandoffPayload(plaintext, this.channelId, options.expectedDeviceId);
             }
             await new Promise((resolve) => setTimeout(resolve, options.pollIntervalMs ?? 1000));
         }
-        throw new Error('Timed out waiting for the mobile app topic transfer');
+        throw new Error('Timed out waiting for the mobile app handoff');
     }
     /** Close the broker channel and invalidate its participant credentials. */
     async close() {
@@ -134,4 +148,4 @@ class TopicHandoffReceiver {
         }
     }
 }
-exports.TopicHandoffReceiver = TopicHandoffReceiver;
+exports.HandoffReceiver = HandoffReceiver;

package/dist/src/utilities/neort-marketplace.js

@@ -64,9 +64,9 @@ const user_agent_1 = require("./user-agent");
 const NEORT_API_BASE = 'https://api.neort.io/v1';
 const NEORT_CDN_BASE = 'https://d32h66pp7fue57.cloudfront.net';
 /**
- * Resolve a Neort art id to a playable asset URL plus title/artist metadata.
+ * Resolve a Neort art id to a displayable asset URL plus title/artist metadata.
  *
- * @throws When the id is unknown, the art is private, or no playable asset
+ * @throws When the id is unknown, the art is private, or no displayable asset
  *   can be constructed from the response.
  */
 async function resolveNeortArt(id) {
@@ -90,7 +90,7 @@ async function resolveNeortArt(id) {
         ? `${NEORT_CDN_BASE}/artPreview/${data.resourceFileName}`
         : thumbnailUrl;
     if (!assetUrl) {
-        throw new Error(`Neort: art "${id}" has no playable asset (resourceFileName and thumbnail are both empty).`);
+        throw new Error(`Neort: art "${id}" has no displayable asset (resourceFileName and thumbnail are both empty).`);
     }
     return {
         id: data.id,

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

@@ -629,7 +629,7 @@ function detectMimeType(url) {
  *   e.g. extensionless IPFS gateway URLs, where without this hint a video
  *   would be misclassified as a static image and stamped a fixed duration.
  * @param {boolean} [options.asWebPage] - Time the item as a web page whatever
- *   the URL's extension says (`play --web`)
+ *   the URL's extension says (`display --web`)
  * @returns {Object} DP1 playlist item
  */
 function buildUrlItem(url, duration, options = {}) {
@@ -669,13 +669,13 @@ function buildUrlItem(url, duration, options = {}) {
         .license('open')
         // offChainURI has no provenance.uri in the DP-1 schema — only type.
         .provenance(new ProvenanceBuilder().type('offChainURI'));
-    // A URL handed to `play` that isn't a recognized media file is treated as an
+    // A URL handed to `display` 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);
-    // `play --web` says the URL is a page whatever its path looks like. Timing
+    // `display --web` says the URL is a page whatever its path looks like. Timing
     // checks the URL extension before the MIME hint, so a page served at
     // /page.mp4 would otherwise be timed as video (no duration, loop false);
     // leaving the URL out of the timing hints makes the page timing win.

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

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.castPlaylist = castPlaylist;
 /**
- * DP-1 signature role used when signing a playlist for playback.
+ * DP-1 signature role used when signing a playlist for display.
  *
  * A cast never passes through a feed, so a document signed here carries no `feed` signature and its own
  * entry is the only one a player could judge. DP-1 §7.1.1 rule 1 has players verify a `feed` or `curator`
@@ -26,15 +26,15 @@ const { signPlaylist } = require('./playlist-signer');
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { sendPlaylistToDevice } = require('./ff1-device');
 /**
- * Shared "(sign →) verify → send to device" sequence used by `play` and
- * `find --play`.
+ * Shared "(sign →) verify → send to device" sequence used by `display` and
+ * `find --display`.
  *
  * This is the single source of truth for getting a playlist onto an FF1: the
  * verification gate, the synthesized-media auto-sign (rebuilding the
  * `signatures[]` envelope), and the device transport. Callers own their
  * console output and map the returned `stage`/`error` to their own messages —
  * keeping delivery behavior consistent without coupling the two commands'
- * UX. Previously this logic was duplicated across `play`, `find`, and the
+ * UX. Previously this logic was duplicated across `display`, `find`, and the
  * (now-removed) chat send path, and drifted between them.
  */
 async function castPlaylist(playlist, options = {}) {
@@ -50,7 +50,7 @@ async function castPlaylist(playlist, options = {}) {
                     signed: false,
                     verified: false,
                     stage: 'sign',
-                    error: 'Cannot sign playlist for playback: no playlist signing key is configured',
+                    error: 'Cannot sign playlist for display: no playlist signing key is configured',
                 };
             }
             try {
@@ -69,7 +69,7 @@ async function castPlaylist(playlist, options = {}) {
                     signed: false,
                     verified: false,
                     stage: 'sign',
-                    error: `Failed to sign playlist for playback: ${error.message}`,
+                    error: `Failed to sign playlist for display: ${error.message}`,
                 };
             }
         }

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

@@ -141,7 +141,7 @@ async function loadPlaylistSource(source) {
 }
 /**
  * buildMediaPlaySource wraps a URL in a synthesized single-item playlist, the
- * shape `play` sends for a direct media file or web page.
+ * shape `display` sends for a direct media file or web page.
  *
  * @param {string} url - Trimmed http(s) URL
  * @param {Object} [options] - Item options
@@ -174,11 +174,11 @@ function looksLikePlaylistUrl(url) {
     }
 }
 /**
- * refusalForLoadFailure returns the error `play` must stop with when a URL it
+ * refusalForLoadFailure returns the error `display` must stop with when a URL it
  * tried to load is known not to exist, or null when it may still be sent.
  *
  * Wrapping a URL that does not exist sends the device an error page and
- * reports "Playing", the silent wrong result an agent trusting exit codes
+ * reports "Displaying", the silent wrong result an agent trusting exit codes
  * cannot catch. These are refused:
  * - HTTP 404 or 410: nothing is there.
  * - DNS failure (ENOTFOUND): the host does not exist. A temporary resolver
@@ -206,7 +206,7 @@ function refusalForLoadFailure(url, failure) {
     return null;
 }
 /**
- * noteForLoadFailure returns the line `play` prints when it sends a URL it
+ * noteForLoadFailure returns the line `display` prints when it sends a URL it
  * could not read itself, or undefined when the URL was read in full and is
  * simply not a playlist (an ordinary page or media file).
  *
@@ -221,11 +221,11 @@ function noteForLoadFailure(failure) {
     return `ff-cli could not read this URL itself (${failure?.message}); sending it to the device anyway.`;
 }
 /**
- * checkWebPageUrl fetches a URL that `play --web` is about to send, refusing
+ * checkWebPageUrl fetches a URL that `display --web` is about to send, refusing
  * one that does not exist and returning a note when it could not be read.
  *
  * `--web` skips the playlist probe, so without this check a typo or a dead
- * link handed to `--web` (the hint `play` prints for marketplace pages) would
+ * link handed to `--web` (the hint `display` prints for marketplace pages) would
  * be cast as an error page with a successful exit. Only the status line is
  * needed; the body is cancelled unread. The `.json` rule does not apply: the
  * caller said this is a page.
@@ -259,7 +259,7 @@ async function checkWebPageUrl(url) {
     return noteForLoadFailure(failure);
 }
 /**
- * Resolve a `play` command argument to a playable source.
+ * Resolve a `display` command argument to a source it can send.
  *
  * Files are always treated as playlists. URLs are tried as playlists first;
  * a URL whose body is not a playlist (an ordinary web page, a video, an

package/dist/src/utilities/raster-client.js

@@ -95,7 +95,7 @@ const INDEXER_CHAIN_TO_CAIP = {
  * Raster could not be reached at the network level (connect failure, broken
  * IPv6 path, timeout). Distinct from API-level errors so callers that hold
  * usable token coordinates can degrade gracefully instead of dying — Raster
- * only enriches a find, it is not required to build a playable playlist.
+ * only enriches a find, it is not required to build a playlist to display.
  */
 class RasterUnreachableError extends Error {
     constructor(message) {