From 1782cebfc4c7be8fda971c571479ed80c06a4a96 Mon Sep 17 00:00:00 2001
From: Mu-Tsun Tsai <don.m.t.tsai@gmail.com>
Date: Sat, 25 Apr 2026 22:55:28 +0800
Subject: [PATCH 1/8] fix(cli): resolve sub-composition <audio> src relative to
 its own file (#489)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`lintAudioSrcNotFound` resolves every `<audio src>` against the project
root, which is correct for index.html but wrong for sub-compositions —
their srcs are written relative to the sub-composition file (e.g.
`../assets/foo.mp3`), and the bundler rewrites them at compile time.

Carry the sub-composition path alongside each html source and run
`<audio src>` strings starting with `../` through the existing
`rewriteAssetPath` helper before checking existence on disk. Mirrors the
runtime/bundler behaviour so the lint check sees the same path the
renderer will fetch.

Original (un-rewritten) src is still surfaced in the finding message so
authors can grep for it in their HTML.
---
 packages/cli/src/utils/lintProject.test.ts | 43 ++++++++++++++++++++++
 packages/cli/src/utils/lintProject.ts      | 43 +++++++++++++++++-----
 2 files changed, 77 insertions(+), 9 deletions(-)
diff --git a/packages/cli/src/utils/lintProject.test.ts b/packages/cli/src/utils/lintProject.test.ts
index c3773945db..bc03648383 100644
--- a/packages/cli/src/utils/lintProject.test.ts
+++ b/packages/cli/src/utils/lintProject.test.ts
@@ -324,6 +324,49 @@ describe("audio_src_not_found", () => {
     const occurrences = (finding?.message.match(/song\.mp3/g) ?? []).length;
     expect(occurrences).toBe(1);
   });
+
+  it("resolves sub-composition src relative to the sub-composition file (../assets/...)", () => {
+    // A sub-composition at compositions/captions.html referencing
+    // ../assets/bgm.mp3 means {projectRoot}/assets/bgm.mp3 — the bundler
+    // rewrites that path before serving, so the lint check has to mirror it.
+    const subComp = `<html><body>
+  <div data-composition-id="captions" data-width="1920" data-height="1080">
+    <audio id="music" src="../assets/bgm.mp3" data-start="0" data-track-index="0" data-volume="1"></audio>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["captions"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+    const project = makeProject(validHtml(), { "captions.html": subComp });
+    mkdirSync(join(project.dir, "assets"), { recursive: true });
+    writeFileSync(join(project.dir, "assets", "bgm.mp3"), "fake");
+
+    const { results } = lintProject(project);
+
+    const first = results[0];
+    expect(first).toBeDefined();
+    const finding = first?.result.findings.find((f) => f.code === "audio_src_not_found");
+    expect(finding).toBeUndefined();
+  });
+
+  it("flags sub-composition src that resolves to a missing file via ../", () => {
+    const subComp = `<html><body>
+  <div data-composition-id="captions" data-width="1920" data-height="1080">
+    <audio id="music" src="../assets/missing.mp3" data-start="0" data-track-index="0" data-volume="1"></audio>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["captions"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+    const project = makeProject(validHtml(), { "captions.html": subComp });
+    // No assets/ directory at all.
+
+    const { results } = lintProject(project);
+
+    const first = results[0];
+    expect(first).toBeDefined();
+    const finding = first?.result.findings.find((f) => f.code === "audio_src_not_found");
+    expect(finding).toBeDefined();
+    // The original (un-rewritten) src is what surfaces in the message so the
+    // author can grep for it in their HTML.
+    expect(finding?.message).toContain("../assets/missing.mp3");
+  });
 });
 
 describe("multiple_root_compositions", () => {
diff --git a/packages/cli/src/utils/lintProject.ts b/packages/cli/src/utils/lintProject.ts
index 3519baad30..c119a141fa 100644
--- a/packages/cli/src/utils/lintProject.ts
+++ b/packages/cli/src/utils/lintProject.ts
@@ -2,8 +2,22 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve, extname } from "node:path";
 import { lintHyperframeHtml, type HyperframeLintResult } from "@hyperframes/core/lint";
 import type { HyperframeLintFinding } from "@hyperframes/core/lint";
+import { rewriteAssetPath } from "@hyperframes/core";
 import type { ProjectDir } from "./project.js";
 
+/**
+ * An HTML source paired with the sub-composition path it came from, if any.
+ * Sub-composition relative paths (`../assets/foo.mp3`) need to be resolved
+ * against the sub-composition's directory before checking the filesystem —
+ * the root index.html is the only source where a bare `resolve(projectDir, src)`
+ * is correct.
+ */
+interface HtmlSource {
+  html: string;
+  /** `data-composition-src` value (e.g. "compositions/scene.html"); undefined for the root. */
+  compSrcPath?: string;
+}
+
 export interface ProjectLintResult {
   results: Array<{ file: string; result: HyperframeLintResult }>;
   totalErrors: number;
@@ -32,14 +46,14 @@ export function lintProject(project: ProjectDir): ProjectLintResult {
   totalInfos += rootResult.infoCount;
 
   // Lint sub-compositions in compositions/ directory, collecting HTML for project-level checks
-  const allHtmlSources = [rootHtml];
+  const allHtmlSources: HtmlSource[] = [{ html: rootHtml }];
   const compositionsDir = resolve(project.dir, "compositions");
   if (existsSync(compositionsDir)) {
     const files = readdirSync(compositionsDir).filter((f) => f.endsWith(".html"));
     for (const file of files) {
       const filePath = join(compositionsDir, file);
       const html = readFileSync(filePath, "utf-8");
-      allHtmlSources.push(html);
+      allHtmlSources.push({ html, compSrcPath: `compositions/${file}` });
       const result = lintHyperframeHtml(html, { filePath, isSubComposition: true });
       results.push({ file: `compositions/${file}`, result });
       totalErrors += result.errorCount;
@@ -83,7 +97,10 @@ export function lintProject(project: ProjectDir): ProjectLintResult {
  * placing an audio file in the project but forgetting the <audio> tag, which
  * results in a silent render.
  */
-function lintProjectAudioFiles(projectDir: string, htmlSources: string[]): HyperframeLintFinding[] {
+function lintProjectAudioFiles(
+  projectDir: string,
+  htmlSources: HtmlSource[],
+): HyperframeLintFinding[] {
   const findings: HyperframeLintFinding[] = [];
 
   // Scan project root for audio files (non-recursive — only top-level)
@@ -99,7 +116,7 @@ function lintProjectAudioFiles(projectDir: string, htmlSources: string[]): Hyper
   if (audioFiles.length === 0) return findings;
 
   // Check if any HTML source contains an <audio> element
-  const hasAudioElement = htmlSources.some((html) => /<audio\b/i.test(html));
+  const hasAudioElement = htmlSources.some(({ html }) => /<audio\b/i.test(html));
 
   if (!hasAudioElement) {
     findings.push({
@@ -121,19 +138,27 @@ function lintProjectAudioFiles(projectDir: string, htmlSources: string[]): Hyper
  * in the project directory. The renderer will silently skip missing audio,
  * producing a silent video with no indication of what went wrong.
  */
-function lintAudioSrcNotFound(projectDir: string, htmlSources: string[]): HyperframeLintFinding[] {
+function lintAudioSrcNotFound(
+  projectDir: string,
+  htmlSources: HtmlSource[],
+): HyperframeLintFinding[] {
   const findings: HyperframeLintFinding[] = [];
 
   const audioSrcRe = /<audio\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi;
 
   const missingSrcs: string[] = [];
-  for (const html of htmlSources) {
+  for (const { html, compSrcPath } of htmlSources) {
     let match: RegExpExecArray | null;
     while ((match = audioSrcRe.exec(html)) !== null) {
       const src = match[1]!;
       if (/^(https?:|data:|blob:)/i.test(src)) continue;
       if (/^__[A-Z_]+__$/.test(src)) continue; // Skip template placeholders
-      const resolved = resolve(projectDir, src);
+      // Sub-composition srcs are written relative to the sub-composition file
+      // (e.g. "../assets/foo.mp3"); the bundler rewrites them to root-relative
+      // before serving. Mirror that rewrite here so the existence check sees
+      // the same path the renderer will. Root-html srcs pass through unchanged.
+      const rootRelative = compSrcPath ? rewriteAssetPath(compSrcPath, src) : src;
+      const resolved = resolve(projectDir, rootRelative);
       if (!existsSync(resolved)) {
         missingSrcs.push(src);
       }
@@ -192,7 +217,7 @@ function lintMultipleRootCompositions(projectDir: string): HyperframeLintFinding
  * Extracts each attribute independently (order-insensitive) to handle any HTML attribute order.
  * Deduplicates by (src, start, duration) to avoid flagging the same audio reached via sub-compositions.
  */
-function lintDuplicateAudioTracks(htmlSources: string[]): HyperframeLintFinding[] {
+function lintDuplicateAudioTracks(htmlSources: HtmlSource[]): HyperframeLintFinding[] {
   const findings: HyperframeLintFinding[] = [];
   function extractAttr(tag: string, name: string): string | null {
     const re = new RegExp(`\\b${name}\\s*=\\s*["']([^"']+)["']`, "i");
@@ -203,7 +228,7 @@ function lintDuplicateAudioTracks(htmlSources: string[]): HyperframeLintFinding[
   const tracks: Array<{ trackIndex: number; start: number; end: number; src: string }> = [];
   const seen = new Set<string>();
 
-  for (const html of htmlSources) {
+  for (const { html } of htmlSources) {
     // Regex with g flag must be created inside the loop — a shared g-regex
     // carries lastIndex across strings, silently skipping matches.
     const audioTagRe = /<audio\b[^>]*>/gi;

From 8ac46b45964569be947134b7974c153752e474c1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sat, 25 Apr 2026 10:59:45 -0400
Subject: [PATCH 2/8] chore: release v0.4.25

---
 packages/cli/package.json                | 2 +-
 packages/core/package.json               | 2 +-
 packages/engine/package.json             | 2 +-
 packages/player/package.json             | 2 +-
 packages/producer/package.json           | 2 +-
 packages/shader-transitions/package.json | 2 +-
 packages/studio/package.json             | 2 +-
 7 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/packages/cli/package.json b/packages/cli/package.json
index 64c344b5a6..bc36e69407 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/cli",
-  "version": "0.4.24",
+  "version": "0.4.25",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "repository": {
     "type": "git",
diff --git a/packages/core/package.json b/packages/core/package.json
index 128874329c..caa8328339 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/core",
-  "version": "0.4.24",
+  "version": "0.4.25",
   "description": "",
   "repository": {
     "type": "git",
diff --git a/packages/engine/package.json b/packages/engine/package.json
index fa35d69266..eb927dcb5c 100644
--- a/packages/engine/package.json
+++ b/packages/engine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.4.24",
+  "version": "0.4.25",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
diff --git a/packages/player/package.json b/packages/player/package.json
index b51f704992..4a087b9168 100644
--- a/packages/player/package.json
+++ b/packages/player/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/player",
-  "version": "0.4.24",
+  "version": "0.4.25",
   "description": "Embeddable web component for HyperFrames compositions",
   "repository": {
     "type": "git",
diff --git a/packages/producer/package.json b/packages/producer/package.json
index c1f787fae7..3a67228f80 100644
--- a/packages/producer/package.json
+++ b/packages/producer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.4.24",
+  "version": "0.4.25",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
diff --git a/packages/shader-transitions/package.json b/packages/shader-transitions/package.json
index 7152189bd8..babd37b71e 100644
--- a/packages/shader-transitions/package.json
+++ b/packages/shader-transitions/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/shader-transitions",
-  "version": "0.4.24",
+  "version": "0.4.25",
   "description": "WebGL shader transitions for HyperFrames compositions",
   "repository": {
     "type": "git",
diff --git a/packages/studio/package.json b/packages/studio/package.json
index eb54380178..dec9347bdc 100644
--- a/packages/studio/package.json
+++ b/packages/studio/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.4.24",
+  "version": "0.4.25",
   "description": "",
   "repository": {
     "type": "git",

From b92341eb983402efd79702ec2df52f224263d3c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sat, 25 Apr 2026 17:09:16 +0200
Subject: [PATCH 3/8] fix(cli): publish projects through staged uploads (#491)

* fix(cli): publish projects through staged uploads

* fix(cli): honor signed upload length header
---
 packages/cli/src/utils/publishProject.test.ts | 148 +++++++++--
 packages/cli/src/utils/publishProject.ts      | 238 ++++++++++++++++--
 2 files changed, 352 insertions(+), 34 deletions(-)

diff --git a/packages/cli/src/utils/publishProject.test.ts b/packages/cli/src/utils/publishProject.test.ts
index 957be1a245..b5a3b81173 100644
--- a/packages/cli/src/utils/publishProject.test.ts
+++ b/packages/cli/src/utils/publishProject.test.ts
@@ -37,9 +37,38 @@ describe("createPublishArchive", () => {
 
 describe("publishProjectArchive", () => {
   beforeEach(() => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue(
+    vi.stubEnv("HYPERFRAMES_PUBLISHED_PROJECTS_API_URL", "");
+    vi.stubEnv("HEYGEN_API_URL", "");
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
+  });
+
+  it("uploads through the staged publish flow and returns the stable project URL", async () => {
+    const dir = makeProjectDir();
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            data: {
+              upload_url:
+                "https://s3.example.com/upload?X-Amz-SignedHeaders=content-length;content-type;host;x-amz-server-side-encryption",
+              upload_key: "ephemeral_store/hyperframes/project_uploads/upload-1/demo.zip",
+              upload_headers: {
+                "content-type": "application/zip",
+                "x-amz-server-side-encryption": "AES256",
+              },
+              content_type: "application/zip",
+            },
+          }),
+          { status: 200 },
+        ),
+      )
+      .mockResolvedValueOnce(new Response(null, { status: 200 }))
+      .mockResolvedValueOnce(
         new Response(
           JSON.stringify({
             data: {
@@ -52,16 +81,9 @@ describe("publishProjectArchive", () => {
           }),
           { status: 200 },
         ),
-      ),
-    );
-  });
-
-  afterEach(() => {
-    vi.unstubAllGlobals();
-  });
+      );
+    vi.stubGlobal("fetch", fetchMock);
 
-  it("uploads the archive and returns the stable project URL", async () => {
-    const dir = makeProjectDir();
     try {
       writeFileSync(join(dir, "index.html"), "<html></html>", "utf-8");
       writeFileSync(join(dir, "styles.css"), "body {}", "utf-8");
@@ -73,8 +95,73 @@ describe("publishProjectArchive", () => {
         projectId: "hfp_123",
         url: "https://hyperframes.dev/p/hfp_123",
       });
-      expect(fetch).toHaveBeenCalledTimes(1);
-      expect(fetch).toHaveBeenCalledWith(
+      expect(fetchMock).toHaveBeenCalledTimes(3);
+      expect(fetchMock).toHaveBeenNthCalledWith(
+        1,
+        "https://api2.heygen.com/v1/hyperframes/projects/publish/upload",
+        expect.objectContaining({
+          method: "POST",
+          headers: { "content-type": "application/json", heygen_route: "canary" },
+          signal: expect.any(AbortSignal),
+        }),
+      );
+      expect(fetchMock).toHaveBeenNthCalledWith(
+        2,
+        "https://s3.example.com/upload?X-Amz-SignedHeaders=content-length;content-type;host;x-amz-server-side-encryption",
+        expect.objectContaining({
+          method: "PUT",
+          headers: {
+            "content-length": expect.any(String),
+            "content-type": "application/zip",
+            "x-amz-server-side-encryption": "AES256",
+          },
+          signal: expect.any(AbortSignal),
+        }),
+      );
+      expect(fetchMock).toHaveBeenNthCalledWith(
+        3,
+        "https://api2.heygen.com/v1/hyperframes/projects/publish/complete",
+        expect.objectContaining({
+          method: "POST",
+          headers: { "content-type": "application/json", heygen_route: "canary" },
+          signal: expect.any(AbortSignal),
+        }),
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("falls back to the legacy multipart endpoint when staged publish is not deployed", async () => {
+    const dir = makeProjectDir();
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(new Response("not found", { status: 404 }))
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            data: {
+              project_id: "hfp_123",
+              title: "demo",
+              file_count: 2,
+              url: "https://hyperframes.dev/p/hfp_123",
+              claim_token: "claim-token",
+            },
+          }),
+          { status: 200 },
+        ),
+      );
+    vi.stubGlobal("fetch", fetchMock);
+
+    try {
+      writeFileSync(join(dir, "index.html"), "<html></html>", "utf-8");
+
+      const result = await publishProjectArchive(dir);
+
+      expect(result.projectId).toBe("hfp_123");
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      expect(fetchMock).toHaveBeenNthCalledWith(
+        2,
         "https://api2.heygen.com/v1/hyperframes/projects/publish",
         expect.objectContaining({
           method: "POST",
@@ -86,4 +173,37 @@ describe("publishProjectArchive", () => {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  it("does not fall back to multipart when a staged S3 upload fails", async () => {
+    const dir = makeProjectDir();
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            data: {
+              upload_url: "https://s3.example.com/upload",
+              upload_key: "ephemeral_store/hyperframes/project_uploads/upload-1/demo.zip",
+              upload_headers: {
+                "content-type": "application/zip",
+                "x-amz-server-side-encryption": "AES256",
+              },
+              content_type: "application/zip",
+            },
+          }),
+          { status: 200 },
+        ),
+      )
+      .mockResolvedValueOnce(new Response("denied", { status: 403 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    try {
+      writeFileSync(join(dir, "index.html"), "<html></html>", "utf-8");
+
+      await expect(publishProjectArchive(dir)).rejects.toThrow("Failed to upload project archive");
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });
diff --git a/packages/cli/src/utils/publishProject.ts b/packages/cli/src/utils/publishProject.ts
index 536b19d475..3b4d628555 100644
--- a/packages/cli/src/utils/publishProject.ts
+++ b/packages/cli/src/utils/publishProject.ts
@@ -4,6 +4,8 @@ import AdmZip from "adm-zip";
 
 const IGNORED_DIRS = new Set([".git", "node_modules", "dist", ".next", "coverage"]);
 const IGNORED_FILES = new Set([".DS_Store", "Thumbs.db"]);
+const PUBLISH_CONTENT_TYPE = "application/zip";
+const PUBLISH_REQUEST_TIMEOUT_MS = 30_000;
 
 export interface PublishArchiveResult {
   buffer: Buffer;
@@ -18,6 +20,128 @@ export interface PublishedProjectResponse {
   claimToken: string;
 }
 
+interface StagedUploadResponse {
+  uploadUrl: string;
+  uploadKey: string;
+  contentType: string;
+  uploadHeaders: Record<string, string>;
+}
+
+type JsonRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function dataRecord(payload: unknown): JsonRecord | null {
+  if (!isRecord(payload) || !isRecord(payload["data"])) return null;
+  return payload["data"];
+}
+
+function stringField(record: JsonRecord, key: string): string | null {
+  const value = record[key];
+  return typeof value === "string" ? value : null;
+}
+
+function parsePublishedProjectResponse(payload: unknown): PublishedProjectResponse | null {
+  const data = dataRecord(payload);
+  if (!data) return null;
+  const projectId = stringField(data, "project_id");
+  const title = stringField(data, "title");
+  const url = stringField(data, "url");
+  const claimToken = stringField(data, "claim_token");
+  const fileCount = data["file_count"];
+  if (!projectId || !title || !url || !claimToken || typeof fileCount !== "number") {
+    return null;
+  }
+  return {
+    projectId,
+    title,
+    fileCount,
+    url,
+    claimToken,
+  };
+}
+
+function parseStagedUploadResponse(
+  payload: unknown,
+  archiveByteLength: number,
+): StagedUploadResponse | null {
+  const data = dataRecord(payload);
+  if (!data) return null;
+  const uploadUrl = stringField(data, "upload_url");
+  const uploadKey = stringField(data, "upload_key");
+  const contentType = stringField(data, "content_type") || PUBLISH_CONTENT_TYPE;
+  if (!uploadUrl || !uploadKey) return null;
+  return {
+    uploadUrl,
+    uploadKey,
+    contentType,
+    uploadHeaders: getUploadHeaders(data, uploadUrl, contentType, archiveByteLength),
+  };
+}
+
+function getUploadHeaders(
+  data: JsonRecord,
+  uploadUrl: string,
+  contentType: string,
+  archiveByteLength: number,
+): Record<string, string> {
+  const headers: Record<string, string> = {};
+  const uploadHeaders = data["upload_headers"];
+  if (isRecord(uploadHeaders)) {
+    for (const [key, value] of Object.entries(uploadHeaders)) {
+      if (typeof value === "string" && key.trim()) {
+        headers[key] = value;
+      }
+    }
+  }
+
+  if (!Object.keys(headers).some((key) => key.toLowerCase() === "content-type")) {
+    headers["content-type"] = contentType;
+  }
+
+  const signedHeaders = new URL(uploadUrl).searchParams.get("X-Amz-SignedHeaders");
+  if (
+    signedHeaders?.split(";").includes("x-amz-server-side-encryption") &&
+    !Object.keys(headers).some((key) => key.toLowerCase() === "x-amz-server-side-encryption")
+  ) {
+    headers["x-amz-server-side-encryption"] = "AES256";
+  }
+  if (
+    signedHeaders?.split(";").includes("content-length") &&
+    !Object.keys(headers).some((key) => key.toLowerCase() === "content-length")
+  ) {
+    headers["content-length"] = String(archiveByteLength);
+  }
+
+  return headers;
+}
+
+async function readJson(response: Response): Promise<unknown> {
+  return response
+    .clone()
+    .json()
+    .catch(() => null);
+}
+
+async function readErrorMessage(response: Response, fallback: string): Promise<string> {
+  const contentType = response.headers.get("content-type") || "";
+  if (contentType.includes("application/json")) {
+    const payload = await readJson(response);
+    if (isRecord(payload) && typeof payload["message"] === "string") {
+      return payload["message"];
+    }
+  }
+
+  if (response.status === 403 && response.headers.get("cf-mitigated") === "challenge") {
+    return "Publish upload was blocked before reaching HyperFrames. Please retry after staged uploads are available.";
+  }
+
+  const text = await response.text().catch(() => "");
+  return text.trim() ? `${fallback}: ${text.trim().slice(0, 180)}` : fallback;
+}
+
 function shouldIgnoreSegment(segment: string): boolean {
   return segment.startsWith(".") || IGNORED_DIRS.has(segment) || IGNORED_FILES.has(segment);
 }
@@ -65,37 +189,111 @@ export function getPublishApiBaseUrl(): string {
   ).replace(/\/$/, "");
 }
 
-export async function publishProjectArchive(projectDir: string): Promise<PublishedProjectResponse> {
-  const title = basename(projectDir);
-  const archive = createPublishArchive(projectDir);
-  const archiveBytes = new Uint8Array(archive.buffer.byteLength);
-  archiveBytes.set(archive.buffer);
+function archiveArrayBuffer(archive: PublishArchiveResult): ArrayBuffer {
+  const arrayBuffer = new ArrayBuffer(archive.buffer.byteLength);
+  new Uint8Array(arrayBuffer).set(archive.buffer);
+  return arrayBuffer;
+}
+
+async function publishProjectArchiveDirect(
+  apiBaseUrl: string,
+  title: string,
+  archive: PublishArchiveResult,
+): Promise<PublishedProjectResponse> {
   const body = new FormData();
   body.set("title", title);
-  body.set("file", new File([archiveBytes], `${title}.zip`, { type: "application/zip" }));
+  body.set(
+    "file",
+    new File([archiveArrayBuffer(archive)], `${title}.zip`, { type: PUBLISH_CONTENT_TYPE }),
+  );
   const headers: Record<string, string> = {
     heygen_route: "canary",
   };
 
-  const response = await fetch(`${getPublishApiBaseUrl()}/v1/hyperframes/projects/publish`, {
+  const response = await fetch(`${apiBaseUrl}/v1/hyperframes/projects/publish`, {
     method: "POST",
     body,
     headers,
-    signal: AbortSignal.timeout(30_000),
+    signal: AbortSignal.timeout(PUBLISH_REQUEST_TIMEOUT_MS),
   });
 
-  const payload = await response.json().catch(() => null);
-  const message =
-    typeof payload?.message === "string" ? payload.message : "Failed to publish project";
-  if (!response.ok || !payload?.data) {
-    throw new Error(message);
+  const payload = await readJson(response);
+  const publishedProject = parsePublishedProjectResponse(payload);
+  if (!response.ok || !publishedProject) {
+    throw new Error(await readErrorMessage(response, "Failed to publish project"));
   }
 
-  return {
-    projectId: String(payload.data.project_id),
-    title: String(payload.data.title),
-    fileCount: Number(payload.data.file_count),
-    url: String(payload.data.url),
-    claimToken: String(payload.data.claim_token),
-  };
+  return publishedProject;
+}
+
+async function publishProjectArchiveStaged(
+  apiBaseUrl: string,
+  title: string,
+  archive: PublishArchiveResult,
+): Promise<PublishedProjectResponse | null> {
+  const fileName = `${title}.zip`;
+  const uploadResponse = await fetch(`${apiBaseUrl}/v1/hyperframes/projects/publish/upload`, {
+    method: "POST",
+    body: JSON.stringify({
+      file_name: fileName,
+      content_type: PUBLISH_CONTENT_TYPE,
+      content_length: archive.buffer.byteLength,
+    }),
+    headers: {
+      "content-type": "application/json",
+      heygen_route: "canary",
+    },
+    signal: AbortSignal.timeout(PUBLISH_REQUEST_TIMEOUT_MS),
+  });
+
+  if (uploadResponse.status === 404 || uploadResponse.status === 405) {
+    return null;
+  }
+
+  const uploadPayload = await readJson(uploadResponse);
+  const stagedUpload = parseStagedUploadResponse(uploadPayload, archive.buffer.byteLength);
+  if (!uploadResponse.ok || !stagedUpload) {
+    throw new Error(await readErrorMessage(uploadResponse, "Failed to prepare project upload"));
+  }
+
+  const s3Response = await fetch(stagedUpload.uploadUrl, {
+    method: "PUT",
+    body: new Blob([archiveArrayBuffer(archive)], { type: stagedUpload.contentType }),
+    headers: stagedUpload.uploadHeaders,
+    signal: AbortSignal.timeout(PUBLISH_REQUEST_TIMEOUT_MS),
+  });
+  if (!s3Response.ok) {
+    throw new Error(await readErrorMessage(s3Response, "Failed to upload project archive"));
+  }
+
+  const completeResponse = await fetch(`${apiBaseUrl}/v1/hyperframes/projects/publish/complete`, {
+    method: "POST",
+    body: JSON.stringify({
+      upload_key: stagedUpload.uploadKey,
+      file_name: fileName,
+      title,
+    }),
+    headers: {
+      "content-type": "application/json",
+      heygen_route: "canary",
+    },
+    signal: AbortSignal.timeout(PUBLISH_REQUEST_TIMEOUT_MS),
+  });
+
+  const completePayload = await readJson(completeResponse);
+  const publishedProject = parsePublishedProjectResponse(completePayload);
+  if (!completeResponse.ok || !publishedProject) {
+    throw new Error(await readErrorMessage(completeResponse, "Failed to publish project"));
+  }
+
+  return publishedProject;
+}
+
+export async function publishProjectArchive(projectDir: string): Promise<PublishedProjectResponse> {
+  const title = basename(projectDir);
+  const archive = createPublishArchive(projectDir);
+  const apiBaseUrl = getPublishApiBaseUrl();
+  const stagedResult = await publishProjectArchiveStaged(apiBaseUrl, title, archive);
+  if (stagedResult) return stagedResult;
+  return publishProjectArchiveDirect(apiBaseUrl, title, archive);
 }

From 45f70004a14f392ebeda52c9e8db2327e2cd9d96 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sat, 25 Apr 2026 11:14:36 -0400
Subject: [PATCH 4/8] chore: release v0.4.26

---
 packages/cli/package.json                | 2 +-
 packages/core/package.json               | 2 +-
 packages/engine/package.json             | 2 +-
 packages/player/package.json             | 2 +-
 packages/producer/package.json           | 2 +-
 packages/shader-transitions/package.json | 2 +-
 packages/studio/package.json             | 2 +-
 7 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/packages/cli/package.json b/packages/cli/package.json
index bc36e69407..afdb7f3397 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/cli",
-  "version": "0.4.25",
+  "version": "0.4.26",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "repository": {
     "type": "git",
diff --git a/packages/core/package.json b/packages/core/package.json
index caa8328339..9233c182cf 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/core",
-  "version": "0.4.25",
+  "version": "0.4.26",
   "description": "",
   "repository": {
     "type": "git",
diff --git a/packages/engine/package.json b/packages/engine/package.json
index eb927dcb5c..e3d773331d 100644
--- a/packages/engine/package.json
+++ b/packages/engine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.4.25",
+  "version": "0.4.26",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
diff --git a/packages/player/package.json b/packages/player/package.json
index 4a087b9168..774c48c711 100644
--- a/packages/player/package.json
+++ b/packages/player/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/player",
-  "version": "0.4.25",
+  "version": "0.4.26",
   "description": "Embeddable web component for HyperFrames compositions",
   "repository": {
     "type": "git",
diff --git a/packages/producer/package.json b/packages/producer/package.json
index 3a67228f80..fefc5e93cf 100644
--- a/packages/producer/package.json
+++ b/packages/producer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.4.25",
+  "version": "0.4.26",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
diff --git a/packages/shader-transitions/package.json b/packages/shader-transitions/package.json
index babd37b71e..ea47b361f8 100644
--- a/packages/shader-transitions/package.json
+++ b/packages/shader-transitions/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/shader-transitions",
-  "version": "0.4.25",
+  "version": "0.4.26",
   "description": "WebGL shader transitions for HyperFrames compositions",
   "repository": {
     "type": "git",
diff --git a/packages/studio/package.json b/packages/studio/package.json
index dec9347bdc..cdfda1f34e 100644
--- a/packages/studio/package.json
+++ b/packages/studio/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.4.25",
+  "version": "0.4.26",
   "description": "",
   "repository": {
     "type": "git",

From 9b72a87c17af63883361712f02d6871c0f356a24 Mon Sep 17 00:00:00 2001
From: Mu-Tsun Tsai <don.m.t.tsai@gmail.com>
Date: Sat, 25 Apr 2026 23:52:12 +0800
Subject: [PATCH 5/8] fix(lint): remove root_composition_missing_data_duration
 (#490)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(lint): remove root_composition_missing_data_duration

Lint cannot statically observe the runtime's true Infinity-emission
condition: it requires a finite GSAP timeline duration AND a finite
media/sub-comp window AND timeline > floor + 1, none of which are
visible to the static linter. The looping shapes that drive the
condition are already covered by `gsap_infinite_repeat` and
`gsap_repeat_ceil_overshoot` (both from #243), which point at the
real authoring mistake — flagging the missing duration separately
was a noisy proxy for the same signal.

Per #490 review discussion, deprecate the static rule and let those
two GSAP rules carry the pre-render coverage. If perfect precision
on `durationInFrames = Infinity` is needed, that belongs on the
runtime/render path where `shouldEmitNonDeterministicInf` is
actually known.

Add regression tests pinning the removal: a docs-compliant root
without `data-duration` no longer warns, and the canonical
loop-inflated shape now surfaces only via `gsap_infinite_repeat`
instead of two duplicate findings.

* docs(skills): update step-6 build checklist after rule removal

Drops the `root_composition_missing_data_duration` reference now that
the rule is gone. Keeps the authoring recommendation (and explains the
runtime Infinity case) but points authors at the GSAP rules that
actually carry the lint signal: `gsap_infinite_repeat` and
`gsap_repeat_ceil_overshoot`.
---
 .../core/src/lint/rules/composition.test.ts   | 59 +++++++++++++++++++
 packages/core/src/lint/rules/composition.ts   | 20 -------
 .../references/step-6-build.md                |  2 +-
 3 files changed, 60 insertions(+), 21 deletions(-)

diff --git a/packages/core/src/lint/rules/composition.test.ts b/packages/core/src/lint/rules/composition.test.ts
index 6d50c42e01..87172ceec8 100644
--- a/packages/core/src/lint/rules/composition.test.ts
+++ b/packages/core/src/lint/rules/composition.test.ts
@@ -380,4 +380,63 @@ describe("composition rules", () => {
       expect(finding).toBeUndefined();
     });
   });
+
+  describe("root_composition_missing_data_duration (removed)", () => {
+    // The rule was a static proxy for the runtime's loop-inflation Infinity
+    // emission, but lint cannot observe GSAP timeline duration statically and
+    // the looping shapes that drive it are already covered by
+    // `gsap_infinite_repeat` and `gsap_repeat_ceil_overshoot`. The rule has
+    // been removed (#243's Infinity-emission concern is now carried by those
+    // GSAP rules); these tests pin the removal so the rule does not silently
+    // come back.
+
+    it("does not warn on a docs-compliant root with no data-duration", () => {
+      // The documented authoring model: root composition without
+      // data-duration, runtime derives it from the GSAP timeline.
+      const html = `<!DOCTYPE html><html><body>
+  <div data-composition-id="docs" data-width="1920" data-height="1080" data-start="0">
+    <video src="clip.mp4" data-start="0" data-track-index="0" muted playsinline></video>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["docs"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = lintHyperframeHtml(html);
+      const finding = result.findings.find(
+        (f) => f.code === "root_composition_missing_data_duration",
+      );
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not warn even on the original Infinity-risk shape (no media, looping timeline)", () => {
+      // This was the canonical "warn" case under the old rule — root with no
+      // data-duration, no media, GSAP timeline driven by repeat: -1. The
+      // looping shape itself is now flagged by `gsap_infinite_repeat`; the
+      // duplicate `root_composition_missing_data_duration` warning is gone.
+      const html = `<!DOCTYPE html><html><body>
+  <div data-composition-id="loopy" data-width="1920" data-height="1080" data-start="0">
+    <div class="caption" data-start="1" data-duration="2">hello</div>
+  </div>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to(".caption", { x: 100, duration: 1, repeat: -1 });
+    window.__timelines["loopy"] = tl;
+  </script>
+</body></html>`;
+      const result = lintHyperframeHtml(html);
+      // The deprecated rule must not fire.
+      const removedFinding = result.findings.find(
+        (f) => f.code === "root_composition_missing_data_duration",
+      );
+      expect(removedFinding).toBeUndefined();
+      // The looping shape is still surfaced — by `gsap_infinite_repeat`,
+      // which is the more actionable signal pointing at the real authoring
+      // mistake.
+      const gsapFinding = result.findings.find((f) => f.code === "gsap_infinite_repeat");
+      expect(gsapFinding).toBeDefined();
+    });
+  });
 });
diff --git a/packages/core/src/lint/rules/composition.ts b/packages/core/src/lint/rules/composition.ts
index 232634e8b8..e7e24e1cd9 100644
--- a/packages/core/src/lint/rules/composition.ts
+++ b/packages/core/src/lint/rules/composition.ts
@@ -210,26 +210,6 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
     return findings;
   },
 
-  // root_composition_missing_data_duration
-  ({ rootTag }) => {
-    const findings: HyperframeLintFinding[] = [];
-    if (!rootTag) return findings;
-    const compId = readAttr(rootTag.raw, "data-composition-id");
-    if (!compId) return findings;
-    const hasDuration = readAttr(rootTag.raw, "data-duration") !== null;
-    if (!hasDuration) {
-      findings.push({
-        code: "root_composition_missing_data_duration",
-        severity: "warning",
-        message: `Root composition "${compId}" is missing data-duration. Without an explicit duration, the runtime may infer Infinity for compositions with repeating animations, causing playback issues.`,
-        fixHint:
-          'Add data-duration="X" to the root composition element, where X is the total duration in seconds.',
-        snippet: truncateSnippet(rootTag.raw),
-      });
-    }
-    return findings;
-  },
-
   // standalone_composition_wrapped_in_template
   ({ rawSource, options }) => {
     const findings: HyperframeLintFinding[] = [];
diff --git a/skills/website-to-hyperframes/references/step-6-build.md b/skills/website-to-hyperframes/references/step-6-build.md
index 7d7704b3cb..0021ccaf28 100644
--- a/skills/website-to-hyperframes/references/step-6-build.md
+++ b/skills/website-to-hyperframes/references/step-6-build.md
@@ -114,7 +114,7 @@ After building the composition, check WITH ACTUAL CODE:
 - [ ] No full-screen dark linear gradients (H.264 creates visible banding — use solid + localized radial glows)
 - [ ] Timeline registered: `window.__timelines["comp-id"] = tl`
 - [ ] Colors match DESIGN.md exactly (paste the HEX value, don't approximate)
-- [ ] **Every `<template>` root element** — not just `index.html`, but every sub-composition's root — has `data-start="0"` **and** `data-duration="<beat_seconds>"`. The linter warns `root_composition_missing_data_start` / `root_composition_missing_data_duration` when missing; without `data-duration` the runtime may infer `Infinity` on repeating animations and stall playback.
+- [ ] **Every `<template>` root element** — not just `index.html`, but every sub-composition's root — has `data-start="0"`. The linter warns `root_composition_missing_data_start` when missing. Authoring `data-duration="<beat_seconds>"` on the root is also recommended for compositions whose GSAP timeline uses repeating animations (`repeat: -1` or large `repeat: N`); without it the runtime may infer `Infinity` and stall playback. The linter flags those repeating shapes directly via `gsap_infinite_repeat` and `gsap_repeat_ceil_overshoot`.
 - [ ] **Caption exits have a hard kill.** If you animate captions out with `tl.to(groupEl, { opacity: 0 }, group.end)`, follow it with `tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end)` as a deterministic kill — per-word karaoke tweens can override the exit tween and leave captions stuck on screen. Linter: `caption_exit_missing_hard_kill`.
 - [ ] **No duplicate media nodes.** If the same image/video source is referenced twice with identical `data-start` + `data-duration`, the compiler discovers it twice and can double-render. Dedupe by using a single `<img>` with appropriate z-layering, or stagger the `data-start` values. Linter: `duplicate_media_discovery_risk`.
 

From 9322ff9c74e20c447ef3d1c522f9d7fcbe76629b Mon Sep 17 00:00:00 2001
From: Ular Kimsanov <ularkimsanov7@gmail.com>
Date: Sat, 25 Apr 2026 16:50:16 -0400
Subject: [PATCH 6/8] refactor: move Claude Design instructions from skills/ to
 docs/ (#495)

---
 .gitignore                                    |  4 ++
 README.md                                     | 17 ++++----
 .../guides/claude-design-hyperframes.md       |  5 ---
 docs/guides/claude-design.mdx                 | 42 +++++++++----------
 docs/guides/prompting.mdx                     |  2 +-
 docs/quickstart.mdx                           |  2 +-
 6 files changed, 35 insertions(+), 37 deletions(-)
 rename skills/claude-design-hyperframes/SKILL.md => docs/guides/claude-design-hyperframes.md (99%)

diff --git a/.gitignore b/.gitignore
index b23d83d47b..55b6babf09 100644
--- a/.gitignore
+++ b/.gitignore
@@ -94,3 +94,7 @@ captures/
 cursor-tests/
 basecamp-video/
 launch-video*/
+ab-test/
+compositions/
+video-6-2-patched/
+claude-design-hyperframes-video/
diff --git a/README.md b/README.md
index d4bbb000c1..e35c1e8c1d 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ npx skills add heygen-com/hyperframes
 
 This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions and GSAP animations. In Claude Code, the skills register as slash commands — invoke `/hyperframes` to author compositions, `/hyperframes-cli` for CLI commands, and `/gsap` for animation help.
 
-For Claude Design, open [`skills/claude-design-hyperframes/SKILL.md`](https://github.com/heygen-com/hyperframes/blob/main/skills/claude-design-hyperframes/SKILL.md) on GitHub and click the download button (↓) to save it, then attach the file to your Claude Design chat. It produces a valid first draft; refine in any AI coding agent. See the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design).
+For Claude Design, open [`docs/guides/claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) on GitHub and click the download button (↓) to save it, then attach the file to your Claude Design chat. It produces a valid first draft; refine in any AI coding agent. See the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design).
 
 For Codex specifically, the same skills are also exposed as an [OpenAI Codex plugin](./.codex-plugin/plugin.json) — sparse-install just the plugin surface:
 
@@ -184,14 +184,13 @@ HyperFrames ships [skills](https://github.com/vercel-labs/skills) that teach AI
 npx skills add heygen-com/hyperframes
 ```
 
-| Skill                       | What it teaches                                                                                                    |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `claude-design-hyperframes` | Template-first Claude Design skill — pre-valid skeletons, produces video drafts for refinement in any coding agent |
-| `hyperframes`               | HTML composition authoring, captions, TTS, audio-reactive animation, transitions                                   |
-| `hyperframes-cli`           | CLI commands: init, lint, preview, render, transcribe, tts, doctor                                                 |
-| `hyperframes-registry`      | Block and component installation via `hyperframes add`                                                             |
-| `website-to-hyperframes`    | Capture a URL and turn it into a video — full website-to-video pipeline                                            |
-| `gsap`                      | GSAP animation API, timelines, easing, ScrollTrigger, plugins, React/Vue/Svelte, performance                       |
+| Skill                    | What it teaches                                                                              |
+| ------------------------ | -------------------------------------------------------------------------------------------- |
+| `hyperframes`            | HTML composition authoring, captions, TTS, audio-reactive animation, transitions             |
+| `hyperframes-cli`        | CLI commands: init, lint, preview, render, transcribe, tts, doctor                           |
+| `hyperframes-registry`   | Block and component installation via `hyperframes add`                                       |
+| `website-to-hyperframes` | Capture a URL and turn it into a video — full website-to-video pipeline                      |
+| `gsap`                   | GSAP animation API, timelines, easing, ScrollTrigger, plugins, React/Vue/Svelte, performance |
 
 ## Contributing
 
diff --git a/skills/claude-design-hyperframes/SKILL.md b/docs/guides/claude-design-hyperframes.md
similarity index 99%
rename from skills/claude-design-hyperframes/SKILL.md
rename to docs/guides/claude-design-hyperframes.md
index 037bf05518..86f5bb0f69 100644
--- a/skills/claude-design-hyperframes/SKILL.md
+++ b/docs/guides/claude-design-hyperframes.md
@@ -1,8 +1,3 @@
----
-name: claude-design-hyperframes
-description: Use when running inside Claude Design specifically. Produces a valid, brand-accurate HyperFrames video draft using pre-valid skeletons. For Claude Code / Cursor / Codex, use the `hyperframes` skill instead.
----
-
 # Claude Design + HyperFrames (Template-First)
 
 Your medium is **HyperFrames compositions**: plain HTML + CSS + a paused GSAP timeline. The CLI (`npx hyperframes render index.html`) turns the HTML into an MP4. You author the HTML -- the user renders locally.
diff --git a/docs/guides/claude-design.mdx b/docs/guides/claude-design.mdx
index 6fca49246b..29c7e6269e 100644
--- a/docs/guides/claude-design.mdx
+++ b/docs/guides/claude-design.mdx
@@ -1,6 +1,6 @@
 ---
 title: Claude Design
-description: "Create HyperFrames video drafts in Claude Design using a template-first skill, then refine in any AI coding agent."
+description: "Create HyperFrames video drafts in Claude Design, then refine in any AI coding agent."
 ---
 
 Claude Design produces a **valid first draft** of a HyperFrames video — brand identity, scene content, layout, animations, and transitions. You then download the ZIP and refine in any AI coding agent (Claude Code, Cursor, Codex, Windsurf, etc.) with linting and live preview.
@@ -8,14 +8,14 @@ Claude Design produces a **valid first draft** of a HyperFrames video — brand
 ## Get started
 
 <Steps>
-  <Step title="Download the skill">
-    Right-click [`SKILL.md`](https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills/claude-design-hyperframes/SKILL.md) → **Save Link As** to download. (Clicking opens it as text in a new tab.)
+  <Step title="Download the instruction file">
+    Open [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) on GitHub and click the download button (↓) to save it. Or right-click [`this raw link`](https://raw.githubusercontent.com/heygen-com/hyperframes/main/docs/guides/claude-design-hyperframes.md) → **Save Link As**.
   </Step>
   <Step title="Open Claude Design">
     Start a new chat at [claude.ai](https://claude.ai) with Claude Design enabled.
   </Step>
-  <Step title="Attach the skill + describe your video">
-    Drag the SKILL.md file into the chat. Describe what you want — include screenshots, brand assets, or a palette if you have them.
+  <Step title="Attach the file + describe your video">
+    Drag the `claude-design-hyperframes.md` file into the chat. Describe what you want — include screenshots, brand assets, or a palette if you have them.
   </Step>
   <Step title="Download the ZIP">
     Claude Design produces `index.html`, `preview.html`, `README.md`, and `DESIGN.md`. Download the ZIP.
@@ -38,27 +38,27 @@ Claude Design produces a **valid first draft** of a HyperFrames video — brand
 
 | Surface                     | Recommended setup                                                                                                             |
 | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| Claude Design               | Right-click [`SKILL.md`](https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills/claude-design-hyperframes/SKILL.md) → Save Link As, then attach to your chat |
+| Claude Design               | Download [`claude-design-hyperframes.md`](https://raw.githubusercontent.com/heygen-com/hyperframes/main/docs/guides/claude-design-hyperframes.md) and attach to your chat |
 | Claude Code                 | `npx skills add heygen-com/hyperframes`, then use `/hyperframes`                                                              |
 | Cursor / Codex / Gemini CLI | `npx skills add heygen-com/hyperframes`                                                                                       |
 
-## How the skill works
+## How it works
 
-The skill gives Claude Design **pre-valid HTML skeletons** — the structural rules (data attributes, timeline registration, scene visibility, preview token forwarding) are already embedded. Claude Design fills in the creative work:
+The instruction file gives Claude Design **pre-valid HTML skeletons** — the structural rules (data attributes, timeline registration, scene visibility, preview token forwarding) are already embedded. Claude Design fills in the creative work:
 
 1. **Palette + typography** — CSS custom properties on `:root`
 2. **Scene content** — text, images, layout inside `.scene-content` wrappers
 3. **Animations** — GSAP entrance tweens and mid-scene activity
 4. **Transitions** — hard cuts for most scenes, shader transitions at 2-3 key moments
 
-This template-first approach means the output passes `npx hyperframes lint` with zero errors on first download — Claude Code can start refining immediately without structural fixes.
+This template-first approach means the output passes `npx hyperframes lint` with zero errors on first download — your coding agent can start refining immediately without structural fixes.
 
 ## Example prompts
 
 <CardGroup cols={1}>
-  <Card title="Feature announcement (attach SKILL.md)">
+  <Card title="Feature announcement">
     ```text
-    Use the attached skill. I just shipped dark mode for my app. Make me a
+    Use the attached file. I just shipped dark mode for my app. Make me a
     15-second Instagram reel announcing it.
 
     - App name: Taskflow
@@ -67,9 +67,9 @@ This template-first approach means the output passes `npx hyperframes lint` with
     - Key stat: "47% of users requested this"
     ```
   </Card>
-  <Card title="Founder pitch (attach SKILL.md)">
+  <Card title="Founder pitch">
     ```text
-    Use the attached skill. 25-second LinkedIn video for my startup.
+    Use the attached file. 25-second LinkedIn video for my startup.
 
     Problem: Sales teams waste 3 hours/day on manual CRM updates.
     Solution: AutoCRM — AI that logs every call, email, and meeting.
@@ -79,9 +79,9 @@ This template-first approach means the output passes `npx hyperframes lint` with
     Professional but not corporate. Think Linear or Vercel energy.
     ```
   </Card>
-  <Card title="Stat highlight (attach SKILL.md)">
+  <Card title="Stat highlight">
     ```text
-    Use the attached skill. 10-second reel. Just one big number:
+    Use the attached file. 10-second reel. Just one big number:
 
     "$4.2 billion processed in Q1 2026"
 
@@ -89,12 +89,12 @@ This template-first approach means the output passes `npx hyperframes lint` with
     confident. End with logo placeholder and "stripe.com"
     ```
   </Card>
-  <Card title="Sparse brief (attach SKILL.md, let it ask)">
+  <Card title="Sparse brief (let it ask)">
     ```text
-    Use the attached skill. Make a 30-second launch video for Orbit.
+    Use the attached file. Make a 30-second launch video for Orbit.
     ```
 
-    The skill asks ONE short clarifying question before generating.
+    The instructions tell Claude Design to ask ONE short clarifying question before generating.
   </Card>
 </CardGroup>
 
@@ -115,9 +115,9 @@ The more specific your prompt, the better the output. Include palette, fonts, du
 
 - **In-pane preview** — scrubbing is unreliable in Claude Design's iframe sandbox. Download and use `npx hyperframes preview` locally for reliable playback.
 - **No linting** — Claude Design can't run `npx hyperframes lint`. The template-first skeletons handle structural validity, but the self-review checklist is the only QA before download.
-- **Shaders work at any aspect ratio** — vertical (1080x1920), landscape (1920x1080), and square (1080x1080) all supported. HyperShader reads dimensions from `data-width`/`data-height` on the composition root.
-- **3 fetch limit** — Claude Design limits web fetches per turn. All critical rules are inlined in the skill; external references are for edge cases only.
-- **Seeking backwards** — scrubbing backwards in the in-pane preview can show blank frames (async capture race condition). Forward seeking usually works.
+- **Shaders work at any aspect ratio** — vertical (1080x1920), landscape (1920x1080), and square (1080x1080) all supported.
+- **3 fetch limit** — Claude Design limits web fetches per turn. All critical rules are inlined; external references are for edge cases only.
+- **Seeking backwards** — scrubbing backwards in the in-pane preview can show blank frames. Forward seeking usually works.
 
 ## The handoff to your coding agent
 
diff --git a/docs/guides/prompting.mdx b/docs/guides/prompting.mdx
index 6f09d50c49..7ea20cb0c9 100644
--- a/docs/guides/prompting.mdx
+++ b/docs/guides/prompting.mdx
@@ -29,7 +29,7 @@ In Claude Code, restart the session after installing. Skills register as **slash
 
 ## Claude Design
 
-Claude Design uses a different setup. Right-click [`SKILL.md`](https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills/claude-design-hyperframes/SKILL.md) → **Save Link As** to download, then **attach it to your chat** (don't paste the URL — file attachments produce better output):
+Claude Design uses a different setup. Right-click [`SKILL.md`](https://raw.githubusercontent.com/heygen-com/hyperframes/main/docs/guides/claude-design-hyperframes.md) → **Save Link As** to download, then **attach it to your chat** (don't paste the URL — file attachments produce better output):
 
 ```text
 Use the attached skill. 25-second LinkedIn video for my startup.
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index 3cf30981a0..498816d66a 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -16,7 +16,7 @@ npx skills add heygen-com/hyperframes
 This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions and GSAP animations. In Claude Code the skills register as slash commands — `/hyperframes` for composition authoring, `/hyperframes-cli` for CLI commands, and `/gsap` for animation help. Invoking the slash command loads the skill context explicitly, which produces correct output the first time.
 
 <Note>
-  Claude Design uses a different entry path. Open [`skills/claude-design-hyperframes/SKILL.md`](https://github.com/heygen-com/hyperframes/blob/main/skills/claude-design-hyperframes/SKILL.md) on GitHub, click the download button (↓) to save it, then attach to your Claude Design chat. It produces a valid first draft you can refine in any AI coding agent. See the [Claude Design guide](/guides/claude-design).
+  Claude Design uses a different entry path. Open [`docs/guides/claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) on GitHub, click the download button (↓) to save it, then attach to your Claude Design chat. It produces a valid first draft you can refine in any AI coding agent. See the [Claude Design guide](/guides/claude-design).
 </Note>
 
 ### Try it: example prompts

From a65c0ce22e1e36a15a715e14c3ecf3f4d5dc161c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sat, 25 Apr 2026 16:53:48 -0400
Subject: [PATCH 7/8] chore: release v0.4.27

---
 packages/cli/package.json                | 2 +-
 packages/core/package.json               | 2 +-
 packages/engine/package.json             | 2 +-
 packages/player/package.json             | 2 +-
 packages/producer/package.json           | 2 +-
 packages/shader-transitions/package.json | 2 +-
 packages/studio/package.json             | 2 +-
 7 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/packages/cli/package.json b/packages/cli/package.json
index afdb7f3397..96acee11ad 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/cli",
-  "version": "0.4.26",
+  "version": "0.4.27",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "repository": {
     "type": "git",
diff --git a/packages/core/package.json b/packages/core/package.json
index 9233c182cf..7e3e5d7bba 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/core",
-  "version": "0.4.26",
+  "version": "0.4.27",
   "description": "",
   "repository": {
     "type": "git",
diff --git a/packages/engine/package.json b/packages/engine/package.json
index e3d773331d..7f782a22e5 100644
--- a/packages/engine/package.json
+++ b/packages/engine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.4.26",
+  "version": "0.4.27",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
diff --git a/packages/player/package.json b/packages/player/package.json
index 774c48c711..6b0671e7f9 100644
--- a/packages/player/package.json
+++ b/packages/player/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/player",
-  "version": "0.4.26",
+  "version": "0.4.27",
   "description": "Embeddable web component for HyperFrames compositions",
   "repository": {
     "type": "git",
diff --git a/packages/producer/package.json b/packages/producer/package.json
index fefc5e93cf..ba3e1aadc8 100644
--- a/packages/producer/package.json
+++ b/packages/producer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.4.26",
+  "version": "0.4.27",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
diff --git a/packages/shader-transitions/package.json b/packages/shader-transitions/package.json
index ea47b361f8..e7b544cd06 100644
--- a/packages/shader-transitions/package.json
+++ b/packages/shader-transitions/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/shader-transitions",
-  "version": "0.4.26",
+  "version": "0.4.27",
   "description": "WebGL shader transitions for HyperFrames compositions",
   "repository": {
     "type": "git",
diff --git a/packages/studio/package.json b/packages/studio/package.json
index cdfda1f34e..ffc9cd8563 100644
--- a/packages/studio/package.json
+++ b/packages/studio/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.4.26",
+  "version": "0.4.27",
   "description": "",
   "repository": {
     "type": "git",

From 979314aee8f4682004d78697f88c62865e37979b Mon Sep 17 00:00:00 2001
From: ishan pandey <ishanpandey@ishans-MacBook-Air.local>
Date: Sun, 26 Apr 2026 02:36:24 +0530
Subject: [PATCH 8/8] feat(lint): error when GSAP animates a <video>'s
 width/height/top/left/x/y
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Animating box dimensions on a <video> directly causes Chromium to stop
pushing frames or to drop the compositor — documented as the most common
cause of broken compositions in the upstream Common Mistakes guide. The
fix is always the same: wrap the <video> in a non-timed <div> and animate
the wrapper instead.

The rule fires when:
- a GSAP method (to/from/fromTo/set on a timeline or gsap.*) targets a
  direct id selector (#id), AND
- the matching tag is a <video>, AND
- the tween animates one of width/height/top/left/x/y.

False-positive guard: only direct id selectors are flagged. Class or
attribute selectors might wrap a video legitimately and we don't want to
penalize wrapper-pattern code.

Tests cover: width/height fires, x/y/top/left fires, opacity/scale/filter
do not fire, wrapper-div pattern does not fire, non-video element does
not fire, class selector touching a video does not fire.

Refs: hyperframes Common Mistakes guide — "Animating video element
dimensions" — closes the GAP-1 audit finding.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 packages/core/src/lint/rules/gsap.test.ts | 119 ++++++++++++++++++++++
 packages/core/src/lint/rules/gsap.ts      |  50 +++++++++
 2 files changed, 169 insertions(+)

diff --git a/packages/core/src/lint/rules/gsap.test.ts b/packages/core/src/lint/rules/gsap.test.ts
index d4d1d6f450..671a25e6d4 100644
--- a/packages/core/src/lint/rules/gsap.test.ts
+++ b/packages/core/src/lint/rules/gsap.test.ts
@@ -725,4 +725,123 @@ describe("GSAP rules", () => {
     const finding = result.findings.find((f) => f.code === "gsap_infinite_repeat");
     expect(finding).toBeUndefined();
   });
+
+  it("errors when GSAP animates width/height on a <video> directly", () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <video id="el-video" muted data-start="0" data-track-index="0" src="./assets/v.mp4"
+           style="width: 1920px; height: 1080px"></video>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#el-video", { width: 500, height: 280, duration: 0.5 }, 4);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_video_dimensions");
+    expect(finding).toBeDefined();
+    expect(finding?.elementId).toBe("el-video");
+    expect(finding?.severity).toBe("error");
+    expect(finding?.message).toContain("width");
+    expect(finding?.message).toContain("height");
+    expect(finding?.fixHint).toContain("wrapper");
+  });
+
+  it("errors when GSAP animates x/y/top/left on a <video> directly", () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <video id="hero-vid" muted data-start="0" data-track-index="0" src="./assets/v.mp4"></video>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.fromTo("#hero-vid", { x: 0, y: 0 }, { x: 200, top: 50, duration: 0.4 }, 1);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_video_dimensions");
+    expect(finding).toBeDefined();
+    expect(finding?.elementId).toBe("hero-vid");
+  });
+
+  it("does NOT fire when GSAP animates safe props on a <video> (opacity, scale, filter)", () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <video id="el-video" muted data-start="0" data-track-index="0" src="./assets/v.mp4"></video>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#el-video", { opacity: 0.6, scale: 1.05, filter: "blur(2px)", duration: 0.5 }, 0);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_video_dimensions");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT fire when the dimension tween targets a wrapper <div>, not the <video>", () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <div id="pip-wrapper" style="position: absolute; width: 1920px; height: 1080px">
+      <video id="el-video" muted data-start="0" data-track-index="0" src="./assets/v.mp4"
+             style="width: 100%; height: 100%"></video>
+    </div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#pip-wrapper", { width: 500, height: 280, top: 700, left: 1400, duration: 0.6 }, 26);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_video_dimensions");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT fire on dimension tweens against non-video elements", () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <div id="card" class="clip" data-start="0" data-duration="3" data-track-index="0">A</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#card", { width: 500, height: 200, duration: 0.5 }, 0);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_video_dimensions");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT fire on a class-selector tween that happens to match a video's class", () => {
+    // Class/attribute selectors avoid false positives — only direct id selectors fire.
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <video id="bg-vid" class="bg" muted data-start="0" data-track-index="0" src="./assets/v.mp4"></video>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to(".bg", { width: 800, duration: 0.5 }, 0);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_video_dimensions");
+    expect(finding).toBeUndefined();
+  });
 });
diff --git a/packages/core/src/lint/rules/gsap.ts b/packages/core/src/lint/rules/gsap.ts
index 8e83dbd42f..2259e1483b 100644
--- a/packages/core/src/lint/rules/gsap.ts
+++ b/packages/core/src/lint/rules/gsap.ts
@@ -779,4 +779,54 @@ export const gsapRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
     }
     return findings;
   },
+
+  // gsap_animates_video_dimensions — wrap the video instead.
+  // Animating width/height/top/left (and CSS transforms x/y) directly on a
+  // <video> element causes Chromium to stop pushing frames or tank the
+  // compositor — a known footgun documented in the upstream Common Mistakes
+  // guide. The fix is to put the <video> inside a non-timed wrapper <div>
+  // and animate the wrapper instead. The video fills the wrapper at 100%.
+  ({ tags, scripts }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const videoIdToTag = new Map<string, OpenTag>();
+    for (const tag of tags) {
+      if (tag.name !== "video") continue;
+      const id = readAttr(tag.raw, "id");
+      if (id) videoIdToTag.set(id, tag);
+    }
+    if (videoIdToTag.size === 0 || scripts.length === 0) return findings;
+
+    const DIM_PROPS = new Set(["width", "height", "top", "left", "x", "y"]);
+
+    for (const script of scripts) {
+      const gsapWindows = extractGsapWindows(script.content);
+      for (const win of gsapWindows) {
+        // Only direct id-selector matches — class/attribute selectors might
+        // legitimately wrap a video and we don't want false positives there.
+        const sel = win.targetSelector.trim();
+        if (!sel.startsWith("#")) continue;
+        const id = sel.slice(1);
+        const videoTag = videoIdToTag.get(id);
+        if (!videoTag) continue;
+
+        const animatedDims = win.properties.filter((p) => DIM_PROPS.has(p));
+        if (animatedDims.length === 0) continue;
+
+        findings.push({
+          code: "gsap_animates_video_dimensions",
+          severity: "error",
+          message:
+            `GSAP animates ${animatedDims.join(", ")} on <video id="${id}">. ` +
+            `Chromium can stop pushing frames or drop the compositor when a <video>'s box is animated directly.`,
+          elementId: id,
+          selector: sel,
+          fixHint:
+            `Wrap the <video> in a non-timed <div id="${id}-wrapper"> ` +
+            `and animate the wrapper instead — let the video fill it at 100% via CSS.`,
+          snippet: truncateSnippet(win.raw),
+        });
+      }
+    }
+    return findings;
+  },
 ];
