ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-03 04:38:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(studio,runtime,engine,compiler): 8 bug fixes — audio, render, timeline, Lottie, thumbnails, video render (#133)

Browse Source 
## Summary

**Original 5 bugs fixed:**

- **Bug 1 — Audio silent after seek**: Added `Accept-Ranges` / `Content-Length` + `206 Partial Content` to the static asset server for byte-range seeking.
- **Bug 2 — Download 404 after restart**: Render list endpoint now registers on-disk renders into the in-memory job map.
- **Bug 3 — Timeline stops at GSAP end**: `resolveRootTimelineFromDocument` pads the GSAP timeline to match `data-duration` when the composition declares longer.
- **Bug 4 — Render stuck at 0%**: Store `jobState` reference (not spread copy) so async progress mutations reach the SSE stream.
- **Bug 5 — Lottie missing in preview/render**: Two fixes — (a) moved Lottie adapter before GSAP so `onUpdate` wins; (b) fixed bundler silently dropping external CDN `\<script src>` tags from sub-compositions (root cause: `$content(s).html()` returns `""` for external scripts).

**3 additional bugs fixed:**

- **Bug 6 — Blank thumbnails outside monorepo**: Implemented `generateThumbnail` in the CLI adapter using Puppeteer.
- **Bug 7 — Video empty in rendered sub-compositions**: Fixed `parseVideoElements` selector from `video[id][src]` to `video[src][data-start]` + auto-assign IDs.
- **Render errors**: Failed renders now show their error message in the renders panel.

## Commits

| Commit | Description |
| --- | --- |
| `3951c6f` | fix(studio): store render job reference instead of snapshot copy |
| `f331c30` | fix(studio): make previously-completed renders downloadable after restart |
| `a5e2d04` | fix(studio): add range request support for audio/video seeking in preview |
| `f24317a` | fix(runtime): pad GSAP timeline to data-duration when composition declares longer duration |
| `7cf38ca` | fix(runtime): fix Lottie adapter conflicting with GSAP-driven animations |
| `bc99209` | fix(studio): surface render error messages in the renders panel |
| `8fc9e8b` | fix(cli): implement generateThumbnail in studio adapter |
| `90277ea` | fix(engine): render videos inside sub-compositions that lack an explicit id |
| `f5bb579` | fix(compiler): preserve external CDN scripts from sub-compositions in bundle |

## Test plan

- [x] `golden-lyric-video`: seek → audio plays from seeked position
- [x] Any project: render → progress advances past 0%, reaches 100%
- [x] Any project: complete render, restart `hyperframes dev`, Download → works
- [x] `intro-vid`: play → runs full 5s (not stopping at 3s)
- [x] `hyperframe-build-up-demo`: play → rocket Lottie visible during 0-2s ✅ verified
- [x] Outside monorepo: Compositions sidebar shows thumbnail images (not blank)
- [x] `bug.zip` project: render → video in polaroid sub-composition appears in output
- [x] Trigger a failed render → error message shown
This commit is contained in:
Miguel Ángel
2026-03-30 23:58:08 +02:00
committed by GitHub
parent 163da680c7
commit 1230657ed0
27 changed files with 948 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/core/src/compiler/htmlBundler.test.ts
+100
View File
@@ -0,0 +1,100 @@
// @vitest-environment node
import { mkdtempSync, writeFileSync, mkdirSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { describe, it, expect } from "vitest";
import { bundleToSingleHtml } from "./htmlBundler";
function makeTempProject(files: Record<string, string>): string {
const dir = mkdtempSync(join(tmpdir(), "hf-bundler-test-"));
for (const [rel, content] of Object.entries(files)) {
const full = join(dir, rel);
mkdirSync(join(full, ".."), { recursive: true });
writeFileSync(full, content, "utf-8");
}
return dir;
}
describe("bundleToSingleHtml", () => {
it("hoists external CDN scripts from sub-compositions into the bundle", async () => {
const dir = makeTempProject({
"index.html": `<!doctype html>
<html><head>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
</head><body>
<div id="root" data-composition-id="main" data-width="1920" data-height="1080">
<div id="rockets-host"
data-composition-id="rockets"
data-composition-src="compositions/rockets.html"
data-start="0" data-duration="2"></div>
</div>
<script>window.__timelines={}; const tl=gsap.timeline({paused:true}); window.__timelines["main"]=tl;</script>
</body></html>`,
"compositions/rockets.html": `<template id="rockets-template">
<div data-composition-id="rockets" data-width="1920" data-height="1080">
<div id="rocket-container"></div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/lottie-web/5.12.2/lottie.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const anim = lottie.loadAnimation({ container: document.querySelector("#rocket-container"), path: "rocket.json" });
window.__timelines["rockets"] = gsap.timeline({ paused: true });
</script>
</div>
</template>`,
});
const bundled = await bundleToSingleHtml(dir);
// Lottie CDN script from sub-composition must be present in the bundle
expect(bundled).toContain(
"https://cdnjs.cloudflare.com/ajax/libs/lottie-web/5.12.2/lottie.min.js",
);
// Should only appear once (deduped)
const occurrences = (bundled.match(/cdnjs\.cloudflare\.com\/ajax\/libs\/lottie-web/g) ?? [])
.length;
expect(occurrences).toBe(1);
// GSAP CDN from main doc should still be present
expect(bundled).toContain("cdn.jsdelivr.net/npm/gsap");
// data-composition-src should be stripped (composition was inlined)
expect(bundled).not.toContain("data-composition-src");
});
it("does not duplicate CDN scripts already present in the main document", async () => {
const dir = makeTempProject({
"index.html": `<!doctype html>
<html><head>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
</head><body>
<div id="root" data-composition-id="main" data-width="1920" data-height="1080">
<div id="child-host"
data-composition-id="child"
data-composition-src="compositions/child.html"
data-start="0" data-duration="5"></div>
</div>
<script>window.__timelines={}; const tl=gsap.timeline({paused:true}); window.__timelines["main"]=tl;</script>
</body></html>`,
"compositions/child.html": `<template id="child-template">
<div data-composition-id="child" data-width="1920" data-height="1080">
<div id="stage"></div>
<!-- Same GSAP CDN as parent — should not be duplicated -->
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
window.__timelines["child"] = gsap.timeline({ paused: true });
</script>
</div>
</template>`,
});
const bundled = await bundleToSingleHtml(dir);
// GSAP CDN should appear exactly once (deduped)
const gsapOccurrences = (
bundled.match(/cdn\.jsdelivr\.net\/npm\/gsap@3\.14\.2\/dist\/gsap\.min\.js/g) ?? []
).length;
expect(gsapOccurrences).toBe(1);
});
});
packages/core/src/compiler/htmlBundler.ts
+21 -3
View File
@@ -390,6 +390,7 @@ export async function bundleToSingleHtml(
// Inline sub-compositions
const compStyleChunks: string[] = [];
const compScriptChunks: string[] = [];
const compExternalScriptSrcs: string[] = [];
$("[data-composition-src]").each((_, hostEl) => {
const src = $(hostEl).attr("data-composition-src");
if (!src || !isRelativeUrl(src)) return;
@@ -416,9 +417,18 @@ export async function bundleToSingleHtml(
$content(s).remove();
});
$content("script").each((_, s) => {
compScriptChunks.push(
`(function(){ try { ${$content(s).html() || ""} } catch (_err) { console.error('[HyperFrames] composition script error:', _err); } })();`,
);
const externalSrc = ($content(s).attr("src") || "").trim();
if (externalSrc) {
// External CDN/remote script — collect for deduped injection into the document.
// Do NOT try to inline the content (external scripts have no innerHTML).
if (!compExternalScriptSrcs.includes(externalSrc)) {
compExternalScriptSrcs.push(externalSrc);
}
} else {
compScriptChunks.push(
`(function(){ try { ${$content(s).html() || ""} } catch (_err) { console.error('[HyperFrames] composition script error:', _err); } })();`,
);
}
$content(s).remove();
});
@@ -439,6 +449,14 @@ export async function bundleToSingleHtml(
$(hostEl).removeAttr("data-composition-src");
});
// Inject external scripts from sub-compositions (e.g., Lottie CDN)
// that aren't already present in the main document.
for (const extSrc of compExternalScriptSrcs) {
if (!$(`script[src="${extSrc}"]`).length) {
$("body").append(`<script src="${extSrc}"></script>`);
}
}
if (compStyleChunks.length) $("head").append(`<style>${compStyleChunks.join("\n\n")}</style>`);
if (compScriptChunks.length)
$("body").append(`<script>${compScriptChunks.join("\n;\n")}</script>`);
packages/core/src/lint/hyperframeLinter.test.ts
+36
View File
@@ -111,6 +111,42 @@ describe("lintHyperframeHtml", () => {
expect(codes.length).toBe(uniqueCodes.length);
});
it("reports info for composition with external CDN script dependency", () => {
const html = `<template id="rockets-template">
<div data-composition-id="rockets" data-width="1920" data-height="1080">
<div id="rocket-container"></div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/lottie-web/5.12.2/lottie.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
window.__timelines["rockets"] = gsap.timeline({ paused: true });
</script>
</div>
</template>`;
const result = lintHyperframeHtml(html, { filePath: "compositions/rockets.html" });
const finding = result.findings.find((f) => f.code === "external_script_dependency");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("info");
expect(finding?.message).toContain("cdnjs.cloudflare.com");
// info findings do not count as errors — ok should still be true
expect(result.ok).toBe(true);
expect(result.errorCount).toBe(0);
});
it("does not report external_script_dependency for inline scripts", () => {
const html = `
<html><body>
<div id="root" data-composition-id="main" data-width="1920" data-height="1080">
<script>
window.__timelines = {};
const tl = gsap.timeline({ paused: true });
window.__timelines["main"] = tl;
</script>
</div>
</body></html>`;
const result = lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "external_script_dependency")).toBeUndefined();
});
it("strips <template> wrapper before linting composition files", () => {
const html = `<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080"
packages/core/src/lint/hyperframeLinter.ts
+26
View File
@@ -675,6 +675,32 @@ export function lintHyperframeHtml(
}
}
// ── External CDN script dependency check ────────────────────────────────
// Compositions that load CDN libraries via <script src="https://..."> work
// correctly in bundled mode (bundleToSingleHtml auto-hoists them to the parent
// document) and in runtime mode (loadExternalCompositions re-injects them).
// But when a composition is used in a custom pipeline that bypasses both, the
// scripts won't be available. Flag this as an info-level finding so developers
// know the dependency exists.
{
const externalScriptRe = /<script\b[^>]*\bsrc=["'](https?:\/\/[^"']+)["'][^>]*>/gi;
let match: RegExpExecArray | null;
const seen = new Set<string>();
while ((match = externalScriptRe.exec(source)) !== null) {
const src = match[1] ?? "";
if (seen.has(src)) continue;
seen.add(src);
pushFinding({
code: "external_script_dependency",
severity: "info",
message: `This composition loads an external script from \`${src}\`. The HyperFrames bundler automatically hoists CDN scripts from sub-compositions into the parent document. In unbundled runtime mode, \`loadExternalCompositions\` re-injects them. If you're using a custom pipeline that bypasses both, you'll need to include this script manually.`,
fixHint:
"No action needed when using `hyperframes dev` or `hyperframes render`. If using a custom pipeline, add this script tag to your root composition or HTML page.",
snippet: truncateSnippet(match[0] ?? ""),
});
}
}
const errorCount = findings.filter((finding) => finding.severity === "error").length;
const warningCount = findings.length - errorCount;
packages/core/src/runtime/adapters/lottie.test.ts
-10
View File
@@ -141,16 +141,6 @@ describe("lottie adapter", () => {
});
});
describe("play", () => {
it("plays lottie-web animation", () => {
const anim = createLottieWebAnim();
lottieWindow.__hfLottie = [anim];
const adapter = createLottieAdapter();
adapter.play!();
expect(anim.play).toHaveBeenCalled();
});
});
describe("revert", () => {
it("does not throw", () => {
const adapter = createLottieAdapter();
packages/core/src/runtime/adapters/lottie.ts
-17
View File
@@ -129,23 +129,6 @@ export function createLottieAdapter(): RuntimeDeterministicAdapter {
}
},
play: () => {
const instances = (window as LottieWindow).__hfLottie;
if (!instances || instances.length === 0) return;
for (const anim of instances) {
try {
if (isLottieWebAnimation(anim)) {
anim.play();
} else if (isDotLottiePlayer(anim)) {
anim.play();
}
} catch {
// ignore
}
}
},
revert: () => {
// Don't clear __hfLottie — the animation objects are owned by the composition.
// Just let them be garbage collected naturally.
packages/core/src/runtime/init.ts
+65 -2
View File
@@ -32,6 +32,21 @@ export function initSandboxRuntimeModular(): void {
// keep runtime resilient across reinits
}
}
// Normalize html/body so browser defaults (8px margin, white background) never
// bleed into renders as white bars. Runs in both preview and render contexts,
// eliminating the preview/render parity gap that existed when only the React
// component's normalizePreviewViewport call applied this normalization.
if (document.documentElement) {
document.documentElement.style.margin = "0";
document.documentElement.style.padding = "0";
document.documentElement.style.overflow = "hidden";
}
if (document.body) {
document.body.style.margin = "0";
document.body.style.padding = "0";
document.body.style.overflow = "hidden";
}
window.__timelines = window.__timelines || {};
const registerRuntimeCleanup = (callback: () => void) => {
runtimeCleanupCallbacks.push(callback);
@@ -707,6 +722,54 @@ export function initSandboxRuntimeModular(): void {
};
}
}
// If the root composition declares an explicit data-duration that meaningfully
// exceeds the captured GSAP timeline, extend the timeline in-place by placing
// a zero-duration no-op tween at the declared end position. This makes
// timeline.duration() report the declared length without creating a composite
// (which would double-count the original duration).
const rootDeclaredDurAttr = rootCompositionNode?.getAttribute("data-duration");
if (rootDeclaredDurAttr) {
const rootDeclaredDur = parseFloat(rootDeclaredDurAttr);
if (
isUsableTimelineDuration(rootDeclaredDur) &&
isUsableTimelineDuration(rootDurationSeconds) &&
// Only pad when the gap is meaningful (>= 0.5s) to avoid floating-point
// false positives on compositions whose GSAP duration is already close
// to data-duration.
rootDeclaredDur >= rootDurationSeconds + 0.5
) {
const tlWithTo = rootTimeline as RuntimeTimelineLike & {
to?: (target: object, vars: { duration: number }, position: number) => unknown;
};
if (typeof tlWithTo.to === "function") {
try {
// Placing a zero-duration tween AT rootDeclaredDur extends
// timeline.duration() to exactly rootDeclaredDur.
tlWithTo.to({}, { duration: 0 }, rootDeclaredDur);
} catch {
// keep runtime resilient
}
}
const newDur = getTimelineDurationSeconds(rootTimeline);
if (isUsableTimelineDuration(newDur)) {
return {
timeline: rootTimeline,
selectedTimelineIds: [rootCompositionId],
selectedDurationSeconds: newDur,
mediaDurationFloorSeconds,
diagnostics: {
code: "root_timeline_padded_to_declared_duration",
details: {
rootCompositionId,
rootDurationSeconds,
rootDeclaredDur,
newDur,
},
},
};
}
}
}
return {
timeline: rootTimeline,
selectedTimelineIds: [rootCompositionId],
@@ -1357,9 +1420,9 @@ export function initSandboxRuntimeModular(): void {
resolveStartSeconds: (element) => resolveStartForElement(element, 0),
}),
createWaapiAdapter(),
createGsapAdapter({ getTimeline: () => state.capturedTimeline }),
createThreeAdapter(),
createLottieAdapter(),
createThreeAdapter(),
createGsapAdapter({ getTimeline: () => state.capturedTimeline }),
] as RuntimeDeterministicAdapter[];
installRuntimeErrorDiagnostics();
runAdapters("discover");
packages/core/src/studio-api/routes/preview.ts
+33 -4
View File
@@ -66,7 +66,7 @@ export function registerPreviewRoutes(api: Hono, adapter: StudioApiAdapter): voi
return c.html(html);
});
// Static asset serving
// Static asset serving (with range request support for audio/video seeking)
api.get("/projects/:id/preview/*", async (c) => {
const project = await adapter.resolveProject(c.req.param("id"));
if (!project) return c.json({ error: "not found" }, 404);
@@ -79,9 +79,38 @@ export function registerPreviewRoutes(api: Hono, adapter: StudioApiAdapter): voi
}
const contentType = getMimeType(subPath);
const isText = /\.(html|css|js|json|svg|txt|md)$/i.test(subPath);
const content = readFileSync(file, isText ? "utf-8" : undefined);
return new Response(content, {
headers: { "Content-Type": contentType },
const buffer: Buffer = isText
? Buffer.from(readFileSync(file, "utf-8"), "utf-8")
: readFileSync(file);
const totalSize = buffer.length;
// Support byte-range requests so browsers can seek audio/video elements.
const rangeHeader = c.req.header("Range");
if (rangeHeader) {
const match = /bytes=(\d+)-(\d*)/.exec(rangeHeader);
if (match) {
const start = parseInt(match[1]!, 10);
const end = match[2] ? parseInt(match[2], 10) : totalSize - 1;
const safeEnd = Math.min(end, totalSize - 1);
const chunkSize = safeEnd - start + 1;
return new Response(new Uint8Array(buffer.slice(start, safeEnd + 1)), {
status: 206,
headers: {
"Content-Type": contentType,
"Content-Range": `bytes ${start}-${safeEnd}/${totalSize}`,
"Accept-Ranges": "bytes",
"Content-Length": String(chunkSize),
},
});
}
}
return new Response(new Uint8Array(buffer), {
headers: {
"Content-Type": contentType,
"Accept-Ranges": "bytes",
"Content-Length": String(totalSize),
},
});
});
}
packages/core/src/studio-api/routes/render.ts
+36 -1
View File
@@ -73,7 +73,8 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
quality,
jobId,
});
renderJobs.set(jobId, { ...jobState, createdAt: Date.now() });
(jobState as RenderJobState & { createdAt: number }).createdAt = Date.now();
renderJobs.set(jobId, jobState as RenderJobState & { createdAt: number });
// Restart cleanup timer if needed
if (!cleanupTimer && typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
@@ -125,6 +126,27 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
});
});
// Serve render inline (for in-browser playback — opens in a new tab)
api.get("/render/:jobId/view", (c) => {
const { jobId } = c.req.param();
const job = renderJobs.get(jobId);
if (!job?.outputPath || !existsSync(job.outputPath)) {
return c.json({ error: "not found" }, 404);
}
const isWebm = job.outputPath.endsWith(".webm");
const contentType = isWebm ? "video/webm" : "video/mp4";
const filename = job.outputPath.split("/").pop() ?? `render.mp4`;
const content = readFileSync(job.outputPath);
return new Response(content, {
headers: {
"Content-Type": contentType,
"Content-Disposition": `inline; filename="${filename}"`,
"Accept-Ranges": "bytes",
"Content-Length": String(content.length),
},
});
});
// Download render
api.get("/render/:jobId/download", (c) => {
const { jobId } = c.req.param();
@@ -195,6 +217,19 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
};
})
.sort((a, b) => b.createdAt - a.createdAt);
// Register on-disk renders that aren't in the current session's job map
// so they remain downloadable after a server restart.
for (const file of files) {
if (!renderJobs.has(file.id)) {
renderJobs.set(file.id, {
id: file.id,
status: file.status,
progress: 100,
outputPath: join(rendersDir, file.filename),
createdAt: file.createdAt,
} as RenderJobState & { createdAt: number });
}
}
return c.json({ renders: files });
});
}