fix: snapshot skips private files, no text-art demuxers, escaped warning text (#7943)

* fix(engine): video warnings show control characters in the src as visible escapes

The missing-source and opaque-alpha warnings pass the authored src, and the path
built from it, through terminalText before writing them to stderr.

* fix(cli): snapshot never probes or decodes a private project file for a page video

projectLocalFile applies the same private-file rule as the render readers, judged as written
and with links resolved, so held-video probes and frame injection skip those files. Studio's
own prepared-assets and requests folders still resolve.

* fix(parsers,engine): media inputs never select a text-art demuxer

The media format allowlist leaves out tty, bin, xbin, idf and adf, so ffmpeg and ffprobe
cannot draw a text file as a video frame, whether or not ffprobe is installed. ffprobe's
refusal of one of these formats still reports the source as a text file.

A link inside the project whose target is outside it is still read by snapshot: links a
person puts in their own project are accepted, imported projects cannot carry links, and
render reads them the same way.

* fix(cli): registry warnings show control characters as visible escapes

A project's hyperframes.json can name the registry, so item names and deprecation text
from it pass through terminalText before the studio install, remote template and
item-loading warnings write them to stderr.

* fix(cli): failed render and frame read messages escape control characters

The render failure box escapes each line of the message, keeping its line breaks, and
snapshot's frame read errors escape the path and the ffmpeg or ffprobe text they quote.

* test(cli): probe a missing path with control characters instead of creating it

Windows cannot create a file with those characters in its name; the failed probe's
message still carries the path.
This commit is contained in:
Michael Wang
2026-11-16 18:13:39 +00:00
committed by GitHub
parent a9b0371c83
commit 8959deb00f
19 changed files with 238 additions and 19 deletions
+26
View File
@@ -543,6 +543,32 @@ describe("renderLocal browser GPU config", () => {
expect(cpuSamplerState.samplers.map((s) => s.stopped)).toEqual([true, true]);
});
it("shows control characters in a failed render's message as escapes, one line each", async () => {
producerState.executeImpl = async () => {
throw new Error("FFmpeg could not read clip\u009b\b\r.mp4\nsecond\u0007 line");
};
const errors = vi.spyOn(console, "error").mockImplementation(() => {});
try {
await expect(
renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
fps: { num: 30, den: 1 },
quality: "standard",
format: "mp4",
gpu: false,
browserGpuMode: "software",
hdrMode: "auto",
quiet: true,
}),
).rejects.toMatchObject({ name: "CliRuntimeError" });
const output = errors.mock.calls.map((call) => String(call[0])).join("\n");
expect(output).toContain("clip\\x9b\\x08\\x0d.mp4");
expect(output).toMatch(/\n\s*.*second\\x07 line/);
for (const control of ["\u009b", "\b", "\r", "\u0007"]) expect(output).not.toContain(control);
} finally {
errors.mockRestore();
}
});
it.each([
{ kind: "solid", rgb: [10, 46, 138] },
{ kind: "none" },
+4 -2
View File
@@ -161,6 +161,7 @@ import {
checkOutputResolutionCompatibility,
suggestMatchingPreset,
fpsToNumber,
terminalText,
type CanvasResolution,
type OutputResolutionIssueKind,
type Fps,
@@ -1965,12 +1966,13 @@ function handleRenderError(
if (options.throwOnError) {
throw new Error(message);
}
const shown = message.split(/\r?\n/).map(terminalText).join("\n");
const launch = chromeLaunchFailure(message);
if (launch) {
errorBox(launch.title, message, launch.remediation);
errorBox(launch.title, shown, launch.remediation);
failCommand();
}
errorBox("Render failed", message, hint);
errorBox("Render failed", shown, hint);
failCommand();
}
@@ -536,6 +536,20 @@ describe("extractVideoFrameToBuffer", () => {
!noProbe &&
execFileSync(ffmpeg!, ["-hide_banner", "-encoders"], { encoding: "utf-8" }).includes("libx265");
it.skipIf(noProbe)("shows control characters in a failed probe's path as escapes", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-snapshot-probe-text-"));
try {
const clip = join(dir, "clip\u0007\b\u009b.mp4");
const probe = probeContainingSourceFrameSeek(clip, 0.5, false);
await expect(probe).rejects.toThrow("clip\\x07\\x08\\x9b.mp4");
const message = await probe.catch((error: Error) => error.message);
for (const control of ["\u0007", "\b", "\u009b", "\r"])
expect(message).not.toContain(control);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it.skipIf(noProbe)("selects containing frames for snapshots and reference pairs", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-snapshot-containing-"));
try {
+5 -1
View File
@@ -413,7 +413,11 @@ export function containingSourceFrameIndex(timestamps: readonly number[], time:
return index;
}
class FrameExtractError extends Error {}
class FrameExtractError extends Error {
constructor(message: string) {
super(terminalText(message));
}
}
const lastLine = (text: string) => text.trim().split("\n").at(-1) ?? "";
@@ -1,7 +1,7 @@
import { execFileSync } from "node:child_process";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { dirname, join } from "node:path";
import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
const run = vi.hoisted(() => vi.fn());
@@ -63,6 +63,29 @@ describe("projectLocalFile", () => {
])("gives null for %s", (_label, src) => {
expect(projectLocalFile(dir, src)).toBeNull();
});
it.each([".hyperframes/handoff.mp4", ".git/clip.mp4", ".env", "keys/id_ed25519"])(
"gives null for the private project file %s",
(rel) => {
mkdirSync(dirname(join(dir, rel)), { recursive: true });
writeFileSync(join(dir, rel), "x");
expect(projectLocalFile(dir, `http://127.0.0.1:3000/${rel}`)).toBeNull();
},
);
it("gives null for a link whose target is a private project file", () => {
mkdirSync(join(dir, ".hyperframes"), { recursive: true });
writeFileSync(join(dir, ".hyperframes", "record.mp4"), "x");
symlinkSync(join(dir, ".hyperframes", "record.mp4"), join(dir, "clips", "link.mp4"));
expect(projectLocalFile(dir, "clips/link.mp4")).toBeNull();
});
it("names a file in Studio's own prepared-assets folder", () => {
const rel = ".hyperframes/prepared-assets/clip.mp4";
mkdirSync(dirname(join(dir, rel)), { recursive: true });
writeFileSync(join(dir, rel), "x");
expect(projectLocalFile(dir, rel)).toBe(join(dir, rel));
});
});
const probeJson = (stream: object, duration = "12.480000") =>
@@ -141,6 +164,16 @@ describe("heldVideoHints", () => {
{ id: "wide", width: 1280, height: 720 },
]);
});
it("never probes a private project file", async () => {
mkdirSync(join(dir, ".hyperframes"), { recursive: true });
writeFileSync(join(dir, ".hyperframes", "record.mp4"), "x");
run.mockResolvedValue({ stdout: probeJson({ width: 1280, height: 720 }) });
const videos = [{ id: "kept", src: ".hyperframes/record.mp4" }];
await expect(heldVideoHints(dir, videos, new Map(), "ffprobe")).resolves.toEqual([]);
expect(run).not.toHaveBeenCalled();
});
});
describe("projectVideoFile", () => {
@@ -2,7 +2,11 @@ import { existsSync } from "node:fs";
import { isAbsolute, relative, resolve } from "node:path";
import { parseHTML } from "linkedom";
import { MEDIA_RENDER_ID_ATTR } from "@hyperframes/core";
import { isNotMediaPayload, type CaptureVideoMetadataHint } from "@hyperframes/engine";
import {
isNotMediaPayload,
isPrivateUnderAssetRoots,
type CaptureVideoMetadataHint,
} from "@hyperframes/engine";
import { mediaInputFormatArgs } from "@hyperframes/parsers/ff-binaries";
import { findFFprobe } from "../browser/ffmpeg.js";
import { runCancellableProcess } from "../utils/cancellableProcess.js";
@@ -22,7 +26,7 @@ export function localVideos(html: string): { id: string; src: string }[] {
export const localVideoRenderIds = (html: string): string[] => localVideos(html).map((v) => v.id);
/** The project file a page URL names, or null when it is remote or outside the project. */
/** The project file a page URL names, or null when it is remote, outside the project or private. */
export function projectLocalFile(projectDir: string, src: string): string | null {
try {
const path = decodeURIComponent(new URL(src, "http://project.invalid/").pathname).replace(
@@ -31,7 +35,8 @@ export function projectLocalFile(projectDir: string, src: string): string | null
);
const file = resolve(projectDir, path);
const rel = relative(projectDir, file);
return !rel.startsWith("..") && !isAbsolute(rel) && existsSync(file) ? file : null;
const inside = !rel.startsWith("..") && !isAbsolute(rel) && existsSync(file);
return inside && !isPrivateUnderAssetRoots(file, [projectDir]) ? file : null;
} catch {
return null;
}
@@ -131,6 +131,19 @@ describe("registry resolver", () => {
expect(warnings.length).toBeGreaterThan(0);
expect(warnings.some((w) => w.includes("beta"))).toBe(true);
});
it("writes a skipped item's name to stderr with control characters escaped", async () => {
const write = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
try {
const entries = [{ name: "be\u001b]0;t\u0007ta", type: "hyperframes:example" as const }];
await loadAllItems(entries, { baseUrl: uniqueBaseUrl() });
const line = write.mock.calls.map(([chunk]) => String(chunk)).join("");
expect(line).toContain("be\\x1b]0;t\\x07ta");
for (const control of ["\u001b", "\u0007"]) expect(line).not.toContain(control);
} finally {
write.mockRestore();
}
});
});
describe("loadAllItems on a slow registry", () => {
+7 -2
View File
@@ -4,7 +4,12 @@
* when blocks/components need it for the `add` command.
*/
import type { ItemType, RegistryItem, RegistryManifestEntry } from "@hyperframes/core";
import {
terminalText,
type ItemType,
type RegistryItem,
type RegistryManifestEntry,
} from "@hyperframes/core";
import { fetchItemManifest, fetchRegistryManifest, DEFAULT_REGISTRY_URL } from "./remote.js";
import { runWithConcurrencyLimit } from "../utils/concurrency.js";
import { closestNames } from "../utils/didYouMean.js";
@@ -22,7 +27,7 @@ export interface ResolveOptions {
}
function defaultWarn(message: string): void {
process.stderr.write(`hyperframes:registry ${message}\n`);
process.stderr.write(`hyperframes:registry ${terminalText(message)}\n`);
}
/**
@@ -37,6 +37,7 @@ const block = (name: string, dependencies?: string[]) => ({
});
const ITEMS = [
block("studio-drop-block"),
{ ...block("studio-drop-retired"), deprecated: "use \u001b]0;t\u0007other" },
block("studio-drop-other"),
block("studio-drop-parent", ["studio-drop-part"]),
{
@@ -125,6 +126,19 @@ function installer(link: string) {
}
describe("Studio catalog install", () => {
it("writes a registry warning to stderr with control characters escaped", async () => {
const { link } = projectWithRegistry();
const write = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
try {
await installer(link)("studio-drop-retired");
const line = write.mock.calls.map(([chunk]) => String(chunk)).join("");
expect(line).toContain("use \\x1b]0;t\\x07other");
for (const control of ["\u001b", "\u0007"]) expect(line).not.toContain(control);
} finally {
write.mockRestore();
}
});
it("answers that the project folder is gone when it is renamed while the item downloads", async () => {
let real = "";
({ real } = projectWithRegistry(() => renameSync(real, `${real}-renamed`)));
+2 -2
View File
@@ -9,7 +9,7 @@ import { PREVIEW_NONCE_HEADER, previewProof } from "@hyperframes/core/preview-pr
import type { HttpBindings } from "@hono/node-server";
import { Hono, type Context } from "hono";
import { streamSSE } from "hono/streaming";
import { realpath } from "@hyperframes/core";
import { realpath, terminalText } from "@hyperframes/core";
import { existsSync, readFileSync, statSync, writeFileSync, unlinkSync } from "node:fs";
import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
import { createHash } from "node:crypto";
@@ -925,7 +925,7 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
source: "studio",
});
for (const warning of result.warnings) {
process.stderr.write(`hyperframes:registry ${warning}\n`);
process.stderr.write(`hyperframes:registry ${terminalText(warning)}\n`);
}
const written = result.written;
+33 -1
View File
@@ -1,4 +1,7 @@
import { describe, expect, it } from "vitest";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { describe, expect, it, onTestFinished, vi } from "vitest";
import { MANIFEST_FILENAME, TEMPLATES_DIR } from "./remote.js";
// These constants construct the GitHub URL that installed CLIs use to fetch
@@ -13,3 +16,32 @@ describe("remote template path constants", () => {
expect(MANIFEST_FILENAME).toBe("templates.json");
});
});
describe("fetchRemoteTemplate", () => {
it("writes a registry warning to stderr with control characters escaped", async () => {
const destDir = mkdtempSync(join(tmpdir(), "hf-remote-template-"));
const write = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
onTestFinished(() => {
write.mockRestore();
vi.doUnmock("../registry/resolver.js");
vi.doUnmock("../registry/index.js");
rmSync(destDir, { recursive: true, force: true });
});
vi.resetModules();
vi.doMock("../registry/resolver.js", () => ({
resolveItemWithDependencies: async () => [
{ name: "starter", type: "hyperframes:example", deprecated: "use \u001b]0;t\u0007x" },
],
}));
vi.doMock("../registry/index.js", () => ({
installItem: async () => writeFileSync(join(destDir, "index.html"), ""),
}));
const { fetchRemoteTemplate } = await import("./remote.js");
await fetchRemoteTemplate("starter", destDir);
const line = write.mock.calls.map(([chunk]) => String(chunk)).join("");
expect(line).toContain("use \\x1b]0;t\\x07x");
for (const control of ["\u001b", "\u0007"]) expect(line).not.toContain(control);
});
});
+2 -1
View File
@@ -5,6 +5,7 @@
import { existsSync } from "node:fs";
import { join } from "node:path";
import { terminalText } from "@hyperframes/core";
import { installItem, listRegistryItems, loadAllItems } from "../registry/index.js";
import { resolveItemWithDependencies } from "../registry/resolver.js";
import { gateRegistryItemsCompatibility } from "../registry/compatibility.js";
@@ -53,7 +54,7 @@ export async function fetchRemoteTemplate(templateId: string, destDir: string):
const items = await resolveItemWithDependencies(templateId);
const warnings = gateRegistryItemsCompatibility(items);
for (const warning of warnings) {
process.stderr.write(`hyperframes:registry ${warning}\n`);
process.stderr.write(`hyperframes:registry ${terminalText(warning)}\n`);
}
for (const item of items) {
await installItem(item, { destDir });
@@ -708,6 +708,29 @@ describe("video extraction failure taxonomy and bounded retry", () => {
}
});
it("warns about a missing source with control characters shown as visible escapes", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-extract-missing-"));
const write = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
try {
const src = "missing\x1b[2J\x07\x9b.mp4";
const video = { id: "v1", src, start: 0, end: 1, mediaStart: 0, loop: false };
const result = await extractAllVideoFrames([{ ...video, hasAudio: false }], dir, {
fps: 30,
outputDir: join(dir, "out"),
assetRoots: [dir],
});
expect(result.errors).toEqual([expect.objectContaining({ kind: "source_missing" })]);
const warning = write.mock.calls
.map(([chunk]) => String(chunk))
.find((chunk) => chunk.includes("could not be resolved on disk"));
expect(warning).toContain('src="missing\\x1b[2J\\x07\\x9b.mp4"');
for (const control of ["\u001b", "\u0007", "\u009b"]) expect(warning).not.toContain(control);
} finally {
write.mockRestore();
rmSync(dir, { recursive: true, force: true });
}
});
it.each([".git/clip.mp4", ".hyperframes/clip.mp4", ".ssh/clip.mp4"])(
"treats the private project file %s as a missing source",
async (src) => {
@@ -45,6 +45,7 @@ import {
hdrToSdrToneMapFilter,
parseFirstFrameColour,
readsKeyframeTransfers,
terminalText,
} from "@hyperframes/core";
import { resolveReferencedStart, type RefResolverEl } from "./referenceResolver.js";
import { isKnownInactiveTimelineWindow } from "./mediaTimelineWindow.js";
@@ -2307,8 +2308,8 @@ export async function extractAllVideoFrames(
if (!warnedSrcs.has(video.src)) {
warnedSrcs.add(video.src);
process.stderr.write(
`[hyperframes:render] WARNING: video src="${video.src}" ` +
`could not be resolved on disk (looked for ${videoPath}). ` +
`[hyperframes:render] WARNING: video src="${terminalText(video.src)}" ` +
`could not be resolved on disk (looked for ${terminalText(videoPath)}). ` +
`The rendered output will show this video's first frame for the entire clip duration. ` +
`If your <video> lives inside a sub-composition, prefer project-root-relative paths ` +
`(e.g. src="assets/foo.mp4") over "../assets/foo.mp4".\n`,
@@ -67,6 +67,12 @@ describe("inputAlphaOpaqueWarning", () => {
expect(line).not.toContain("yuva420p");
expect(line.endsWith("\n")).toBe(true);
});
it("shows control characters in the src as visible escapes", () => {
const line = inputAlphaOpaqueWarning("a\x1b]0;title\x07\x9bb.webm");
expect(line).toContain('src="a\\x1b]0;title\\x07\\x9bb.webm"');
for (const control of ["\u001b", "\u0007", "\u009b"]) expect(line).not.toContain(control);
});
});
const HAS_FFMPEG = spawnSync(getFfmpegBinary(), ["-version"], { encoding: "utf-8" }).status === 0;
+2 -1
View File
@@ -1,6 +1,7 @@
import { mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { terminalText } from "@hyperframes/core";
import { runFfmpeg } from "./runFfmpeg.js";
import { urlInputArgs } from "./urlInput.js";
@@ -68,7 +69,7 @@ export async function probeInputAlphaPlane(
export function inputAlphaOpaqueWarning(src: string): string {
return (
`[hyperframes:render] WARNING: video src="${src}" declares an alpha channel ` +
`[hyperframes:render] WARNING: video src="${terminalText(src)}" declares an alpha channel ` +
"but its first frames decode fully opaque. If it should be transparent, re-export " +
"it with an alpha pixel format and avoid remuxing afterward, which can drop the " +
"alpha while keeping the tag.\n"
+3
View File
@@ -63,6 +63,8 @@ function sanitizeFfprobeDiagnostic(stderr: string, filePath: string): string {
}
/** Spawn ffprobe with given args, return stdout. Throws on non-zero exit or missing binary. */
const REFUSED_TEXT_ART = /^\[(?:tty|bin|xbin|idf|adf) @ [^\]]*\] Format not on whitelist/m;
export async function runFfprobe(
filePath: string,
argsWithoutInput: string[],
@@ -173,6 +175,7 @@ async function spawnFfprobe(
throw outcome.error ?? new Error(outcome.stderr);
}
if (outcome.reason !== "exit" || outcome.exitCode !== 0) {
if (REFUSED_TEXT_ART.test(outcome.stderr)) throw new TextArtMediaError();
const diagnostic = sanitizeFfprobeDiagnostic(outcome.stderr, filePath);
throw new Error(
`[FFmpeg] ffprobe ${outcome.reason} with code ${outcome.exitCode}: ${diagnostic}`,
+33
View File
@@ -1,3 +1,4 @@
import { spawnSync } from "node:child_process";
import {
type PathLike,
chmodSync,
@@ -499,6 +500,38 @@ describe("mediaInputFormatArgs", () => {
expect(formatsOf(mediaInputFormatArgs("/ffprobe"))).toEqual(["3dostr", "mov", "mp4", "m4a"]);
});
it("leaves out the demuxers that draw a text file as a picture", async () => {
const { _setDemuxerListingForTests, mediaInputFormatArgs } = await importFresh();
_setDemuxerListingForTests(
[
" D adf Artworx Data Format",
" D bin Binary text",
" D idf iCE Draw File",
" D mov,mp4,m4a QuickTime / MOV",
" D tty Tele-typewriter",
" D xbin eXtended BINary text (XBIN)",
].join("\n"),
);
expect(formatsOf(mediaInputFormatArgs("/ffmpeg"))).toEqual(["mov", "mp4", "m4a"]);
});
it("keeps the installed ffmpeg from decoding a text file into a frame", async () => {
vi.resetModules();
vi.doUnmock("node:fs");
vi.doUnmock("node:child_process");
const { findFfBinary, mediaInputFormatArgs } = await importFresh();
const ffmpeg = findFfBinary("ffmpeg");
if (!ffmpeg) return;
const dir = mkdtempSync(join(tmpdir(), "hf-text-art-"));
onTestFinished(() => rmSync(dir, { recursive: true, force: true }));
const note = join(dir, "note.asc");
writeFileSync(note, "API_KEY=not-a-video\nsecond line\n");
const frame = join(dir, "frame.png");
const args = ["-v", "error", "-y", ...mediaInputFormatArgs(ffmpeg), "-i", note];
spawnSync(ffmpeg, [...args, "-frames:v", "1", frame]);
expect(existsSync(frame)).toBe(false);
});
it.skipIf(process.platform === "win32")("asks a binary that failed once again", async () => {
const { mediaInputFormatArgs, SELF_CONTAINED_FORMATS } = await importFresh();
const dir = mkdtempSync(join(tmpdir(), "hf-demuxers-"));
+5 -2
View File
@@ -268,6 +268,8 @@ const PATH_OPENING_DEMUXERS = new Set([
"lavfi",
]);
const TEXT_ART_DEMUXERS = new Set(["tty", "bin", "xbin", "idf", "adf"]);
/** A `-format_whitelist` value from a `-demuxers` listing; undefined when no row parses. */
function demuxersFromListing(listing: string): string | undefined {
const row = /Is a device/.test(listing) ? /^ D[E ]([d ]) (\S+)/ : /^ D[E ]() (\S+)/;
@@ -276,7 +278,8 @@ function demuxersFromListing(listing: string): string | undefined {
const match = row.exec(line);
if (!match || match[1] === "d") continue;
const aliases = match[2]!.split(",");
if (aliases.some((alias) => PATH_OPENING_DEMUXERS.has(alias))) continue;
if (aliases.some((alias) => PATH_OPENING_DEMUXERS.has(alias) || TEXT_ART_DEMUXERS.has(alias)))
continue;
for (const alias of aliases) names.add(alias);
}
return names.size > 0 ? [...names].join(",") : undefined;
@@ -291,7 +294,7 @@ export function _setDemuxerListingForTests(listing?: string): void {
demuxerLists.clear();
}
/** Every demuxer `listingBinary` reports that opens nothing by itself; one that cannot be asked gets the self-contained list, and is asked again. */
/** Every demuxer `listingBinary` reports that opens nothing by itself and is not text art; one that cannot be asked gets the self-contained list, and is asked again. */
export function mediaInputFormatArgs(listingBinary: string): string[] {
let formats = demuxerLists.get(listingBinary);
if (formats === undefined) {