diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 356339d53a..f379445b7f 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "hyperframes", "description": "HyperFrames by HeyGen. Write HTML, render video. Compositions, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website capture for HyperFrames.", - "version": "0.8.61", + "version": "0.8.62", "author": { "name": "HeyGen", "email": "hyperframes@heygen.com", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 44782b6737..2dd1605c7b 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "hyperframes", "description": "Write HTML, render video. Compositions, Tailwind v4 styles, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website capture for HyperFrames.", - "version": "0.8.61", + "version": "0.8.62", "author": { "name": "HeyGen", "email": "hyperframes@heygen.com", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 629623d1e4..a529c3dfba 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -3,7 +3,7 @@ "name": "hyperframes", "displayName": "HyperFrames by HeyGen", "description": "Write HTML, render video. Compositions, Tailwind v4 styles, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website capture for HyperFrames.", - "version": "0.8.61", + "version": "0.8.62", "author": { "name": "HeyGen", "email": "hyperframes@heygen.com" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0502cd4865..81fd4e1349 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -483,6 +483,7 @@ jobs: - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 with: node-version: 22 + - uses: ./.github/actions/install-ffmpeg-linux - name: Discover and run skills tests # We expand the test list via bash so the job fails loudly when the # matcher comes back empty, rather than silently no-op'ing (which diff --git a/README.md b/README.md index 58fa6d4e56..7614fe451a 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ Try a prompt like: > Using `/hyperframes`, create a 10-second product intro with a fade-in title, a background video, and subtle background music. -The skills teach agents the HyperFrames production loop: plan the video, write valid HTML, wire seekable animations, add media, lint, preview, and render. They work with Claude Code, Cursor, Gemini CLI, Codex, and other coding agents that support skills. +The skills teach agents the HyperFrames production loop: plan the video, write valid HTML, wire seekable animations, add media, lint, preview, and render. They work with Claude Code, Codex, Cursor, Gemini CLI, IBM Bob, and other coding agents that support skills. ## Skills diff --git a/bun.lock b/bun.lock index 1b3374002c..279120a05e 100644 --- a/bun.lock +++ b/bun.lock @@ -24,7 +24,7 @@ }, "packages/aws-lambda": { "name": "@hyperframes/aws-lambda", - "version": "0.8.59", + "version": "0.8.62", "dependencies": { "@aws-sdk/client-s3": "^3.700.0", "@aws-sdk/client-sfn": "^3.700.0", @@ -57,7 +57,7 @@ }, "packages/cli": { "name": "@hyperframes/cli", - "version": "0.8.59", + "version": "0.8.62", "bin": { "hyperframes": "./bin/hyperframes.mjs", "hyperframes-localize-fonts": "./bin/hyperframes-localize-fonts.mjs", @@ -109,7 +109,7 @@ }, "packages/core": { "name": "@hyperframes/core", - "version": "0.8.59", + "version": "0.8.62", "dependencies": { "@chenglou/pretext": "^0.0.5", "@hyperframes/lint": "workspace:*", @@ -134,7 +134,7 @@ }, "packages/engine": { "name": "@hyperframes/engine", - "version": "0.8.59", + "version": "0.8.62", "dependencies": { "@hono/node-server": "^2.0.5", "@hyperframes/core": "workspace:^", @@ -153,7 +153,7 @@ }, "packages/gcp-cloud-run": { "name": "@hyperframes/gcp-cloud-run", - "version": "0.8.59", + "version": "0.8.62", "dependencies": { "@google-cloud/storage": "^7.14.0", "@google-cloud/workflows": "^4.2.0", @@ -174,7 +174,7 @@ }, "packages/lint": { "name": "@hyperframes/lint", - "version": "0.8.59", + "version": "0.8.62", "dependencies": { "@hyperframes/parsers": "workspace:*", "htmlparser2": "^10.1.0", @@ -192,7 +192,7 @@ }, "packages/parsers": { "name": "@hyperframes/parsers", - "version": "0.8.59", + "version": "0.8.62", "dependencies": { "@babel/parser": "^7.27.0", "acorn": "^8.17.0", @@ -212,7 +212,7 @@ }, "packages/player": { "name": "@hyperframes/player", - "version": "0.8.59", + "version": "0.8.62", "dependencies": { "@hyperframes/core": "workspace:*", }, @@ -227,7 +227,7 @@ }, "packages/producer": { "name": "@hyperframes/producer", - "version": "0.8.59", + "version": "0.8.62", "dependencies": { "@fontsource/archivo-black": "^5.2.8", "@fontsource/eb-garamond": "^5.2.7", @@ -272,7 +272,7 @@ }, "packages/sdk": { "name": "@hyperframes/sdk", - "version": "0.8.59", + "version": "0.8.62", "dependencies": { "@hyperframes/core": "workspace:*", "@hyperframes/parsers": "workspace:*", @@ -302,7 +302,7 @@ }, "packages/shader-transitions": { "name": "@hyperframes/shader-transitions", - "version": "0.8.59", + "version": "0.8.62", "dependencies": { "html2canvas": "^1.4.1", }, @@ -314,7 +314,7 @@ }, "packages/studio": { "name": "@hyperframes/studio", - "version": "0.8.59", + "version": "0.8.62", "dependencies": { "@base-ui/react": "1.7.0", "@codemirror/autocomplete": "^6.20.1", @@ -366,7 +366,7 @@ }, "packages/studio-server": { "name": "@hyperframes/studio-server", - "version": "0.8.59", + "version": "0.8.62", "dependencies": { "@hyperframes/core": "workspace:*", "@hyperframes/parsers": "workspace:*", diff --git a/docs/changelog.mdx b/docs/changelog.mdx index 9564dceef6..f056409202 100644 --- a/docs/changelog.mdx +++ b/docs/changelog.mdx @@ -8,6 +8,22 @@ Recent HyperFrames releases, including user-facing features, fixes, and migratio {/* New release entries are prepended by `bun run changelog:draft --write`. */} + +Studio no longer drops an edit's preview while its tab is in the background, and the catalog gains a text match cut. + +## Fixes + +- **Studio:** Don't fail a shadow reload while the tab is hidden ([16959deea](https://github.com/heygen-com/hyperframes/commit/16959deeac55c65a730d18b3a4ef7c366b0e0223), [#4292](https://github.com/heygen-com/hyperframes/pull/4292)). + +## Catalog + +- **Registry:** Text-match-cut ([0945de83c](https://github.com/heygen-com/hyperframes/commit/0945de83c7f51ba0c20c7c0a56421f066a378ee8), [#4288](https://github.com/heygen-com/hyperframes/pull/4288)). + + { if (shuttingDown) return; shuttingDown = true; - process.off("SIGINT", shutdown); - process.off("SIGTERM", shutdown); rl?.close(); reportPreviewShutdown(Boolean(options?.json)); @@ -1653,24 +1655,18 @@ async function runEmbeddedMode( // can't be blocked by a stuck drainBrowserPool(). setTimeout(() => requestCliExit(0), 3000).unref(); - // Kill ffmpeg first (sync, fast), then drain browsers (async, slower). - const cleanup = async () => { - const { closeThumbnailBrowser } = await import("../server/studioServer.js"); - const { drainBrowserPool, killTrackedProcesses } = await import("@hyperframes/engine"); - killTrackedProcesses(); - await closeThumbnailBrowser().catch(() => {}); - await drainBrowserPool().catch(() => {}); - }; - - cleanup() + shutdownStudio() .catch(() => {}) .finally(() => { watcher.close(); result.server.close(() => resolveRun()); }); }; - process.once("SIGINT", shutdown); - process.once("SIGTERM", shutdown); + // `on`, not `once`: a repeat Ctrl+C/SIGTERM while shutdown is running must + // stay caught and no-op via `shuttingDown`, not fall through to the OS + // default once a one-shot listener has self-removed after the first signal. + process.on("SIGINT", shutdown); + process.on("SIGTERM", shutdown); // Last-resort cleanup for crash paths (unhandled exceptions/rejections) // that bypass the signal handlers. Eagerly resolve the sync killer so diff --git a/packages/cli/src/media-use/lib/transcriptCutFade.mjs b/packages/cli/src/media-use/lib/transcriptCutFade.mjs new file mode 100644 index 0000000000..bc1676074a --- /dev/null +++ b/packages/cli/src/media-use/lib/transcriptCutFade.mjs @@ -0,0 +1,21 @@ +function round3(n) { + return Math.round(Number(n) * 1000) / 1000; +} + +// 30ms in/out ramps kill the click at every concat boundary. A segment shorter +// than 4x the ramp would spend its whole length fading, so scale down there and +// skip entirely on a degenerate one. fadeIn/fadeOut are false at the export's +// own true start/end, where there is no splice to smooth. +export function fadeFilterFor(durationSeconds, { fadeIn, fadeOut }) { + if (!fadeIn && !fadeOut) return null; + const FADE_SECONDS = 0.03; + if (!Number.isFinite(durationSeconds) || durationSeconds <= 0.01) return null; + const d = Math.min(FADE_SECONDS, durationSeconds / 4); + const parts = []; + if (fadeIn) parts.push(`afade=t=in:st=0:d=${round3(d)}`); + if (fadeOut) { + const out = round3(durationSeconds - d); + if (out > 0) parts.push(`afade=t=out:st=${out}:d=${round3(d)}`); + } + return parts.length ? parts.join(",") : null; +} diff --git a/packages/cli/src/media-use/lib/transcriptCutFade.test.mjs b/packages/cli/src/media-use/lib/transcriptCutFade.test.mjs new file mode 100644 index 0000000000..55c97ebf08 --- /dev/null +++ b/packages/cli/src/media-use/lib/transcriptCutFade.test.mjs @@ -0,0 +1,33 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { fadeFilterFor } from "./transcriptCutFade.mjs"; + +test("fades in only at the first segment's trailing splice", () => { + assert.equal(fadeFilterFor(2, { fadeIn: false, fadeOut: true }), "afade=t=out:st=1.97:d=0.03"); +}); + +test("fades both edges of a middle segment's two splices", () => { + assert.equal( + fadeFilterFor(2, { fadeIn: true, fadeOut: true }), + "afade=t=in:st=0:d=0.03,afade=t=out:st=1.97:d=0.03", + ); +}); + +test("fades out only at the last segment's leading splice", () => { + assert.equal(fadeFilterFor(2, { fadeIn: true, fadeOut: false }), "afade=t=in:st=0:d=0.03"); +}); + +test("a single kept segment borders no splice at all", () => { + assert.equal(fadeFilterFor(2, { fadeIn: false, fadeOut: false }), null); +}); + +test("still scales the ramp down on a short segment with both edges faded", () => { + assert.equal( + fadeFilterFor(0.08, { fadeIn: true, fadeOut: true }), + "afade=t=in:st=0:d=0.02,afade=t=out:st=0.06:d=0.02", + ); +}); + +test("skips a degenerate segment even when a splice is requested", () => { + assert.equal(fadeFilterFor(0.005, { fadeIn: true, fadeOut: true }), null); +}); diff --git a/packages/cli/src/server/studioServer.pathSafety.test.ts b/packages/cli/src/server/studioServer.pathSafety.test.ts new file mode 100644 index 0000000000..1ee03ad6ee --- /dev/null +++ b/packages/cli/src/server/studioServer.pathSafety.test.ts @@ -0,0 +1,73 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import * as fs from "node:fs"; +import * as path from "node:path"; +import { createStudioServer } from "./studioServer.js"; +import { + cleanupStudioServerRoot, + makeStudioServerRoot, + writeStudioIndexHtml, +} from "./studioServerTestFixture.js"; + +/** + * The static SPA handlers resolve the raw request path against the bundle + * directory. Hono decodes percent escapes when routing, so an encoded + * separator or dot segment in the request must never walk out of the bundle + * root — browsers would not send those shapes, but anything that can reach + * the bound port can. These tests pin containment at the handler. + */ + +const hooks = vi.hoisted(() => ({ studioDir: "" })); + +// The bundle directory is resolved from __dirname at server construction, so +// point that one `resolve(<...>/server, "studio")` call at a temp tree. +// fallow-ignore-next-line code-duplication +vi.mock("node:path", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + resolve: (...parts: string[]) => + hooks.studioDir && parts.length === 2 && parts[0]?.endsWith("server") && parts[1] === "studio" + ? hooks.studioDir + : actual.resolve(...parts), + }; +}); + +let root: string; +let server: Awaited>; + +beforeEach(async () => { + const fixture = makeStudioServerRoot("hf-studio-containment-"); + root = fixture.root; + hooks.studioDir = fixture.studioDir; + fs.writeFileSync(path.join(root, "studio-marker.txt"), "STUDIO-MARKER"); + writeStudioIndexHtml(hooks.studioDir); + server = await createStudioServer({ projectDir: fixture.projectDir }); +}); + +afterEach(() => { + cleanupStudioServerRoot(server, root, () => (hooks.studioDir = "")); +}); + +describe("static file path containment", () => { + // A percent-encoded backslash decodes to a real separator on Windows, so + // two encoded hops walk from the bundle root to the temp root above it. + it.each(["/assets/..%5c..%5cstudio-marker.txt", "/icons/..%5c..%5cstudio-marker.txt"])( + "rejects encoded traversal %s", + async (requestPath) => { + const response = await server.app.request(requestPath); + expect(response.status).toBe(404); + expect(await response.text()).not.toContain("STUDIO-MARKER"); + }, + ); + + it("still serves the SPA shell and bundle assets", async () => { + const shell = await server.app.request("/"); + expect(shell.status).toBe(200); + expect(await shell.text()).toContain("Studio"); + + fs.writeFileSync(path.join(hooks.studioDir, "assets", "app.js"), "export {};"); + const asset = await server.app.request("/assets/app.js"); + expect(asset.status).toBe(200); + expect(await asset.text()).toContain("export {};"); + }); +}); diff --git a/packages/cli/src/server/studioServer.staticAssets.test.ts b/packages/cli/src/server/studioServer.staticAssets.test.ts index 39a5c11f87..94a514d3ba 100644 --- a/packages/cli/src/server/studioServer.staticAssets.test.ts +++ b/packages/cli/src/server/studioServer.staticAssets.test.ts @@ -1,8 +1,12 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import * as fs from "node:fs"; import * as path from "node:path"; -import { tmpdir } from "node:os"; import { createStudioServer, type StudioServer } from "./studioServer.js"; +import { + cleanupStudioServerRoot, + makeStudioServerRoot, + writeStudioIndexHtml, +} from "./studioServerTestFixture.js"; /** * Cache policy for the studio bundle, decided by ROUTE. Vite emits only @@ -15,6 +19,7 @@ const hooks = vi.hoisted(() => ({ studioDir: "" })); // The bundle directory is resolved from __dirname at server construction, so // point that one `resolve(<...>/server, "studio")` call at a temp tree. +// fallow-ignore-next-line code-duplication vi.mock("node:path", async (importOriginal) => { const actual = await importOriginal(); return { @@ -38,26 +43,19 @@ let root: string; let server: StudioServer; beforeEach(() => { - root = fs.mkdtempSync(path.join(tmpdir(), "hf-studio-assets-")); - hooks.studioDir = path.join(root, "studio"); - const projectDir = path.join(root, "project"); - fs.mkdirSync(projectDir); - fs.mkdirSync(path.join(hooks.studioDir, "assets"), { recursive: true }); + const fixture = makeStudioServerRoot("hf-studio-assets-"); + root = fixture.root; + hooks.studioDir = fixture.studioDir; fs.mkdirSync(path.join(hooks.studioDir, "icons"), { recursive: true }); fs.writeFileSync(path.join(hooks.studioDir, "assets", HASHED_BUNDLE), BUNDLE_BYTES); fs.writeFileSync(path.join(hooks.studioDir, "icons", PUBLIC_ICON), ""); fs.writeFileSync(path.join(hooks.studioDir, "favicon.svg"), ""); - fs.writeFileSync( - path.join(hooks.studioDir, "index.html"), - "Studio", - ); - server = createStudioServer({ projectDir }); + writeStudioIndexHtml(hooks.studioDir); + server = createStudioServer({ projectDir: fixture.projectDir }); }); afterEach(() => { - server.watcher.close(); - fs.rmSync(root, { recursive: true, force: true }); - hooks.studioDir = ""; + cleanupStudioServerRoot(server, root, () => (hooks.studioDir = "")); }); describe("studio bundle cache policy", () => { diff --git a/packages/cli/src/server/studioServer.test.ts b/packages/cli/src/server/studioServer.test.ts index 22c36a7af1..de46426a77 100644 --- a/packages/cli/src/server/studioServer.test.ts +++ b/packages/cli/src/server/studioServer.test.ts @@ -9,6 +9,54 @@ import { loadRuntimeSource } from "./runtimeSource.js"; import { findFFmpeg, findFFprobe } from "../browser/ffmpeg.js"; import { createStudioServer, type StudioServer } from "./studioServer.js"; +// Forces loadStudioProducer() down its production import branch (real +// isDevMode() is true for a .ts test file, which instead throws a +// "requires bun" error before ever reaching executeRenderJob — see +// studioServer.ts's loadStudioProducer). Only startRender reads this. +vi.mock("../utils/env.js", () => ({ isDevMode: () => false })); + +const producerState = vi.hoisted(() => ({ + // Set per-test to control when the render "finishes" so a shutdown that + // races an in-flight render is observable instead of vacuous. + executeRenderJob: ( + _job: unknown, + _dir: string, + _outputPath: string, + _onProgress: unknown, + _signal: AbortSignal, + ): Promise => Promise.resolve(), +})); +vi.mock("@hyperframes/producer", () => ({ + createRenderJob: (opts: Record) => ({ ...opts, perfSummary: undefined }), + executeRenderJob: (...args: Parameters) => + producerState.executeRenderJob(...args), +})); +const engineState = vi.hoisted(() => ({ + acquireBrowser: async (..._args: unknown[]): Promise => { + throw new Error("acquireBrowser called without a test double"); + }, + closeBrowserPool: async (): Promise => {}, +})); +vi.mock("@hyperframes/engine", () => ({ + acquireBrowser: (...args: unknown[]) => engineState.acquireBrowser(...args), + buildChromeArgs: () => [], + killTrackedProcesses: () => {}, + closeBrowserPool: () => engineState.closeBrowserPool(), +})); +vi.mock("../browser/gpuPolicy.js", () => ({ + resolveCaptureBrowserGpuMode: async () => "software", + resolveLocalBrowserGpuMode: () => "software", + compositionRequiresWebGpu: () => false, + assertWebGpuAdapterAvailable: async () => {}, +})); +vi.mock("../browser/preflight.js", async (importOriginal) => ({ + ...(await importOriginal()), + resolveRenderBrowser: async () => ({ executablePath: "/fake/chrome", source: "system" }), +})); +vi.mock("../browser/manager.js", () => ({ + ensureBrowser: async () => ({ executablePath: undefined, source: "system" }), +})); + // Only `fs.watch` is replaced, so the SSE describe below can fire a file-change // on demand; every other server test keeps reading and writing real files. const mockWatcher = new EventEmitter() as EventEmitter & { close: () => void }; @@ -106,6 +154,238 @@ describe("createStudioServer autoProxy plumbing", () => { }); }); +// A render that never reaches the executor (browser check refused, import failed) must fail with +// its reason, not hang until the suite timeout. +async function untilStarted(started: Promise, state: { status: string; error?: string }) { + let timer: ReturnType | undefined; + const never = new Promise((_, reject) => { + timer = setTimeout( + () => + reject( + new Error( + `render never reached executeRenderJob: status=${state.status} error=${state.error}`, + ), + ), + 5_000, + ); + }); + try { + await Promise.race([started, never]); + } finally { + clearTimeout(timer); + } +} + +describe("createStudioServer shutdown", () => { + function startRenderOpts(jobId: string, outputPath: string) { + return { + project: { id: "demo", dir: tmpProject(), title: "demo" }, + outputPath, + format: "mp4" as const, + fps: { num: 30, den: 1 }, + quality: "draft", + jobId, + }; + } + + it("cancels an in-flight render's signal and waits for it before draining the browser pool", async () => { + const events: string[] = []; + let started!: () => void; + const startedPromise = new Promise((resolve) => { + started = resolve; + }); + producerState.executeRenderJob = (_job, _dir, _outputPath, _onProgress, signal) => { + started(); + return new Promise((_resolve, reject) => { + const onAbort = () => + setTimeout(() => { + events.push("render-settled"); + reject(Object.assign(new Error("cancelled"), { name: "AbortError" })); + }, 20); + // A signal aborted before this executor ran would never fire a later + // "abort" listener (edge-triggered, not level-triggered) — check the + // already-aborted case too, same as real capture code must. + if (signal.aborted) onAbort(); + else signal.addEventListener("abort", onAbort); + }); + }; + + server = createStudioServer({ projectDir: tmpProject() }); + const outputPath = join(tmpdir(), "shutdown-render.mp4"); + const state = server.adapter.startRender(startRenderOpts("job-1", outputPath)); + expect(state.status).toBe("rendering"); + + // Wait until the render has actually reached executeRenderJob (several + // microtask hops through loadStudioProducer/ensureBrowser) before racing + // it against shutdown, or shutdown could abort a signal nothing is + // listening on yet — a race in this test, not in the fix under test. + await untilStarted(startedPromise, state); + + await server.shutdown(); + events.push("drain-and-shutdown-returned"); + + expect(events).toEqual(["render-settled", "drain-and-shutdown-returned"]); + }); + + it("refuses a render started after shutdown has begun instead of launching a fresh browser", async () => { + let releaseFirstRender: () => void = () => {}; + let started!: () => void; + const startedPromise = new Promise((resolve) => { + started = resolve; + }); + producerState.executeRenderJob = () => { + started(); + return new Promise((resolve) => { + releaseFirstRender = resolve; + }); + }; + + server = createStudioServer({ projectDir: tmpProject() }); + const first = server.adapter.startRender(startRenderOpts("job-1", join(tmpdir(), "a.mp4"))); + await untilStarted(startedPromise, first); + + const shutdownPromise = server.shutdown(); + // shuttingDown is set synchronously as shutdown()'s first statement, so a + // render request arriving anywhere after that call has been made (even + // before it resolves) must already see it. + const late = server.adapter.startRender(startRenderOpts("job-2", join(tmpdir(), "b.mp4"))); + + expect(late.status).toBe("failed"); + expect(late.error).toMatch(/shutting down/i); + + releaseFirstRender(); + await shutdownPromise; + }); + + const thumbnailOpts = () => ({ + project: { id: "demo", dir: tmpProject(), title: "demo" }, + compPath: "index.html", + seekTime: 0.5, + width: 640, + height: 360, + outputWidth: 640, + outputHeight: 360, + previewUrl: "http://localhost/preview", + signal: new AbortController().signal, + }); + + it("does not launch a browser for a thumbnail request after shutdown has begun", async () => { + const acquire = vi.fn(); + engineState.acquireBrowser = acquire; + server = createStudioServer({ projectDir: tmpProject() }); + await server.shutdown(); + + await expect(server.adapter.generateThumbnail?.(thumbnailOpts())).resolves.toBeNull(); + expect(acquire).not.toHaveBeenCalled(); + }); + + it("releases a thumbnail browser that finished launching after shutdown began", async () => { + const release = vi.fn(async () => {}); + let launched!: () => void; + const launchedPromise = new Promise((resolve) => (launched = resolve)); + let finishLaunch: () => void = () => {}; + engineState.acquireBrowser = async () => { + launched(); + await new Promise((resolve) => (finishLaunch = resolve)); + return { browser: new EventEmitter(), release }; + }; + let reachedBrowserClose!: () => void; + const reachedBrowserClosePromise = new Promise( + (resolve) => (reachedBrowserClose = resolve), + ); + engineState.closeBrowserPool = async () => reachedBrowserClose(); + server = createStudioServer({ projectDir: tmpProject() }); + const thumbnail = server.adapter.generateThumbnail?.(thumbnailOpts()); + await launchedPromise; + + const shutdown = server.shutdown(); + // shutdown() starts the pool close alongside the thumbnail-browser close, + // before it waits on renders: closing is the signal the close has begun + // while the launch is still pending, without racing a fixed sleep. + await reachedBrowserClosePromise; + finishLaunch(); + await shutdown; + + await expect(thumbnail).resolves.toBeNull(); + expect(release).toHaveBeenCalledTimes(1); + }); + + it("closes browsers within a bounded timeout even when a render's done promise never settles", async () => { + const closeBrowserPool = vi.fn(async () => {}); + engineState.closeBrowserPool = closeBrowserPool; + const release = vi.fn(async () => {}); + let launched!: () => void; + const launchedPromise = new Promise((resolve) => (launched = resolve)); + let finishLaunch: () => void = () => {}; + engineState.acquireBrowser = async () => { + launched(); + await new Promise((resolve) => (finishLaunch = resolve)); + return { browser: new EventEmitter(), release }; + }; + + let started!: () => void; + const startedPromise = new Promise((resolve) => { + started = resolve; + }); + producerState.executeRenderJob = () => { + started(); + // Never settles, even once aborted -- the pathological case the CLI's + // 3s exit watchdog exists to survive. + return new Promise(() => {}); + }; + + server = createStudioServer({ projectDir: tmpProject() }); + const state = server.adapter.startRender(startRenderOpts("job-1", join(tmpdir(), "hang.mp4"))); + await untilStarted(startedPromise, state); + + const thumbnail = server.adapter.generateThumbnail?.(thumbnailOpts()); + await launchedPromise; + finishLaunch(); + + let timer: ReturnType | undefined; + const never = new Promise((_, reject) => { + timer = setTimeout( + () => reject(new Error("shutdown() did not resolve within its bound")), + 3_000, + ); + }); + try { + await Promise.race([server.shutdown(), never]); + } finally { + clearTimeout(timer); + } + + expect(release).toHaveBeenCalledTimes(1); + expect(closeBrowserPool).toHaveBeenCalledTimes(1); + await expect(thumbnail).resolves.toBeNull(); + }); + + it("does not hand an already-leased browser to a new caller once shutdown has begun", async () => { + const release = vi.fn(async () => {}); + const newPage = vi.fn(async () => { + throw new Error("no real page in this test double"); + }); + engineState.acquireBrowser = async () => ({ + browser: { connected: true, newPage, on: () => {} }, + release, + }); + + server = createStudioServer({ projectDir: tmpProject() }); + await server.adapter.generateThumbnail?.(thumbnailOpts()); + expect(newPage).toHaveBeenCalledTimes(1); + + const shutdownPromise = server.shutdown(); + // shuttingDown flips true synchronously as shutdown()'s first statement, + // before its closeThumbnailBrowser() call runs -- this request lands in + // that window and must not reuse the still-connected lease. + const late = server.adapter.generateThumbnail?.(thumbnailOpts()); + + await expect(late).resolves.toBeNull(); + expect(newPage).toHaveBeenCalledTimes(1); + await shutdownPromise; + }); +}); + describe("Studio project lint endpoint", () => { it("surfaces findings that require the complete project graph", async () => { const projectDir = tmpProject(); diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.ts index 9c63828896..cdc6c5a313 100644 --- a/packages/cli/src/server/studioServer.ts +++ b/packages/cli/src/server/studioServer.ts @@ -49,6 +49,7 @@ import { resolveAutoProxy } from "../utils/projectConfig.js"; import { getElementScreenshotClip } from "@hyperframes/studio-server/screenshot-clip"; import type { ScreenshotClip } from "@hyperframes/studio-server/screenshot-clip"; import type { RenderJob } from "@hyperframes/producer"; +import { isWithinProjectRoot } from "@hyperframes/parsers/asset-resolution"; import { seekCompositionTimeline } from "../capture/captureCompositionFrame.js"; import { assertWebGpuAdapterAvailable, @@ -61,6 +62,10 @@ import { const STUDIO_MANUAL_EDITS_PATH = ".hyperframes/studio-manual-edits.json"; +// Under preview.ts's 3s process-exit watchdog, so shutdown() always returns +// before that watchdog can fire and skip this file's browser cleanup. +const RENDER_SHUTDOWN_WAIT_MS = 2_000; + // Vite emits only content-hashed files under dist/assets; hand-authored // public/ files land at the dist root. The route is the signal because the // filename is not: rollup's base64url hash may itself contain a hyphen. @@ -223,7 +228,9 @@ interface ThumbnailBrowserSession { async function getThumbnailBrowser( requestedGpuMode: BrowserGpuMode, + isShuttingDown: () => boolean, ): Promise { + if (isShuttingDown()) return null; if ( _thumbnailBrowserLease?.browser.connected && _thumbnailBrowserModes?.requested === requestedGpuMode @@ -242,6 +249,7 @@ async function getThumbnailBrowser( _thumbnailBrowserInitializing = (async () => { try { + if (isShuttingDown()) return null; const { ensureBrowser } = await import("../browser/manager.js"); const { acquireBrowser, buildChromeArgs } = await import("@hyperframes/engine"); let executablePath: string | undefined; @@ -286,7 +294,11 @@ async function getThumbnailBrowser( return _thumbnailBrowserInitializing; } -export async function closeThumbnailBrowser(): Promise { +async function closeThumbnailBrowser(): Promise { + // A launch kicked off just before this call isn't in _thumbnailBrowserLease + // yet; awaiting it here closes a browser that was mid-launch when the stop + // signal arrived, instead of leaving it running, unreferenced, after exit. + if (_thumbnailBrowserInitializing) await _thumbnailBrowserInitializing.catch(() => {}); if (!_thumbnailBrowserLease) return; const lease = _thumbnailBrowserLease; _thumbnailBrowserLease = null; @@ -315,6 +327,8 @@ export interface StudioServerOptions { export interface StudioServer { app: Hono; watcher: ProjectWatcher; + /** Cancels in-flight renders, then closes every browser this server owns. */ + shutdown(): Promise; /** Exposed for tests: the adapter handed to the shared studio API (carries * the resolved `autoProxy` flag the preview routes read). */ adapter: PreviewApiAdapter; @@ -389,6 +403,12 @@ export function createStudioServer(options: StudioServerOptions): StudioServer { } }); + const inFlightRenders = new Map>(); + // Set synchronously by shutdown() before any await, so a render or + // thumbnail request already queued behind it sees the flag instead of + // launching a browser shutdown() has no way to know about and close. + let shuttingDown = false; + const adapter: PreviewApiAdapter = { // Explicit option wins (preview's resolved --proxy/--no-proxy + config); // otherwise honor the project's hyperframes.json media.autoProxy so every @@ -467,6 +487,15 @@ export function createStudioServer(options: StudioServerOptions): StudioServer { rendersDir: () => join(projectDir, "renders"), startRender(opts): RenderJobState { + if (shuttingDown) { + return { + id: opts.jobId, + status: "failed", + progress: 0, + outputPath: opts.outputPath, + error: "Studio server is shutting down", + }; + } // The render POST is a request boundary like any other. Without this an // already-open Studio tab keeps rendering under the posture cached when // the server booted. @@ -482,7 +511,7 @@ export function createStudioServer(options: StudioServerOptions): StudioServer { // Run render asynchronously, mutating the state object const startTime = Date.now(); - (async () => { + const run = (async () => { let renderJob: RenderJob | undefined; const removeCancelledOutput = () => { // User-initiated cancel: not a failure. Remove any output so the @@ -569,6 +598,9 @@ export function createStudioServer(options: StudioServerOptions): StudioServer { } } })(); + inFlightRenders.set(abortController, run); + const forget = () => void inFlightRenders.delete(abortController); + run.then(forget, forget); return state; }, @@ -584,9 +616,11 @@ export function createStudioServer(options: StudioServerOptions): StudioServer { }, async generateThumbnail(opts): Promise { - const session = await getThumbnailBrowser(browserGpuMode); + const session = await getThumbnailBrowser(browserGpuMode, () => shuttingDown); if (!session) { - console.warn("[Studio] Thumbnail: no browser available — Chrome may not be installed"); + if (!shuttingDown) { + console.warn("[Studio] Thumbnail: no browser available — Chrome may not be installed"); + } return null; } const sourcePath = join(opts.project.dir, opts.compPath); @@ -893,6 +927,12 @@ export function createStudioServer(options: StudioServerOptions): StudioServer { // Studio SPA static files const serveStudioStaticFile = (cacheControl: string) => (c: Context) => { const filePath = resolve(studioDir, c.req.path.slice(1)); + // Percent escapes can decode into separators and dot segments before this + // resolve, so a hostile request can name files above the bundle + // directory. Containment stays lexical on purpose: bundle assets may sit + // behind symlinked directories (same tradeoff as the preview asset + // route), but dot segments must never collapse outside the bundle root. + if (!isWithinProjectRoot(studioDir, filePath)) return c.text("not found", 404); const content = readBundleFile(filePath); if (content === null) return c.text("not found", 404); return new Response(content, { @@ -1003,5 +1043,25 @@ export function createStudioServer(options: StudioServerOptions): StudioServer { return c.html(html, 200, { "Cache-Control": "no-cache" }); }); - return { app, watcher, adapter }; + const shutdown = async (): Promise => { + shuttingDown = true; + const renders = [...inFlightRenders]; + for (const [abortController] of renders) abortController.abort(); + const { killTrackedProcesses, closeBrowserPool } = await import("@hyperframes/engine"); + killTrackedProcesses(); + // Browser close must not wait on renders: a render can outlast preview.ts's + // 3s watchdog, which exits without running this cleanup. closeBrowserPool + // (not drainBrowserPool) also refuses a still-unwinding render's acquire(). + const closeBrowsers = Promise.allSettled([ + closeThumbnailBrowser().catch(() => {}), + closeBrowserPool().catch(() => {}), + ]); + await Promise.race([ + Promise.allSettled(renders.map(([, done]) => done)), + new Promise((resolve) => setTimeout(resolve, RENDER_SHUTDOWN_WAIT_MS).unref()), + ]); + await closeBrowsers; + }; + + return { app, watcher, adapter, shutdown }; } diff --git a/packages/cli/src/server/studioServerTestFixture.ts b/packages/cli/src/server/studioServerTestFixture.ts new file mode 100644 index 0000000000..e66b5ea4fb --- /dev/null +++ b/packages/cli/src/server/studioServerTestFixture.ts @@ -0,0 +1,40 @@ +import * as fs from "node:fs"; +import * as path from "node:path"; +import { tmpdir } from "node:os"; + +/** + * Temp root plus empty `studio/assets` and `project` dirs, shared by every + * studioServer static-file test; each caller writes its own fixture files + * into the returned `studioDir` before constructing the server. + */ +export function makeStudioServerRoot(prefix: string): { + root: string; + studioDir: string; + projectDir: string; +} { + const root = fs.mkdtempSync(path.join(tmpdir(), prefix)); + const studioDir = path.join(root, "studio"); + const projectDir = path.join(root, "project"); + fs.mkdirSync(projectDir); + fs.mkdirSync(path.join(studioDir, "assets"), { recursive: true }); + return { root, studioDir, projectDir }; +} + +/** The one SPA shell every studioServer static-file test needs, unchanged. */ +export function writeStudioIndexHtml(studioDir: string): void { + fs.writeFileSync( + path.join(studioDir, "index.html"), + "Studio", + ); +} + +/** Pairs with makeStudioServerRoot; `onDone` resets caller-local state (e.g. the `hooks.studioDir` mock target). */ +export function cleanupStudioServerRoot( + server: { watcher: { close(): void } }, + root: string, + onDone?: () => void, +): void { + server.watcher.close(); + fs.rmSync(root, { recursive: true, force: true }); + onDone?.(); +} diff --git a/packages/cli/src/telemetry/agent_runtime.test.ts b/packages/cli/src/telemetry/agent_runtime.test.ts index bc96c1897f..5fd2f71f8f 100644 --- a/packages/cli/src/telemetry/agent_runtime.test.ts +++ b/packages/cli/src/telemetry/agent_runtime.test.ts @@ -6,6 +6,9 @@ import { HINT_KEY_PATTERN } from "./agent_runtime.js"; // detectSandboxRuntime is exercised through a small set of node:os mocks. const VENDOR_ENV_KEYS = [ + "BOBSHELL_CLI", + "BOBSHELL_API_KEY", + "BOBSHELL_NO_RELAUNCH", "CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "CODEX_THREAD_ID", @@ -96,6 +99,35 @@ describe("detectAgentRuntime — base behavior", () => { }); }); +describe("detectAgentRuntime — IBM Bob Shell", () => { + const savedEnv = { ...process.env }; + beforeEach(stripVendorEnv); + afterEach(() => { + process.env = { ...savedEnv }; + }); + + it("detects via BOBSHELL_CLI (set on both shell execution paths)", async () => { + process.env["BOBSHELL_CLI"] = "1"; + const { detectAgentRuntime } = await import("./agent_runtime.js"); + expect(detectAgentRuntime()).toBe("bob"); + }); + + it("wins over inherited outer-agent markers as the immediate executor", async () => { + process.env["BOBSHELL_CLI"] = "1"; + process.env["CLAUDECODE"] = "1"; + process.env["CODEX_THREAD_ID"] = "thread-1"; + const { detectAgentRuntime } = await import("./agent_runtime.js"); + expect(detectAgentRuntime()).toBe("bob"); + }); + + it("does not treat Bob authentication or relaunch state as execution proof", async () => { + process.env["BOBSHELL_API_KEY"] = "secret-not-read"; + process.env["BOBSHELL_NO_RELAUNCH"] = "true"; + const { detectAgentRuntime } = await import("./agent_runtime.js"); + expect(detectAgentRuntime()).toBeNull(); + }); +}); + describe("detectAgentRuntime — Claude Code", () => { const savedEnv = { ...process.env }; beforeEach(stripVendorEnv); diff --git a/packages/cli/src/telemetry/agent_runtime.ts b/packages/cli/src/telemetry/agent_runtime.ts index a4b21624f2..9f8ac5f706 100644 --- a/packages/cli/src/telemetry/agent_runtime.ts +++ b/packages/cli/src/telemetry/agent_runtime.ts @@ -22,6 +22,7 @@ import { detectWSL } from "./platform.js"; export type SandboxRuntime = "gvisor" | "firecracker" | "docker" | "kvm" | "wsl" | null; export type AgentRuntime = + | "bob" | "claude_code" | "codex" | "cursor" @@ -47,6 +48,18 @@ interface VendorRule { // before more generic ones (e.g. copilot_agent before a hypothetical generic // 'github_actions' rule). const VENDOR_RULES: VendorRule[] = [ + // IBM Bob Shell — both shell execution paths stamp BOBSHELL_CLI=1 onto the + // child environment: childProcessFallback's spawn env and executeWithPty's + // PTY env. Keep this ahead of other agents because Bob inherits the parent + // environment, so a Bob session launched from Codex or Claude can carry both + // vendors' markers; BOBSHELL_CLI identifies the immediate executor. + // BOBSHELL_API_KEY is deliberately ignored: it is an authentication setting, + // not proof that Bob launched the current process. + // Source: IBM Bob Shell 1.0.6 bundle (lb.childProcessFallback / executeWithPty). + { + name: "bob", + check: (env) => typeof env["BOBSHELL_CLI"] === "string", + }, // Anthropic Claude Code — sets CLAUDECODE=1 on every Bash/PowerShell tool // spawn (Shell.ts:321) and CLAUDE_CODE_ENTRYPOINT at startup, inherited by // every child (main.tsx:527). Both propagate to spawned subprocesses. diff --git a/packages/cli/src/utils/skillsMirror.test.ts b/packages/cli/src/utils/skillsMirror.test.ts index ae5d60f967..06dccbb033 100644 --- a/packages/cli/src/utils/skillsMirror.test.ts +++ b/packages/cli/src/utils/skillsMirror.test.ts @@ -119,6 +119,7 @@ describe("mirrorGlobalSkills", () => { const home = makeHome(); seedStore(home, ["hyperframes", "hyperframes-core"]); installMarker(home, ".cursor"); // cursor present + installMarker(home, ".bob"); // IBM Bob present installMarker(home, ".config/goose"); // goose present (XDG base) // windsurf NOT installed (no ~/.codeium/windsurf) @@ -130,6 +131,7 @@ describe("mirrorGlobalSkills", () => { }); const agents = mirrored.map((m) => m.agent); expect(agents).toContain("cursor"); + expect(agents).toContain("bob"); expect(agents).toContain("goose"); expect(agents).not.toContain("windsurf"); @@ -139,6 +141,12 @@ describe("mirrorGlobalSkills", () => { expect(realpathSync(link)).toBe(realpathSync(join(home, ".claude", "skills", "hyperframes"))); expect(existsSync(join(link, "SKILL.md"))).toBe(true); + const bobLink = join(home, ".bob", "skills", "hyperframes"); + expect(lstatSync(bobLink).isSymbolicLink()).toBe(true); + expect(realpathSync(bobLink)).toBe( + realpathSync(join(home, ".claude", "skills", "hyperframes")), + ); + // goose lands in the XDG config dir (~/.config/goose), not ~/.goose expect( existsSync(join(home, ".config", "goose", "skills", "hyperframes-core", "SKILL.md")), @@ -283,6 +291,7 @@ describe("AGENT_GLOBAL_DIRS (generated table)", () => { const byAgent = new Map(AGENT_GLOBAL_DIRS.map((e) => [e.agent, e])); expect(byAgent.get("claude-code")).toMatchObject({ base: "claudeHome", sub: "skills" }); expect(byAgent.get("cursor")).toMatchObject({ base: "home", sub: ".cursor/skills" }); + expect(byAgent.get("bob")).toMatchObject({ base: "home", sub: ".bob/skills" }); expect(byAgent.get("codex")).toMatchObject({ base: "codexHome", sub: "skills" }); expect(byAgent.get("goose")).toMatchObject({ base: "configHome", sub: "goose/skills" }); expect(byAgent.get("windsurf")).toMatchObject({ diff --git a/packages/core/package.json b/packages/core/package.json index 7cf9e132a3..f7c2a3db8e 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -1,6 +1,6 @@ { "name": "@hyperframes/core", - "version": "0.8.61", + "version": "0.8.62", "description": "", "repository": { "type": "git", diff --git a/packages/engine/package.json b/packages/engine/package.json index 868f3b33bf..81198ce32a 100644 --- a/packages/engine/package.json +++ b/packages/engine/package.json @@ -1,6 +1,6 @@ { "name": "@hyperframes/engine", - "version": "0.8.61", + "version": "0.8.62", "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)", "repository": { "type": "git", diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts index 6806092c03..511999abcc 100644 --- a/packages/engine/src/index.ts +++ b/packages/engine/src/index.ts @@ -79,6 +79,7 @@ export { acquireBrowser, releaseBrowser, drainBrowserPool, + closeBrowserPool, resolveHeadlessShellPath, resolveBrowserGpuMode, buildChromeArgs, diff --git a/packages/engine/src/services/browserLeasePool.test.ts b/packages/engine/src/services/browserLeasePool.test.ts index b2cbf21bf4..a5e2296b48 100644 --- a/packages/engine/src/services/browserLeasePool.test.ts +++ b/packages/engine/src/services/browserLeasePool.test.ts @@ -160,4 +160,50 @@ describe("BrowserLeasePool", () => { await draining; expect(close).toHaveBeenCalledWith(value); }); + + it("refuses acquire after close, even once the drain it started has resolved", async () => { + const value = browser("only"); + const launch = vi.fn().mockResolvedValue({ browser: value, captureMode: "screenshot" }); + const pool = new BrowserLeasePool({ + launch, + close: async (v) => v.close(), + forceClose: vi.fn(), + }); + const first = await pool.acquire(fingerprint(), true); + const releasing = first.release(); + + // drain()'s own drainPromise resets to null once it settles -- close() + // must still refuse a request that arrives after that, not just a + // request that raced the drain while it was in flight. + await pool.close(); + await releasing; + launch.mockClear(); + + await expect(pool.acquire(fingerprint(), true)).rejects.toThrow(/pool is closed/i); + expect(launch).not.toHaveBeenCalled(); + }); + + it("force-closes an entry whose graceful close hangs past drain's bound", async () => { + vi.useFakeTimers(); + try { + const value = browser("stuck"); + const forceClose = vi.fn(); + const pool = new BrowserLeasePool({ + launch: vi.fn().mockResolvedValue({ browser: value, captureMode: "screenshot" }), + close: () => new Promise(() => {}), // never resolves + forceClose, + }); + const lease = await pool.acquire(fingerprint(), true); + const releasing = lease.release(); + + const draining = pool.drain(); + await vi.advanceTimersByTimeAsync(1_100); + await draining; + await releasing; + + expect(forceClose).toHaveBeenCalledWith(value); + } finally { + vi.useRealTimers(); + } + }); }); diff --git a/packages/engine/src/services/browserLeasePool.ts b/packages/engine/src/services/browserLeasePool.ts index 11675727d2..8a4b9e8141 100644 --- a/packages/engine/src/services/browserLeasePool.ts +++ b/packages/engine/src/services/browserLeasePool.ts @@ -63,10 +63,13 @@ function fingerprintKey(fingerprint: Readonly): string /** Owns pooled browser generations and hands callers exactly-once leases. */ export class BrowserLeasePool { + /** Under the CLI's 3s exit watchdog, alongside the render-wait bound it races. */ + private static readonly DRAIN_FORCE_CLOSE_MS = 1_000; private readonly available = new Map(); private readonly entries = new Set(); private readonly leasesByBrowser = new Map>(); private drainPromise: Promise | null = null; + private closed = false; constructor(private readonly options: BrowserLeasePoolOptions) {} @@ -74,7 +77,12 @@ export class BrowserLeasePool { fingerprintInput: BrowserLaunchFingerprint, pooled: boolean, ): Promise { + if (this.closed) throw new Error("Browser pool is closed; no new browsers can be acquired"); if (this.drainPromise) await this.drainPromise; + // Re-check: close() can land while this call was awaiting an unrelated, + // already-resolving drain -- drainPromise resets to null on completion, + // so only `closed` (permanent) still catches a request that raced it. + if (this.closed) throw new Error("Browser pool is closed; no new browsers can be acquired"); const fingerprint = freezeFingerprint(fingerprintInput); const entry = this.reserveEntry(fingerprint, pooled); @@ -141,18 +149,36 @@ export class BrowserLeasePool { if (this.drainPromise) return this.drainPromise; const entries = [...this.entries]; for (const entry of entries) this.requestClose(entry, false); - this.drainPromise = Promise.all(entries.map((entry) => entry.closePromise)).then(() => { - this.drainPromise = null; - }); + const settle = Promise.all(entries.map((entry) => entry.closePromise)); + const bound = new Promise((resolve) => + setTimeout(resolve, BrowserLeasePool.DRAIN_FORCE_CLOSE_MS).unref(), + ); + this.drainPromise = Promise.race([settle, bound]) + .then(() => { + // A close() past the bound gets escalated instead of left to block + // the caller's own shutdown deadline indefinitely. + for (const entry of entries) if (this.entries.has(entry)) this.requestClose(entry, true); + return settle; + }) + .then(() => { + this.drainPromise = null; + }); return this.drainPromise; } + /** Terminal: drains every entry and refuses every `acquire()` after. */ + close(): Promise { + this.closed = true; + return this.drain(); + } + /** Test-only state reset. Call `drain()` first when entries own real browsers. */ reset(): void { this.available.clear(); this.entries.clear(); this.leasesByBrowser.clear(); this.drainPromise = null; + this.closed = false; } private createEntry( diff --git a/packages/engine/src/services/browserManager.ts b/packages/engine/src/services/browserManager.ts index 96c358b354..861728014d 100644 --- a/packages/engine/src/services/browserManager.ts +++ b/packages/engine/src/services/browserManager.ts @@ -793,6 +793,11 @@ export async function drainBrowserPool(): Promise { await browserLeasePool.drain(); } +/** Terminal shutdown: drains the pool and makes every later acquire() reject. */ +export async function closeBrowserPool(): Promise { + await browserLeasePool.close(); +} + /** Test-only: reset all pool state. */ export function _resetBrowserPoolForTests(): void { browserLeasePool.reset(); diff --git a/packages/engine/src/services/fileServer.pathSafety.test.ts b/packages/engine/src/services/fileServer.pathSafety.test.ts new file mode 100644 index 0000000000..4df08092d3 --- /dev/null +++ b/packages/engine/src/services/fileServer.pathSafety.test.ts @@ -0,0 +1,63 @@ +import { afterEach, beforeEach, describe, expect, it } from "vitest"; +import * as fs from "node:fs"; +import * as path from "node:path"; +import { tmpdir } from "node:os"; +import { createFileServer, type FileServerHandle } from "./fileServer.js"; + +/** + * The server derives each request path from the URL and joins it onto + * compiledDir/projectDir. Hono decodes percent escapes when routing, so an + * encoded separator or dot segment in the request must never walk out of the + * served roots — Chrome never requests those shapes, but anything that can + * reach the port (LAN bind, other local processes) can. On Windows an encoded + * backslash (%5c) decodes to a real separator, so `..%5c..%5c` escapes even + * though `..%2f` is normalized away by join(). These tests pin containment + * at the handler. + */ +describe("fileServer path containment", () => { + let root: string; + let projectDir: string; + let outsideFile: string; + let server: FileServerHandle; + + beforeEach(async () => { + root = fs.mkdtempSync(path.join(tmpdir(), "hf-fileserver-containment-")); + projectDir = path.join(root, "project"); + fs.mkdirSync(projectDir); + fs.writeFileSync(path.join(projectDir, "index.html"), ""); + outsideFile = path.join(root, "outside-secret.txt"); + fs.writeFileSync(outsideFile, "OUTSIDE"); + server = await createFileServer({ + headScripts: [], + bodyScripts: [], + projectDir, + }); + }); + + afterEach(async () => { + await server.close(); + fs.rmSync(root, { recursive: true, force: true }); + }); + + const escapeAttempts = [ + // Encoded separators: %2f collapses with a leading dot-segment only via a + // nested hop, %5c is a live separator on Windows. + "/..%2foutside-secret.txt", + "/%2e%2e%2foutside-secret.txt", + "/nested%2f..%2f..%2foutside-secret.txt", + "/..%5coutside-secret.txt", + "/..%5c..%5coutside-secret.txt", + ]; + + it.each(escapeAttempts)("rejects encoded traversal %s", async (requestPath) => { + const response = await fetch(`${server.url}${requestPath}`); + expect(response.status).toBe(404); + expect(await response.text()).not.toContain("OUTSIDE"); + }); + + it("still serves files inside the project", async () => { + const response = await fetch(`${server.url}/index.html`); + expect(response.status).toBe(200); + expect(await response.text()).toContain(""); + }); +}); diff --git a/packages/engine/src/services/fileServer.ts b/packages/engine/src/services/fileServer.ts index 04b4a62fe2..d0133ed305 100644 --- a/packages/engine/src/services/fileServer.ts +++ b/packages/engine/src/services/fileServer.ts @@ -11,6 +11,7 @@ import { serve } from "@hono/node-server"; import { readFileSync, openSync, fstatSync, closeSync, statSync, constants } from "node:fs"; import { join, extname } from "node:path"; import { injectScriptsIntoHtml } from "@hyperframes/core/compiler"; +import { isWithinProjectRoot } from "@hyperframes/parsers/asset-resolution"; const MIME_TYPES: Record = { ".html": "text/html; charset=utf-8", @@ -84,6 +85,24 @@ function readRegularFile(filePath: string): Buffer | null { } } +/** + * Resolves the request path against both roots and rejects the pair the + * moment either escapes -- lexically, so a symlinked asset directory still + * resolves (see the containment note at the call site). + */ +function resolveContainedPaths( + projectDir: string, + compiledDir: string | undefined, + relativePath: string, +): { projectPath: string; compiledPath: string | null } | null { + const projectPath = join(projectDir, relativePath); + if (!isWithinProjectRoot(projectDir, projectPath)) return null; + if (!compiledDir) return { projectPath, compiledPath: null }; + const compiledPath = join(compiledDir, relativePath); + if (!isWithinProjectRoot(compiledDir, compiledPath)) return null; + return { projectPath, compiledPath }; +} + export function createFileServer(options: FileServerOptions): Promise { const { projectDir, compiledDir, port = 0, stripEmbeddedRuntime = true } = options; @@ -98,10 +117,14 @@ export function createFileServer(options: FileServerOptions): Promise { + it("rejects a backslash traversal under path.win32", () => { + const root = "C:\\project"; + const candidate = win32.join(root, "..\\secret.txt"); + expect(isWithinProjectRoot(root, candidate, win32)).toBe(false); + }); + + it("rejects a mixed backslash/forward-slash traversal under path.win32", () => { + const root = "C:\\project"; + const candidate = win32.join(root, "..\\../secret.txt"); + expect(isWithinProjectRoot(root, candidate, win32)).toBe(false); + }); + + it("rejects a drive-letter path outside the root under path.win32", () => { + const root = "C:\\project"; + const candidate = "D:\\secret.txt"; + expect(isWithinProjectRoot(root, candidate, win32)).toBe(false); + }); + + it("allows a nested asset under path.win32", () => { + const root = "C:\\project"; + const candidate = win32.join(root, "assets\\a.png"); + expect(isWithinProjectRoot(root, candidate, win32)).toBe(true); + }); + + it("rejects a forward-slash traversal under path.posix", () => { + const root = "/project"; + const candidate = posix.join(root, "../secret.txt"); + expect(isWithinProjectRoot(root, candidate, posix)).toBe(false); + }); + + it("allows a nested asset under path.posix", () => { + const root = "/project"; + const candidate = posix.join(root, "assets/a.png"); + expect(isWithinProjectRoot(root, candidate, posix)).toBe(true); + }); + + it("allows the root itself", () => { + expect(isWithinProjectRoot("/project", "/project", posix)).toBe(true); + }); +}); diff --git a/packages/parsers/src/assetResolution.ts b/packages/parsers/src/assetResolution.ts index b14212aa52..0378a9d7ab 100644 --- a/packages/parsers/src/assetResolution.ts +++ b/packages/parsers/src/assetResolution.ts @@ -2,6 +2,14 @@ import { existsSync } from "node:fs"; import { isAbsolute, join, posix, relative, resolve, sep } from "node:path"; import { decodeUrlPathVariants } from "./composition.js"; +/** The subset of `node:path` that `isWithinProjectRoot` needs to run under + * an injected platform (tests pass `path.win32` / `path.posix`). */ +interface PathModuleLike { + resolve: (...segments: string[]) => string; + relative: (from: string, to: string) => string; + isAbsolute: (path: string) => boolean; +} + /** * Shared local-asset resolution helpers for every package that maps * composition asset URLs to files on disk (lint project rules, the HEVC @@ -115,10 +123,22 @@ export function cleanAssetUrl(url: string): string { return url.trim().split(/[?#]/, 1)[0] ?? ""; } -export function isWithinProjectRoot(projectDir: string, candidate: string): boolean { - const projectRoot = resolve(projectDir); - const relativePath = relative(projectRoot, candidate); - return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath)); +/** + * `pathModule` defaults to the host's native `node:path`, so every existing + * caller gets its actual OS's separator and drive-letter rules unchanged. + * Tests inject `path.win32` / `path.posix` to exercise both platforms' rules + * from a single OS (same pattern as producer/fileServer.ts's `isPathInside`). + */ +export function isWithinProjectRoot( + projectDir: string, + candidate: string, + pathModule: PathModuleLike = { resolve, relative, isAbsolute }, +): boolean { + const projectRoot = pathModule.resolve(projectDir); + const relativePath = pathModule.relative(projectRoot, candidate); + return ( + relativePath === "" || (!relativePath.startsWith("..") && !pathModule.isAbsolute(relativePath)) + ); } function addCandidate(candidates: string[], candidate: string): void { diff --git a/packages/player/package.json b/packages/player/package.json index e9ff7c4774..332d967dec 100644 --- a/packages/player/package.json +++ b/packages/player/package.json @@ -1,6 +1,6 @@ { "name": "@hyperframes/player", - "version": "0.8.61", + "version": "0.8.62", "description": "Embeddable web component for HyperFrames compositions", "repository": { "type": "git", diff --git a/packages/producer/package.json b/packages/producer/package.json index 3b20d74404..8dae9b2cbe 100644 --- a/packages/producer/package.json +++ b/packages/producer/package.json @@ -1,6 +1,6 @@ { "name": "@hyperframes/producer", - "version": "0.8.61", + "version": "0.8.62", "description": "HTML-to-video rendering engine using Chrome's BeginFrame API", "repository": { "type": "git", diff --git a/packages/sdk/package.json b/packages/sdk/package.json index dc0bd57419..1f3e946281 100644 --- a/packages/sdk/package.json +++ b/packages/sdk/package.json @@ -1,6 +1,6 @@ { "name": "@hyperframes/sdk", - "version": "0.8.61", + "version": "0.8.62", "description": "Headless, framework-neutral HyperFrames composition editing engine", "repository": { "type": "git", diff --git a/packages/shader-transitions/package.json b/packages/shader-transitions/package.json index dbb4bf648b..72a89b8183 100644 --- a/packages/shader-transitions/package.json +++ b/packages/shader-transitions/package.json @@ -1,6 +1,6 @@ { "name": "@hyperframes/shader-transitions", - "version": "0.8.61", + "version": "0.8.62", "description": "WebGL shader transitions for HyperFrames compositions", "repository": { "type": "git", diff --git a/packages/studio-server/package.json b/packages/studio-server/package.json index ca75cb8205..5340f7355f 100644 --- a/packages/studio-server/package.json +++ b/packages/studio-server/package.json @@ -1,6 +1,6 @@ { "name": "@hyperframes/studio-server", - "version": "0.8.61", + "version": "0.8.62", "repository": { "type": "git", "url": "https://github.com/heygen-com/hyperframes", diff --git a/packages/studio/package.json b/packages/studio/package.json index af83f5b1fc..728d507c14 100644 --- a/packages/studio/package.json +++ b/packages/studio/package.json @@ -1,6 +1,6 @@ { "name": "@hyperframes/studio", - "version": "0.8.61", + "version": "0.8.62", "description": "", "repository": { "type": "git", diff --git a/packages/studio/src/player/hooks/useShadowPreviewReload.ts b/packages/studio/src/player/hooks/useShadowPreviewReload.ts index 0e01d6d18f..b813ef497a 100644 --- a/packages/studio/src/player/hooks/useShadowPreviewReload.ts +++ b/packages/studio/src/player/hooks/useShadowPreviewReload.ts @@ -16,8 +16,13 @@ import type { PlaybackAdapter } from "../lib/playbackTypes"; // The single wait budget for a shadow: the player's 8s asset cap plus its 0.42s loader fade // leaves about 6.5s for the document load and runtime boot. Nothing shorter may fail the swap. +// It only runs while the tab is visible: readiness is frame-driven, and a hidden tab renders none. export const SHADOW_READY_TIMEOUT_MS = 15_000; +function isDocumentHidden(): boolean { + return typeof document !== "undefined" && document.visibilityState === "hidden"; +} + type UseShadowPreviewReloadParams = Omit< UseTimelineSyncCallbacksParams, "probeIntervalRef" | "onAdapterReady" | "getAdapter" | "isCurrent" | "onLoadGiveUp" @@ -55,11 +60,14 @@ export function useShadowPreviewReload({ const onReloadFailedRef = useRef(onReloadFailed); onReloadFailedRef.current = onReloadFailed; const readyTimerRef = useRef | undefined>(undefined); + // The shadow still owed a wait budget, so a hidden tab can resume it when it becomes visible. + const budgetGenRef = useRef(null); const cancelPendingLoadRef = useRef<() => void>(() => {}); const [previewSlots, setPreviewSlots] = useState([{ gen: 0, role: "live" }]); const stopPendingShadow = useCallback(() => { clearTimeout(readyTimerRef.current); + budgetGenRef.current = null; cancelPendingLoadRef.current(); pendingCommitRef.current = null; visuallyReadyGenRef.current = null; @@ -145,18 +153,30 @@ export function useShadowPreviewReload({ shadowIframeRef.current = node; }, []); + const armReadyTimer = useCallback( + (gen: number) => { + clearTimeout(readyTimerRef.current); + if (isDocumentHidden()) return; + readyTimerRef.current = setTimeout( + () => failShadow(gen, "it took too long to load"), + SHADOW_READY_TIMEOUT_MS, + ); + }, + [failShadow], + ); + const armReadyTimerRef = useRef(armReadyTimer); + armReadyTimerRef.current = armReadyTimer; + const beginShadowReload = useCallback( (url: string) => { shadowGenRef.current += 1; const gen = shadowGenRef.current; stopPendingShadow(); - readyTimerRef.current = setTimeout( - () => failShadow(gen, "it took too long to load"), - SHADOW_READY_TIMEOUT_MS, - ); + budgetGenRef.current = gen; + armReadyTimer(gen); setPreviewSlots((prev) => planShadowReload(prev, gen, url)); }, - [stopPendingShadow, failShadow], + [stopPendingShadow, armReadyTimer], ); // Composition switch (not an edit reload): drop any in-flight shadow. @@ -169,7 +189,22 @@ export function useShadowPreviewReload({ setPreviewSlots(planShadowDiscard); }, [stopPendingShadow, isRefreshingRef, pendingSeekRef]); - useMountEffect(() => stopPendingShadow); + // Hiding the tab pauses the budget; showing it again restarts the full budget for a pending shadow. + useMountEffect(() => { + const onVisibilityChange = () => { + if (isDocumentHidden()) { + clearTimeout(readyTimerRef.current); + return; + } + const gen = budgetGenRef.current; + if (gen != null && gen === shadowGenRef.current) armReadyTimerRef.current(gen); + }; + document.addEventListener("visibilitychange", onVisibilityChange); + return () => { + document.removeEventListener("visibilitychange", onVisibilityChange); + stopPendingShadow(); + }; + }); return { previewSlots, diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.ts b/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.ts index 25439e3dc9..7fa37aa5d2 100644 --- a/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.ts +++ b/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.ts @@ -289,6 +289,50 @@ describe("shadow reload readiness and failure", () => { unmount(root); }); + it("does not spend the budget while the tab is hidden, and promotes once it is visible", () => { + vi.useFakeTimers(); + const onPreviewReloadFailed = vi.fn(); + const setVisibility = stubVisibility("hidden"); + const { getApi, gen, root } = beginReload({ onPreviewReloadFailed }); + const shadow = makeShadowWithSpies(); + act(() => { + getApi().setShadowIframeNode(shadow.iframe); + getApi().onShadowIframeLoad(gen); + }); + + // A hidden tab renders no frames, so readiness cannot arrive; the wall clock must not fail it. + act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS * 3)); + expect(onPreviewReloadFailed).not.toHaveBeenCalled(); + expect(getApi().previewSlots).toHaveLength(2); + + act(() => setVisibility("visible")); + act(() => getApi().onShadowReadyChange(gen, true)); + expect(getApi().iframeRef.current).toBe(shadow.iframe); + expect(onPreviewReloadFailed).not.toHaveBeenCalled(); + unmount(root); + }); + + it("restarts the full budget when a hidden tab becomes visible, then fails a shadow that stays silent", () => { + vi.useFakeTimers(); + vi.spyOn(console, "error").mockImplementation(() => {}); + const onPreviewReloadFailed = vi.fn(); + const setVisibility = stubVisibility("visible"); + const { getApi, live, root } = beginReload({ onPreviewReloadFailed }); + + act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS - 1000)); + act(() => setVisibility("hidden")); + act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS)); + expect(onPreviewReloadFailed).not.toHaveBeenCalled(); + + act(() => setVisibility("visible")); + act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS - 1)); + expect(onPreviewReloadFailed).not.toHaveBeenCalled(); + act(() => void vi.advanceTimersByTime(1)); + expect(onPreviewReloadFailed).toHaveBeenCalledWith(expect.stringContaining("too long")); + expect(getApi().iframeRef.current).toBe(live); + unmount(root); + }); + it("drops a shadow whose document reports an error and reports the cause", () => { vi.spyOn(console, "error").mockImplementation(() => {}); const onPreviewReloadFailed = vi.fn(); @@ -455,3 +499,12 @@ function unmount(root: ReturnType) { root.unmount(); }); } + +function stubVisibility(initial: DocumentVisibilityState) { + let state = initial; + vi.spyOn(document, "visibilityState", "get").mockImplementation(() => state); + return (next: DocumentVisibilityState) => { + state = next; + document.dispatchEvent(new Event("visibilitychange")); + }; +} diff --git a/releases/v0.8.62.md b/releases/v0.8.62.md new file mode 100644 index 0000000000..51f6588791 --- /dev/null +++ b/releases/v0.8.62.md @@ -0,0 +1,17 @@ +# HyperFrames v0.8.62 + +Released on 2026-09-22. + +Studio no longer drops an edit's preview while its tab is in the background, and the catalog gains a text match cut. + +## Fixes + +- **Studio:** Don't fail a shadow reload while the tab is hidden ([16959deea](https://github.com/heygen-com/hyperframes/commit/16959deeac55c65a730d18b3a4ef7c366b0e0223), [#4292](https://github.com/heygen-com/hyperframes/pull/4292)). + +## Catalog + +- **Registry:** Text-match-cut ([0945de83c](https://github.com/heygen-com/hyperframes/commit/0945de83c7f51ba0c20c7c0a56421f066a378ee8), [#4288](https://github.com/heygen-com/hyperframes/pull/4288)). + +## Full changelog + +https://github.com/heygen-com/hyperframes/compare/v0.8.61...v0.8.62 diff --git a/scripts/check-media-use-copy-parity.test.mjs b/scripts/check-media-use-copy-parity.test.mjs index a5bedac0c5..8ebab828d0 100644 --- a/scripts/check-media-use-copy-parity.test.mjs +++ b/scripts/check-media-use-copy-parity.test.mjs @@ -19,6 +19,7 @@ export const MEDIA_USE_COPY_NAMES = [ "prefs-store.mjs", "recipe-store.mjs", "telemetry.mjs", + "transcriptCutFade.mjs", "words.mjs", ]; diff --git a/skills-manifest.json b/skills-manifest.json index 0f5f97ef2a..f0ed394bc9 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -54,8 +54,8 @@ "files": 1 }, "media-use": { - "hash": "e5376453c0d08ac3", - "files": 88 + "hash": "7263711f70b299d6", + "files": 90 }, "motion-graphics": { "hash": "9c2ca2e8c384875d", diff --git a/skills/media-use/scripts/lib/transcriptCutFade.mjs b/skills/media-use/scripts/lib/transcriptCutFade.mjs new file mode 100644 index 0000000000..bc1676074a --- /dev/null +++ b/skills/media-use/scripts/lib/transcriptCutFade.mjs @@ -0,0 +1,21 @@ +function round3(n) { + return Math.round(Number(n) * 1000) / 1000; +} + +// 30ms in/out ramps kill the click at every concat boundary. A segment shorter +// than 4x the ramp would spend its whole length fading, so scale down there and +// skip entirely on a degenerate one. fadeIn/fadeOut are false at the export's +// own true start/end, where there is no splice to smooth. +export function fadeFilterFor(durationSeconds, { fadeIn, fadeOut }) { + if (!fadeIn && !fadeOut) return null; + const FADE_SECONDS = 0.03; + if (!Number.isFinite(durationSeconds) || durationSeconds <= 0.01) return null; + const d = Math.min(FADE_SECONDS, durationSeconds / 4); + const parts = []; + if (fadeIn) parts.push(`afade=t=in:st=0:d=${round3(d)}`); + if (fadeOut) { + const out = round3(durationSeconds - d); + if (out > 0) parts.push(`afade=t=out:st=${out}:d=${round3(d)}`); + } + return parts.length ? parts.join(",") : null; +} diff --git a/skills/media-use/scripts/transcript-cut.mjs b/skills/media-use/scripts/transcript-cut.mjs index d76bd022fb..b7e4f468e0 100644 --- a/skills/media-use/scripts/transcript-cut.mjs +++ b/skills/media-use/scripts/transcript-cut.mjs @@ -6,6 +6,7 @@ import { tmpdir } from "node:os"; import { dirname, extname, join, resolve } from "node:path"; import { parseArgs } from "node:util"; import { compileCutList } from "./lib/cutlist.mjs"; +import { fadeFilterFor } from "./lib/transcriptCutFade.mjs"; import { track } from "./lib/telemetry.mjs"; const { values: args } = parseArgs({ @@ -92,11 +93,23 @@ function run() { try { const parts = segments.map((segment, index) => { - const out = join( - tmpDir, - `segment-${String(index).padStart(4, "0")}${extname(outPath) || ".mp4"}`, - ); - cutSegment(inputPath, segment, out, Boolean(args.copy)); + // Intermediates carry PCM audio, not the final codec. Encoding each + // segment to a lossy codec separately makes the encoder pad every segment + // with priming silence (~25-35ms for AAC), which concat then bakes in as a + // gap at each cut -- a defect distinct from, and surviving, the fades + // below. PCM has no priming, so audio is encoded exactly once, at concat. + const ext = args.copy ? extname(outPath) || ".mp4" : isAudioOnly(outPath) ? ".wav" : ".mkv"; + const out = join(tmpDir, `segment-${String(index).padStart(4, "0")}${ext}`); + // --copy stays fade-free (stream copy cannot filter). A segment's true + // start/end (index 0's start, the last segment's end) borders nothing + // kept, so only an interior splice edge gets a ramp. + const fade = args.copy + ? null + : fadeFilterFor(segment.end - segment.start, { + fadeIn: index > 0, + fadeOut: index < segments.length - 1, + }); + cutSegment(inputPath, segment, out, args.copy, fade); return out; }); const listPath = join(tmpDir, "list.txt"); @@ -107,9 +120,16 @@ function run() { // Encode to a sibling temp (same extension so ffmpeg picks the right muxer), // then atomic-rename so a SIGKILL mid-encode can't leave a truncated outPath. const tmpOut = `${outPath}.part${extname(outPath) || ".mp4"}`; + // --copy already produced final-codec segments, so concat can stream-copy. + // Otherwise the PCM intermediates are encoded here, once, for the whole file. + const concatCodecs = args.copy + ? ["-c", "copy"] + : isAudioOnly(outPath) + ? encodeArgsFor(extname(outPath).toLowerCase()) + : ["-c:v", "copy", "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart"]; execFileSync( "ffmpeg", - ["-y", "-f", "concat", "-safe", "0", "-i", listPath, "-c", "copy", tmpOut], + ["-y", "-f", "concat", "-safe", "0", "-i", listPath, ...concatCodecs, tmpOut], { stdio: "ignore", }, @@ -158,7 +178,7 @@ function run() { console.log(`next: resolve --from ${outPath} --type `); } -function cutSegment(inputPath, segment, outPath, copy) { +function cutSegment(inputPath, segment, outPath, copy, fade) { const argv = [ "-y", "-nostdin", @@ -171,8 +191,15 @@ function cutSegment(inputPath, segment, outPath, copy) { ]; if (copy) { argv.push("-c", "copy", "-avoid_negative_ts", "make_zero"); + } else if (extname(outPath).toLowerCase() === ".mkv") { + // Concat splices raw segment edges together; without a short ramp the + // waveform steps discontinuously at every boundary and you hear a click. + if (fade) argv.push("-af", fade); + // Video intermediate: keep the picture cheap and the audio uncompressed. + argv.push("-c:v", "libx264", "-preset", "veryfast", "-crf", "18", "-c:a", "pcm_s16le"); } else { - argv.push(...encodeArgsFor(extname(outPath).toLowerCase())); + if (fade) argv.push("-af", fade); + argv.push("-c:a", "pcm_s16le"); } argv.push(outPath); execFileSync("ffmpeg", argv, { stdio: "ignore" }); @@ -180,6 +207,10 @@ function cutSegment(inputPath, segment, outPath, copy) { // Codec set per output container. Audio-only outputs must not get the // video-centric aac/x264 set (aac inside .wav breaks timing entirely). +function isAudioOnly(filePath) { + return [".wav", ".mp3", ".m4a", ".aac", ".flac"].includes(extname(filePath).toLowerCase()); +} + function encodeArgsFor(ext) { if (ext === ".wav") return ["-c:a", "pcm_s16le"]; if (ext === ".mp3") return ["-c:a", "libmp3lame", "-q:a", "2"]; diff --git a/skills/media-use/scripts/transcript-cut.test.mjs b/skills/media-use/scripts/transcript-cut.test.mjs new file mode 100644 index 0000000000..99b52dce42 --- /dev/null +++ b/skills/media-use/scripts/transcript-cut.test.mjs @@ -0,0 +1,117 @@ +import assert from "node:assert/strict"; +import { execFileSync, spawnSync } from "node:child_process"; +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; + +const SCRIPT = fileURLToPath(new URL("./transcript-cut.mjs", import.meta.url)); +const HAS_FFMPEG = + spawnSync("ffmpeg", ["-version"], { stdio: "ignore" }).status === 0 && + spawnSync("ffprobe", ["-version"], { stdio: "ignore" }).status === 0; + +const SAMPLE_RATE = 44100; +// A continuous tone's own slope between samples never exceeds amplitude * 2*pi*f/rate +// (~2054 for 440Hz at full scale here); a raw splice between two independently-cut +// points on the same tone lands at two unrelated phases, so an unfaded join jumps far +// past that. This threshold sits well above normal tone motion and well below a splice. +const MAX_CONTINUOUS_STEP = 6000; +const MIN_SUSPICIOUS_ZERO_RUN = 20; + +function fixture() { + const dir = mkdtempSync(join(tmpdir(), "media-use-transcript-cut-")); + return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) }; +} + +function run(args) { + return spawnSync(process.execPath, [SCRIPT, ...args], { encoding: "utf8" }); +} + +function readPcm(filePath) { + const raw = execFileSync("ffmpeg", [ + "-hide_banner", + "-loglevel", + "error", + "-i", + filePath, + "-f", + "s16le", + "-ac", + "1", + "-ar", + String(SAMPLE_RATE), + "-", + ]); + const samples = new Int16Array(raw.buffer, raw.byteOffset, raw.length / 2); + return samples; +} + +test( + "keeps a spliced tone continuous at every cut, with no raw phase jump or silence gap", + { skip: !HAS_FFMPEG }, + (t) => { + const { dir, cleanup } = fixture(); + t.after(cleanup); + + const source = join(dir, "tone.wav"); + execFileSync("ffmpeg", [ + "-y", + "-hide_banner", + "-loglevel", + "error", + "-f", + "lavfi", + "-i", + `sine=frequency=440:duration=6:sample_rate=${SAMPLE_RATE}`, + source, + ]); + + const transcriptPath = join(dir, "transcript.json"); + writeFileSync(transcriptPath, JSON.stringify({ words: [{ text: "tone", start: 0, end: 6 }] })); + + const output = join(dir, "out.wav"); + // Two "ugly" removal ranges: neither aligned to the 440Hz period, so the kept + // segments' cut edges land at unrelated phases of the same continuous tone -- + // exactly the shape that clicks without a fade, and the shape jrusso1020's + // review proved this branch never actually fades. + const result = run([ + "--input", + source, + "--transcript", + transcriptPath, + "--remove", + "1.37-1.83,3.29-3.71", + "--out", + output, + "--json", + ]); + assert.equal(result.status, 0, result.stderr || result.stdout); + + const samples = readPcm(output); + assert.ok(samples.length > SAMPLE_RATE, "expected several seconds of audio"); + + let maxStep = 0; + let zeroRun = 0; + let maxZeroRun = 0; + for (let i = 1; i < samples.length; i++) { + const step = Math.abs(samples[i] - samples[i - 1]); + if (step > maxStep) maxStep = step; + if (samples[i] === 0) { + zeroRun++; + if (zeroRun > maxZeroRun) maxZeroRun = zeroRun; + } else { + zeroRun = 0; + } + } + + assert.ok( + maxStep <= MAX_CONTINUOUS_STEP, + `largest sample-to-sample step was ${maxStep}, expected <= ${MAX_CONTINUOUS_STEP} (a raw, unfaded splice)`, + ); + assert.ok( + maxZeroRun < MIN_SUSPICIOUS_ZERO_RUN, + `found a run of ${maxZeroRun} consecutive zero samples, expected < ${MIN_SUSPICIOUS_ZERO_RUN} (a priming-silence gap)`, + ); + }, +);