diff --git a/docs/concepts/variables.mdx b/docs/concepts/variables.mdx
index 81e3ffb923..972337e16a 100644
--- a/docs/concepts/variables.mdx
+++ b/docs/concepts/variables.mdx
@@ -245,6 +245,13 @@ npx hyperframes render \
--output "renders/{name}.mp4"
```
+Every output stays inside the folder written before the first placeholder
+(`renders/` here). A row value may name a subfolder of it, but a value that
+leads outside it, such as `../other`, stops the batch before anything renders.
+A template that starts with a placeholder, such as `--output "{path}"`, names
+no folder, so each row's value is used as the whole output path, absolute
+paths included.
+
Start with the default single-row concurrency. Increase `--batch-concurrency`
only after one real render is stable and the machine has enough memory for
several renders at once.
diff --git a/packages/cli/src/commands/batchRender.test.ts b/packages/cli/src/commands/batchRender.test.ts
index 716385f2f2..3439f539a4 100644
--- a/packages/cli/src/commands/batchRender.test.ts
+++ b/packages/cli/src/commands/batchRender.test.ts
@@ -126,6 +126,72 @@ describe("prepareBatchRender", () => {
expect(prepared.manifestPath).toBe(resolve(outDir, "manifest.json"));
});
+ it("keeps row values that name subfolders inside the --output folder", () => {
+ const batchPath = writeJson("rows.json", '[{"name":"eu/acme"},{"name":"x/../northstar"}]');
+ const outDir = join(tmpDir, "renders");
+ const prepared = prepareBatchRender({
+ batchPath,
+ outputTemplate: join(outDir, "{name}.mp4"),
+ indexPath: writeIndex(),
+ strictVariables: false,
+ quiet: true,
+ json: false,
+ });
+
+ expect(prepared.rows.map((row) => row.outputPath)).toEqual([
+ resolve(outDir, "eu", "acme.mp4"),
+ resolve(outDir, "northstar.mp4"),
+ ]);
+ });
+
+ it.each([
+ { template: join("renders", "{name}.mp4"), name: "../escaped" },
+ { template: join("renders", "v{name}.mp4"), name: "/../../escaped" },
+ ])("refuses a row value that leaves the folder of $template", ({ template, name }) => {
+ const batchPath = writeJson("rows.json", JSON.stringify([{ name }]));
+ const error = expectBatchError(
+ () =>
+ prepareBatchRender({
+ batchPath,
+ outputTemplate: join(tmpDir, template),
+ indexPath: writeIndex(),
+ strictVariables: false,
+ quiet: true,
+ json: false,
+ }),
+ "Batch output outside --output folder",
+ );
+ expect(error.message).toMatch(/Row 0 resolves to/);
+ });
+
+ it("keeps a backslash in a row value or file name on every platform", () => {
+ const batchPath = writeJson("rows.json", '[{"name":"a\\\\b"}]');
+ const outDir = join(tmpDir, "renders\\");
+ const prepared = prepareBatchRender({
+ batchPath,
+ outputTemplate: `${outDir}{name}.mp4`,
+ indexPath: writeIndex(),
+ strictVariables: false,
+ quiet: true,
+ json: false,
+ });
+ expect(prepared.rows[0]?.outputPath).toBe(resolve(`${outDir}a\\b.mp4`));
+ });
+
+ it("lets the rows name the whole path when the template starts with a placeholder", () => {
+ const elsewhere = join(tmpDir, "elsewhere", "launch.mp4");
+ const batchPath = writeJson("rows.json", JSON.stringify([{ path: elsewhere }]));
+ const prepared = prepareBatchRender({
+ batchPath,
+ outputTemplate: "{path}",
+ indexPath: writeIndex(),
+ strictVariables: false,
+ quiet: true,
+ json: false,
+ });
+ expect(prepared.rows[0]?.outputPath).toBe(resolve(elsewhere));
+ });
+
it("rejects output collisions before rendering", () => {
const batchPath = writeJson("rows.json", '[{"name":"Alice"},{"name":"Bob"}]');
const error = expectBatchError(
diff --git a/packages/cli/src/commands/batchRender.ts b/packages/cli/src/commands/batchRender.ts
index b901f31111..d432bc3dd6 100644
--- a/packages/cli/src/commands/batchRender.ts
+++ b/packages/cli/src/commands/batchRender.ts
@@ -2,7 +2,7 @@ import { failCommand } from "../utils/commandResult.js";
import { writeFileSync } from "node:fs";
import { makeOutputFolder } from "../utils/outputFolder.js";
import { readJsonFileText } from "../utils/jsonFlag.js";
-import { dirname, join, resolve, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { c } from "../ui/colors.js";
import { errorBox } from "../ui/format.js";
import { normalizeErrorMessage as errorMessage } from "../utils/errorMessage.js";
@@ -155,6 +155,26 @@ export function resolveOutputTemplate(
);
}
+function folderOfPrefix(prefix: string): string {
+ return prefix.endsWith("/") || prefix.endsWith(sep) ? resolve(prefix) : dirname(resolve(prefix));
+}
+
+function checkOutputsInsideTemplateFolder(rows: readonly PreparedBatchRow[], template: string) {
+ const firstPlaceholder = template.search(PLACEHOLDER_RE);
+ if (firstPlaceholder <= 0) return;
+ const folder = folderOfPrefix(template.slice(0, firstPlaceholder));
+ for (const row of rows) {
+ const rel = relative(folder, row.outputPath);
+ const outside = rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+ if (!outside) continue;
+ throw new BatchRenderInputError(
+ "Batch output outside --output folder",
+ `Row ${row.index} resolves to ${row.outputPath}, outside ${folder}.`,
+ "Row values may name subfolders of the --output folder but not leave it.",
+ );
+ }
+}
+
function isSameOrChildPath(path: string, parent: string): boolean {
return path === parent || path.startsWith(parent.endsWith(sep) ? parent : parent + sep);
}
@@ -262,6 +282,7 @@ export function prepareBatchRender(options: PrepareBatchRenderOptions): Prepared
variables,
outputPath: resolve(resolveOutputTemplate(options.outputTemplate, variables, index)),
}));
+ checkOutputsInsideTemplateFolder(rows, options.outputTemplate);
const manifestPath = join(
commonOutputDirectory(rows.map((row) => row.outputPath)),
"manifest.json",
diff --git a/packages/cli/src/commands/check.test.ts b/packages/cli/src/commands/check.test.ts
index e9fddf6c2f..37e31cea0b 100644
--- a/packages/cli/src/commands/check.test.ts
+++ b/packages/cli/src/commands/check.test.ts
@@ -78,7 +78,7 @@ import type {
LayoutOverflow,
LayoutRect,
} from "../utils/layoutAudit.js";
-import type { CraftFrame, SeekClock } from "../utils/checkTypes.js";
+import type { CheckContrastFinding, CraftFrame, SeekClock } from "../utils/checkTypes.js";
import type { ProjectDir } from "../utils/project.js";
const PROJECT: ProjectDir = {
@@ -803,6 +803,80 @@ it("distinguishes unavailable HDR inspection from no promotion", async () => {
expect(report.hdr).toEqual({ autoPromotion: null, inspection: "unavailable" });
});
+it("prints composition text in a finding with its control characters as visible escapes", async () => {
+ const planted: CheckFinding = {
+ code: "audio_source_unreadable",
+ severity: "error",
+ message: "voice\u001b[2K.wav has no audio",
+ selector: "#v\u001b]0;t\u0007",
+ dataAttributes: {},
+ sourceFile: "scene\u009b2J.html",
+ fixHint: "use \u001b]52;c;Y2xpcA==\u0007",
+ bbox: { x: 0, y: 0, width: 0, height: 0 },
+ time: 1,
+ };
+ const { report } = await runScenario(
+ fakeDriver(),
+ {},
+ { inspectAudio: vi.fn(async () => [planted]) },
+ );
+ const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+ const command = createCheckCommand({
+ resolveProject: () => PROJECT,
+ runPipeline: vi.fn(async () => report),
+ prepareMedia: vi.fn(async () => []),
+ withMeta: (value) => value,
+ });
+
+ await runCommand(command, { rawArgs: [] }).catch(() => undefined);
+
+ const out = log.mock.calls.map((call) => String(call[0] ?? "")).join("\n");
+ for (const control of ["\u0007", "\u001b]", "\u001b[2K", "\u009b"])
+ expect(out).not.toContain(control);
+ expect(out).toContain("voice\\x1b[2K.wav has no audio");
+ expect(out).toContain("scene\\x9b2J.html #v\\x1b]0;t\\x07");
+ expect(out).toContain("Fix: use \\x1b]52;c;Y2xpcA==\\x07");
+});
+
+it("prints a contrast finding's selector, colour and source with control characters escaped", async () => {
+ const planted: CheckContrastFinding = {
+ code: "contrast_aa_failure",
+ severity: "error",
+ message: "low contrast",
+ selector: "#t\u001b]0;x\u0007",
+ dataAttributes: {},
+ sourceFile: "scene\u009b2J.html",
+ bbox: { x: 0, y: 0, width: 0, height: 0 },
+ time: 1,
+ fg: "#777",
+ bg: "#888",
+ ratio: 1.2,
+ requiredRatio: 4.5,
+ suggestedColor: "#000\u001b[2K",
+ large: false,
+ };
+ const { report } = await runScenario(fakeDriver());
+ const plantedReport = {
+ ...report,
+ contrast: { ...report.contrast, enabled: true, findings: [planted], errorCount: 1 },
+ };
+ const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+ const command = createCheckCommand({
+ resolveProject: () => PROJECT,
+ runPipeline: vi.fn(async () => plantedReport),
+ prepareMedia: vi.fn(async () => []),
+ withMeta: (value) => value,
+ });
+
+ await runCommand(command, { rawArgs: [] }).catch(() => undefined);
+
+ const out = log.mock.calls.map((call) => String(call[0] ?? "")).join("\n");
+ for (const control of ["\u0007", "\u001b]", "\u001b[2K", "\u009b"])
+ expect(out).not.toContain(control);
+ expect(out).toContain("#t\\x1b]0;x\\x07 1.2:1");
+ expect(out).toContain("Try #000\\x1b[2K; source scene\\x9b2J.html");
+});
+
it("fails the check on an audio error and reports it in its own section", async () => {
const unreadable: CheckFinding = {
code: "audio_source_unreadable",
diff --git a/packages/cli/src/commands/check.ts b/packages/cli/src/commands/check.ts
index 009a5226ce..6da1d44cfd 100644
--- a/packages/cli/src/commands/check.ts
+++ b/packages/cli/src/commands/check.ts
@@ -18,6 +18,7 @@ import type { ArgsDef } from "citty";
import type { Example } from "./_examples.js";
import { parseAt } from "./layout.js";
import { c } from "../ui/colors.js";
+import { terminalText } from "../utils/terminalText.js";
import { registerBrowserSessionCleanup } from "../browser/launch.js";
import { normalizeErrorMessage } from "../utils/errorMessage.js";
import { CliUsageError, failUsage, setCommandExitCode } from "../utils/commandResult.js";
@@ -847,9 +848,10 @@ function printContrastSection(report: CheckReport): void {
}
for (const finding of section.findings) {
console.log(
- ` ${c.error("✗")} ${finding.selector} ${finding.ratio}:1 (need ${finding.requiredRatio}:1, ${formatFindingTimes(finding)})`,
+ ` ${c.error("✗")} ${terminalText(finding.selector)} ${finding.ratio}:1 (need ${finding.requiredRatio}:1, ${formatFindingTimes(finding)})`,
);
- console.log(` ${c.dim(`Try ${finding.suggestedColor}; source ${finding.sourceFile}`)}`);
+ const source = `Try ${terminalText(finding.suggestedColor)}; source ${terminalText(finding.sourceFile)}`;
+ console.log(` ${c.dim(source)}`);
}
printCounts(section);
}
@@ -883,10 +885,10 @@ function printSnapshotSection(report: CheckReport): void {
}
function printFinding(finding: CheckFinding): void {
- const where = `${finding.sourceFile} ${finding.selector} ${formatFindingTimes(finding)}`;
- console.log(` ${findingIcon(finding)} ${finding.code}: ${finding.message}`);
+ const where = `${terminalText(finding.sourceFile)} ${terminalText(finding.selector)} ${formatFindingTimes(finding)}`;
+ console.log(` ${findingIcon(finding)} ${finding.code}: ${terminalText(finding.message)}`);
console.log(` ${c.dim(where)}`);
- if (finding.fixHint) console.log(` ${c.dim(`Fix: ${finding.fixHint}`)}`);
+ if (finding.fixHint) console.log(` ${c.dim(`Fix: ${terminalText(finding.fixHint)}`)}`);
}
function findingIcon(finding: CheckFinding): string {
diff --git a/packages/cli/src/commands/compositions.ts b/packages/cli/src/commands/compositions.ts
index eeead49e37..f1abc76e1c 100644
--- a/packages/cli/src/commands/compositions.ts
+++ b/packages/cli/src/commands/compositions.ts
@@ -15,6 +15,7 @@ import { ensureDOMParser } from "../utils/dom.js";
import { resolveProject } from "../utils/project.js";
import { resolveReferencedStart } from "@hyperframes/engine";
import { withMeta } from "../utils/updateCheck.js";
+import { terminalText } from "../utils/terminalText.js";
interface CompositionInfo {
id: string;
@@ -208,16 +209,19 @@ export default defineCommand({
console.log();
// Calculate padding for alignment
- const maxIdLen = compositions.reduce((max, comp) => Math.max(max, comp.id.length), 0);
+ const maxIdLen = compositions.reduce(
+ (max, comp) => Math.max(max, terminalText(comp.id).length),
+ 0,
+ );
for (const comp of compositions) {
- const id = c.accent(comp.id.padEnd(maxIdLen));
+ const id = c.accent(terminalText(comp.id).padEnd(maxIdLen));
const duration = c.bold(`${comp.duration.toFixed(1)}s`);
const resolution = c.dim(`${comp.width}×${comp.height}`);
const elements = c.dim(
`${comp.elementCount} ${comp.elementCount === 1 ? "element" : "elements"}`,
);
- const source = comp.source ? c.dim(` ← ${comp.source}`) : "";
+ const source = comp.source ? c.dim(` ← ${terminalText(comp.source)}`) : "";
console.log(` ${id} ${duration} ${resolution} ${elements}${source}`);
}
diff --git a/packages/cli/src/commands/info.ts b/packages/cli/src/commands/info.ts
index 7e4f0a9267..79cad6e718 100644
--- a/packages/cli/src/commands/info.ts
+++ b/packages/cli/src/commands/info.ts
@@ -15,6 +15,7 @@ import {
} from "@hyperframes/core/runtime/composition-length";
import { readDataDurationSeconds } from "@hyperframes/parsers/media-duration";
import { heardClips } from "../utils/projectMedia.js";
+import { terminalText } from "../utils/terminalText.js";
import { c } from "../ui/colors.js";
import { formatBytes, label } from "../ui/format.js";
import { ensureDOMParser } from "../utils/dom.js";
@@ -129,7 +130,9 @@ export default defineCommand({
console.log(label("Size", formatBytes(size)));
for (const clip of heard ?? []) {
const until = clip.end > 0 ? `${clip.end.toFixed(2)}s` : "its end";
- console.log(label("Heard", `${clip.src} ${clip.start.toFixed(2)}s to ${until}`));
+ console.log(
+ label("Heard", `${terminalText(clip.src)} ${clip.start.toFixed(2)}s to ${until}`),
+ );
}
},
});
diff --git a/packages/cli/src/commands/keyframes.ts b/packages/cli/src/commands/keyframes.ts
index 16b8e2dd22..aa80e544fd 100644
--- a/packages/cli/src/commands/keyframes.ts
+++ b/packages/cli/src/commands/keyframes.ts
@@ -9,6 +9,7 @@ import {
} from "@hyperframes/core/gsap-parser";
import type { Example } from "./_examples.js";
import { c } from "../ui/colors.js";
+import { terminalText } from "../utils/terminalText.js";
import { ensureDOMParser } from "../utils/dom.js";
import { resolveProject } from "../utils/project.js";
import { withMeta } from "../utils/updateCheck.js";
@@ -999,7 +1000,7 @@ function printCompositionTweens(cmp: SurfacedComposition): void {
// Print one composition's traces + tweens (skipping strokes already shown in a trace).
function printComposition(cmp: SurfacedComposition): void {
if (isEmptyComposition(cmp)) return;
- console.log(c.bold(`${cmp.composition}`) + c.dim(` (${cmp.source})`));
+ console.log(c.bold(terminalText(cmp.composition)) + c.dim(` (${terminalText(cmp.source)})`));
for (const tr of cmp.traces) printTrace(tr);
printCompositionTweens(cmp);
for (const cssKeyframes of cmp.cssKeyframes) printCssKeyframes(cssKeyframes);
diff --git a/packages/cli/src/commands/lint.test.ts b/packages/cli/src/commands/lint.test.ts
index c527ec608d..0c4ed99ce9 100644
--- a/packages/cli/src/commands/lint.test.ts
+++ b/packages/cli/src/commands/lint.test.ts
@@ -87,6 +87,20 @@ describe("lint command exit handling", () => {
expect(vi.mocked(process.exit)).not.toHaveBeenCalled();
expect(consumeCommandResult().exitCode).toBe(1);
});
+
+ it("names a file with control characters in it as visible escapes", async () => {
+ const log = vi.spyOn(console, "log").mockImplementation(() => {});
+ lintProjectMock.mockResolvedValue({
+ results: [{ result: { findings: [] }, file: "a\u001b]0;t\u0007.html" }],
+ totalErrors: 0,
+ totalWarnings: 0,
+ totalInfos: 0,
+ });
+ await run({ json: false, verbose: false });
+ const header = String(log.mock.calls.find((call) => String(call[0]).includes("Linting"))?.[0]);
+ expect(header).toContain("proj/a\\x1b]0;t\\x07.html");
+ expect(header).not.toContain("\u001b]");
+ });
});
describe("lint --lint-verbose", () => {
diff --git a/packages/cli/src/commands/lint.ts b/packages/cli/src/commands/lint.ts
index 3c3a93ef5f..1108b95a99 100644
--- a/packages/cli/src/commands/lint.ts
+++ b/packages/cli/src/commands/lint.ts
@@ -18,6 +18,7 @@ import { isUnderCompositions, resolveLintTarget } from "../utils/project.js";
import { trackLintRun } from "../telemetry/lintRun.js";
import { getRunId } from "../telemetry/runId.js";
import { withMeta } from "../utils/updateCheck.js";
+import { terminalText } from "../utils/terminalText.js";
export default defineCommand({
meta: {
@@ -96,7 +97,9 @@ export default defineCommand({
const fileCount = lintResult.results.length;
const fileLabel =
fileCount === 1 ? (lintResult.results[0]?.file ?? "index.html") : `${fileCount} files`;
- console.log(`${c.accent("◆")} Linting ${c.accent(`${project.name}/${fileLabel}`)}`);
+ console.log(
+ `${c.accent("◆")} Linting ${c.accent(terminalText(`${project.name}/${fileLabel}`))}`,
+ );
if (unmounted.length > 0) console.log(c.dim(unmountedNotice(unmounted.length)));
console.log();
diff --git a/packages/cli/src/utils/layoutAudit.test.ts b/packages/cli/src/utils/layoutAudit.test.ts
index ff0222ba13..fd1f9c71de 100644
--- a/packages/cli/src/utils/layoutAudit.test.ts
+++ b/packages/cli/src/utils/layoutAudit.test.ts
@@ -164,6 +164,22 @@ describe("layoutAudit helpers", () => {
expect(formatted).toContain("Fix: Increase container padding");
});
+ it("shows control characters in composition text as visible escapes", () => {
+ const formatted = formatLayoutIssue({
+ ...issue("text_box_overflow", "error"),
+ selector: "#h\u001b]0;t\u0007",
+ containerSelector: ".b\u009b2J",
+ text: "Plan\u001b[2K",
+ message: "clipped\u001b[1A",
+ fixHint: "pad \u001b]52;c;Y2xpcA==\u0007",
+ });
+
+ for (const control of ["\u0007", "\u001b", "\u009b"]) expect(formatted).not.toContain(control);
+ expect(formatted).toContain("#h\\x1b]0;t\\x07 inside .b\\x9b2J");
+ expect(formatted).toContain('"Plan\\x1b[2K" — clipped\\x1b[1A');
+ expect(formatted).toContain("\n Fix: pad \\x1b]52;c;Y2xpcA==\\x07");
+ });
+
it("formats collapsed issue time ranges", () => {
const formatted = formatLayoutIssue({
...issue("text_box_overflow", "error"),
diff --git a/packages/cli/src/utils/layoutAudit.ts b/packages/cli/src/utils/layoutAudit.ts
index 6e04a2adb7..9b522d76eb 100644
--- a/packages/cli/src/utils/layoutAudit.ts
+++ b/packages/cli/src/utils/layoutAudit.ts
@@ -1,4 +1,5 @@
import { formatFindingTimes } from "./checkFindings.js";
+import { terminalText } from "./terminalText.js";
export interface LayoutRect {
left: number;
top: number;
@@ -158,14 +159,14 @@ export function formatLayoutIssue(issue: LayoutIssue): string {
const parts = [
timeLabel,
issue.code,
- issue.selector,
- issue.containerSelector ? `inside ${issue.containerSelector}` : "",
+ terminalText(issue.selector),
+ issue.containerSelector ? `inside ${terminalText(issue.containerSelector)}` : "",
issue.overflow ? `overflowed ${formatOverflow(issue.overflow)}` : "",
- issue.text ? quoteText(issue.text) : "",
+ issue.text ? terminalText(quoteText(issue.text)) : "",
].filter(Boolean);
- const line = `${parts.join(" ")} — ${issue.message}`;
- return issue.fixHint ? `${line}\n Fix: ${issue.fixHint}` : line;
+ const line = `${parts.join(" ")} — ${terminalText(issue.message)}`;
+ return issue.fixHint ? `${line}\n Fix: ${terminalText(issue.fixHint)}` : line;
}
export function dedupeLayoutIssues(issues: LayoutIssue[]): LayoutIssue[] {
diff --git a/packages/cli/src/utils/lintFormat.test.ts b/packages/cli/src/utils/lintFormat.test.ts
index 63f8a2fc86..54cc942416 100644
--- a/packages/cli/src/utils/lintFormat.test.ts
+++ b/packages/cli/src/utils/lintFormat.test.ts
@@ -38,6 +38,30 @@ function project(
}
describe("formatLintFindings", () => {
+ it("shows control characters in project-derived text as visible escapes", () => {
+ const lines = formatLintFindings(
+ project([
+ {
+ file: "a\u001b]0;title\u0007.html",
+ findings: [
+ finding("error", {
+ elementId: "x\u001b[2K",
+ message: "bad \u009b2J\rclean",
+ fixHint: "fix \u001b]52;c;Y2xpcA==\u0007",
+ line: 3,
+ }),
+ ],
+ },
+ ]),
+ );
+ const out = lines.join("\n");
+ for (const control of ["\u0007", "\r", "\u001b", "\u009b"]) expect(out).not.toContain(control);
+ expect(out).toContain("[x\\x1b[2K]");
+ expect(out).toContain("bad \\x9b2J\\x0dclean");
+ expect(out).toContain("Fix: fix \\x1b]52;c;Y2xpcA==\\x07");
+ expect(out).toContain("[a\\x1b]0;title\\x07.html:3]");
+ });
+
it("returns no lines when no file has findings", () => {
expect(formatLintFindings(project([{ file: "index.html", findings: [] }]))).toEqual([]);
});
diff --git a/packages/cli/src/utils/lintFormat.ts b/packages/cli/src/utils/lintFormat.ts
index 7d490acd1f..98a486b514 100644
--- a/packages/cli/src/utils/lintFormat.ts
+++ b/packages/cli/src/utils/lintFormat.ts
@@ -1,4 +1,5 @@
import { c } from "../ui/colors.js";
+import { terminalText } from "./terminalText.js";
import type { ProjectLintResult } from "./lintProject.js";
export interface LintFormatOptions {
@@ -41,9 +42,12 @@ export function formatLintFindings(
: c.dim("ℹ");
const fileLabel = findingFileLabel(file, finding, multiFile);
const loc =
- showElementId && finding.elementId ? ` ${c.accent(`[${finding.elementId}]`)}` : "";
- lines.push(` ${prefix} ${fileLabel}${c.bold(finding.code)}${loc}: ${finding.message}`);
- if (finding.fixHint) lines.push(` ${c.dim(`Fix: ${finding.fixHint}`)}`);
+ showElementId && finding.elementId
+ ? ` ${c.accent(`[${terminalText(finding.elementId)}]`)}`
+ : "";
+ const message = terminalText(finding.message);
+ lines.push(` ${prefix} ${fileLabel}${c.bold(finding.code)}${loc}: ${message}`);
+ if (finding.fixHint) lines.push(` ${c.dim(`Fix: ${terminalText(finding.fixHint)}`)}`);
};
if (errorsFirst) {
@@ -100,7 +104,7 @@ function findingFileLabel(
finding: import("@hyperframes/lint").HyperframeLintFinding,
multiFile: boolean,
): string {
- if (finding.line === undefined) return multiFile ? c.dim(`[${file}] `) : "";
+ if (finding.line === undefined) return multiFile ? c.dim(`[${terminalText(file)}] `) : "";
const column = finding.column === undefined ? "" : `:${finding.column}`;
- return c.dim(`[${finding.file ?? file}:${finding.line}${column}] `);
+ return c.dim(`[${terminalText(finding.file ?? file)}:${finding.line}${column}] `);
}
diff --git a/packages/cli/src/utils/terminalText.test.ts b/packages/cli/src/utils/terminalText.test.ts
new file mode 100644
index 0000000000..0cbe060d25
--- /dev/null
+++ b/packages/cli/src/utils/terminalText.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { terminalText } from "./terminalText.js";
+
+describe("terminalText", () => {
+ it("leaves ordinary text and tabs alone", () => {
+ expect(terminalText("intro-scene\tassets/clip é.mp4")).toBe("intro-scene\tassets/clip é.mp4");
+ });
+
+ it("writes C0, DEL and C1 controls out as visible escapes", () => {
+ expect(terminalText("a\u001b[31mb\u0007c\nd\u007fe\u009bf\u0085")).toBe(
+ "a\\x1b[31mb\\x07c\\x0ad\\x7fe\\x9bf\\x85",
+ );
+ });
+});
diff --git a/packages/cli/src/utils/terminalText.ts b/packages/cli/src/utils/terminalText.ts
new file mode 100644
index 0000000000..92a68efbd2
--- /dev/null
+++ b/packages/cli/src/utils/terminalText.ts
@@ -0,0 +1,11 @@
+const isControlCode = (code: number) =>
+ (code < 0x20 && code !== 0x09) || (code >= 0x7f && code <= 0x9f);
+
+export function terminalText(text: string): string {
+ let shown = "";
+ for (const ch of text) {
+ const code = ch.charCodeAt(0);
+ shown += isControlCode(code) ? `\\x${code.toString(16).padStart(2, "0")}` : ch;
+ }
+ return shown;
+}
diff --git a/packages/core/src/runtime/editingAgent.test.ts b/packages/core/src/runtime/editingAgent.test.ts
index 9561f25554..f20dbca530 100644
--- a/packages/core/src/runtime/editingAgent.test.ts
+++ b/packages/core/src/runtime/editingAgent.test.ts
@@ -1,5 +1,6 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { installEditingAgent } from "./editingAgent";
+import { PREVIEW_FOR_ANOTHER_SITE_META } from "../studioPreviewMark";
const CONNECT = { source: "hf-parent", type: "editing-connect", v: 1 };
const H = "0123456789abcdef:1";
@@ -110,6 +111,20 @@ describe("installEditingAgent", () => {
}
});
+ it("never hands off in a document its server answered to another site", () => {
+ const mark = document.createElement("meta");
+ mark.name = PREVIEW_FOR_ANOTHER_SITE_META;
+ document.head.appendChild(mark);
+ try {
+ post(parent, CONNECT);
+ expect(handoff).not.toHaveBeenCalled();
+ } finally {
+ mark.remove();
+ }
+ post(parent, CONNECT);
+ expect(handoff).toHaveBeenCalledOnce();
+ });
+
it("stops listening for a connect once disposed", () => {
agent.dispose();
post(parent, CONNECT);
diff --git a/packages/core/src/runtime/editingAgent.ts b/packages/core/src/runtime/editingAgent.ts
index a1d5aaddc2..1379d03d45 100644
--- a/packages/core/src/runtime/editingAgent.ts
+++ b/packages/core/src/runtime/editingAgent.ts
@@ -2,8 +2,8 @@
* The runtime's end of the editing channel (wire types in `editingPort.ts`).
*
* Each connect from `window.parent` gets a fresh port, so only the parent holds a channel and a
- * remounted client is served too; a connect from anything else is ignored. Earlier ports stay
- * open: a client may take any one of them, and a disposed client closes its own.
+ * remounted client is served too; any other connect, or any in a page served to another site, is
+ * ignored. Earlier ports stay open: a client may take any of them; a disposed one closes its own.
* Requests on the port are validated; a bad one gets a typed error reply, never a throw.
*/
import { swallow } from "./diagnostics";
@@ -32,7 +32,7 @@ import { pointerTargetsAt } from "./editingTargets";
import { layersOf } from "./editingLayers";
import { drawDrafts } from "./editingDraft";
import { gestureStart } from "./editingGestureStart";
-import { getLogicalOpacity } from "../studioPreviewMark";
+import { getLogicalOpacity, servedToAnotherSite } from "../studioPreviewMark";
type Handlers = {
[K in EditingRequestKind]: (
@@ -144,7 +144,7 @@ export function installEditingAgent(parent: Window = window.parent): { dispose:
const data = event.data;
if (!isPlainRecord(data) || data.source !== "hf-parent" || data.type !== EDITING_CONNECT)
return;
- if (data.v !== EDITING_PROTOCOL_VERSION) return;
+ if (data.v !== EDITING_PROTOCOL_VERSION || servedToAnotherSite(document)) return;
const channel = new MessageChannel();
const port = channel.port1;
ports.add(port);
diff --git a/packages/core/src/studioPreviewMark.ts b/packages/core/src/studioPreviewMark.ts
index 101843de72..0a0012c692 100644
--- a/packages/core/src/studioPreviewMark.ts
+++ b/packages/core/src/studioPreviewMark.ts
@@ -6,6 +6,11 @@ export const PREVIEW_VIDEO_FRAME_ATTR = "data-hf-preview-video-frame";
export const PREVIEW_VIDEO_SOURCE_ATTR = "data-hf-preview-video-source";
export const PREVIEW_VIDEO_CANVAS_ATTR = "data-hf-preview-video-canvas";
export const STUDIO_PREVIEW_CAPTURE_MODE = "capture";
+export const PREVIEW_FOR_ANOTHER_SITE_META = "hyperframes-preview-for-another-site";
+
+export function servedToAnotherSite(doc: Document): boolean {
+ return doc.querySelector(`meta[name="${PREVIEW_FOR_ANOTHER_SITE_META}"]`) !== null;
+}
export function getLogicalOpacity(el: Element, computed: CSSStyleDeclaration): string {
const overlay = el.previousElementSibling;
diff --git a/packages/studio-server/src/createStudioApi.originGuard.test.ts b/packages/studio-server/src/createStudioApi.originGuard.test.ts
index 3658369add..077d4bdb51 100644
--- a/packages/studio-server/src/createStudioApi.originGuard.test.ts
+++ b/packages/studio-server/src/createStudioApi.originGuard.test.ts
@@ -280,6 +280,32 @@ describe("createStudioApi cross-origin write guard", () => {
});
});
+describe("createStudioApi media analysis from another site", () => {
+ it.each([
+ ["waveform", "cross-site"],
+ ["waveform", "same-site"],
+ ["peaks", "cross-site"],
+ ["peaks", "same-site"],
+ ])("refuses a %s request marked %s", async (route, site) => {
+ const { app } = createApp();
+ const res = await app.request(`http://localhost/projects/demo/${route}/talk.mp4`, {
+ headers: { Host: "localhost", "Sec-Fetch-Site": site },
+ });
+ expect(res.status).toBe(403);
+ });
+
+ it.each([
+ ["waveform", "same-origin"],
+ ["peaks", "none"],
+ ])("answers a %s request marked %s", async (route, site) => {
+ const { app } = createApp();
+ const res = await app.request(`http://localhost/projects/demo/${route}/talk.mp4`, {
+ headers: { Host: "localhost", "Sec-Fetch-Site": site },
+ });
+ expect(res.status).toBe(404);
+ });
+});
+
describe("previewAllowedHostsFromEnv", () => {
it("parses a comma separated list, trimming blanks", () => {
expect(
diff --git a/packages/studio-server/src/createStudioApi.ts b/packages/studio-server/src/createStudioApi.ts
index bc447773ad..0335c6513d 100644
--- a/packages/studio-server/src/createStudioApi.ts
+++ b/packages/studio-server/src/createStudioApi.ts
@@ -1,4 +1,6 @@
import { Hono, type Context, type Next } from "hono";
+import { injectTagsAtHeadStart } from "@hyperframes/core/compiler/html-document";
+import { PREVIEW_FOR_ANOTHER_SITE_META } from "@hyperframes/core/studio-preview-mark";
import type { StudioApiAdapter } from "./types.js";
import { registerProjectRoutes } from "./routes/projects.js";
import { registerFileRoutes } from "./routes/files.js";
@@ -47,19 +49,46 @@ const fromAnotherSite = (c: Context) => {
const isThumbnailCapture = (c: Context) => c.req.query(PREVIEW_CAPTURE_PARAM) !== undefined;
+async function markPreviewForAnotherSite(c: Context) {
+ if (c.res.status !== 200 || !c.res.headers.get("content-type")?.startsWith("text/html")) return;
+ const headers = new Headers(c.res.headers);
+ headers.delete("content-length");
+ headers.delete("etag");
+ const marked = injectTagsAtHeadStart(
+ await c.res.text(),
+ ``,
+ );
+ c.res = undefined;
+ c.res = new Response(marked, { status: 200, headers });
+}
+
+const FRAMED_DESTS = new Set(["document", "iframe", "frame", "embed", "object", "fencedframe"]);
+const framedByAnotherSite = (c: Context) =>
+ fromAnotherSite(c) && FRAMED_DESTS.has(c.req.header("sec-fetch-dest") ?? "");
+
+function withoutValidators(request: Request): Request {
+ const headers = new Headers(request.headers);
+ headers.delete("if-none-match");
+ headers.delete("if-modified-since");
+ return new Request(request, { headers });
+}
+
const sandboxPreviewForAnotherSiteOrCapture =
(sandboxCaptures: boolean) => async (c: Context, next: Next) => {
+ if (framedByAnotherSite(c)) c.req.raw = withoutValidators(c.req.raw);
await next();
c.header("Vary", "Sec-Fetch-Site", { append: true });
- if (fromAnotherSite(c) || (sandboxCaptures && isThumbnailCapture(c)))
+ const anotherSite = fromAnotherSite(c);
+ if (anotherSite || (sandboxCaptures && isThumbnailCapture(c)))
c.header("Content-Security-Policy", "sandbox allow-scripts");
+ if (anotherSite) await markPreviewForAnotherSite(c);
};
-async function refuseThumbnailForAnotherSite(c: Context, next: Next) {
+const refuseForAnotherSite = (what: string) => async (c: Context, next: Next) => {
if (fromAnotherSite(c))
- return c.json({ error: "forbidden: thumbnail requested by another site" }, 403);
+ return c.json({ error: `forbidden: ${what} requested by another site` }, 403);
return next();
-}
+};
function urlHost(url: string): string | undefined {
try {
@@ -103,7 +132,9 @@ export function createStudioApi(adapter: StudioApiAdapter, options: StudioApiOpt
if (!projectId) return c.json({ error: "not found" }, 404);
return c.json({ token: frameTokens.tokenFor(projectId) }, 200, { "Cache-Control": "no-store" });
});
- api.use("/projects/:id/thumbnail/*", refuseThumbnailForAnotherSite);
+ api.use("/projects/:id/thumbnail/*", refuseForAnotherSite("thumbnail"));
+ api.use("/projects/:id/waveform/*", refuseForAnotherSite("waveform"));
+ api.use("/projects/:id/peaks/*", refuseForAnotherSite("peaks"));
// This API is unauthenticated and simple cross-origin POSTs need no
// preflight, so the guard rejects writes the shared predicate refuses.
api.use(async function rejectCrossOriginWrites(c, next) {
diff --git a/packages/studio-server/src/helpers/jobSlots.test.ts b/packages/studio-server/src/helpers/jobSlots.test.ts
new file mode 100644
index 0000000000..21f2d92507
--- /dev/null
+++ b/packages/studio-server/src/helpers/jobSlots.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { createJobSlots, JobAbandonedError } from "./jobSlots.js";
+
+const gate = () => {
+ let open: () => void = () => {};
+ const opened = new Promise((resolve) => (open = resolve));
+ return { open, opened };
+};
+
+describe("createJobSlots", () => {
+ it("queues jobs past the limit and runs them as slots free", async () => {
+ const run = createJobSlots(1);
+ const first = gate();
+ const running = run(() => first.opened);
+ const queued = [run(async () => "second"), run(async () => "third")];
+ first.open();
+ await running;
+ await expect(Promise.all(queued)).resolves.toEqual(["second", "third"]);
+ });
+
+ it("drops a queued job whose request went away, and frees its place", async () => {
+ const run = createJobSlots(1);
+ const first = gate();
+ const running = run(() => first.opened);
+ const gone = new AbortController();
+ let started = false;
+ const abandoned = run(async () => {
+ started = true;
+ }, gone.signal);
+ gone.abort();
+ await expect(abandoned).rejects.toBeInstanceOf(JobAbandonedError);
+ const next = run(async () => "next");
+ first.open();
+ await running;
+ await expect(next).resolves.toBe("next");
+ expect(started).toBe(false);
+ });
+});
diff --git a/packages/studio-server/src/helpers/jobSlots.ts b/packages/studio-server/src/helpers/jobSlots.ts
new file mode 100644
index 0000000000..dfe07062ea
--- /dev/null
+++ b/packages/studio-server/src/helpers/jobSlots.ts
@@ -0,0 +1,46 @@
+export class JobAbandonedError extends Error {
+ constructor() {
+ super("job abandoned before it started");
+ this.name = "JobAbandonedError";
+ }
+}
+
+/** Runs at most `limit` jobs at once; a waiter whose signal aborts leaves the queue without starting. */
+export function createJobSlots(limit: number) {
+ let running = 0;
+ const waiting: Array<() => void> = [];
+
+ const acquire = (signal?: AbortSignal) =>
+ new Promise((resolve, reject) => {
+ if (signal?.aborted) return reject(new JobAbandonedError());
+ if (running < limit) {
+ running++;
+ return resolve();
+ }
+ const leave = () => {
+ waiting.splice(waiting.indexOf(start), 1);
+ reject(new JobAbandonedError());
+ };
+ const start = () => {
+ signal?.removeEventListener("abort", leave);
+ resolve();
+ };
+ waiting.push(start);
+ signal?.addEventListener("abort", leave, { once: true });
+ });
+
+ const release = () => {
+ const next = waiting.shift();
+ if (next) next();
+ else running--;
+ };
+
+ return async function run(job: () => Promise, signal?: AbortSignal): Promise {
+ await acquire(signal);
+ try {
+ return await job();
+ } finally {
+ release();
+ }
+ };
+}
diff --git a/packages/studio-server/src/helpers/proxyTranscoder.test.ts b/packages/studio-server/src/helpers/proxyTranscoder.test.ts
index a3ebc1e0d9..fc85e68126 100644
--- a/packages/studio-server/src/helpers/proxyTranscoder.test.ts
+++ b/packages/studio-server/src/helpers/proxyTranscoder.test.ts
@@ -2033,6 +2033,89 @@ describe("resolveStill", () => {
},
60_000,
);
+
+ async function stillSetup() {
+ const spy = createSpawnSpy();
+ const { resolveStill } = await loadModule(spy.spawn, FFMPEG_PATH);
+ const projectDir = tmpProject();
+ const clip = join(projectDir, "clip.mp4");
+ writeFileSync(clip, "clip");
+ const ask = (signal?: AbortSignal) =>
+ resolveStill(projectDir, clip, 1, undefined, undefined, signal);
+ return { calls: spy.calls, ask };
+ }
+
+ it("ends a still's ffmpeg once the last request waiting on it leaves, and starts afresh after", async () => {
+ const { calls, ask } = await stillSetup();
+ const first = new AbortController();
+ const second = new AbortController();
+ const firstWait = ask(first.signal);
+ const secondWait = ask(second.signal);
+ await flush();
+ expect(calls).toHaveLength(1);
+
+ first.abort();
+ await expect(firstWait).rejects.toBe(first.signal.reason);
+ expect(calls[0]!.options?.signal?.aborted).toBe(false);
+ second.abort();
+ await expect(secondWait).rejects.toBe(second.signal.reason);
+ expect(calls[0]!.options?.signal?.aborted).toBe(true);
+
+ calls[0]!.proc.emit("close", null, "SIGKILL");
+ await flush();
+ const again = ask();
+ await flush();
+ expect(calls).toHaveLength(2);
+ succeed(calls[1]!);
+ await expect(again).resolves.toMatch(/\.jpg$/);
+ });
+
+ it("keeps a still's ffmpeg running while a request without a signal waits on it", async () => {
+ const { calls, ask } = await stillSetup();
+ const kept = ask();
+ const leaving = new AbortController();
+ const left = ask(leaving.signal);
+ await flush();
+ leaving.abort();
+ await expect(left).rejects.toBe(leaving.signal.reason);
+
+ expect(calls[0]!.options?.signal?.aborted).toBe(false);
+ succeed(calls[0]!);
+ await expect(kept).resolves.toMatch(/\.jpg$/);
+ expect(calls).toHaveLength(1);
+ });
+
+ it.skipIf(process.platform === "win32")(
+ "kills a still's running ffmpeg when its only request leaves",
+ async () => {
+ let child: ChildProcess | undefined;
+ const neverFinishes = (_command: string, _args: string[], options?: SpawnOptions) => {
+ child = realSpawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], options);
+ return child as unknown as FakeProc;
+ };
+ const { resolveStill } = await loadModule(neverFinishes, FFMPEG_PATH);
+ const projectDir = tmpProject();
+ const clip = join(projectDir, "clip.mp4");
+ writeFileSync(clip, "clip");
+ const leaving = new AbortController();
+ const left = resolveStill(projectDir, clip, 1, undefined, undefined, leaving.signal);
+ await flush();
+ leaving.abort();
+ await expect(left).rejects.toBe(leaving.signal.reason);
+
+ const [, exitSignal] = child!.exitCode === null ? await once(child!, "exit") : [];
+ expect(exitSignal).toBe("SIGKILL");
+ },
+ );
+
+ it("starts no ffmpeg for a request that already left", async () => {
+ const { calls, ask } = await stillSetup();
+ const gone = new AbortController();
+ gone.abort();
+ await expect(ask(gone.signal)).rejects.toBe(gone.signal.reason);
+ await flush();
+ expect(calls).toHaveLength(0);
+ });
});
describe("sourceFolderKind", () => {
diff --git a/packages/studio-server/src/helpers/proxyTranscoder.ts b/packages/studio-server/src/helpers/proxyTranscoder.ts
index 0b4d47a041..c39d75c680 100644
--- a/packages/studio-server/src/helpers/proxyTranscoder.ts
+++ b/packages/studio-server/src/helpers/proxyTranscoder.ts
@@ -1145,27 +1145,63 @@ export async function resolveProxies(
return results;
}
-const stillsInFlight = new Map>();
+interface StillJob {
+ made: Promise;
+ /** Requests still waiting; one without a signal never leaves, so its still is always made. */
+ waiters: number;
+ abandoned: AbortController;
+}
-/** One JPEG of the source at a time (to a tenth of a second), sized like the copy's box. */
+const stillsInFlight = new Map();
+
+/** One JPEG of the source at a time (to a tenth of a second), sized like the copy's box. A
+ * caller's `signal` detaches that caller; once no caller is left, the still's ffmpeg is ended. */
export function resolveStill(
projectDir: string,
absoluteSourcePath: string,
atSeconds: number,
box?: PreviewProxyBox,
+ startUncachedStill: (make: () => Promise) => Promise = (make) => make(),
+ signal?: AbortSignal,
): Promise {
+ if (signal?.aborted) return Promise.reject(signal.reason);
const source = canonicalizeProxySource(projectDir, absoluteSourcePath);
const at = Math.max(0, Math.round(atSeconds * 10) / 10);
const key = fastCopyKey(source.sourcePath, PROXY_PARAMS_VERSION, `still@${at}`, box);
const cachePath = join(source.projectDir, CACHE_DIR_NAME, `${key}${PROXY_STILL_EXTENSION}`);
if (existsSync(cachePath)) return Promise.resolve(cachePath);
- const shared = stillsInFlight.get(cachePath);
- if (shared) return shared;
- const made = makeStill(source, at, box, cachePath).finally(() =>
- stillsInFlight.delete(cachePath),
- );
- stillsInFlight.set(cachePath, made);
- return made;
+ let job = stillsInFlight.get(cachePath);
+ if (!job) {
+ const abandoned = new AbortController();
+ const made = startUncachedStill(() =>
+ makeStill(source, at, box, cachePath, abandoned.signal),
+ ).finally(() => forgetStill(cachePath, started));
+ const started: StillJob = { made, waiters: 0, abandoned };
+ stillsInFlight.set(cachePath, started);
+ job = started;
+ }
+ return waitForStill(job, cachePath, signal);
+}
+
+function forgetStill(cachePath: string, job: StillJob): void {
+ if (stillsInFlight.get(cachePath) === job) stillsInFlight.delete(cachePath);
+}
+
+function waitForStill(job: StillJob, cachePath: string, signal?: AbortSignal): Promise {
+ job.waiters++;
+ if (!signal) return job.made;
+ return new Promise((resolveWait, rejectWait) => {
+ const leave = (): void => {
+ rejectWait(signal.reason);
+ if (--job.waiters > 0) return;
+ forgetStill(cachePath, job);
+ job.abandoned.abort();
+ };
+ signal.addEventListener("abort", leave, { once: true });
+ job.made
+ .finally(() => signal.removeEventListener("abort", leave))
+ .then(resolveWait, rejectWait);
+ });
}
async function makeStill(
@@ -1173,6 +1209,7 @@ async function makeStill(
at: number,
box: PreviewProxyBox | undefined,
cachePath: string,
+ signal: AbortSignal,
): Promise {
const ffmpegPath = findFfBinary("ffmpeg", { configuredMustExist: true });
if (!ffmpegPath) throw new FfmpegUnavailableError();
@@ -1193,7 +1230,7 @@ async function makeStill(
"0:V:0",
];
args.push("-frames:v", "1", "-vf", filter, "-pix_fmt", "yuvj420p", "-q:v", "3", tempPath);
- await spawnFfmpeg(ffmpegPath, args, TRANSCODE_STALL_MS, new AbortController().signal);
+ await spawnFfmpeg(ffmpegPath, args, TRANSCODE_STALL_MS, signal);
renameSync(tempPath, cachePath);
} finally {
rmSync(tempPath, { force: true });
diff --git a/packages/studio-server/src/routes/peaks.test.ts b/packages/studio-server/src/routes/peaks.test.ts
index b4986fd72f..6f53f63485 100644
--- a/packages/studio-server/src/routes/peaks.test.ts
+++ b/packages/studio-server/src/routes/peaks.test.ts
@@ -1,6 +1,6 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { Hono } from "hono";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { registerPeakRoutes } from "./peaks";
@@ -15,6 +15,8 @@ function setup(decode: (path: string) => Promise) {
const dir = mkdtempSync(join(tmpdir(), "hf-peaks-route-"));
dirs.push(dir);
writeFileSync(join(dir, "talk.mp4"), "video");
+ mkdirSync(join(dir, "media"));
+ writeFileSync(join(dir, "media", "talk.mp4"), "video");
const app = new Hono();
registerPeakRoutes(app, stubAdapter(dir), decode);
return app;
@@ -45,6 +47,16 @@ describe("GET /projects/:id/peaks/*", () => {
expect(decode).toHaveBeenCalledTimes(1);
});
+ it("decodes a file once however the request spells its path", async () => {
+ const decode = vi.fn(async () => [0.4]);
+ const app = setup(decode);
+ for (const spelling of ["media/talk.mp4", "media//talk.mp4", "media/talk.mp4/"]) {
+ const res = await app.request(`http://localhost/projects/p/peaks/${spelling}`);
+ expect((await res.json()).bins).toEqual([0.4]);
+ }
+ expect(decode).toHaveBeenCalledTimes(1);
+ });
+
it("404s a missing file and a path outside the project", async () => {
const app = setup(async () => []);
expect((await app.request("http://localhost/projects/p/peaks/nope.mp4")).status).toBe(404);
diff --git a/packages/studio-server/src/routes/peaks.ts b/packages/studio-server/src/routes/peaks.ts
index 2697461c05..6d36bfd2c6 100644
--- a/packages/studio-server/src/routes/peaks.ts
+++ b/packages/studio-server/src/routes/peaks.ts
@@ -1,5 +1,5 @@
import { existsSync, readFileSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { join, relative, resolve } from "node:path";
import { isWithinProjectRoot } from "@hyperframes/parsers/asset-resolution";
import type { Hono } from "hono";
import type { StudioApiAdapter } from "../types.js";
@@ -46,7 +46,7 @@ export function registerPeakRoutes(
if (!stats?.isFile()) return c.json({ error: "file not found" }, 404);
const cacheDir = join(project.dir, ".waveform-cache");
- const cachePath = join(cacheDir, buildPeakMapCacheKey(assetPath, stats));
+ const cachePath = join(cacheDir, buildPeakMapCacheKey(relative(project.dir, mediaPath), stats));
const cached = readCachedBins(cacheDir, cachePath);
if (cached) return c.json({ binSeconds: PEAK_BIN_SECONDS, bins: cached });
diff --git a/packages/studio-server/src/routes/preview.sandbox.test.ts b/packages/studio-server/src/routes/preview.sandbox.test.ts
index 559b61d107..cad9493387 100644
--- a/packages/studio-server/src/routes/preview.sandbox.test.ts
+++ b/packages/studio-server/src/routes/preview.sandbox.test.ts
@@ -67,18 +67,61 @@ describe.each(routes)("%s", (_name, path, type) => {
);
});
+describe("a preview document answered to another site", () => {
+ const MARK = '';
+ const documents = routes.filter(([, , type]) => type === "text/html");
+
+ it.each(documents)("%s is marked so its runtime offers no editing port", async (_n, path) => {
+ const res = await get(path, "cross-site");
+ const body = await res.text();
+ expect(body).toContain(MARK);
+ expect(res.headers.get("content-length")).toBeNull();
+ expect(res.headers.get("etag")).toBeNull();
+ expect(res.headers.get("content-security-policy")).toBe(SANDBOX);
+ });
+
+ it.each(documents)("%s stays unmarked for the Studio's own pages", async (_n, path) => {
+ const res = await get(path, "same-origin");
+ expect(await res.text()).not.toContain(MARK);
+ });
+
+ it("leaves a file that is not a document as served", async () => {
+ const res = await get("/projects/demo/preview/icon.svg", "cross-site");
+ expect(await res.text()).not.toContain(MARK);
+ });
+});
+
describe("a revalidated preview", () => {
- it("still names Sec-Fetch-Site in Vary and carries the sandbox on a 304", async () => {
- const first = await get("/projects/demo/preview", "same-origin");
- const etag = first.headers.get("etag");
+ it("still names Sec-Fetch-Site in Vary on a 304 to the Studio's own pages", async () => {
+ const etag = (await get("/projects/demo/preview", "same-origin")).headers.get("etag");
expect(etag).toBeTruthy();
const res = await api.request("http://localhost/projects/demo/preview", {
- headers: { "sec-fetch-site": "cross-site", "if-none-match": etag! },
+ headers: { "sec-fetch-site": "same-origin", "if-none-match": etag! },
});
expect(res.status).toBe(304);
expect(res.headers.get("vary")).toBe("Sec-Fetch-Site");
- expect(res.headers.get("content-security-policy")).toBe(SANDBOX);
});
+
+ it.each(["cross-site", "same-site"])(
+ "answers a %s frame load carrying the unmarked copy's validators with a marked 200",
+ async (site) => {
+ const first = await get("/projects/demo/preview", "same-origin");
+ const etag = first.headers.get("etag");
+ expect(etag).toBeTruthy();
+ const res = await api.request("http://localhost/projects/demo/preview", {
+ headers: {
+ "sec-fetch-site": site,
+ "sec-fetch-dest": "iframe",
+ "if-none-match": etag!,
+ "if-modified-since": new Date(Date.now() + 60_000).toUTCString(),
+ },
+ });
+ expect(res.status).toBe(200);
+ expect(await res.text()).toContain('');
+ expect(res.headers.get("vary")).toBe("Sec-Fetch-Site");
+ expect(res.headers.get("content-security-policy")).toBe(SANDBOX);
+ },
+ );
});
describe("a thumbnail capture document", () => {
diff --git a/packages/studio-server/src/routes/preview.test.ts b/packages/studio-server/src/routes/preview.test.ts
index 035d5b1f0b..987e864112 100644
--- a/packages/studio-server/src/routes/preview.test.ts
+++ b/packages/studio-server/src/routes/preview.test.ts
@@ -1674,6 +1674,7 @@ describe("hf-proxy negotiation and media codec map injection (U3)", () => {
absoluteSourcePath: string,
at: number,
box?: { width: number; height: number },
+ startUncachedStill?: (make: () => Promise) => Promise,
) => Promise;
scanMapImpl?: ScanMapImpl;
probeAssetCodecImpl?: () => Promise<{
@@ -1939,6 +1940,8 @@ describe("hf-proxy negotiation and media codec map injection (U3)", () => {
join(projectDir, "clip.mp4"),
12.34,
undefined,
+ expect.any(Function),
+ expect.any(AbortSignal),
);
expect((await app.request(`${url}&hf-proxy-still=-1`)).status).toBe(404);
@@ -1950,6 +1953,108 @@ describe("hf-proxy negotiation and media codec map injection (U3)", () => {
expect(resolveStillMock).toHaveBeenCalledTimes(1);
});
+ it("makes at most four new stills at once, and serves a finished still without waiting", async () => {
+ const projectDir = createProjectDir();
+ writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes");
+ const stillPath = join(projectDir, "still.jpg");
+ writeFileSync(stillPath, "jpegbytes");
+ const finishers: Array<() => void> = [];
+ let running = 0;
+ let mostRunning = 0;
+ const resolveStillMock = vi.fn(
+ async (
+ _dir: string,
+ _file: string,
+ at: number,
+ _box?: { width: number; height: number },
+ startUncachedStill?: (make: () => Promise) => Promise,
+ ) => {
+ if (at === 99) return stillPath;
+ return startUncachedStill!(async () => {
+ mostRunning = Math.max(mostRunning, ++running);
+ await new Promise((resolve) => finishers.push(resolve));
+ running--;
+ return stillPath;
+ });
+ },
+ );
+ const { registerPreviewRoutes: register } = await loadPreviewModule({
+ resolveStillImpl: resolveStillMock,
+ });
+ const app = new Hono();
+ register(app, createAdapter(projectDir));
+ const url = "http://localhost/projects/demo/preview/clip.mp4?hf-proxy=h264&hf-proxy-still=";
+
+ const made = Array.from({ length: 40 }, (_, i) => app.request(`${url}${i}`));
+ await vi.waitFor(() => expect(finishers).toHaveLength(4));
+ const finished = await app.request(`${url}99`);
+ expect(finished.status).toBe(200);
+ expect(finishers).toHaveLength(4);
+
+ let ended = 0;
+ while (ended < 40) {
+ await vi.waitFor(() => expect(finishers.length).toBeGreaterThan(0));
+ finishers.shift()?.();
+ ended++;
+ }
+ for (const res of await Promise.all(made)) expect(res.status).toBe(200);
+ expect(mostRunning).toBe(4);
+ });
+
+ it("makes a still again for a request that shared a waiter whose client left", async () => {
+ const projectDir = createProjectDir();
+ writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes");
+ const stillPath = join(projectDir, "still.jpg");
+ writeFileSync(stillPath, "jpegbytes");
+ const finishers: Array<() => void> = [];
+ const inFlight = new Map>();
+ const made: number[] = [];
+ const resolveStillMock = vi.fn(
+ (
+ _dir: string,
+ _file: string,
+ at: number,
+ _box?: { width: number; height: number },
+ startUncachedStill?: (make: () => Promise) => Promise,
+ ) => {
+ const shared = inFlight.get(at);
+ if (shared) return shared;
+ const making = startUncachedStill!(async () => {
+ made.push(at);
+ await new Promise((resolve) => finishers.push(resolve));
+ return stillPath;
+ }).finally(() => inFlight.delete(at));
+ inFlight.set(at, making);
+ return making;
+ },
+ );
+ const { registerPreviewRoutes: register } = await loadPreviewModule({
+ resolveStillImpl: resolveStillMock,
+ });
+ const app = new Hono();
+ register(app, createAdapter(projectDir));
+ const url = "http://localhost/projects/demo/preview/clip.mp4?hf-proxy=h264&hf-proxy-still=";
+
+ const busy = [1, 2, 3, 4].map((at) => app.request(`${url}${at}`));
+ await vi.waitFor(() => expect(finishers).toHaveLength(4));
+ const leaving = new AbortController();
+ const first = app.request(`${url}10`, { signal: leaving.signal }).catch(() => null);
+ await vi.waitFor(() => expect(resolveStillMock).toHaveBeenCalledTimes(5));
+ const second = app.request(`${url}10`);
+ await vi.waitFor(() => expect(resolveStillMock).toHaveBeenCalledTimes(6));
+ leaving.abort();
+ await first;
+ await vi.waitFor(() => expect(resolveStillMock).toHaveBeenCalledTimes(7));
+
+ for (let ended = 0; ended < 5; ended++) {
+ await vi.waitFor(() => expect(finishers.length).toBeGreaterThan(0));
+ finishers.shift()?.();
+ }
+ expect((await second).status).toBe(200);
+ for (const res of await Promise.all(busy)) expect(res.status).toBe(200);
+ expect(made).toEqual([1, 2, 3, 4, 10]);
+ });
+
it("honors If-None-Match on a repeat request with a 304, without re-invoking resolveProxy", async () => {
const projectDir = createProjectDir();
writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes");
diff --git a/packages/studio-server/src/routes/preview.ts b/packages/studio-server/src/routes/preview.ts
index 634706da57..a8cc8b8fb1 100644
--- a/packages/studio-server/src/routes/preview.ts
+++ b/packages/studio-server/src/routes/preview.ts
@@ -103,8 +103,11 @@ import {
import { requestSubPath } from "../helpers/requestSubPath.js";
import { lazyPreviewImages } from "../helpers/lazyPreviewImages.js";
import { corsProjectVideos } from "../helpers/captureVideos.js";
+import { createJobSlots, JobAbandonedError } from "../helpers/jobSlots.js";
const PROJECT_SIGNATURE_META = "hyperframes-project-signature";
+const runStillJob = createJobSlots(4);
+
function escapeGsapUrl(url: string): string {
return url.replace(/&/g, "&").replace(/"/g, """);
}
@@ -778,7 +781,13 @@ export function registerPreviewRoutes(
return c.text("not found", 404);
}
try {
- const still = await resolveStill(project.dir, file, at, proxyBox);
+ const inSlot = (make: () => Promise) => runStillJob(make, c.req.raw.signal);
+ const ask = () => resolveStill(project.dir, file, at, proxyBox, inSlot, c.req.raw.signal);
+ const still = await ask().catch((err) =>
+ err instanceof JobAbandonedError && !c.req.raw.signal.aborted
+ ? ask()
+ : Promise.reject(err),
+ );
return new Response(readFileSync(still), {
headers: { "Content-Type": "image/jpeg", "Cache-Control": "private, max-age=3600" },
});
diff --git a/packages/studio-server/src/routes/waveform.test.ts b/packages/studio-server/src/routes/waveform.test.ts
new file mode 100644
index 0000000000..3c3b2d2e09
--- /dev/null
+++ b/packages/studio-server/src/routes/waveform.test.ts
@@ -0,0 +1,35 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Hono } from "hono";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { decodeAudioPeaks } from "../helpers/waveform.js";
+import { registerWaveformRoutes } from "./waveform";
+import { stubAdapter } from "./stubAdapter.test-helpers";
+
+vi.mock("../helpers/waveform.js", async (importOriginal) => ({
+ ...(await importOriginal()),
+ decodeAudioPeaks: vi.fn(async () => [0.3]),
+}));
+
+const dirs: string[] = [];
+afterEach(() => {
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+describe("GET /projects/:id/waveform/*", () => {
+ it("decodes a file once however the request spells its path", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "hf-waveform-route-"));
+ dirs.push(dir);
+ mkdirSync(join(dir, "media"));
+ writeFileSync(join(dir, "media", "bed.wav"), "audio");
+ const app = new Hono();
+ registerWaveformRoutes(app, stubAdapter(dir));
+
+ for (const spelling of ["media/bed.wav", "media//bed.wav", "media/bed.wav/"]) {
+ const res = await app.request(`http://localhost/projects/p/waveform/${spelling}`);
+ expect(await res.json()).toEqual({ peaks: [0.3] });
+ }
+ expect(decodeAudioPeaks).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/packages/studio-server/src/routes/waveform.ts b/packages/studio-server/src/routes/waveform.ts
index 3a6054bebd..ed8a1a518c 100644
--- a/packages/studio-server/src/routes/waveform.ts
+++ b/packages/studio-server/src/routes/waveform.ts
@@ -1,5 +1,5 @@
import { existsSync, readFileSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { join, relative, resolve } from "node:path";
import { isWithinProjectRoot } from "@hyperframes/parsers/asset-resolution";
import type { Hono } from "hono";
import type { StudioApiAdapter } from "../types.js";
@@ -27,7 +27,10 @@ export function registerWaveformRoutes(api: Hono, adapter: StudioApiAdapter): vo
const cacheDir = join(project.dir, ".waveform-cache");
// Keyed on the file's size and mtime as well as its name, so re-encoding an
// asset in place invalidates its peaks instead of drawing the old ones.
- const cachePath = join(cacheDir, buildWaveformCacheKey(assetPath, stats));
+ const cachePath = join(
+ cacheDir,
+ buildWaveformCacheKey(relative(project.dir, audioPath), stats),
+ );
try {
if (isWaveformCacheDirectory(cacheDir) && existsSync(cachePath)) {
diff --git a/scripts/package-size-budgets.json b/scripts/package-size-budgets.json
index 9649cb8889..ffc9a0be13 100644
--- a/scripts/package-size-budgets.json
+++ b/scripts/package-size-budgets.json
@@ -57,6 +57,6 @@
},
"@hyperframes/studio-server": {
"packed": 172000,
- "unpacked": 654000
+ "unpacked": 672000
}
}