From b1f971d7ebe7d370b6651c92b5ac4fc06e3382f9 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Fri, 26 Jun 2026 21:20:32 -0400
Subject: [PATCH 1/6] refactor: extract @hyperframes/lint package from core

Moves all lint rules, hyperframeLinter, lintProject, and related types
from packages/core/src/lint/ into a new standalone packages/lint package.

Core keeps a thin re-export stub at @hyperframes/core/lint for backward
compatibility. Consumer imports (cli lint command, producer hyperframeLint)
are updated to import from @hyperframes/lint directly.

Depends on @hyperframes/parsers (PR #1755).
---
 .fallowrc.jsonc                               |   25 +-
 .github/workflows/publish.yml                 |    1 +
 bun.lock                                      |   28 +-
 package.json                                  |    2 +-
 packages/cli/package.json                     |    1 +
 packages/cli/src/commands/lint.ts             |    2 +-
 packages/cli/src/commands/preview.ts          |    3 +-
 packages/cli/src/commands/publish.ts          |    7 +-
 packages/cli/src/commands/render.ts           |    2 +-
 packages/cli/src/server/studioServer.ts       |    2 +-
 packages/cli/src/utils/lintProject.ts         |  576 +------
 packages/cli/tsup.config.ts                   |    1 +
 packages/core/package.json                    |    4 +-
 packages/core/src/index.ts                    |   10 +-
 packages/core/src/lint/index.ts               |    9 +-
 packages/core/src/slideshow/index.ts          |    1 +
 packages/lint/package.json                    |   56 +
 packages/lint/src/context.ts                  |   66 +
 packages/lint/src/hyperframeLinter.test.ts    |  124 ++
 packages/lint/src/hyperframeLinter.ts         |  155 ++
 packages/lint/src/index.ts                    |    9 +
 packages/lint/src/project.ts                  |  511 +++++++
 packages/lint/src/rules/adapters.test.ts      |  144 ++
 packages/lint/src/rules/adapters.ts           |   55 +
 packages/lint/src/rules/captions.test.ts      |  166 +++
 packages/lint/src/rules/captions.ts           |  271 ++++
 packages/lint/src/rules/composition.test.ts   | 1104 ++++++++++++++
 packages/lint/src/rules/composition.ts        |  723 +++++++++
 packages/lint/src/rules/core.test.ts          |  730 +++++++++
 packages/lint/src/rules/core.ts               |  475 ++++++
 packages/lint/src/rules/fonts.test.ts         |  285 ++++
 packages/lint/src/rules/fonts.ts              |  222 +++
 packages/lint/src/rules/gsap.test.ts          | 1318 +++++++++++++++++
 packages/lint/src/rules/gsap.ts               | 1142 ++++++++++++++
 packages/lint/src/rules/media.test.ts         |  251 ++++
 packages/lint/src/rules/media.ts              |  526 +++++++
 packages/lint/src/rules/slideshow.test.ts     |   73 +
 packages/lint/src/rules/slideshow.ts          |   85 ++
 packages/lint/src/rules/textures.test.ts      |  145 ++
 packages/lint/src/rules/textures.ts           |  226 +++
 packages/lint/src/types.ts                    |   40 +
 packages/lint/src/utils.ts                    |  300 ++++
 packages/lint/tsconfig.json                   |   18 +
 packages/lint/tsup.config.ts                  |   14 +
 packages/lint/vitest.config.ts                |    8 +
 packages/producer/package.json                |    1 +
 .../producer/src/services/hyperframeLint.ts   |    2 +-
 scripts/set-version.ts                        |    1 +
 48 files changed, 9311 insertions(+), 609 deletions(-)
 create mode 100644 packages/lint/package.json
 create mode 100644 packages/lint/src/context.ts
 create mode 100644 packages/lint/src/hyperframeLinter.test.ts
 create mode 100644 packages/lint/src/hyperframeLinter.ts
 create mode 100644 packages/lint/src/index.ts
 create mode 100644 packages/lint/src/project.ts
 create mode 100644 packages/lint/src/rules/adapters.test.ts
 create mode 100644 packages/lint/src/rules/adapters.ts
 create mode 100644 packages/lint/src/rules/captions.test.ts
 create mode 100644 packages/lint/src/rules/captions.ts
 create mode 100644 packages/lint/src/rules/composition.test.ts
 create mode 100644 packages/lint/src/rules/composition.ts
 create mode 100644 packages/lint/src/rules/core.test.ts
 create mode 100644 packages/lint/src/rules/core.ts
 create mode 100644 packages/lint/src/rules/fonts.test.ts
 create mode 100644 packages/lint/src/rules/fonts.ts
 create mode 100644 packages/lint/src/rules/gsap.test.ts
 create mode 100644 packages/lint/src/rules/gsap.ts
 create mode 100644 packages/lint/src/rules/media.test.ts
 create mode 100644 packages/lint/src/rules/media.ts
 create mode 100644 packages/lint/src/rules/slideshow.test.ts
 create mode 100644 packages/lint/src/rules/slideshow.ts
 create mode 100644 packages/lint/src/rules/textures.test.ts
 create mode 100644 packages/lint/src/rules/textures.ts
 create mode 100644 packages/lint/src/types.ts
 create mode 100644 packages/lint/src/utils.ts
 create mode 100644 packages/lint/tsconfig.json
 create mode 100644 packages/lint/tsup.config.ts
 create mode 100644 packages/lint/vitest.config.ts

diff --git a/.fallowrc.jsonc b/.fallowrc.jsonc
index d393d3acb2..22e9af259f 100644
--- a/.fallowrc.jsonc
+++ b/.fallowrc.jsonc
@@ -267,6 +267,18 @@
       "packages/parsers/src/gsapWriterParity.acorn.test.ts",
       "packages/parsers/src/htmlParser.roundtrip.test.ts",
       "packages/parsers/src/htmlParser.test.ts",
+      // @hyperframes/lint rule test files: parallel arrange/act/assert test cases
+      // (pre-existing structure from when lint lived in packages/core/src/lint/).
+      "packages/lint/src/rules/adapters.test.ts",
+      "packages/lint/src/rules/captions.test.ts",
+      "packages/lint/src/rules/composition.test.ts",
+      "packages/lint/src/rules/core.test.ts",
+      "packages/lint/src/rules/fonts.test.ts",
+      "packages/lint/src/rules/gsap.test.ts",
+      "packages/lint/src/rules/media.test.ts",
+      "packages/lint/src/rules/slideshow.test.ts",
+      "packages/lint/src/rules/textures.test.ts",
+      "packages/lint/src/hyperframeLinter.test.ts",
       // slideshowPanelHelpers.ts: setSlideNotes/addFragment/addHotspot share an
       // intentional parallel shape (signature + mapSlidesIn → exists-check →
       // map/append); the per-slide mutation differs, so a shared abstraction
@@ -311,6 +323,13 @@
       "packages/parsers/src/htmlParser.ts",
       // executeGsapMutation (CRITICAL) pre-dates this PR; studio-api still lives in core.
       "packages/core/src/studio-api/routes/files.ts",
+      // lint rule implementations and project linter: pre-existing complexity
+      // (moved from packages/core/src/lint/). File-level exemption avoids the
+      // line-shift fingerprint problem for inherited findings.
+      "packages/lint/src/rules/media.ts",
+      "packages/lint/src/rules/textures.ts",
+      "packages/lint/src/rules/gsap.ts",
+      "packages/lint/src/project.ts",
       // SlideshowPanel.tsx: top-level editor panel that wires several independent
       // sections (slides/inspector/branches/hotspot). Its cyclomatic count comes
       // from that fan-out; splitting it would scatter shared state without
@@ -329,7 +348,7 @@
       // generated table's shape test; this is dev tooling, not shipped runtime.
       "packages/cli/scripts/sync-agent-dirs.ts",
       // Files modified only for import-path updates (one-line changes to switch
-      // from @hyperframes/core/* subpaths to @hyperframes/parsers). Their complexity
+      // from @hyperframes/core/* subpaths to the new packages). Their complexity
       // is pre-existing; the line-shift fingerprint problem makes fallow treat
       // the violations as new even though no logic changed.
       "packages/core/src/core.types.ts",
@@ -338,6 +357,10 @@
       "packages/studio/src/hooks/gsapShared.ts",
       "packages/studio/src/hooks/gsapDragPositionCommit.ts",
       "packages/studio/src/hooks/gsapKeyframeCacheHelpers.ts",
+      "packages/cli/src/commands/lint.ts",
+      "packages/cli/src/commands/preview.ts",
+      "packages/cli/src/commands/publish.ts",
+      "packages/cli/src/server/studioServer.ts",
       // set-version.ts: compareSemver helper has pre-existing complexity from
       // semver string parsing logic; line-shift fingerprint problem from new
       // packages added to PACKAGES array makes fallow treat it as new.
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 42123e75f1..e12a14e47c 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -125,6 +125,7 @@ jobs:
           }
 
           publish_pkg "@hyperframes/parsers" "@hyperframes/parsers"
+          publish_pkg "@hyperframes/lint" "@hyperframes/lint"
           publish_pkg "@hyperframes/core" "@hyperframes/core"
           publish_pkg "@hyperframes/sdk" "@hyperframes/sdk"
           publish_pkg "@hyperframes/engine" "@hyperframes/engine"
diff --git a/bun.lock b/bun.lock
index 35c28338b2..3d83ce6005 100644
--- a/bun.lock
+++ b/bun.lock
@@ -82,6 +82,7 @@
         "@hyperframes/core": "workspace:*",
         "@hyperframes/engine": "workspace:*",
         "@hyperframes/gcp-cloud-run": "workspace:*",
+        "@hyperframes/lint": "workspace:*",
         "@hyperframes/producer": "workspace:*",
         "@hyperframes/studio": "workspace:*",
         "@types/adm-zip": "^0.5.7",
@@ -104,11 +105,11 @@
       "version": "0.7.13",
       "dependencies": {
         "@chenglou/pretext": "^0.0.5",
+        "@hyperframes/lint": "workspace:*",
         "@hyperframes/parsers": "workspace:*",
         "bpm-detective": "^2.0.5",
         "linkedom": "^0.18.12",
         "postcss": "^8.5.8",
-        "postcss-selector-parser": "^7.1.2",
       },
       "devDependencies": {
         "@types/jsdom": "^28.0.0",
@@ -167,6 +168,22 @@
         "typescript": "^5.7.2",
       },
     },
+    "packages/lint": {
+      "name": "@hyperframes/lint",
+      "version": "0.7.11",
+      "dependencies": {
+        "@hyperframes/core": "workspace:*",
+        "@hyperframes/parsers": "workspace:*",
+        "postcss": "^8.5.8",
+      },
+      "devDependencies": {
+        "@types/node": "^25.0.10",
+        "tsup": "^8.0.0",
+        "tsx": "^4.21.0",
+        "typescript": "^5.0.0",
+        "vitest": "^3.2.4",
+      },
+    },
     "packages/parsers": {
       "name": "@hyperframes/parsers",
       "version": "0.7.11",
@@ -220,6 +237,7 @@
         "@hono/node-server": "^1.13.0",
         "@hyperframes/core": "workspace:^",
         "@hyperframes/engine": "workspace:^",
+        "@hyperframes/lint": "workspace:^",
         "hono": "^4.6.0",
         "linkedom": "^0.18.12",
         "postcss": "^8.4.0",
@@ -685,6 +703,8 @@
 
     "@hyperframes/gcp-cloud-run": ["@hyperframes/gcp-cloud-run@workspace:packages/gcp-cloud-run"],
 
+    "@hyperframes/lint": ["@hyperframes/lint@workspace:packages/lint"],
+
     "@hyperframes/parsers": ["@hyperframes/parsers@workspace:packages/parsers"],
 
     "@hyperframes/player": ["@hyperframes/player@workspace:packages/player"],
@@ -1815,7 +1835,7 @@
 
     "postcss-nested": ["postcss-nested@6.2.0", "", { "dependencies": { "postcss-selector-parser": "^6.1.1" }, "peerDependencies": { "postcss": "^8.2.14" } }, "sha512-HQbt28KulC5AJzG+cZtj9kvKB93CFCdLvog1WFLf1D+xmMvPGlBstkpTEZfK5+AN9hfJocyBFCNiqyS48bpgzQ=="],
 
-    "postcss-selector-parser": ["postcss-selector-parser@7.1.4", "", { "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" } }, "sha512-HeP7D2wyhkR+XaK6v4W8oRF62Dsz4flyuczALJp61GckGm42u1saSSJ/0auvcBqxs3jMRFEcPK34At/0JBKdOg=="],
+    "postcss-selector-parser": ["postcss-selector-parser@6.1.2", "", { "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" } }, "sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg=="],
 
     "postcss-value-parser": ["postcss-value-parser@4.2.0", "", {}, "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ=="],
 
@@ -2213,8 +2233,6 @@
 
     "path-scurry/minipass": ["minipass@7.1.3", "", {}, "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A=="],
 
-    "postcss-nested/postcss-selector-parser": ["postcss-selector-parser@6.1.2", "", { "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" } }, "sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg=="],
-
     "proxy-agent/agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
 
     "proxy-agent/https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
@@ -2231,8 +2249,6 @@
 
     "tailwindcss/jiti": ["jiti@1.21.7", "", { "bin": { "jiti": "bin/jiti.js" } }, "sha512-/imKNG4EbWNrVjoNC/1H5/9GFy+tqjGBHCaSsN+P2RnPqjsLmv6UD3Ej+Kj8nBWaRAwyk7kK5ZUc+OEatnTR3A=="],
 
-    "tailwindcss/postcss-selector-parser": ["postcss-selector-parser@6.1.2", "", { "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" } }, "sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg=="],
-
     "tar/minipass": ["minipass@7.1.3", "", {}, "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A=="],
 
     "teeny-request/http-proxy-agent": ["http-proxy-agent@5.0.0", "", { "dependencies": { "@tootallnate/once": "2", "agent-base": "6", "debug": "4" } }, "sha512-n2hY8YdoRE1i7r6M0w9DIw5GgZN0G25P8zLCRQ8rjXtTU3vsNFBI/vWK/UIeE6g5MUUz6avwAPXmL6Fy9D/90w=="],
diff --git a/package.json b/package.json
index ac70315d6a..6751dd3a85 100644
--- a/package.json
+++ b/package.json
@@ -11,7 +11,7 @@
   "type": "module",
   "scripts": {
     "dev": "bun run studio",
-    "build": "bun run --filter @hyperframes/parsers build && bun run --filter @hyperframes/core build && bun run --filter '@hyperframes/{core,engine,producer,player,studio,shader-transitions,aws-lambda,gcp-cloud-run,sdk}' build && bun run --filter @hyperframes/cli build",
+    "build": "bun run --filter '@hyperframes/{parsers,lint}' build && bun run --filter @hyperframes/core build && bun run --filter '@hyperframes/{core,engine,producer,player,studio,shader-transitions,aws-lambda,gcp-cloud-run,sdk}' build && bun run --filter @hyperframes/cli build",
     "build:producer": "bun run --filter @hyperframes/producer build",
     "studio": "bun run --filter @hyperframes/studio dev",
     "build:hyperframes-runtime": "bun run --filter @hyperframes/core build:hyperframes-runtime",
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 11237086fa..5c8e474508 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -50,6 +50,7 @@
     "@hyperframes/core": "workspace:*",
     "@hyperframes/engine": "workspace:*",
     "@hyperframes/gcp-cloud-run": "workspace:*",
+    "@hyperframes/lint": "workspace:*",
     "@hyperframes/producer": "workspace:*",
     "@hyperframes/studio": "workspace:*",
     "@types/adm-zip": "^0.5.7",
diff --git a/packages/cli/src/commands/lint.ts b/packages/cli/src/commands/lint.ts
index 73b74555e6..e64a973e9a 100644
--- a/packages/cli/src/commands/lint.ts
+++ b/packages/cli/src/commands/lint.ts
@@ -38,7 +38,7 @@ export default defineCommand({
   async run({ args }) {
     try {
       const project = resolveProject(args.dir);
-      const lintResult = await lintProject(project);
+      const lintResult = await lintProject(project.dir);
 
       if (args.json) {
         const allFindings = lintResult.results.flatMap((r) => r.result.findings);
diff --git a/packages/cli/src/commands/preview.ts b/packages/cli/src/commands/preview.ts
index 80749a8a6e..8a26503cda 100644
--- a/packages/cli/src/commands/preview.ts
+++ b/packages/cli/src/commands/preview.ts
@@ -123,11 +123,10 @@ export default defineCommand({
     const isImplicitCwd = !rawArg || rawArg === "." || rawArg === "./";
     const project = resolveProject(rawArg);
     const dir = project.dir;
-    const indexPath = project.indexPath;
     const projectName = isImplicitCwd ? basename(process.env.PWD ?? dir) : project.name;
 
     // Lint before starting — surface issues for the agent to fix.
-    const lintResult = await lintProject({ dir, name: projectName, indexPath });
+    const lintResult = await lintProject(dir);
     if (lintResult.totalErrors > 0 || lintResult.totalWarnings > 0) {
       console.log();
       for (const line of formatLintFindings(lintResult)) console.log(line);
diff --git a/packages/cli/src/commands/publish.ts b/packages/cli/src/commands/publish.ts
index 182743fcc9..260eb082d5 100644
--- a/packages/cli/src/commands/publish.ts
+++ b/packages/cli/src/commands/publish.ts
@@ -1,4 +1,4 @@
-import { basename, resolve } from "node:path";
+import { resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { defineCommand } from "citty";
@@ -33,12 +33,9 @@ export default defineCommand({
   async run({ args }) {
     const rawArg = args.dir;
     const dir = resolve(rawArg ?? ".");
-    const isImplicitCwd = !rawArg || rawArg === "." || rawArg === "./";
-    const projectName = isImplicitCwd ? basename(process.env["PWD"] ?? dir) : basename(dir);
-
     const indexPath = join(dir, "index.html");
     if (existsSync(indexPath)) {
-      const lintResult = await lintProject({ dir, name: projectName, indexPath });
+      const lintResult = await lintProject(dir);
       if (lintResult.totalErrors > 0 || lintResult.totalWarnings > 0) {
         console.log();
         for (const line of formatLintFindings(lintResult)) console.log(line);
diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts
index 77660857dd..65f12f67d2 100644
--- a/packages/cli/src/commands/render.ts
+++ b/packages/cli/src/commands/render.ts
@@ -738,7 +738,7 @@ export default defineCommand({
 
     // ── Pre-render lint ──────────────────────────────────────────────────
     {
-      const lintResult = await lintProject(project);
+      const lintResult = await lintProject(project.dir);
       if (!quiet && (lintResult.totalErrors > 0 || lintResult.totalWarnings > 0)) {
         console.log("");
         for (const line of formatLintFindings(lintResult, { errorsFirst: true })) console.log(line);
diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.ts
index f25228b562..3b284cee72 100644
--- a/packages/cli/src/server/studioServer.ts
+++ b/packages/cli/src/server/studioServer.ts
@@ -339,7 +339,7 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
     },
 
     async lint(html: string, opts?: { filePath?: string }) {
-      const { lintHyperframeHtml } = await import("@hyperframes/core/lint");
+      const { lintHyperframeHtml } = await import("@hyperframes/lint");
       return await lintHyperframeHtml(html, opts);
     },
 
diff --git a/packages/cli/src/utils/lintProject.ts b/packages/cli/src/utils/lintProject.ts
index 8558c852bf..f63ce12608 100644
--- a/packages/cli/src/utils/lintProject.ts
+++ b/packages/cli/src/utils/lintProject.ts
@@ -1,573 +1,3 @@
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { dirname, extname, isAbsolute, join, posix, relative, resolve } from "node:path";
-import { lintHyperframeHtml, type HyperframeLintResult } from "@hyperframes/core/lint";
-import type { HyperframeLintFinding } from "@hyperframes/core/lint";
-import { decodeUrlPathVariants, 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;
-}
-
-interface CssSource {
-  content: string;
-  /** Root-relative path to the CSS file. Undefined means inline HTML CSS. */
-  rootRelativePath?: string;
-}
-
-export interface ProjectLintResult {
-  results: Array<{ file: string; result: HyperframeLintResult }>;
-  totalErrors: number;
-  totalWarnings: number;
-  totalInfos: number;
-}
-
-const AUDIO_EXTENSIONS = new Set([".mp3", ".wav", ".aac", ".ogg", ".m4a", ".flac", ".opus"]);
-const STYLE_BLOCK_RE = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
-const OPEN_TAG_RE = /<([a-z][\w:-]*)(\s[^<>]*?)?>/gi;
-const MASK_IMAGE_URL_RE =
-  /\b(?:-webkit-)?mask-image\s*:\s*[^;{}]*url\(\s*(?:"([^"]+)"|'([^']+)'|([^"')\s]+))\s*\)/gi;
-
-function readHtmlAttr(tag: string, name: string): string | null {
-  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const match = tag.match(new RegExp(`\\b${escaped}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, "i"));
-  return match?.[1] ?? match?.[2] ?? null;
-}
-
-function isLocalStylesheetHref(href: string): boolean {
-  return !!href && !/^(https?:|data:|blob:|\/\/)/i.test(href);
-}
-
-function collectExternalStyles(
-  projectDir: string,
-  html: string,
-  compSrcPath?: string,
-): Array<{ href: string; content: string }> {
-  const styles: Array<{ href: string; content: string }> = [];
-  const linkRe = /<link\b[^>]*>/gi;
-  let match: RegExpExecArray | null;
-  while ((match = linkRe.exec(html)) !== null) {
-    const tag = match[0];
-    const rel = tag.match(/\brel\s*=\s*["']([^"']+)["']/i)?.[1] ?? "";
-    if (!rel.split(/\s+/).some((part) => part.toLowerCase() === "stylesheet")) continue;
-    const href = tag.match(/\bhref\s*=\s*["']([^"']+)["']/i)?.[1] ?? "";
-    if (!isLocalStylesheetHref(href)) continue;
-    const rootRelative = compSrcPath ? join(dirname(compSrcPath), href) : href;
-    const stylesheet = resolveExistingLocalAsset(projectDir, rootRelative);
-    if (!stylesheet) continue;
-    styles.push({ href, content: readFileSync(stylesheet.resolved, "utf-8") });
-  }
-  return styles;
-}
-
-function collectCssSources(projectDir: string, html: string, compSrcPath?: string): CssSource[] {
-  const sources: CssSource[] = [];
-
-  let styleMatch: RegExpExecArray | null;
-  const stylePattern = new RegExp(STYLE_BLOCK_RE.source, STYLE_BLOCK_RE.flags);
-  while ((styleMatch = stylePattern.exec(html)) !== null) {
-    sources.push({ content: styleMatch[1] ?? "" });
-  }
-
-  const linkRe = /<link\b[^>]*>/gi;
-  let linkMatch: RegExpExecArray | null;
-  while ((linkMatch = linkRe.exec(html)) !== null) {
-    const tag = linkMatch[0];
-    const rel = readHtmlAttr(tag, "rel") ?? "";
-    if (!rel.split(/\s+/).some((part) => part.toLowerCase() === "stylesheet")) continue;
-    const href = readHtmlAttr(tag, "href") ?? "";
-    if (!isLocalStylesheetHref(href)) continue;
-
-    const rootRelativePath = compSrcPath ? join(dirname(compSrcPath), href) : href;
-    const stylesheet = resolveExistingLocalAsset(projectDir, rootRelativePath);
-    if (!stylesheet) continue;
-    sources.push({
-      content: readFileSync(stylesheet.resolved, "utf-8"),
-      rootRelativePath: stylesheet.rootRelativePath,
-    });
-  }
-
-  let tagMatch: RegExpExecArray | null;
-  const tagPattern = new RegExp(OPEN_TAG_RE.source, OPEN_TAG_RE.flags);
-  while ((tagMatch = tagPattern.exec(html)) !== null) {
-    const tag = tagMatch[0];
-    const style = readHtmlAttr(tag, "style");
-    if (!style) continue;
-    sources.push({ content: style });
-  }
-
-  return sources;
-}
-
-function isRemoteOrInlineUrl(url: string): boolean {
-  return /^(https?:|data:|blob:|\/\/|#)/i.test(url);
-}
-
-function cleanAssetUrl(url: string): string {
-  return url.trim().split(/[?#]/, 1)[0] ?? "";
-}
-
-function isWithinProjectRoot(projectDir: string, candidate: string): boolean {
-  const projectRoot = resolve(projectDir);
-  const relativePath = relative(projectRoot, candidate);
-  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
-}
-
-function addCandidate(candidates: string[], candidate: string): void {
-  if (!candidates.includes(candidate)) candidates.push(candidate);
-}
-
-function resolveLocalAssetCandidates(projectDir: string, url: string): string[] {
-  const cleanUrl = cleanAssetUrl(url);
-  const projectRoot = resolve(projectDir);
-  const candidates: string[] = [];
-
-  for (const variant of decodeUrlPathVariants(cleanUrl)) {
-    const projectRelative = variant.startsWith("/") ? variant.slice(1) : variant;
-    const resolved = resolve(projectRoot, projectRelative);
-    if (isWithinProjectRoot(projectRoot, resolved)) {
-      addCandidate(candidates, resolved);
-      continue;
-    }
-
-    const normalized = posix.normalize(projectRelative.replace(/\\/g, "/"));
-    const clamped = normalized.replace(/^(\.\.\/)+/, "");
-    if (clamped && !clamped.startsWith("..")) {
-      addCandidate(candidates, resolve(projectRoot, clamped));
-    }
-  }
-
-  return candidates;
-}
-
-function resolveExistingLocalAsset(
-  projectDir: string,
-  url: string,
-): { resolved: string; rootRelativePath: string } | null {
-  const projectRoot = resolve(projectDir);
-  const resolved = resolveLocalAssetCandidates(projectRoot, url).find(existsSync);
-  if (!resolved) return null;
-  return { resolved, rootRelativePath: relative(projectRoot, resolved) };
-}
-
-function resolveCssAssetCandidates(
-  projectDir: string,
-  url: string,
-  htmlCompSrcPath?: string,
-  cssRootRelativePath?: string,
-): string[] {
-  if (url.startsWith("/")) return resolveLocalAssetCandidates(projectDir, url);
-  if (cssRootRelativePath) {
-    return resolveLocalAssetCandidates(projectDir, join(dirname(cssRootRelativePath), url));
-  }
-  if (htmlCompSrcPath) {
-    return resolveLocalAssetCandidates(projectDir, rewriteAssetPath(htmlCompSrcPath, url));
-  }
-  return resolveLocalAssetCandidates(projectDir, url);
-}
-
-/**
- * Lint the root index.html and all sub-compositions in the compositions/ directory.
- * Returns aggregated results across all files.
- */
-export async function lintProject(project: ProjectDir): Promise<ProjectLintResult> {
-  const results: Array<{ file: string; result: HyperframeLintResult }> = [];
-  let totalErrors = 0;
-  let totalWarnings = 0;
-  let totalInfos = 0;
-
-  // Lint root composition
-  const rootHtml = readFileSync(project.indexPath, "utf-8");
-  const rootResult = await lintHyperframeHtml(rootHtml, {
-    filePath: project.indexPath,
-    externalStyles: collectExternalStyles(project.dir, rootHtml),
-  });
-  results.push({ file: "index.html", result: rootResult });
-  totalErrors += rootResult.errorCount;
-  totalWarnings += rootResult.warningCount;
-  totalInfos += rootResult.infoCount;
-
-  // Lint sub-compositions in compositions/ directory, collecting HTML for project-level checks
-  const allHtmlSources: HtmlSource[] = [{ html: rootHtml }];
-  const compositionsDir = resolve(project.dir, "compositions");
-  if (existsSync(compositionsDir)) {
-    // Recurse: per-frame compositions live in nested dirs (e.g. compositions/frames/*.html).
-    // A non-recursive readdir silently skipped them, so sub-composition rules never ran on
-    // the frames that make up the video. Walk the whole tree; keep posix-style src paths.
-    const collectHtmlFiles = (dir: string, rel: string): string[] => {
-      const out: string[] = [];
-      for (const entry of readdirSync(dir, { withFileTypes: true })) {
-        const relPath = rel ? `${rel}/${entry.name}` : entry.name;
-        if (entry.isDirectory()) out.push(...collectHtmlFiles(join(dir, entry.name), relPath));
-        else if (entry.isFile() && entry.name.endsWith(".html")) out.push(relPath);
-      }
-      return out;
-    };
-    const files = collectHtmlFiles(compositionsDir, "").sort();
-    for (const file of files) {
-      const filePath = join(compositionsDir, file);
-      const html = readFileSync(filePath, "utf-8");
-      const compSrcPath = `compositions/${file}`;
-      allHtmlSources.push({ html, compSrcPath });
-      const result = await lintHyperframeHtml(html, {
-        filePath,
-        isSubComposition: true,
-        externalStyles: collectExternalStyles(project.dir, html, compSrcPath),
-      });
-      results.push({ file: `compositions/${file}`, result });
-      totalErrors += result.errorCount;
-      totalWarnings += result.warningCount;
-      totalInfos += result.infoCount;
-    }
-  }
-
-  // ── Project-level checks ──────────────────────────────────────────────
-
-  const projectFindings = [
-    ...lintProjectAudioFiles(project.dir, allHtmlSources),
-    ...lintAudioSrcNotFound(project.dir, allHtmlSources),
-    ...lintMissingLocalAsset(project.dir, allHtmlSources),
-    ...lintTextureMaskAssetNotFound(project.dir, allHtmlSources),
-    ...lintMultipleRootCompositions(project.dir),
-    ...lintDuplicateAudioTracks(allHtmlSources),
-  ];
-  if (projectFindings.length > 0) {
-    // Append project-level findings to the root index.html result
-    for (const finding of projectFindings) {
-      rootResult.findings.push(finding);
-      if (finding.severity === "error") {
-        rootResult.errorCount++;
-        rootResult.ok = false;
-        totalErrors++;
-      } else if (finding.severity === "warning") {
-        rootResult.warningCount++;
-        totalWarnings++;
-      } else {
-        rootResult.infoCount++;
-        totalInfos++;
-      }
-    }
-  }
-
-  return { results, totalErrors, totalWarnings, totalInfos };
-}
-
-/**
- * Check for audio files in the project directory that have no corresponding
- * <audio> element in any composition HTML. This catches the common mistake of
- * placing an audio file in the project but forgetting the <audio> tag, which
- * results in a silent render.
- */
-function lintProjectAudioFiles(
-  projectDir: string,
-  htmlSources: HtmlSource[],
-): HyperframeLintFinding[] {
-  const findings: HyperframeLintFinding[] = [];
-
-  // Scan project root for audio files (non-recursive — only top-level)
-  let audioFiles: string[];
-  try {
-    audioFiles = readdirSync(projectDir).filter((f) =>
-      AUDIO_EXTENSIONS.has(extname(f).toLowerCase()),
-    );
-  } catch {
-    return findings;
-  }
-
-  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));
-
-  if (!hasAudioElement) {
-    findings.push({
-      code: "audio_file_without_element",
-      severity: "warning",
-      message: `Found audio file(s) in project (${audioFiles.join(", ")}) but no <audio> element in any composition. The rendered video will be silent.`,
-      fixHint:
-        'Add an <audio id="my-audio" src="' +
-        audioFiles[0] +
-        '" data-start="0" data-duration="__DURATION__" data-track-index="0" data-volume="1"></audio> element inside the composition root. Replace __DURATION__ with the audio length in seconds.',
-    });
-  }
-
-  return findings;
-}
-
-/**
- * Check for <audio> elements whose src points to a file that doesn't exist
- * 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: HtmlSource[],
-): HyperframeLintFinding[] {
-  const findings: HyperframeLintFinding[] = [];
-
-  const audioSrcRe = /<audio\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi;
-
-  const missingSrcs: string[] = [];
-  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
-      // 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;
-      if (!resolveLocalAssetCandidates(projectDir, rootRelative).some(existsSync)) {
-        missingSrcs.push(src);
-      }
-    }
-  }
-
-  if (missingSrcs.length > 0) {
-    const unique = [...new Set(missingSrcs)];
-    findings.push({
-      code: "audio_src_not_found",
-      severity: "error",
-      message: `<audio> element references file(s) not found in the project: ${unique.join(", ")}. The rendered video will be silent.`,
-      fixHint:
-        unique.length === 1
-          ? `Add the file "${unique[0]}" to the project directory, or update the src attribute to point to an existing file.`
-          : `Add the missing files to the project directory, or update the src attributes to point to existing files.`,
-    });
-  }
-
-  return findings;
-}
-
-// Same-length whitespace preserves offsets.
-function maskRange(src: string, pattern: RegExp): string {
-  return src.replace(pattern, (m) => " ".repeat(m.length));
-}
-
-// Closing tags allow junk before `>` (`</script foo>` is valid HTML); use `[^>]*` to mask permissively.
-function maskNonScannableRanges(html: string): string {
-  let out = maskRange(html, /<!--[\s\S]*?-->/g);
-  out = maskRange(out, /<style\b[^>]*>[\s\S]*?<\/style\b[^>]*>/gi);
-  out = maskRange(out, /<script\b[^>]*>[\s\S]*?<\/script\b[^>]*>/gi);
-  return out;
-}
-
-// <audio> is handled by lintAudioSrcNotFound — its "silent video" message is tailored.
-// fallow-ignore-next-line complexity
-function lintMissingLocalAsset(
-  projectDir: string,
-  htmlSources: HtmlSource[],
-): HyperframeLintFinding[] {
-  const findings: HyperframeLintFinding[] = [];
-
-  const localAssetSrcRe = /<(video|img|source)\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi;
-
-  // Dedup by resolved path: same missing file from root + sub-comp → ONE finding.
-  const missingByTag = new Map<string, Map<string, string>>();
-
-  for (const { html, compSrcPath } of htmlSources) {
-    const scannable = maskNonScannableRanges(html);
-    const re = new RegExp(localAssetSrcRe.source, localAssetSrcRe.flags);
-    let match: RegExpExecArray | null;
-    while ((match = re.exec(scannable)) !== null) {
-      const tagName = (match[1] ?? "").toLowerCase();
-      const rawSrc = match[2] ?? "";
-      const src = cleanAssetUrl(rawSrc);
-      if (!src) continue;
-      if (isRemoteOrInlineUrl(src)) continue;
-      if (/^__[A-Z_]+__$/.test(src)) continue; // template placeholder
-      const rootRelative = compSrcPath ? rewriteAssetPath(compSrcPath, src) : src;
-      // resolveExistingLocalAsset matches the bundler's notion of "resolves" (handles root-absolute, rejects escapes).
-      const resolvedAsset = resolveExistingLocalAsset(projectDir, rootRelative);
-      if (resolvedAsset) continue;
-
-      const resolvedKey = resolve(projectDir, rootRelative);
-      let bucket = missingByTag.get(tagName);
-      if (!bucket) {
-        bucket = new Map<string, string>();
-        missingByTag.set(tagName, bucket);
-      }
-      if (!bucket.has(resolvedKey)) bucket.set(resolvedKey, src);
-    }
-  }
-
-  for (const [tagName, byResolved] of missingByTag) {
-    const unique = [...byResolved.values()];
-    findings.push({
-      code: "missing_local_asset",
-      severity: "error",
-      message:
-        `<${tagName}> element references local file(s) not found in the project: ${unique.join(", ")}. ` +
-        "The renderer will silently skip these and produce a video with missing visuals.",
-      fixHint:
-        unique.length === 1
-          ? `Add "${unique[0]}" to the project directory, or update the src attribute to point to an existing file. ` +
-            "Common cause: captured asset filenames are unreliable (heygen-logo.svg often contains Google, nvidia-logo.svg may contain Autodesk, etc.). " +
-            "Open the contact sheets and verify the file actually exists at this path before referencing it."
-          : "Add the missing files to the project directory, or update the src attributes to point to existing files. " +
-            "Captured asset filenames are unreliable — verify against capture/contact-sheets/ and capture/extracted/asset-descriptions.md.",
-    });
-  }
-
-  return findings;
-}
-
-function lintTextureMaskAssetNotFound(
-  projectDir: string,
-  htmlSources: HtmlSource[],
-): HyperframeLintFinding[] {
-  const missing = new Map<string, string>();
-
-  for (const { html, compSrcPath } of htmlSources) {
-    for (const cssSource of collectCssSources(projectDir, html, compSrcPath)) {
-      let match: RegExpExecArray | null;
-      const pattern = new RegExp(MASK_IMAGE_URL_RE.source, MASK_IMAGE_URL_RE.flags);
-      while ((match = pattern.exec(cssSource.content)) !== null) {
-        const rawUrl = match[1] ?? match[2] ?? match[3] ?? "";
-        const url = cleanAssetUrl(rawUrl);
-        if (!url || isRemoteOrInlineUrl(url)) continue;
-        if (/^__[A-Z_]+__$/.test(url)) continue;
-
-        const candidates = resolveCssAssetCandidates(
-          projectDir,
-          url,
-          compSrcPath,
-          cssSource.rootRelativePath,
-        );
-        if (candidates.some(existsSync)) continue;
-        missing.set(url, candidates[0] ?? resolve(projectDir, url));
-      }
-    }
-  }
-
-  if (missing.size === 0) return [];
-  const urls = [...missing.keys()];
-  return [
-    {
-      code: "texture_mask_asset_not_found",
-      severity: "error",
-      message: `CSS mask-image references file(s) not found in the project: ${urls.join(", ")}.`,
-      fixHint:
-        urls.length === 1
-          ? `Add "${urls[0]}" to the project, or update the mask-image URL to point to an existing texture mask.`
-          : "Add the missing texture mask files to the project, or update the mask-image URLs to point to existing files.",
-    },
-  ];
-}
-
-/**
- * Error if multiple root-level HTML files with data-composition-id exist.
- * Scans the project directory filesystem (not just what lintProject chose to read)
- * to catch stray scaffold files, duplicates, or backup copies.
- */
-function lintMultipleRootCompositions(projectDir: string): HyperframeLintFinding[] {
-  const findings: HyperframeLintFinding[] = [];
-  try {
-    const rootHtmlFiles = readdirSync(projectDir).filter((f) => f.endsWith(".html"));
-    const rootCompositions: string[] = [];
-    for (const file of rootHtmlFiles) {
-      if (file === "caption-skin.html") continue;
-      const content = readFileSync(join(projectDir, file), "utf-8");
-      if (/data-composition-id/i.test(content)) {
-        rootCompositions.push(file);
-      }
-    }
-    if (rootCompositions.length > 1) {
-      findings.push({
-        code: "multiple_root_compositions",
-        severity: "error",
-        message: `Multiple root-level HTML files with data-composition-id: ${rootCompositions.join(", ")}. The runtime may discover both as entry points, causing duplicate audio playback.`,
-        fixHint:
-          "A project should have exactly one root index.html with data-composition-id. Remove or rename extra files.",
-      });
-    }
-  } catch {
-    /* directory read failed — skip */
-  }
-  return findings;
-}
-
-/**
- * Warn if multiple <audio> elements on the same data-track-index overlap in time.
- * 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: HtmlSource[]): HyperframeLintFinding[] {
-  const findings: HyperframeLintFinding[] = [];
-  function extractAttr(tag: string, name: string): string | null {
-    const re = new RegExp(`\\b${name}\\s*=\\s*["']([^"']+)["']`, "i");
-    const m = tag.match(re);
-    return m?.[1] ?? null;
-  }
-
-  const tracks: Array<{ trackIndex: number; start: number; end: number; src: string }> = [];
-  const seen = new Set<string>();
-
-  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;
-    let match: RegExpExecArray | null;
-    while ((match = audioTagRe.exec(html)) !== null) {
-      const tag = match[0];
-      const trackStr = extractAttr(tag, "data-track-index");
-      const startStr = extractAttr(tag, "data-start");
-      const durStr = extractAttr(tag, "data-duration");
-      const src = extractAttr(tag, "src") ?? "unknown";
-      if (!trackStr || !startStr) continue;
-
-      const trackIndex = parseInt(trackStr, 10);
-      const start = parseFloat(startStr);
-      // Runtime falls back to Infinity when data-duration is absent (plays full track).
-      // Mirror that here so audio without explicit duration still participates in overlap checks.
-      const duration = durStr ? parseFloat(durStr) : Infinity;
-      // Deduplicate: same audio reached from multiple HTML sources
-      const key = `${src}:${start}:${duration}:${trackIndex}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-
-      tracks.push({ trackIndex, start, end: start + duration, src });
-    }
-  }
-
-  for (let i = 0; i < tracks.length; i++) {
-    for (let j = i + 1; j < tracks.length; j++) {
-      const a = tracks[i]!;
-      const b = tracks[j]!;
-      if (a.trackIndex !== b.trackIndex) continue;
-      if (a.start < b.end && b.start < a.end) {
-        findings.push({
-          code: "duplicate_audio_track",
-          severity: "warning",
-          message: `Multiple <audio> elements on track ${a.trackIndex} overlap (${a.src} at ${a.start}-${Number.isFinite(a.end) ? a.end.toFixed(1) : "end"}s, ${b.src} at ${b.start}-${Number.isFinite(b.end) ? b.end.toFixed(1) : "end"}s). This causes layered audio playback.`,
-          fixHint: "Use non-overlapping time windows or different track indices.",
-        });
-      }
-    }
-  }
-  return findings;
-}
-
-/**
- * Determine whether a render should be blocked based on lint results and strict mode.
- * --strict blocks on errors; --strict-all blocks on errors or warnings.
- */
-export function shouldBlockRender(
-  strictErrors: boolean,
-  strictAll: boolean,
-  totalErrors: number,
-  totalWarnings: number,
-): boolean {
-  return (strictErrors && totalErrors > 0) || (strictAll && (totalErrors > 0 || totalWarnings > 0));
-}
+// ponytail: thin re-export — lintProject lives in @hyperframes/lint so it's usable without the CLI
+export { lintProject, shouldBlockRender } from "@hyperframes/lint";
+export type { ProjectLintResult } from "@hyperframes/lint";
diff --git a/packages/cli/tsup.config.ts b/packages/cli/tsup.config.ts
index faa734199d..b34f45d030 100644
--- a/packages/cli/tsup.config.ts
+++ b/packages/cli/tsup.config.ts
@@ -62,6 +62,7 @@ var __dirname = __hf_dirname(__filename);`,
   noExternal: [
     "@hyperframes/core",
     "@hyperframes/parsers",
+    "@hyperframes/lint",
     "@hyperframes/producer",
     "@hyperframes/engine",
     "@clack/prompts",
diff --git a/packages/core/package.json b/packages/core/package.json
index b188ebabd7..41f7f30d63 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -353,11 +353,11 @@
   },
   "dependencies": {
     "@chenglou/pretext": "^0.0.5",
+    "@hyperframes/lint": "workspace:*",
     "@hyperframes/parsers": "workspace:*",
     "bpm-detective": "^2.0.5",
     "linkedom": "^0.18.12",
-    "postcss": "^8.5.8",
-    "postcss-selector-parser": "^7.1.2"
+    "postcss": "^8.5.8"
   },
   "devDependencies": {
     "@types/jsdom": "^28.0.0",
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 52da038494..e71b76f8bb 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -138,18 +138,12 @@ export {
   MEDIA_DURATION_CLAMP_EPSILON_SECONDS,
 } from "./compiler/timingCompiler";
 
-// Lint
-export type {
-  HyperframeLintSeverity,
-  HyperframeLintFinding,
-  HyperframeLintResult,
-  HyperframeLinterOptions,
-} from "./lint/types";
-export { lintHyperframeHtml } from "./lint/hyperframeLinter";
+// Lint — import from @hyperframes/lint directly
 export {
   rewriteAssetPaths,
   rewriteAssetPath,
   rewriteCssAssetUrls,
+  rewriteInlineStyleAssetUrls,
 } from "./compiler/rewriteSubCompPaths";
 export { CSS_URL_RE, isNonRelativeUrl, isPathInside } from "./compiler/assetPaths";
 export { queryByAttr } from "./utils/cssSelector";
diff --git a/packages/core/src/lint/index.ts b/packages/core/src/lint/index.ts
index 4d0c0eb4ae..209e7cd5a9 100644
--- a/packages/core/src/lint/index.ts
+++ b/packages/core/src/lint/index.ts
@@ -1,7 +1,2 @@
-export type {
-  HyperframeLintSeverity,
-  HyperframeLintFinding,
-  HyperframeLintResult,
-  HyperframeLinterOptions,
-} from "./types";
-export { lintHyperframeHtml, lintMediaUrls } from "./hyperframeLinter";
+/** @deprecated Import from @hyperframes/lint */
+export * from "@hyperframes/lint";
diff --git a/packages/core/src/slideshow/index.ts b/packages/core/src/slideshow/index.ts
index 084a555bf3..4612820a55 100644
--- a/packages/core/src/slideshow/index.ts
+++ b/packages/core/src/slideshow/index.ts
@@ -1,2 +1,3 @@
 export * from "./slideshow.types";
 export * from "./parseSlideshow";
+export { isSceneLikeCompositionId } from "./sceneId";
diff --git a/packages/lint/package.json b/packages/lint/package.json
new file mode 100644
index 0000000000..8b098ac6ea
--- /dev/null
+++ b/packages/lint/package.json
@@ -0,0 +1,56 @@
+{
+  "name": "@hyperframes/lint",
+  "version": "0.7.11",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heygen-com/hyperframes",
+    "directory": "packages/lint"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "node": "./dist/index.js",
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "import": "./dist/index.js",
+        "types": "./dist/index.d.ts"
+      },
+      "./package.json": "./package.json"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "echo skip"
+  },
+  "dependencies": {
+    "@hyperframes/core": "workspace:*",
+    "@hyperframes/parsers": "workspace:*",
+    "postcss": "^8.5.8"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.2.4"
+  }
+}
diff --git a/packages/lint/src/context.ts b/packages/lint/src/context.ts
new file mode 100644
index 0000000000..7ee0d75164
--- /dev/null
+++ b/packages/lint/src/context.ts
@@ -0,0 +1,66 @@
+import type { HyperframeLintFinding, HyperframeLinterOptions } from "./types";
+import {
+  extractBlocks,
+  extractOpenTags,
+  findRootTag,
+  collectCompositionIds,
+  readAttr,
+  stripHtmlComments,
+  STYLE_BLOCK_PATTERN,
+  SCRIPT_BLOCK_PATTERN,
+} from "./utils";
+import type { OpenTag, ExtractedBlock } from "./utils";
+
+export type { OpenTag, ExtractedBlock };
+
+export type LintContext = {
+  source: string;
+  rawSource: string;
+  tags: OpenTag[];
+  styles: ExtractedBlock[];
+  scripts: ExtractedBlock[];
+  compositionIds: Set<string>;
+  rootTag: OpenTag | null;
+  rootCompositionId: string | null;
+  options: HyperframeLinterOptions;
+};
+
+// Re-export for convenience so rule modules only need one import for the finding type
+export type { HyperframeLintFinding };
+
+export function buildLintContext(html: string, options: HyperframeLinterOptions = {}): LintContext {
+  const rawSource = html || "";
+  // Strip HTML comments before scanning so a commented-out <template> or tag can't
+  // hijack the boundary match below. Linear + fixpoint (see stripHtmlComments) to
+  // stay ReDoS-free and catch markers that re-form when a comment is removed.
+  let source = stripHtmlComments(rawSource);
+  const templateMatch = source.match(/<template[^>]*>([\s\S]*)<\/template>/i);
+  if (templateMatch?.[1]) source = templateMatch[1];
+
+  const tags = extractOpenTags(source);
+  const styles = [
+    ...extractBlocks(source, STYLE_BLOCK_PATTERN),
+    ...(options.externalStyles ?? []).map((style) => ({
+      attrs: `href="${style.href}"`,
+      content: style.content,
+      raw: style.content,
+      index: -1,
+    })),
+  ];
+  const scripts = extractBlocks(source, SCRIPT_BLOCK_PATTERN);
+  const compositionIds = collectCompositionIds(tags);
+  const rootTag = findRootTag(source);
+  const rootCompositionId = readAttr(rootTag?.raw || "", "data-composition-id");
+
+  return {
+    source,
+    rawSource,
+    tags,
+    styles,
+    scripts,
+    compositionIds,
+    rootTag,
+    rootCompositionId,
+    options,
+  };
+}
diff --git a/packages/lint/src/hyperframeLinter.test.ts b/packages/lint/src/hyperframeLinter.test.ts
new file mode 100644
index 0000000000..8590bc41c5
--- /dev/null
+++ b/packages/lint/src/hyperframeLinter.test.ts
@@ -0,0 +1,124 @@
+import { describe, it, expect } from "vitest";
+import { lintHyperframeHtml } from "./hyperframeLinter.js";
+
+describe("lintHyperframeHtml — orchestrator", () => {
+  const validComposition = `
+<html>
+<body>
+  <div id="root" data-composition-id="comp-1" data-width="1920" data-height="1080" data-start="0">
+    <div id="stage"></div>
+  </div>
+  <script src="https://cdn.gsap.com/gsap.min.js"></script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#stage", { opacity: 1, duration: 1 }, 0);
+    window.__timelines["comp-1"] = tl;
+  </script>
+</body>
+</html>`;
+
+  it("reports no errors for a valid composition", async () => {
+    const result = await lintHyperframeHtml(validComposition);
+    expect(result.ok).toBe(true);
+    expect(result.errorCount).toBe(0);
+  });
+
+  it("attaches filePath to findings when option is set", async () => {
+    const html = "<html><body><div></div></body></html>";
+    const result = await lintHyperframeHtml(html, { filePath: "test.html" });
+    for (const finding of result.findings) {
+      expect(finding.file).toBe("test.html");
+    }
+  });
+
+  it("deduplicates identical findings", async () => {
+    const html = `
+<html><body>
+  <div id="root"></div>
+  <script>const tl = gsap.timeline();</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const codes = result.findings.map((f) => `${f.code}|${f.message}`);
+    const uniqueCodes = [...new Set(codes)];
+    expect(codes.length).toBe(uniqueCodes.length);
+  });
+
+  it("strips <template> wrapper before linting composition files", async () => {
+    const html = `<template id="my-comp-template">
+  <div data-composition-id="my-comp" data-width="1920" data-height="1080"
+       style="position:relative;width:1920px;height:1080px;">
+    <div id="stage"></div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#stage", { opacity: 1, duration: 1 }, 0);
+    window.__timelines["my-comp"] = tl;
+  </script>
+</template>`;
+    const result = await lintHyperframeHtml(html, { filePath: "compositions/my-comp.html" });
+    const missing = result.findings.filter(
+      (f) => f.code === "missing-composition-id" || f.code === "missing-dimensions",
+    );
+    expect(missing).toHaveLength(0);
+  });
+
+  it("ignores comments that mention template tags before the real template", async () => {
+    const html = `<!doctype html>
+<html>
+  <head>
+    <!-- Authoring note: styles and scripts live inside <template>. -->
+  </head>
+  <body>
+    <template id="my-comp-template">
+      <style>#root { width: 1920px; height: 1080px; }</style>
+      <div data-composition-id="my-comp" data-width="1920" data-height="1080">
+        <div id="stage"></div>
+      </div>
+      <script>
+        window.__timelines = window.__timelines || {};
+        const tl = gsap.timeline({ paused: true });
+        tl.to("#stage", { opacity: 1, duration: 1 }, 0);
+        window.__timelines["my-comp"] = tl;
+      </script>
+    </template>
+  </body>
+</html>`;
+    const result = await lintHyperframeHtml(html, { filePath: "compositions/my-comp.html" });
+    const rootFindings = result.findings.filter(
+      (f) => f.code === "root_missing_composition_id" || f.code === "root_missing_dimensions",
+    );
+    expect(rootFindings).toHaveLength(0);
+  });
+
+  it("strips comments whose markers re-form after one pass (no decoy template survives)", async () => {
+    // Adjacent comment markers: removing the inner `<!-- -->` in a single pass
+    // re-joins `<` + `!-- … -->` into a fresh, complete `<!-- … -->` that a lone
+    // global replace leaves behind — surfacing a decoy <template> with no
+    // composition-id. A fixpoint strip removes it; this guards that behavior.
+    const html = `<!doctype html>
+<html>
+  <body>
+    <<!-- -->!-- <template id="decoy-template"></template> -->
+    <template id="my-comp-template">
+      <style>#root { width: 1920px; height: 1080px; }</style>
+      <div data-composition-id="my-comp" data-width="1920" data-height="1080">
+        <div id="stage"></div>
+      </div>
+      <script>
+        window.__timelines = window.__timelines || {};
+        const tl = gsap.timeline({ paused: true });
+        tl.to("#stage", { opacity: 1, duration: 1 }, 0);
+        window.__timelines["my-comp"] = tl;
+      </script>
+    </template>
+  </body>
+</html>`;
+    const result = await lintHyperframeHtml(html, { filePath: "compositions/my-comp.html" });
+    const rootFindings = result.findings.filter(
+      (f) => f.code === "root_missing_composition_id" || f.code === "root_missing_dimensions",
+    );
+    expect(rootFindings).toHaveLength(0);
+  });
+});
diff --git a/packages/lint/src/hyperframeLinter.ts b/packages/lint/src/hyperframeLinter.ts
new file mode 100644
index 0000000000..1dc88067c6
--- /dev/null
+++ b/packages/lint/src/hyperframeLinter.ts
@@ -0,0 +1,155 @@
+import type { HyperframeLintFinding, HyperframeLintResult, HyperframeLinterOptions } from "./types";
+import { buildLintContext } from "./context";
+import { readAttr, truncateSnippet } from "./utils";
+import { coreRules } from "./rules/core";
+import { mediaRules } from "./rules/media";
+import { gsapRules } from "./rules/gsap";
+import { captionRules } from "./rules/captions";
+import { compositionRules } from "./rules/composition";
+import { adapterRules } from "./rules/adapters";
+import { textureRules } from "./rules/textures";
+import { fontRules } from "./rules/fonts";
+import { slideshowRules } from "./rules/slideshow";
+
+const ALL_RULES = [
+  ...coreRules,
+  ...mediaRules,
+  ...gsapRules,
+  ...captionRules,
+  ...compositionRules,
+  ...adapterRules,
+  ...textureRules,
+  ...fontRules,
+  ...slideshowRules,
+];
+
+export async function lintHyperframeHtml(
+  html: string,
+  options: HyperframeLinterOptions = {},
+): Promise<HyperframeLintResult> {
+  const ctx = buildLintContext(html, options);
+  const findings: HyperframeLintFinding[] = [];
+  const seen = new Set<string>();
+
+  for (const rule of ALL_RULES) {
+    for (const finding of await Promise.resolve(rule(ctx))) {
+      const dedupeKey = [
+        finding.code,
+        finding.severity,
+        finding.selector || "",
+        finding.elementId || "",
+        finding.message,
+      ].join("|");
+      if (seen.has(dedupeKey)) continue;
+      seen.add(dedupeKey);
+      findings.push(options.filePath ? { ...finding, file: options.filePath } : finding);
+    }
+  }
+
+  const errorCount = findings.filter((f) => f.severity === "error").length;
+  const warningCount = findings.filter((f) => f.severity === "warning").length;
+  const infoCount = findings.filter((f) => f.severity === "info").length;
+
+  return {
+    ok: errorCount === 0,
+    errorCount,
+    warningCount,
+    infoCount,
+    findings,
+  };
+}
+
+// ── Async media URL accessibility checker ─────────────────────────────────
+
+function extractMediaUrls(html: string): Array<{
+  url: string;
+  tagName: string;
+  elementId?: string;
+  snippet: string;
+}> {
+  const results: Array<{
+    url: string;
+    tagName: string;
+    elementId?: string;
+    snippet: string;
+  }> = [];
+  const tagRe = /<(video|audio|img|source)\b[^>]*>/gi;
+  let match: RegExpExecArray | null;
+  while ((match = tagRe.exec(html)) !== null) {
+    const tagName = (match[1] ?? "").toLowerCase();
+    const raw = match[0];
+    const src = readAttr(raw, "src");
+    if (!src) continue;
+    if (/^https?:\/\//i.test(src)) {
+      results.push({
+        url: src,
+        tagName,
+        elementId: readAttr(raw, "id") || undefined,
+        snippet: truncateSnippet(raw) ?? "",
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * Async lint pass: HEAD-checks every remote media URL in the HTML.
+ * Returns findings for URLs that are unreachable (non-2xx status or network error).
+ *
+ * Call this after `lintHyperframeHtml()` and merge the findings.
+ *
+ * @param timeoutMs - per-request timeout (default 8000ms)
+ */
+export async function lintMediaUrls(
+  html: string,
+  options: { timeoutMs?: number } = {},
+): Promise<HyperframeLintFinding[]> {
+  const urls = extractMediaUrls(html);
+  if (urls.length === 0) return [];
+
+  const timeout = options.timeoutMs ?? 8000;
+  const findings: HyperframeLintFinding[] = [];
+
+  const seen = new Set<string>();
+  const unique = urls.filter((u) => {
+    if (seen.has(u.url)) return false;
+    seen.add(u.url);
+    return true;
+  });
+
+  const checks = unique.map(async ({ url, tagName, elementId, snippet }) => {
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+      const resp = await fetch(url, {
+        method: "HEAD",
+        signal: controller.signal,
+        redirect: "follow",
+      });
+      clearTimeout(timer);
+      if (!resp.ok) {
+        findings.push({
+          code: "inaccessible_media_url",
+          severity: "error",
+          message: `<${tagName}${elementId ? ` id="${elementId}"` : ""}> references a URL that returned HTTP ${resp.status}: ${url.slice(0, 100)}`,
+          elementId,
+          fixHint: "This URL is not accessible. Replace with a valid, reachable media URL.",
+          snippet,
+        });
+      }
+    } catch (err) {
+      const reason = err instanceof Error ? err.name : "unknown";
+      findings.push({
+        code: "inaccessible_media_url",
+        severity: "error",
+        message: `<${tagName}${elementId ? ` id="${elementId}"` : ""}> references an unreachable URL (${reason}): ${url.slice(0, 100)}`,
+        elementId,
+        fixHint: "This URL is not accessible. Replace with a valid, reachable media URL.",
+        snippet,
+      });
+    }
+  });
+
+  await Promise.all(checks);
+  return findings;
+}
diff --git a/packages/lint/src/index.ts b/packages/lint/src/index.ts
new file mode 100644
index 0000000000..9ee218b7a7
--- /dev/null
+++ b/packages/lint/src/index.ts
@@ -0,0 +1,9 @@
+export type {
+  HyperframeLintSeverity,
+  HyperframeLintFinding,
+  HyperframeLintResult,
+  HyperframeLinterOptions,
+} from "./types.js";
+export { lintHyperframeHtml, lintMediaUrls } from "./hyperframeLinter.js";
+export { lintProject, shouldBlockRender } from "./project.js";
+export type { ProjectLintResult } from "./project.js";
diff --git a/packages/lint/src/project.ts b/packages/lint/src/project.ts
new file mode 100644
index 0000000000..34e6e167e1
--- /dev/null
+++ b/packages/lint/src/project.ts
@@ -0,0 +1,511 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, extname, isAbsolute, join, posix, relative, resolve } from "node:path";
+import { decodeUrlPathVariants, rewriteAssetPath } from "@hyperframes/core";
+import { lintHyperframeHtml } from "./hyperframeLinter.js";
+import type { HyperframeLintFinding, HyperframeLintResult } from "./types.js";
+
+interface HtmlSource {
+  html: string;
+  compSrcPath?: string;
+}
+
+interface CssSource {
+  content: string;
+  rootRelativePath?: string;
+}
+
+export interface ProjectLintResult {
+  results: Array<{ file: string; result: HyperframeLintResult }>;
+  totalErrors: number;
+  totalWarnings: number;
+  totalInfos: number;
+}
+
+const AUDIO_EXTENSIONS = new Set([".mp3", ".wav", ".aac", ".ogg", ".m4a", ".flac", ".opus"]);
+const STYLE_BLOCK_RE = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
+const OPEN_TAG_RE = /<([a-z][\w:-]*)(\s[^<>]*?)?>/gi;
+const MASK_IMAGE_URL_RE =
+  /\b(?:-webkit-)?mask-image\s*:\s*[^;{}]*url\(\s*(?:"([^"]+)"|'([^']+)'|([^"')\s]+))\s*\)/gi;
+
+function readHtmlAttr(tag: string, name: string): string | null {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = tag.match(new RegExp(`\\b${escaped}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, "i"));
+  return match?.[1] ?? match?.[2] ?? null;
+}
+
+function isLocalStylesheetHref(href: string): boolean {
+  return !!href && !/^(https?:|data:|blob:|\/\/)/i.test(href);
+}
+
+function collectExternalStyles(
+  projectDir: string,
+  html: string,
+  compSrcPath?: string,
+): Array<{ href: string; content: string }> {
+  const styles: Array<{ href: string; content: string }> = [];
+  const linkRe = /<link\b[^>]*>/gi;
+  let match: RegExpExecArray | null;
+  while ((match = linkRe.exec(html)) !== null) {
+    const tag = match[0];
+    const rel = tag.match(/\brel\s*=\s*["']([^"']+)["']/i)?.[1] ?? "";
+    if (!rel.split(/\s+/).some((part) => part.toLowerCase() === "stylesheet")) continue;
+    const href = tag.match(/\bhref\s*=\s*["']([^"']+)["']/i)?.[1] ?? "";
+    if (!isLocalStylesheetHref(href)) continue;
+    const rootRelative = compSrcPath ? join(dirname(compSrcPath), href) : href;
+    const stylesheet = resolveExistingLocalAsset(projectDir, rootRelative);
+    if (!stylesheet) continue;
+    styles.push({ href, content: readFileSync(stylesheet.resolved, "utf-8") });
+  }
+  return styles;
+}
+
+function collectCssSources(projectDir: string, html: string, compSrcPath?: string): CssSource[] {
+  const sources: CssSource[] = [];
+
+  let styleMatch: RegExpExecArray | null;
+  const stylePattern = new RegExp(STYLE_BLOCK_RE.source, STYLE_BLOCK_RE.flags);
+  while ((styleMatch = stylePattern.exec(html)) !== null) {
+    sources.push({ content: styleMatch[1] ?? "" });
+  }
+
+  const linkRe = /<link\b[^>]*>/gi;
+  let linkMatch: RegExpExecArray | null;
+  while ((linkMatch = linkRe.exec(html)) !== null) {
+    const tag = linkMatch[0];
+    const rel = readHtmlAttr(tag, "rel") ?? "";
+    if (!rel.split(/\s+/).some((part) => part.toLowerCase() === "stylesheet")) continue;
+    const href = readHtmlAttr(tag, "href") ?? "";
+    if (!isLocalStylesheetHref(href)) continue;
+
+    const rootRelativePath = compSrcPath ? join(dirname(compSrcPath), href) : href;
+    const stylesheet = resolveExistingLocalAsset(projectDir, rootRelativePath);
+    if (!stylesheet) continue;
+    sources.push({
+      content: readFileSync(stylesheet.resolved, "utf-8"),
+      rootRelativePath: stylesheet.rootRelativePath,
+    });
+  }
+
+  let tagMatch: RegExpExecArray | null;
+  const tagPattern = new RegExp(OPEN_TAG_RE.source, OPEN_TAG_RE.flags);
+  while ((tagMatch = tagPattern.exec(html)) !== null) {
+    const tag = tagMatch[0];
+    const style = readHtmlAttr(tag, "style");
+    if (!style) continue;
+    sources.push({ content: style });
+  }
+
+  return sources;
+}
+
+function isRemoteOrInlineUrl(url: string): boolean {
+  return /^(https?:|data:|blob:|\/\/|#)/i.test(url);
+}
+
+function cleanAssetUrl(url: string): string {
+  return url.trim().split(/[?#]/, 1)[0] ?? "";
+}
+
+function isWithinProjectRoot(projectDir: string, candidate: string): boolean {
+  const projectRoot = resolve(projectDir);
+  const relativePath = relative(projectRoot, candidate);
+  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+
+function addCandidate(candidates: string[], candidate: string): void {
+  if (!candidates.includes(candidate)) candidates.push(candidate);
+}
+
+function resolveLocalAssetCandidates(projectDir: string, url: string): string[] {
+  const cleanUrl = cleanAssetUrl(url);
+  const projectRoot = resolve(projectDir);
+  const candidates: string[] = [];
+
+  for (const variant of decodeUrlPathVariants(cleanUrl)) {
+    const projectRelative = variant.startsWith("/") ? variant.slice(1) : variant;
+    const resolved = resolve(projectRoot, projectRelative);
+    if (isWithinProjectRoot(projectRoot, resolved)) {
+      addCandidate(candidates, resolved);
+      continue;
+    }
+
+    const normalized = posix.normalize(projectRelative.replace(/\\/g, "/"));
+    const clamped = normalized.replace(/^(\.\.\/)+/, "");
+    if (clamped && !clamped.startsWith("..")) {
+      addCandidate(candidates, resolve(projectRoot, clamped));
+    }
+  }
+
+  return candidates;
+}
+
+function resolveExistingLocalAsset(
+  projectDir: string,
+  url: string,
+): { resolved: string; rootRelativePath: string } | null {
+  const projectRoot = resolve(projectDir);
+  const resolved = resolveLocalAssetCandidates(projectRoot, url).find(existsSync);
+  if (!resolved) return null;
+  return { resolved, rootRelativePath: relative(projectRoot, resolved) };
+}
+
+function resolveCssAssetCandidates(
+  projectDir: string,
+  url: string,
+  htmlCompSrcPath?: string,
+  cssRootRelativePath?: string,
+): string[] {
+  if (url.startsWith("/")) return resolveLocalAssetCandidates(projectDir, url);
+  if (cssRootRelativePath) {
+    return resolveLocalAssetCandidates(projectDir, join(dirname(cssRootRelativePath), url));
+  }
+  if (htmlCompSrcPath) {
+    return resolveLocalAssetCandidates(projectDir, rewriteAssetPath(htmlCompSrcPath, url));
+  }
+  return resolveLocalAssetCandidates(projectDir, url);
+}
+
+export async function lintProject(projectDir: string): Promise<ProjectLintResult> {
+  const indexPath = resolve(projectDir, "index.html");
+  const results: Array<{ file: string; result: HyperframeLintResult }> = [];
+  let totalErrors = 0;
+  let totalWarnings = 0;
+  let totalInfos = 0;
+
+  const rootHtml = readFileSync(indexPath, "utf-8");
+  const rootResult = await lintHyperframeHtml(rootHtml, {
+    filePath: indexPath,
+    externalStyles: collectExternalStyles(projectDir, rootHtml),
+  });
+  results.push({ file: "index.html", result: rootResult });
+  totalErrors += rootResult.errorCount;
+  totalWarnings += rootResult.warningCount;
+  totalInfos += rootResult.infoCount;
+
+  const allHtmlSources: HtmlSource[] = [{ html: rootHtml }];
+  const compositionsDir = resolve(projectDir, "compositions");
+  if (existsSync(compositionsDir)) {
+    const collectHtmlFiles = (dir: string, rel: string): string[] => {
+      const out: string[] = [];
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) out.push(...collectHtmlFiles(join(dir, entry.name), relPath));
+        else if (entry.isFile() && entry.name.endsWith(".html")) out.push(relPath);
+      }
+      return out;
+    };
+    const files = collectHtmlFiles(compositionsDir, "").sort();
+    for (const file of files) {
+      const filePath = join(compositionsDir, file);
+      const html = readFileSync(filePath, "utf-8");
+      const compSrcPath = `compositions/${file}`;
+      allHtmlSources.push({ html, compSrcPath });
+      const result = await lintHyperframeHtml(html, {
+        filePath,
+        isSubComposition: true,
+        externalStyles: collectExternalStyles(projectDir, html, compSrcPath),
+      });
+      results.push({ file: `compositions/${file}`, result });
+      totalErrors += result.errorCount;
+      totalWarnings += result.warningCount;
+      totalInfos += result.infoCount;
+    }
+  }
+
+  const projectFindings = [
+    ...lintProjectAudioFiles(projectDir, allHtmlSources),
+    ...lintAudioSrcNotFound(projectDir, allHtmlSources),
+    ...lintMissingLocalAsset(projectDir, allHtmlSources),
+    ...lintTextureMaskAssetNotFound(projectDir, allHtmlSources),
+    ...lintMultipleRootCompositions(projectDir),
+    ...lintDuplicateAudioTracks(allHtmlSources),
+  ];
+  if (projectFindings.length > 0) {
+    for (const finding of projectFindings) {
+      rootResult.findings.push(finding);
+      if (finding.severity === "error") {
+        rootResult.errorCount++;
+        rootResult.ok = false;
+        totalErrors++;
+      } else if (finding.severity === "warning") {
+        rootResult.warningCount++;
+        totalWarnings++;
+      } else {
+        rootResult.infoCount++;
+        totalInfos++;
+      }
+    }
+  }
+
+  return { results, totalErrors, totalWarnings, totalInfos };
+}
+
+export function shouldBlockRender(
+  strictErrors: boolean,
+  strictAll: boolean,
+  totalErrors: number,
+  totalWarnings: number,
+): boolean {
+  return (strictErrors && totalErrors > 0) || (strictAll && (totalErrors > 0 || totalWarnings > 0));
+}
+
+function lintProjectAudioFiles(
+  projectDir: string,
+  htmlSources: HtmlSource[],
+): HyperframeLintFinding[] {
+  const findings: HyperframeLintFinding[] = [];
+
+  let audioFiles: string[];
+  try {
+    audioFiles = readdirSync(projectDir).filter((f) =>
+      AUDIO_EXTENSIONS.has(extname(f).toLowerCase()),
+    );
+  } catch {
+    return findings;
+  }
+
+  if (audioFiles.length === 0) return findings;
+
+  const hasAudioElement = htmlSources.some(({ html }) => /<audio\b/i.test(html));
+
+  if (!hasAudioElement) {
+    findings.push({
+      code: "audio_file_without_element",
+      severity: "warning",
+      message: `Found audio file(s) in project (${audioFiles.join(", ")}) but no <audio> element in any composition. The rendered video will be silent.`,
+      fixHint:
+        'Add an <audio id="my-audio" src="' +
+        audioFiles[0] +
+        '" data-start="0" data-duration="__DURATION__" data-track-index="0" data-volume="1"></audio> element inside the composition root. Replace __DURATION__ with the audio length in seconds.',
+    });
+  }
+
+  return findings;
+}
+
+function lintAudioSrcNotFound(
+  projectDir: string,
+  htmlSources: HtmlSource[],
+): HyperframeLintFinding[] {
+  const findings: HyperframeLintFinding[] = [];
+
+  const audioSrcRe = /<audio\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi;
+
+  const missingSrcs: string[] = [];
+  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;
+      const rootRelative = compSrcPath ? rewriteAssetPath(compSrcPath, src) : src;
+      if (!resolveLocalAssetCandidates(projectDir, rootRelative).some(existsSync)) {
+        missingSrcs.push(src);
+      }
+    }
+  }
+
+  if (missingSrcs.length > 0) {
+    const unique = [...new Set(missingSrcs)];
+    findings.push({
+      code: "audio_src_not_found",
+      severity: "error",
+      message: `<audio> element references file(s) not found in the project: ${unique.join(", ")}. The rendered video will be silent.`,
+      fixHint:
+        unique.length === 1
+          ? `Add the file "${unique[0]}" to the project directory, or update the src attribute to point to an existing file.`
+          : `Add the missing files to the project directory, or update the src attributes to point to existing files.`,
+    });
+  }
+
+  return findings;
+}
+
+function maskRange(src: string, pattern: RegExp): string {
+  return src.replace(pattern, (m) => " ".repeat(m.length));
+}
+
+function maskNonScannableRanges(html: string): string {
+  let out = maskRange(html, /<!--[\s\S]*?-->/g);
+  out = maskRange(out, /<style\b[^>]*>[\s\S]*?<\/style\b[^>]*>/gi);
+  out = maskRange(out, /<script\b[^>]*>[\s\S]*?<\/script\b[^>]*>/gi);
+  return out;
+}
+
+// fallow-ignore-next-line complexity
+function lintMissingLocalAsset(
+  projectDir: string,
+  htmlSources: HtmlSource[],
+): HyperframeLintFinding[] {
+  const findings: HyperframeLintFinding[] = [];
+
+  const localAssetSrcRe = /<(video|img|source)\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi;
+
+  const missingByTag = new Map<string, Map<string, string>>();
+
+  for (const { html, compSrcPath } of htmlSources) {
+    const scannable = maskNonScannableRanges(html);
+    const re = new RegExp(localAssetSrcRe.source, localAssetSrcRe.flags);
+    let match: RegExpExecArray | null;
+    while ((match = re.exec(scannable)) !== null) {
+      const tagName = (match[1] ?? "").toLowerCase();
+      const rawSrc = match[2] ?? "";
+      const src = cleanAssetUrl(rawSrc);
+      if (!src) continue;
+      if (isRemoteOrInlineUrl(src)) continue;
+      if (/^__[A-Z_]+__$/.test(src)) continue;
+      const rootRelative = compSrcPath ? rewriteAssetPath(compSrcPath, src) : src;
+      const resolvedAsset = resolveExistingLocalAsset(projectDir, rootRelative);
+      if (resolvedAsset) continue;
+
+      const resolvedKey = resolve(projectDir, rootRelative);
+      let bucket = missingByTag.get(tagName);
+      if (!bucket) {
+        bucket = new Map<string, string>();
+        missingByTag.set(tagName, bucket);
+      }
+      if (!bucket.has(resolvedKey)) bucket.set(resolvedKey, src);
+    }
+  }
+
+  for (const [tagName, byResolved] of missingByTag) {
+    const unique = [...byResolved.values()];
+    findings.push({
+      code: "missing_local_asset",
+      severity: "error",
+      message:
+        `<${tagName}> element references local file(s) not found in the project: ${unique.join(", ")}. ` +
+        "The renderer will silently skip these and produce a video with missing visuals.",
+      fixHint:
+        unique.length === 1
+          ? `Add "${unique[0]}" to the project directory, or update the src attribute to point to an existing file. ` +
+            "Common cause: captured asset filenames are unreliable (heygen-logo.svg often contains Google, nvidia-logo.svg may contain Autodesk, etc.). " +
+            "Open the contact sheets and verify the file actually exists at this path before referencing it."
+          : "Add the missing files to the project directory, or update the src attributes to point to existing files. " +
+            "Captured asset filenames are unreliable — verify against capture/contact-sheets/ and capture/extracted/asset-descriptions.md.",
+    });
+  }
+
+  return findings;
+}
+
+function lintTextureMaskAssetNotFound(
+  projectDir: string,
+  htmlSources: HtmlSource[],
+): HyperframeLintFinding[] {
+  const missing = new Map<string, string>();
+
+  for (const { html, compSrcPath } of htmlSources) {
+    for (const cssSource of collectCssSources(projectDir, html, compSrcPath)) {
+      let match: RegExpExecArray | null;
+      const pattern = new RegExp(MASK_IMAGE_URL_RE.source, MASK_IMAGE_URL_RE.flags);
+      while ((match = pattern.exec(cssSource.content)) !== null) {
+        const rawUrl = match[1] ?? match[2] ?? match[3] ?? "";
+        const url = cleanAssetUrl(rawUrl);
+        if (!url || isRemoteOrInlineUrl(url)) continue;
+        if (/^__[A-Z_]+__$/.test(url)) continue;
+
+        const candidates = resolveCssAssetCandidates(
+          projectDir,
+          url,
+          compSrcPath,
+          cssSource.rootRelativePath,
+        );
+        if (candidates.some(existsSync)) continue;
+        missing.set(url, candidates[0] ?? resolve(projectDir, url));
+      }
+    }
+  }
+
+  if (missing.size === 0) return [];
+  const urls = [...missing.keys()];
+  return [
+    {
+      code: "texture_mask_asset_not_found",
+      severity: "error",
+      message: `CSS mask-image references file(s) not found in the project: ${urls.join(", ")}.`,
+      fixHint:
+        urls.length === 1
+          ? `Add "${urls[0]}" to the project, or update the mask-image URL to point to an existing texture mask.`
+          : "Add the missing texture mask files to the project, or update the mask-image URLs to point to existing files.",
+    },
+  ];
+}
+
+function lintMultipleRootCompositions(projectDir: string): HyperframeLintFinding[] {
+  const findings: HyperframeLintFinding[] = [];
+  try {
+    const rootHtmlFiles = readdirSync(projectDir).filter((f) => f.endsWith(".html"));
+    const rootCompositions: string[] = [];
+    for (const file of rootHtmlFiles) {
+      if (file === "caption-skin.html") continue;
+      const content = readFileSync(join(projectDir, file), "utf-8");
+      if (/data-composition-id/i.test(content)) {
+        rootCompositions.push(file);
+      }
+    }
+    if (rootCompositions.length > 1) {
+      findings.push({
+        code: "multiple_root_compositions",
+        severity: "error",
+        message: `Multiple root-level HTML files with data-composition-id: ${rootCompositions.join(", ")}. The runtime may discover both as entry points, causing duplicate audio playback.`,
+        fixHint:
+          "A project should have exactly one root index.html with data-composition-id. Remove or rename extra files.",
+      });
+    }
+  } catch {
+    /* directory read failed — skip */
+  }
+  return findings;
+}
+
+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");
+    const m = tag.match(re);
+    return m?.[1] ?? null;
+  }
+
+  const tracks: Array<{ trackIndex: number; start: number; end: number; src: string }> = [];
+  const seen = new Set<string>();
+
+  for (const { html } of htmlSources) {
+    const audioTagRe = /<audio\b[^>]*>/gi;
+    let match: RegExpExecArray | null;
+    while ((match = audioTagRe.exec(html)) !== null) {
+      const tag = match[0];
+      const trackStr = extractAttr(tag, "data-track-index");
+      const startStr = extractAttr(tag, "data-start");
+      const durStr = extractAttr(tag, "data-duration");
+      const src = extractAttr(tag, "src") ?? "unknown";
+      if (!trackStr || !startStr) continue;
+
+      const trackIndex = parseInt(trackStr, 10);
+      const start = parseFloat(startStr);
+      const duration = durStr ? parseFloat(durStr) : Infinity;
+      const key = `${src}:${start}:${duration}:${trackIndex}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      tracks.push({ trackIndex, start, end: start + duration, src });
+    }
+  }
+
+  for (let i = 0; i < tracks.length; i++) {
+    for (let j = i + 1; j < tracks.length; j++) {
+      const a = tracks[i]!;
+      const b = tracks[j]!;
+      if (a.trackIndex !== b.trackIndex) continue;
+      if (a.start < b.end && b.start < a.end) {
+        findings.push({
+          code: "duplicate_audio_track",
+          severity: "warning",
+          message: `Multiple <audio> elements on track ${a.trackIndex} overlap (${a.src} at ${a.start}-${Number.isFinite(a.end) ? a.end.toFixed(1) : "end"}s, ${b.src} at ${b.start}-${Number.isFinite(b.end) ? b.end.toFixed(1) : "end"}s). This causes layered audio playback.`,
+          fixHint: "Use non-overlapping time windows or different track indices.",
+        });
+      }
+    }
+  }
+  return findings;
+}
diff --git a/packages/lint/src/rules/adapters.test.ts b/packages/lint/src/rules/adapters.test.ts
new file mode 100644
index 0000000000..d28e49abc9
--- /dev/null
+++ b/packages/lint/src/rules/adapters.test.ts
@@ -0,0 +1,144 @@
+// fallow-ignore-file code-duplication
+import { describe, it, expect } from "vitest";
+import { lintHyperframeHtml } from "../hyperframeLinter.js";
+
+describe("adapter rules", () => {
+  it("reports error when GSAP is used without a GSAP script tag", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#box", { x: 100, duration: 1 }, 0);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.message).toContain("GSAP");
+  });
+
+  it("does not report missing_gsap_script when GSAP CDN script is present", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></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("#box", { x: 100, duration: 1 }, 0);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
+    expect(finding).toBeUndefined();
+  });
+
+  it("reports error when Lottie container exists without a Lottie script tag", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <div id="lottie-player" data-lottie-src="animation.json"></div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["main"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "missing_lottie_script");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.message).toContain("Lottie");
+  });
+
+  it("reports error when lottie.loadAnimation is used without a Lottie script tag", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["main"] = gsap.timeline({ paused: true });
+    lottie.loadAnimation({ container: document.getElementById('lottie'), path: 'anim.json' });
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "missing_lottie_script");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+  });
+
+  it("does not report missing_lottie_script when Lottie CDN script is present", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <div id="lottie-player" data-lottie-src="animation.json"></div>
+  </div>
+  <script src="https://cdn.jsdelivr.net/npm/lottie-web@5/build/player/lottie.min.js"></script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["main"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "missing_lottie_script");
+    expect(finding).toBeUndefined();
+  });
+
+  it("reports error when Three.js is used without a Three.js script tag", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["main"] = gsap.timeline({ paused: true });
+    const scene = new THREE.Scene();
+    const renderer = new THREE.WebGLRenderer();
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "missing_three_script");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.message).toContain("Three.js");
+  });
+
+  it("does not report missing_three_script when Three.js CDN script is present", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
+  <script src="https://cdn.jsdelivr.net/npm/three@0.160/build/three.min.js"></script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["main"] = gsap.timeline({ paused: true });
+    const scene = new THREE.Scene();
+    const renderer = new THREE.WebGLRenderer();
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "missing_three_script");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not report any adapter errors for composition with no adapter usage", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <div id="content">Hello World</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["main"] = { totalDuration: function() { return 3; } };
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const adapterFindings = result.findings.filter((f) =>
+      ["missing_gsap_script", "missing_lottie_script", "missing_three_script"].includes(f.code),
+    );
+    expect(adapterFindings).toHaveLength(0);
+  });
+});
diff --git a/packages/lint/src/rules/adapters.ts b/packages/lint/src/rules/adapters.ts
new file mode 100644
index 0000000000..2a9b05bc28
--- /dev/null
+++ b/packages/lint/src/rules/adapters.ts
@@ -0,0 +1,55 @@
+import type { LintContext, HyperframeLintFinding } from "../context";
+import { readAttr, extractScriptTextsAndSrcs } from "../utils";
+
+export const adapterRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
+  // missing_lottie_script
+  ({ tags, scripts }) => {
+    const { texts, srcs } = extractScriptTextsAndSrcs(scripts);
+
+    const hasLottieAttr = tags.some((t) => readAttr(t.raw, "data-lottie-src") !== null);
+    const usesLottieApi = texts.some((t) =>
+      /lottie\.(loadAnimation|setSpeed|play|stop|destroy)\b/.test(t),
+    );
+    const hasLottieScript = srcs.some((src) => /lottie/i.test(src));
+
+    if (!(hasLottieAttr || usesLottieApi) || hasLottieScript) return [];
+    return [
+      {
+        code: "missing_lottie_script",
+        severity: "error",
+        message:
+          "Composition uses Lottie but no Lottie script is loaded. The animation will not render.",
+        fixHint:
+          'Add <script src="https://cdn.jsdelivr.net/npm/lottie-web@5/build/player/lottie.min.js"></script> before your Lottie code.',
+      },
+    ];
+  },
+
+  // missing_three_script
+  ({ scripts }) => {
+    const { texts, srcs } = extractScriptTextsAndSrcs(scripts);
+
+    const usesThree = texts.some((t) => /\bTHREE\./.test(t));
+    const hasThreeScript = srcs.some((src) => /three/i.test(src));
+    const hasThreeImportMap = texts.some(
+      (t) =>
+        /["']three["']/.test(t) &&
+        /importmap/.test(scripts.find((s) => s.content === t)?.attrs || ""),
+    );
+    const hasThreeModuleImport = texts.some(
+      (t) => /\bimport\b.*['"]three['"]/.test(t) || /\bfrom\s+['"]three['"]/.test(t),
+    );
+
+    if (!usesThree || hasThreeScript || hasThreeImportMap || hasThreeModuleImport) return [];
+    return [
+      {
+        code: "missing_three_script",
+        severity: "error",
+        message:
+          "Composition uses Three.js but no Three.js script is loaded. The 3D scene will not render.",
+        fixHint:
+          'Add <script src="https://cdn.jsdelivr.net/npm/three@0.160/build/three.min.js"></script> before your Three.js code.',
+      },
+    ];
+  },
+];
diff --git a/packages/lint/src/rules/captions.test.ts b/packages/lint/src/rules/captions.test.ts
new file mode 100644
index 0000000000..6977acb6e6
--- /dev/null
+++ b/packages/lint/src/rules/captions.test.ts
@@ -0,0 +1,166 @@
+import { describe, it, expect } from "vitest";
+import { lintHyperframeHtml } from "../hyperframeLinter.js";
+
+describe("caption rules", () => {
+  it("warns when caption exit has no hard kill tl.set", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="captions" data-width="1920" data-height="1080">
+    <div id="caption-container"></div>
+    <script>
+      window.__timelines = window.__timelines || {};
+      var tl = gsap.timeline({ paused: true });
+      GROUPS.forEach(function(group, gi) {
+        var groupEl = document.createElement("div");
+        groupEl.id = "cg-" + gi;
+        tl.set(groupEl, { opacity: 1 }, group.start);
+        tl.to(groupEl, { opacity: 0, duration: 0.12 }, group.end - 0.12);
+      });
+      window.__timelines["captions"] = tl;
+    </script>
+  </div>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "caption_exit_missing_hard_kill");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+  });
+
+  it("does not warn when caption exit has hard kill tl.set", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="captions" data-width="1920" data-height="1080">
+    <div id="caption-container"></div>
+    <script>
+      window.__timelines = window.__timelines || {};
+      var tl = gsap.timeline({ paused: true });
+      GROUPS.forEach(function(group, gi) {
+        var groupEl = document.createElement("div");
+        groupEl.id = "cg-" + gi;
+        tl.set(groupEl, { opacity: 1 }, group.start);
+        tl.to(groupEl, { opacity: 0, duration: 0.12 }, group.end - 0.12);
+        tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end);
+      });
+      window.__timelines["captions"] = tl;
+    </script>
+  </div>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "caption_exit_missing_hard_kill");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not warn for generic GSAP opacity exits in non-caption loops", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <script>
+      window.__timelines = window.__timelines || {};
+      var tl = gsap.timeline({ paused: true });
+      var sceneCaption = document.querySelector("#scene-caption");
+      CARDS.forEach(function(group, gi) {
+        var groupEl = document.createElement("div");
+        groupEl.id = "card-" + gi;
+        tl.to(groupEl, { opacity: 0, duration: 0.12 }, 2);
+      });
+      window.__timelines["main"] = tl;
+    </script>
+  </div>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "caption_exit_missing_hard_kill");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not warn on a content frame that only mentions karaoke in a comment", async () => {
+    const html = `<template id="06-one-platform-template">
+  <div id="root" data-composition-id="06-one-platform" data-width="1920" data-height="1080">
+    <script>
+      window.__timelines = window.__timelines || {};
+      var tl = gsap.timeline({ paused: true });
+      // "Minutes, not weeks" lands with a karaoke-style keyword glow
+      SCREENS.forEach(function (s, i) {
+        var el = document.getElementById("screen-" + i);
+        tl.to(el, { y: -40, opacity: 0, duration: 0.3 }, i * 1.3);
+      });
+      window.__timelines["06-one-platform"] = tl;
+    </script>
+  </div>
+</template>`;
+    const result = await lintHyperframeHtml(html, { isSubComposition: true });
+    const finding = result.findings.find((f) => f.code === "caption_exit_missing_hard_kill");
+    expect(finding).toBeUndefined();
+  });
+
+  it("warns when caption group has nowrap without max-width", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="captions" data-width="1920" data-height="1080">
+    <style>
+      .caption-group {
+        position: absolute;
+        white-space: nowrap;
+        text-align: center;
+      }
+    </style>
+    <script>
+      window.__timelines = window.__timelines || {};
+      var tl = gsap.timeline({ paused: true });
+      window.__timelines["captions"] = tl;
+    </script>
+  </div>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "caption_text_overflow_risk");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("warning");
+  });
+
+  it("does not warn when caption group has nowrap with max-width", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="captions" data-width="1920" data-height="1080">
+    <style>
+      .caption-group {
+        position: absolute;
+        white-space: nowrap;
+        max-width: 1600px;
+        overflow: hidden;
+      }
+    </style>
+    <script>
+      window.__timelines = window.__timelines || {};
+      var tl = gsap.timeline({ paused: true });
+      window.__timelines["captions"] = tl;
+    </script>
+  </div>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find(
+      (f) => f.code === "caption_text_overflow_risk" && f.severity === "warning",
+    );
+    expect(finding).toBeUndefined();
+  });
+
+  it("warns when caption container uses position: relative", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="captions" data-width="1920" data-height="1080">
+    <style>
+      .caption-group {
+        position: relative;
+      }
+    </style>
+    <script>
+      window.__timelines = window.__timelines || {};
+      var tl = gsap.timeline({ paused: true });
+      window.__timelines["captions"] = tl;
+    </script>
+  </div>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "caption_container_relative_position");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+  });
+});
diff --git a/packages/lint/src/rules/captions.ts b/packages/lint/src/rules/captions.ts
new file mode 100644
index 0000000000..21af66d0e7
--- /dev/null
+++ b/packages/lint/src/rules/captions.ts
@@ -0,0 +1,271 @@
+import type { LintContext, HyperframeLintFinding } from "../context";
+
+/** Extract a bracket-balanced array literal starting at the `[` found by `varMatch`. */
+// fallow-ignore-next-line complexity
+function extractArrayLiteral(src: string, varMatch: RegExpExecArray): string | null {
+  const openIdx = varMatch.index + varMatch[0].length - 1;
+  let depth = 0;
+  let inStr = false;
+  let strChar = "";
+  for (let i = openIdx; i < src.length; i++) {
+    const c = src[i]!;
+    if (inStr) {
+      if (c === "\\") {
+        i++;
+        continue;
+      }
+      if (c === strChar) inStr = false;
+    } else if (c === '"' || c === "'") {
+      inStr = true;
+      strChar = c;
+    } else if (c === "[") {
+      depth++;
+    } else if (c === "]") {
+      depth--;
+      if (depth === 0) return src.slice(openIdx, i + 1);
+    }
+  }
+  return null;
+}
+
+export const captionRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
+  // caption_exit_missing_hard_kill
+  ({ scripts, styles, options, rootCompositionId }) => {
+    const findings: HyperframeLintFinding[] = [];
+    // Only the ACTUAL captions composition. A content frame that merely mentions
+    // "karaoke" / "caption-*" in a comment (or uses an unrelated forEach + opacity:0
+    // screen-swap) is NOT captions — gating here prevents the false positive that fired
+    // on a content frame whose only caption signal was a descriptive comment.
+    const isCaptionComposition =
+      Boolean(options.filePath && /caption/i.test(options.filePath)) ||
+      rootCompositionId === "captions" ||
+      styles.some((s) => /\.caption[-_]?(?:group|word|line|block)\b|\.cg-/.test(s.content));
+    if (!isCaptionComposition) return findings;
+    for (const script of scripts) {
+      const content = script.content;
+      const hasExitTween = /\.to\s*\([^,]+,\s*\{[^}]*opacity\s*:\s*0/.test(content);
+      const hasHardKill =
+        /\.set\s*\([^,]+,\s*\{[^}]*(?:visibility\s*:\s*["']hidden["']|opacity\s*:\s*0)/.test(
+          content,
+        );
+      const hasCaptionLoop =
+        /forEach|\.forEach\s*\(/.test(content) &&
+        /karaoke|caption[-_]?(?:group|word|line|block)|cg-/.test(content);
+      if (hasCaptionLoop && hasExitTween && !hasHardKill) {
+        findings.push({
+          code: "caption_exit_missing_hard_kill",
+          severity: "error",
+          message:
+            "Caption exit animations (tl.to with opacity: 0) detected without a hard tl.set kill. " +
+            "Exit tweens can fail when karaoke word-level tweens conflict, leaving captions stuck on screen.",
+          fixHint:
+            'Add `tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end)` after every ' +
+            "exit tl.to animation as a deterministic kill.",
+        });
+      }
+    }
+    return findings;
+  },
+
+  // caption_text_overflow_risk
+  ({ styles }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const style of styles) {
+      const captionBlocks = style.content.matchAll(
+        /(\.caption[-_]?(?:group|container|text|line|word)|#caption[-_]?container)\s*\{([^}]+)\}/gi,
+      );
+      for (const [, selector, body] of captionBlocks) {
+        if (!body) continue;
+        const hasNowrap = /white-space\s*:\s*nowrap/i.test(body);
+        const hasMaxWidth = /max-width/i.test(body);
+        if (hasNowrap && !hasMaxWidth) {
+          findings.push({
+            code: "caption_text_overflow_risk",
+            severity: "warning",
+            selector: (selector ?? "").trim(),
+            message: `Caption selector "${(selector ?? "").trim()}" has white-space: nowrap but no max-width. Long phrases will clip off-screen.`,
+            fixHint:
+              "Add max-width: 1600px (landscape) or max-width: 900px (portrait) and overflow: hidden.",
+          });
+        }
+      }
+    }
+    return findings;
+  },
+
+  // caption_transcript_not_inline
+  // fallow-ignore-next-line complexity
+  ({ scripts, styles, options }) => {
+    const findings: HyperframeLintFinding[] = [];
+    // Only check files that look like caption compositions
+    const isCaptionFile =
+      (options.filePath && /caption/i.test(options.filePath)) ||
+      styles.some((s) => /\.caption[-_]?(?:group|word)/i.test(s.content));
+    if (!isCaptionFile) return findings;
+
+    const allScript = scripts.map((s) => s.content).join("\n");
+    const hasInlineTranscript = /(?:const|let|var)\s+(?:TRANSCRIPT|script)\s*=\s*\[/.test(
+      allScript,
+    );
+    const hasFetchTranscript = /fetch\s*\(\s*["'][^"']*transcript/i.test(allScript);
+
+    if (!hasInlineTranscript && hasFetchTranscript) {
+      findings.push({
+        code: "caption_transcript_not_inline",
+        severity: "error",
+        message:
+          "Captions composition loads transcript via fetch(). The studio caption editor " +
+          "requires an inline `var TRANSCRIPT = [...]` array to detect and edit captions.",
+        fixHint:
+          'Embed the transcript as `var TRANSCRIPT = [{ "text": "...", "start": 0, "end": 1 }, ...]` ' +
+          "with JSON-quoted property keys. See the captions skill for details.",
+      });
+    }
+
+    if (hasInlineTranscript) {
+      // Verify the inline transcript can be parsed.
+      // Use a balanced-bracket scan instead of a regex to correctly handle
+      // nested arrays (e.g. word-level timing arrays inside each entry).
+      const varStart = /(?:const|let|var)\s+(?:TRANSCRIPT|script)\s*=\s*\[/.exec(allScript);
+      const transcriptJson = varStart ? extractArrayLiteral(allScript, varStart) : null;
+      if (transcriptJson) {
+        try {
+          JSON.parse(transcriptJson);
+        } catch {
+          findings.push({
+            code: "caption_transcript_parse_error",
+            severity: "error",
+            message:
+              "Inline TRANSCRIPT array is not valid JSON. The studio caption editor may fail " +
+              "to parse it. Common cause: unquoted property keys with apostrophes in text.",
+            fixHint:
+              'Use JSON-quoted keys: { "text": "don\'t", "start": 0, "end": 1 } instead of ' +
+              '{ text: "don\'t", start: 0, end: 1 }.',
+          });
+        }
+      }
+    }
+
+    return findings;
+  },
+
+  // caption_container_relative_position
+  ({ styles }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const style of styles) {
+      const captionBlocks = style.content.matchAll(
+        /(\.caption[-_]?(?:group|container|text|line)|#caption[-_]?container)\s*\{([^}]+)\}/gi,
+      );
+      for (const [, selector, body] of captionBlocks) {
+        if (!body) continue;
+        if (/position\s*:\s*relative/i.test(body)) {
+          findings.push({
+            code: "caption_container_relative_position",
+            severity: "error",
+            selector: (selector ?? "").trim(),
+            message: `Caption selector "${(selector ?? "").trim()}" uses position: relative which causes overflow and breaks caption stacking.`,
+            fixHint: "Use position: absolute for all caption elements.",
+          });
+        }
+      }
+    }
+    return findings;
+  },
+
+  // caption_overflow_clips_scaled_words
+  ({ styles, scripts }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const hasScaledWords = scripts.some(
+      (s) => /scale\s*:\s*1\.[2-9]/.test(s.content) && /caption|word|cg-/.test(s.content),
+    );
+    if (!hasScaledWords) return findings;
+
+    for (const style of styles) {
+      const captionBlocks = style.content.matchAll(
+        /(\.caption[-_]?(?:group|container)|#caption[-_]?(?:layer|container))\s*\{([^}]+)\}/gi,
+      );
+      for (const [, selector, body] of captionBlocks) {
+        if (!body) continue;
+        if (/overflow\s*:\s*hidden/i.test(body)) {
+          findings.push({
+            code: "caption_overflow_clips_scaled_words",
+            severity: "error",
+            selector: (selector ?? "").trim(),
+            message: `"${(selector ?? "").trim()}" has overflow: hidden but GSAP scales caption words above 1.0x. Scaled emphasis words and their glow effects will be clipped.`,
+            fixHint:
+              "Use overflow: visible on caption containers. Rely on fitTextFontSize with reduced maxWidth to prevent overflow instead.",
+          });
+        }
+      }
+    }
+    return findings;
+  },
+
+  // caption_textshadow_on_group_container
+  ({ scripts, styles }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const isCaptionFile = styles.some((s) => /\.caption[-_]?(?:group|word)/i.test(s.content));
+    if (!isCaptionFile) return findings;
+
+    for (const script of scripts) {
+      // Detect textShadow tweened on a group container (div with child word spans)
+      const groupShadowPattern =
+        /\.to\s*\(\s*(?:div|groupEl|el|captionEl|document\.getElementById\s*\(\s*["']cg-)\s*[^,]*,\s*\{[^}]*textShadow/g;
+      // Also catch selector-based targeting of group containers
+      const selectorShadowPattern =
+        /\.to\s*\(\s*["'](?:#cg-\d+|\.caption[-_]?group)["']\s*,\s*\{[^}]*textShadow/g;
+      if (groupShadowPattern.test(script.content) || selectorShadowPattern.test(script.content)) {
+        findings.push({
+          code: "caption_textshadow_on_group_container",
+          severity: "warning",
+          message:
+            "textShadow is tweened on a caption group container. When children have semi-transparent " +
+            "color (e.g., inactive karaoke words at rgba opacity), the glow renders as a visible " +
+            "rectangle behind the entire group.",
+          fixHint:
+            "Apply textShadow to individual active word elements instead of the group container. " +
+            "Use scale on the group for bass-reactive pulsing.",
+        });
+      }
+    }
+    return findings;
+  },
+
+  // caption_fittext_scale_mismatch
+  // fallow-ignore-next-line complexity
+  ({ scripts }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const script of scripts) {
+      const content = script.content;
+      const fitTextMatch = content.match(/fitTextFontSize\s*\([^)]*maxWidth\s*:\s*(\d+)/);
+      if (!fitTextMatch) continue;
+      const maxWidth = parseInt(fitTextMatch[1] ?? "0", 10);
+      if (!maxWidth) continue;
+
+      // Find max scale on caption words
+      const scaleMatches = [...content.matchAll(/scale\s*:\s*(1\.\d+)/g)];
+      const captionContext = /caption|word|cg-|karaoke/i.test(content);
+      if (!captionContext || scaleMatches.length === 0) continue;
+
+      let maxScale = 1;
+      for (const m of scaleMatches) {
+        const val = parseFloat(m[1] ?? "1");
+        if (val > maxScale) maxScale = val;
+      }
+
+      // Check if maxWidth * maxScale exceeds safe bounds (1920 - reasonable margins)
+      const effectiveWidth = maxWidth * maxScale;
+      if (effectiveWidth > 1760) {
+        findings.push({
+          code: "caption_fittext_scale_mismatch",
+          severity: "warning",
+          message:
+            `fitTextFontSize uses maxWidth: ${maxWidth}px but emphasis words scale up to ${maxScale}x. ` +
+            `Effective width ${Math.round(effectiveWidth)}px may overflow the composition (1920px minus margins).`,
+          fixHint: `Reduce maxWidth to ${Math.floor(1700 / maxScale)}px to leave headroom for scaled emphasis words.`,
+        });
+      }
+    }
+    return findings;
+  },
+];
diff --git a/packages/lint/src/rules/composition.test.ts b/packages/lint/src/rules/composition.test.ts
new file mode 100644
index 0000000000..6e308a2a84
--- /dev/null
+++ b/packages/lint/src/rules/composition.test.ts
@@ -0,0 +1,1104 @@
+import { describe, it, expect } from "vitest";
+import { lintHyperframeHtml } from "../hyperframeLinter.js";
+
+describe("composition rules", () => {
+  describe("subcomposition guidance", () => {
+    it("warns when any HTML composition file is over 300 lines", async () => {
+      const html = Array.from({ length: 301 }, (_, i) =>
+        i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
+      ).join("\n");
+
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+      });
+      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
+      expect(finding).toBeDefined();
+      expect(finding?.severity).toBe("warning");
+    });
+
+    it("does not warn when an HTML composition file is exactly 300 lines", async () => {
+      const html = Array.from({ length: 300 }, (_, i) =>
+        i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
+      ).join("\n");
+
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not count a final trailing newline as an extra physical line", async () => {
+      const html =
+        Array.from({ length: 300 }, (_, i) =>
+          i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
+        ).join("\n") + "\n";
+
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not count inline style block internals as structural lines", async () => {
+      const style = `<style>\n${Array.from({ length: 320 }, (_, i) => `.rule-${i} { color: red; }`).join("\n")}\n</style>`;
+      const html = `<!doctype html>
+<html>
+  <head>${style}</head>
+  <body>
+    <div data-composition-id="main" data-start="0" data-duration="1">TEXT</div>
+  </body>
+</html>`;
+
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not warn for large registry source block files", async () => {
+      const html = Array.from({ length: 301 }, (_, i) =>
+        i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
+      ).join("\n");
+
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/registry/blocks/data-chart/data-chart.html",
+      });
+      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
+      expect(finding).toBeUndefined();
+    });
+
+    it("warns for large installed block composition files", async () => {
+      const html = Array.from({ length: 301 }, (_, i) =>
+        i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
+      ).join("\n");
+
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/data-chart.html",
+      });
+      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
+      expect(finding).toBeDefined();
+      expect(finding?.severity).toBe("warning");
+    });
+
+    it("does not warn for large registry-installed block composition files", async () => {
+      const html =
+        "<!-- hyperframes-registry-item: data-chart -->\n" +
+        Array.from({ length: 300 }, (_, i) =>
+          i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
+        ).join("\n");
+
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/data-chart.html",
+      });
+      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
+      expect(finding).toBeUndefined();
+    });
+
+    it("uses nested split copy for large sub-composition files", async () => {
+      const html = Array.from({ length: 301 }, (_, i) =>
+        i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
+      ).join("\n");
+
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+        isSubComposition: true,
+      });
+      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
+      expect(finding?.fixHint).toContain("Split this sub-composition further");
+    });
+
+    it("warns when more than 3 timed elements share the same track", async () => {
+      const html = `<!DOCTYPE html>
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0">
+    <div class="clip" data-start="0" data-duration="1" data-track-index="0">A</div>
+    <div class="clip" data-start="1" data-duration="1" data-track-index="0">B</div>
+    <div class="clip" data-start="2" data-duration="1" data-track-index="0">C</div>
+    <div class="clip" data-start="3" data-duration="1" data-track-index="0">D</div>
+  </div>
+</body></html>`;
+
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+      });
+      const finding = result.findings.find((f) => f.code === "timeline_track_too_dense");
+      expect(finding).toBeDefined();
+      expect(finding?.severity).toBe("warning");
+      expect(finding?.message).toContain("Track 0 has 4 timed elements");
+    });
+
+    it("does not warn when 3 timed elements share the same track", async () => {
+      const html = `<!DOCTYPE html>
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0">
+    <div class="clip" data-start="0" data-duration="1" data-track-index="0">A</div>
+    <div class="clip" data-start="1" data-duration="1" data-track-index="0">B</div>
+    <div class="clip" data-start="2" data-duration="1" data-track-index="0">C</div>
+  </div>
+</body></html>`;
+
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      const finding = result.findings.find((f) => f.code === "timeline_track_too_dense");
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not warn when timed elements are split across tracks", async () => {
+      const html = `<!DOCTYPE html>
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0">
+    <div class="clip" data-start="0" data-duration="1" data-track-index="0">A</div>
+    <div class="clip" data-start="1" data-duration="1" data-track-index="0">B</div>
+    <div class="clip" data-start="2" data-duration="1" data-track-index="1">C</div>
+    <div class="clip" data-start="3" data-duration="1" data-track-index="1">D</div>
+  </div>
+</body></html>`;
+
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      const finding = result.findings.find((f) => f.code === "timeline_track_too_dense");
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not count timed media or script/style tags as dense track elements", async () => {
+      const html = `<!DOCTYPE html>
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0">
+    <audio data-start="0" data-duration="1" data-track-index="0"></audio>
+    <audio data-start="1" data-duration="1" data-track-index="0"></audio>
+    <video muted data-start="2" data-duration="1" data-track-index="0"></video>
+    <script data-start="3" data-duration="1" data-track-index="0"></script>
+    <style data-start="4" data-duration="1" data-track-index="0"></style>
+  </div>
+</body></html>`;
+
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      const finding = result.findings.find((f) => f.code === "timeline_track_too_dense");
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not count root composition or mounted sub-compositions as dense elements", async () => {
+      const html = `<!DOCTYPE html>
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-track-index="0">
+    <div data-composition-id="a" data-composition-src="compositions/a.html" data-start="0" data-duration="1" data-track-index="0"></div>
+    <div data-composition-id="b" data-composition-src="compositions/b.html" data-start="1" data-duration="1" data-track-index="0"></div>
+    <div data-composition-id="c" data-composition-src="compositions/c.html" data-start="2" data-duration="1" data-track-index="0"></div>
+    <div data-composition-id="d" data-composition-src="compositions/d.html" data-start="3" data-duration="1" data-track-index="0"></div>
+  </div>
+</body></html>`;
+
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      const finding = result.findings.find((f) => f.code === "timeline_track_too_dense");
+      expect(finding).toBeUndefined();
+    });
+  });
+
+  it("reports error when querySelector uses template literal variable", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <div class="chart"></div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const compId = "main";
+    const el = document.querySelector(\`[data-composition-id="\${compId}"] .chart\`);
+    const tl = gsap.timeline({ paused: true });
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "template_literal_selector");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+  });
+
+  it("reports error for querySelectorAll with template literal variable", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const id = "main";
+    document.querySelectorAll(\`[data-composition-id="\${id}"] .item\`);
+    const tl = gsap.timeline({ paused: true });
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "template_literal_selector");
+    expect(finding).toBeDefined();
+  });
+
+  it("does not report error for hardcoded querySelector strings", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <div class="chart"></div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const el = document.querySelector('[data-composition-id="main"] .chart');
+    const tl = gsap.timeline({ paused: true });
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "template_literal_selector");
+    expect(finding).toBeUndefined();
+  });
+
+  it("reports error when a selector combines data attributes in one bracket", async () => {
+    const html = `
+<template id="scene-template">
+  <div data-composition-id="scene" data-start="0" data-width="1920" data-height="1080">
+    <style>
+      [data-composition-id="scene" data-start="0"] .title { opacity: 0; }
+    </style>
+    <script>
+      window.__timelines = window.__timelines || {};
+      const title = document.querySelector('[data-composition-id="scene" data-start="0"] .title');
+      const tl = gsap.timeline({ paused: true });
+      tl.to('[data-composition-id="scene" data-start="0"]', { opacity: 0, duration: 0.5 }, 4);
+      window.__timelines["scene"] = tl;
+    </script>
+  </div>
+</template>`;
+    const result = await lintHyperframeHtml(html, { filePath: "compositions/scene.html" });
+    const findings = result.findings.filter((f) => f.code === "split_data_attribute_selector");
+    expect(findings.length).toBe(1);
+    expect(findings[0]?.severity).toBe("error");
+    expect(findings[0]?.fixHint).toContain('[data-composition-id="scene"][data-start="0"]');
+  });
+
+  describe("timed_element_missing_clip_class", () => {
+    it("flags element with data-start but no class='clip'", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="box" data-start="0" data-duration="2">Hello</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["c1"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "timed_element_missing_clip_class");
+      expect(finding).toBeDefined();
+      expect(finding?.severity).toBe("error");
+    });
+
+    it("does not flag element that has class='clip'", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="box" class="clip" data-start="0" data-duration="2">Hello</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["c1"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "timed_element_missing_clip_class");
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not flag audio or video elements", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <audio data-start="0" data-duration="5" src="music.mp3"></audio>
+    <video data-start="0" data-duration="5" src="clip.mp4"></video>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["c1"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "timed_element_missing_clip_class");
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not flag element with only data-track-index (layer container, no timing)", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="layer" data-track-index="0">
+      <div id="box" class="clip" data-start="0" data-duration="2">Hello</div>
+    </div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["c1"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "timed_element_missing_clip_class");
+      expect(finding).toBeUndefined();
+    });
+  });
+
+  describe("overlapping_clips_same_track", () => {
+    it("flags overlapping clips on the same track", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div class="clip" data-start="0" data-duration="3" data-track-index="0">A</div>
+    <div class="clip" data-start="2" data-duration="3" data-track-index="0">B</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["c1"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "overlapping_clips_same_track");
+      expect(finding).toBeDefined();
+      expect(finding?.severity).toBe("error");
+    });
+
+    it("does not flag clips on different tracks", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div class="clip" data-start="0" data-duration="3" data-track-index="0">A</div>
+    <div class="clip" data-start="1" data-duration="3" data-track-index="1">B</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["c1"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "overlapping_clips_same_track");
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not flag sequential clips on the same track", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div class="clip" data-start="0" data-duration="2" data-track-index="0">A</div>
+    <div class="clip" data-start="2" data-duration="2" data-track-index="0">B</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["c1"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "overlapping_clips_same_track");
+      expect(finding).toBeUndefined();
+    });
+  });
+
+  describe("root_composition_missing_html_wrapper", () => {
+    it("flags bare composition div as error", async () => {
+      // Exact scenario from the screenshot — bare div with composition attributes, no HTML wrapper
+      const html = `<div
+  id="comp-main"
+  data-composition-id="no-limits"
+  data-start="0"
+  data-duration="15"
+  data-width="1920"
+  data-height="1080"
+>
+  <!-- Sub-composition: the visual spectacle -->
+  <div
+    id="el-visuals"
+    data-composition-id="visuals"
+    data-composition-src="compositions/visuals.html"
+    data-duration="15"
+    data-track-index="0"
+  ></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 });
+    window.__timelines["no-limits"] = tl;
+  </script>
+</div>`;
+      const result = await lintHyperframeHtml(html, { filePath: "index.html" });
+      const finding = result.findings.find(
+        (f) => f.code === "root_composition_missing_html_wrapper",
+      );
+      expect(finding).toBeDefined();
+      expect(finding?.severity).toBe("error");
+      expect(result.ok).toBe(false);
+    });
+
+    it("does not flag properly wrapped HTML composition", async () => {
+      const html = `<!DOCTYPE html>
+<html><head><meta charset="UTF-8"></head><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10">
+    <div class="clip" data-start="0" data-duration="5">Hello</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["main"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find(
+        (f) => f.code === "root_composition_missing_html_wrapper",
+      );
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not flag composition starting with <html> (no doctype)", async () => {
+      const html = `<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="5"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["main"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find(
+        (f) => f.code === "root_composition_missing_html_wrapper",
+      );
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not flag sub-compositions", async () => {
+      const html = `<div data-composition-id="sub" data-width="1920" data-height="1080">
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["sub"] = gsap.timeline({ paused: true });
+  </script>
+</div>`;
+      const result = await lintHyperframeHtml(html, { isSubComposition: true });
+      const finding = result.findings.find(
+        (f) => f.code === "root_composition_missing_html_wrapper",
+      );
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not flag HTML without composition attributes", async () => {
+      const html = `<div id="hello"><p>Not a composition</p></div>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find(
+        (f) => f.code === "root_composition_missing_html_wrapper",
+      );
+      expect(finding).toBeUndefined();
+    });
+
+    it("includes root tag snippet in finding", async () => {
+      const html = `<div data-composition-id="bare" data-width="1920" data-height="1080">
+  <script>
+    window.__timelines = window.__timelines || {};
+    window.__timelines["bare"] = gsap.timeline({ paused: true });
+  </script>
+</div>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find(
+        (f) => f.code === "root_composition_missing_html_wrapper",
+      );
+      expect(finding).toBeDefined();
+      expect(finding?.snippet).toContain("data-composition-id");
+    });
+  });
+
+  describe("standalone_composition_wrapped_in_template", () => {
+    it("flags root index.html wrapped in template", async () => {
+      const html = `<template id="main-template">
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <script>
+      window.__timelines = window.__timelines || {};
+      window.__timelines["main"] = gsap.timeline({ paused: true });
+    </script>
+  </div>
+</template>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find(
+        (f) => f.code === "standalone_composition_wrapped_in_template",
+      );
+      expect(finding).toBeDefined();
+      expect(finding?.severity).toBe("error");
+    });
+
+    it("does not flag sub-compositions in template", async () => {
+      const html = `<template id="sub-template">
+  <div data-composition-id="sub" data-width="1920" data-height="1080">
+    <script>
+      window.__timelines = window.__timelines || {};
+      window.__timelines["sub"] = gsap.timeline({ paused: true });
+    </script>
+  </div>
+</template>`;
+      const result = await lintHyperframeHtml(html, { isSubComposition: true });
+      const finding = result.findings.find(
+        (f) => f.code === "standalone_composition_wrapped_in_template",
+      );
+      expect(finding).toBeUndefined();
+    });
+  });
+
+  describe("requestanimationframe_in_composition", () => {
+    it("flags requestAnimationFrame usage in script content", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    requestAnimationFrame(() => { console.log("tick"); });
+    window.__timelines["c1"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find(
+        (f) => f.code === "requestanimationframe_in_composition",
+      );
+      expect(finding).toBeDefined();
+      expect(finding?.severity).toBe("error");
+    });
+
+    it("does not flag requestAnimationFrame in comments", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    // requestAnimationFrame(() => { });
+    window.__timelines["c1"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find(
+        (f) => f.code === "requestanimationframe_in_composition",
+      );
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not flag installed registry blocks that use rAF (e.g. particle effects)", async () => {
+      const html =
+        `<!-- hyperframes-registry-item: particles -->\n` +
+        `<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    requestAnimationFrame(function loop() { requestAnimationFrame(loop); });
+    window.__timelines["c1"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find(
+        (f) => f.code === "requestanimationframe_in_composition",
+      );
+      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", async () => {
+      // 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 = await 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)", async () => {
+      // 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 = await 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();
+    });
+  });
+
+  describe("root_composition_missing_data_start", () => {
+    it("does not warn for template-wrapped sub-composition files", async () => {
+      const html = `
+<template id="foo-template">
+  <div data-composition-id="foo" data-width="1920" data-height="1080">
+    <div class="clip" data-start="0" data-duration="1"></div>
+  </div>
+</template>`;
+      const result = await lintHyperframeHtml(html, { isSubComposition: true });
+      const finding = result.findings.find((f) => f.code === "root_composition_missing_data_start");
+      expect(finding).toBeUndefined();
+    });
+  });
+
+  describe("invalid_variable_values_json", () => {
+    it("warns when data-variable-values is unparseable JSON", async () => {
+      const html = `<html><body>
+<div data-composition-id="card-1" data-composition-src="card.html" data-variable-values='{not json'></div>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "invalid_variable_values_json");
+      expect(finding).toBeDefined();
+      expect(finding?.severity).toBe("error");
+    });
+
+    it("warns when data-variable-values is a JSON array (must be an object)", async () => {
+      const html = `<html><body>
+<div data-composition-src="card.html" data-variable-values='[1,2,3]'></div>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "invalid_variable_values_json");
+      expect(finding).toBeDefined();
+      expect(finding?.message).toMatch(/must be a JSON object/);
+    });
+
+    it("warns when data-variable-values is a JSON string (must be an object)", async () => {
+      const html = `<html><body>
+<div data-composition-src="card.html" data-variable-values='"hello"'></div>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "invalid_variable_values_json");
+      expect(finding).toBeDefined();
+    });
+
+    it("does not warn for a valid JSON object", async () => {
+      const html = `<html><body>
+<div data-composition-src="card.html" data-variable-values='{"title":"Hello","count":3}'></div>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "invalid_variable_values_json");
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not warn when data-variable-values is absent", async () => {
+      const html = `<html><body>
+<div data-composition-src="card.html"></div>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "invalid_variable_values_json");
+      expect(finding).toBeUndefined();
+    });
+  });
+
+  describe("invalid_composition_variables_declaration", () => {
+    it("warns when data-composition-variables is unparseable JSON", async () => {
+      const html = `<html data-composition-variables='[{not json'><body><div data-composition-id="x"></div></body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find(
+        (f) => f.code === "invalid_composition_variables_declaration",
+      );
+      expect(finding).toBeDefined();
+    });
+
+    it("warns when data-composition-variables is not an array", async () => {
+      const html = `<html data-composition-variables='{"title":"Hello"}'><body><div data-composition-id="x"></div></body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find(
+        (f) => f.code === "invalid_composition_variables_declaration",
+      );
+      expect(finding).toBeDefined();
+      expect(finding?.message).toMatch(/array of variable declarations/);
+    });
+
+    it("warns per-entry when an entry is missing required fields", async () => {
+      const html = `<html data-composition-variables='[{"id":"ok","type":"string","label":"Ok","default":"x"},{"id":"bad"}]'><body><div data-composition-id="x"></div></body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const findings = result.findings.filter(
+        (f) => f.code === "invalid_composition_variables_declaration",
+      );
+      expect(findings.length).toBe(1);
+      expect(findings[0]?.message).toMatch(/\[1\]/);
+      expect(findings[0]?.message).toMatch(/type|label|default/);
+    });
+
+    it("warns when a declaration uses an unknown type", async () => {
+      const html = `<html data-composition-variables='[{"id":"x","type":"date","label":"X","default":"y"}]'><body><div data-composition-id="x"></div></body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find(
+        (f) => f.code === "invalid_composition_variables_declaration",
+      );
+      expect(finding).toBeDefined();
+      expect(finding?.message).toMatch(/type/);
+    });
+
+    it("does not warn for a fully valid declarations array", async () => {
+      const html = `<html data-composition-variables='[
+        {"id":"title","type":"string","label":"Title","default":"Hello"},
+        {"id":"count","type":"number","label":"Count","default":3},
+        {"id":"theme","type":"enum","label":"Theme","default":"light","options":[{"value":"light","label":"Light"}]}
+      ]'><body><div data-composition-id="x"></div></body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find(
+        (f) => f.code === "invalid_composition_variables_declaration",
+      );
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not warn when data-composition-variables is absent", async () => {
+      const html = `<html><body><div data-composition-id="x"></div></body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find(
+        (f) => f.code === "invalid_composition_variables_declaration",
+      );
+      expect(finding).toBeUndefined();
+    });
+  });
+
+  describe("invalid_parent_traversal_in_asset_path", () => {
+    const RULE_CODE = "invalid_parent_traversal_in_asset_path";
+
+    it("errors when an <img> src uses ../capture/", async () => {
+      const html = `<html><body>
+        <div data-composition-id="x">
+          <img src="../capture/assets/logo.svg" alt="logo">
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+      });
+      const finding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(finding).toBeDefined();
+      expect(finding?.severity).toBe("error");
+      expect(finding?.message).toContain("../capture/");
+    });
+
+    it("errors when a <video> src uses ../assets/ (HF#1698 shape)", async () => {
+      const html = `<html><body>
+        <div data-composition-id="x">
+          <video src="../assets/clip.mp4" muted></video>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+      });
+      const finding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(finding).toBeDefined();
+      expect(finding?.severity).toBe("error");
+      expect(finding?.message).toContain("../assets/");
+    });
+
+    it("errors when a <video> src uses ../../assets/ from a nested compositions/frames/ file", async () => {
+      const html = `<html><body>
+        <div data-composition-id="x">
+          <video src="../../assets/clip.mp4" muted></video>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/frames/scene.html",
+      });
+      const finding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(finding).toBeDefined();
+      expect(finding?.message).toContain("../../assets/");
+    });
+
+    it("errors when a <link> href uses ../fonts/", async () => {
+      const html = `<html><head>
+        <link rel="stylesheet" href="../fonts/brand.css">
+      </head><body>
+        <div data-composition-id="x"></div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+      });
+      const finding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(finding).toBeDefined();
+      expect(finding?.message).toContain("../fonts/");
+    });
+
+    it("errors when a CSS url() uses ../assets/ in a <style> block (counts all occurrences)", async () => {
+      const html = `<html><body>
+        <style>
+          @font-face { font-family: 'Brand'; src: url('../fonts/Brand.woff2'); }
+          .hero { background-image: url('../assets/hero.png'); }
+        </style>
+        <div data-composition-id="x"></div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+      });
+      const finding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(finding).toBeDefined();
+      expect(finding?.message).toContain("2 asset path(s)");
+    });
+
+    it("errors when an inline style url() uses ../assets/", async () => {
+      const html = `<html><body>
+        <div data-composition-id="x">
+          <div style="background-image: url('../assets/hero.png');"></div>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+      });
+      const finding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(finding).toBeDefined();
+      expect(finding?.message).toContain("../assets/");
+    });
+
+    it("does not flag root-relative capture/ paths", async () => {
+      const html = `<html><body>
+        <div data-composition-id="x">
+          <img src="capture/assets/logo.svg" alt="logo">
+        </div>
+        <style>.hero { background-image: url('capture/assets/hero.png'); }</style>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+      });
+      const finding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not flag plain relative asset paths (e.g. assets/x.mp4)", async () => {
+      const html = `<html><body>
+        <div data-composition-id="x">
+          <video src="assets/x.mp4" muted></video>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+      });
+      const finding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not flag absolute URLs", async () => {
+      const html = `<html><body>
+        <div data-composition-id="x">
+          <img src="https://example.com/foo.png">
+          <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
+          <style>.hero { background-image: url('https://example.com/hero.png'); }</style>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+      });
+      const finding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not flag data: URIs", async () => {
+      const html = `<html><body>
+        <div data-composition-id="x">
+          <img src="data:image/png;base64,iVBORw0KGgo=">
+          <style>.hero { background-image: url('data:image/svg+xml,%3Csvg/%3E'); }</style>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+      });
+      const finding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not flag root-relative absolute paths (e.g. /absolute/path.mp4)", async () => {
+      const html = `<html><body>
+        <div data-composition-id="x">
+          <video src="/absolute/path.mp4" muted></video>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+      });
+      const finding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(finding).toBeUndefined();
+    });
+
+    it('does not flag hash refs (e.g. href="#anchor")', async () => {
+      const html = `<html><body>
+        <div data-composition-id="x">
+          <a href="#section">jump</a>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+      });
+      const finding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not flag registry source block files", async () => {
+      const html = `<html><body>
+        <div data-composition-id="x">
+          <img src="../assets/should-be-ignored.png">
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/registry/blocks/data-chart/data-chart.html",
+      });
+      const finding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not flag installed registry blocks", async () => {
+      const html = `<!-- hyperframes-registry-item: data-chart -->\n<html><body>
+        <div data-composition-id="x">
+          <img src="../assets/should-be-ignored.png">
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/data-chart.html",
+      });
+      const finding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(finding).toBeUndefined();
+    });
+
+    it("does not regress under the old code (invalid_capture_path) — the rule was renamed", async () => {
+      const html = `<html><body>
+        <div data-composition-id="x">
+          <img src="../capture/assets/logo.svg" alt="logo">
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        filePath: "/project/compositions/scene.html",
+      });
+      // The old code is gone; the new code subsumes it.
+      const oldFinding = result.findings.find((f) => f.code === "invalid_capture_path");
+      expect(oldFinding).toBeUndefined();
+      const newFinding = result.findings.find((f) => f.code === RULE_CODE);
+      expect(newFinding).toBeDefined();
+    });
+  });
+
+  describe("subcomposition_blanks_before_host", () => {
+    const find = (findings: Array<{ code: string }>) =>
+      findings.find((f) => f.code === "subcomposition_blanks_before_host");
+
+    it("fires on the issue #1540 shape (child shorter than host)", async () => {
+      const html = `<html><body>
+        <div id="root" data-composition-id="main" data-start="0" data-duration="331.224" data-width="1920" data-height="1080">
+          <div id="decision-tree-comp" data-composition-id="decision-tree" data-composition-src="compositions/decision_tree.html" data-start="0" data-duration="15"></div>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      const finding = find(result.findings);
+      expect(finding).toBeDefined();
+      expect(finding?.severity).toBe("warning");
+      expect(finding?.message).toContain("blank");
+      expect(finding?.message).toContain("331.224");
+    });
+
+    it("fires when the mount starts within the start tolerance", async () => {
+      const html = `<html><body>
+        <div id="root" data-composition-id="main" data-start="0" data-duration="60">
+          <div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0.3" data-duration="15"></div>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      expect(find(result.findings)).toBeDefined();
+    });
+
+    it("fires at exactly the start tolerance boundary (start=0.5)", async () => {
+      const html = `<html><body>
+        <div id="root" data-composition-id="main" data-start="0" data-duration="60">
+          <div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0.5" data-duration="15"></div>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      expect(find(result.findings)).toBeDefined();
+    });
+
+    it("stays silent on an intentional short intro followed by another clip", async () => {
+      const html = `<html><body>
+        <div id="root" data-composition-id="main" data-start="0" data-duration="60">
+          <div data-composition-id="intro" data-composition-src="compositions/intro.html" data-start="0" data-duration="15"></div>
+          <div data-composition-id="body" data-composition-src="compositions/body.html" data-start="15" data-duration="45"></div>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      expect(find(result.findings)).toBeUndefined();
+    });
+
+    it("stays silent when the child matches the host window", async () => {
+      const html = `<html><body>
+        <div id="root" data-composition-id="main" data-start="0" data-duration="15">
+          <div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0" data-duration="15"></div>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      expect(find(result.findings)).toBeUndefined();
+    });
+
+    it("stays silent when the child is longer than the host", async () => {
+      const html = `<html><body>
+        <div id="root" data-composition-id="main" data-start="0" data-duration="15">
+          <div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0" data-duration="30"></div>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      expect(find(result.findings)).toBeUndefined();
+    });
+
+    it("stays silent for a non-sub-composition timed element", async () => {
+      const html = `<html><body>
+        <div id="root" data-composition-id="main" data-start="0" data-duration="60">
+          <div class="clip" data-start="0" data-duration="15"></div>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      expect(find(result.findings)).toBeUndefined();
+    });
+
+    it("stays silent when the root has no numeric data-duration", async () => {
+      const html = `<html><body>
+        <div id="root" data-composition-id="main" data-start="0">
+          <div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0" data-duration="15"></div>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      expect(find(result.findings)).toBeUndefined();
+    });
+
+    it("stays silent for a late-starting clip", async () => {
+      const html = `<html><body>
+        <div id="root" data-composition-id="main" data-start="0" data-duration="60">
+          <div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="40" data-duration="5"></div>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      expect(find(result.findings)).toBeUndefined();
+    });
+
+    it("stays silent when an unknown-duration sibling covers the tail", async () => {
+      const html = `<html><body>
+        <div id="root" data-composition-id="main" data-start="0" data-duration="60">
+          <div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0" data-duration="15"></div>
+          <div class="clip" data-start="0"></div>
+        </div>
+      </body></html>`;
+      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
+      expect(find(result.findings)).toBeUndefined();
+    });
+  });
+});
diff --git a/packages/lint/src/rules/composition.ts b/packages/lint/src/rules/composition.ts
new file mode 100644
index 0000000000..4c1ccd1499
--- /dev/null
+++ b/packages/lint/src/rules/composition.ts
@@ -0,0 +1,723 @@
+import type { LintContext, HyperframeLintFinding, ExtractedBlock } from "../context";
+import { findHtmlTag, readAttr, readJsonAttr, stripJsComments, truncateSnippet } from "../utils";
+import { COMPOSITION_VARIABLE_TYPES } from "@hyperframes/parsers";
+
+// Agent guidance thresholds: warning-only nudges for files/tracks that become hard
+// to inspect and revise reliably in a single composition.
+const MAX_COMPOSITION_LINES = 300;
+const MAX_TIMED_ELEMENTS_PER_TRACK = 3;
+const TRACK_DENSITY_EXEMPT_TAGS = new Set(["audio", "script", "style", "video"]);
+
+function countPhysicalLines(source: string): number {
+  if (source.length === 0) return 0;
+
+  const normalized = source.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const withoutFinalNewline = normalized.endsWith("\n") ? normalized.slice(0, -1) : normalized;
+  return withoutFinalNewline.split("\n").length;
+}
+
+function countStructuralLines(source: string): number {
+  return countPhysicalLines(source.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "<style></style>"));
+}
+
+export function isRegistrySourceFile(filePath?: string): boolean {
+  if (!filePath) return false;
+
+  const normalized = filePath.replace(/\\/g, "/");
+  return /(?:^|\/)registry\/blocks\/([^/]+)\/\1\.html$/i.test(normalized);
+}
+
+export function isRegistryInstalledFile(rawSource: string): boolean {
+  return /^\s*<!--\s*hyperframes-registry-item:[^>]*-->/i.test(rawSource.slice(0, 512));
+}
+
+function isCompositionRootOrMount(rawTag: string): boolean {
+  return Boolean(
+    readAttr(rawTag, "data-composition-id") || readAttr(rawTag, "data-composition-src"),
+  );
+}
+
+// Asset references inside CSS `url(...)`/`url("...")`/`url('...')` functions.
+// Returns the inner path without quotes; comments are stripped first so
+// `/* url(foo) */` is ignored. Bare `url()` and `data:` are excluded by the
+// rules that consume this — the helper just yields raw URL values.
+function extractCssUrlReferences(css: string): string[] {
+  const out: string[] = [];
+  const noComments = css.replace(/\/\*[\s\S]*?\*\//g, "");
+  const urlPattern = /\burl\(\s*(["']?)([^)"']+)\1\s*\)/g;
+  let m: RegExpExecArray | null;
+  while ((m = urlPattern.exec(noComments)) !== null) {
+    const raw = (m[2] ?? "").trim();
+    if (raw) out.push(raw);
+  }
+  return out;
+}
+
+// Top-level CSS selectors (comma-split) in a stylesheet, skipping at-rule headers
+// (@media/@keyframes/...) and keyframe stops. Heuristic — the lint layer has no
+// full CSS parser, and rules elsewhere in this file scan CSS the same way.
+function extractCssSelectors(css: string): string[] {
+  const out: string[] = [];
+  const noComments = css.replace(/\/\*[\s\S]*?\*\//g, "");
+  const ruleHeader = /([^{}]+)\{/g;
+  let m: RegExpExecArray | null;
+  while ((m = ruleHeader.exec(noComments)) !== null) {
+    const header = (m[1] ?? "").trim();
+    if (!header || header.startsWith("@")) continue;
+    for (const sel of header.split(",")) {
+      const s = sel.trim();
+      if (s) out.push(s);
+    }
+  }
+  return out;
+}
+
+// Class tokens in a selector's leftmost compound (before the first descendant /
+// child / sibling combinator). `.frame .title` → ["frame"]; `.a.b > .c` → ["a","b"].
+function leftmostCompoundClasses(selector: string): string[] {
+  const leftmost = selector.trim().split(/[\s>+~]+/)[0] ?? "";
+  return (leftmost.match(/\.([\w-]+)/g) ?? []).map((c) => c.slice(1));
+}
+
+// Distinct selectors across all <style> blocks whose leftmost compound keys off one
+// of the root element's own classes — the ones that break under id-scoping.
+function rootClassStyledSelectors(styles: ExtractedBlock[], rootClasses: string[]): string[] {
+  const offenders: string[] = [];
+  for (const style of styles) {
+    for (const selector of extractCssSelectors(style.content)) {
+      const hitsRoot = leftmostCompoundClasses(selector).some((c) => rootClasses.includes(c));
+      if (hitsRoot && !offenders.includes(selector)) offenders.push(selector);
+    }
+  }
+  return offenders;
+}
+
+export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
+  // invalid_parent_traversal_in_asset_path — catches `../` traversal in src,
+  // href, inline-style url(), and <style> url() asset references on
+  // compositions. Sub-compositions live under compositions/ but are served
+  // with the project root as their base URL, so any `../`-traversing path
+  // climbs above the project root and 404s in Studio preview. Renders
+  // tolerate it because the server-side bundler rewrites `../foo` against
+  // each sub-composition's source path; the runtime now mirrors that fallback
+  // (see rewriteSubCompositionAssetPaths in runtime/compositionLoader.ts), but
+  // the authoring-time signal is still wrong — flag it at lint time so the
+  // baked path is plain root-relative and matches what the bundler emits.
+  //
+  // Mirrors the runtime fallback's surface: `[src]` / `[href]` attribute
+  // values, `[style]` inline url(), and `<style>` block url() references.
+  // Skips absolute URLs (http(s)://, //, data:, /-prefixed root-relative),
+  // hash anchors, and plain relative paths (`assets/x.mp4`) — only `../`
+  // traversal is flagged. Subsumes the older `../capture/`-specific rule.
+  // fallow-ignore-next-line complexity
+  ({ tags, styles, rawSource, options }) => {
+    if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
+
+    const offenders: string[] = [];
+    const collect = (value: string | null) => {
+      if (!value) return;
+      const trimmed = value.trim();
+      if (!trimmed.startsWith("../") && trimmed !== "..") return;
+      offenders.push(trimmed);
+    };
+
+    for (const tag of tags) {
+      collect(readAttr(tag.raw, "src"));
+      collect(readAttr(tag.raw, "href"));
+      // Use readJsonAttr for `style` — inline url('...') values contain the
+      // opposite quote, which readAttr's [^"']+ class would truncate.
+      const styleAttr = readJsonAttr(tag.raw, "style");
+      if (styleAttr) {
+        for (const url of extractCssUrlReferences(styleAttr)) collect(url);
+      }
+    }
+    for (const style of styles) {
+      for (const url of extractCssUrlReferences(style.content)) collect(url);
+    }
+
+    if (offenders.length === 0) return [];
+
+    // Group counts by leading path token (e.g. ../capture/, ../assets/, ../../assets/)
+    // so the message names the offending prefixes instead of a bare count.
+    const prefixCounts = new Map<string, number>();
+    for (const path of offenders) {
+      const prefix = path.match(/^(?:\.\.\/)+[^/]+\//)?.[0] ?? path;
+      prefixCounts.set(prefix, (prefixCounts.get(prefix) ?? 0) + 1);
+    }
+    const prefixSummary = Array.from(prefixCounts.entries())
+      .sort(([, a], [, b]) => b - a)
+      .map(([prefix, count]) => (count > 1 ? `${prefix} (${count})` : prefix))
+      .join(", ");
+
+    return [
+      {
+        code: "invalid_parent_traversal_in_asset_path",
+        severity: "error",
+        message:
+          `Found ${offenders.length} asset path(s) traversing above the project root with "../" ` +
+          `(${prefixSummary}). Renders rewrite this against each sub-composition's source path, but Studio preview and other live consumers resolve against the project root and 404.`,
+        fixHint:
+          'Use plain root-relative paths (e.g. "assets/...", "capture/...", "fonts/...") — compositions are served with the project root as their base URL, so paths must be root-relative, not relative to the compositions/ directory.',
+      },
+    ];
+  },
+
+  // composition_file_too_large
+  ({ rawSource, options }) => {
+    if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
+
+    const lineCount = countStructuralLines(rawSource);
+    if (lineCount <= MAX_COMPOSITION_LINES) return [];
+
+    const splitTarget = options.isSubComposition
+      ? "Split this sub-composition further into smaller .html files"
+      : "Split coherent scenes or layers into separate .html files under compositions/";
+
+    return [
+      {
+        code: "composition_file_too_large",
+        severity: "warning",
+        message: `This HTML composition file has ${lineCount} lines. Smaller sub-compositions are easier to read, iterate on, and diff.`,
+        fixHint: `${splitTarget}, then mount them from the parent with data-composition-src so each file stays small enough to inspect, revise, and validate independently.`,
+      },
+    ];
+  },
+
+  // timeline_track_too_dense
+  // fallow-ignore-next-line complexity
+  ({ tags, options }) => {
+    const trackCounts = new Map<string, number>();
+    for (const tag of tags) {
+      if (TRACK_DENSITY_EXEMPT_TAGS.has(tag.name)) continue;
+      if (isCompositionRootOrMount(tag.raw)) continue;
+      if (!readAttr(tag.raw, "data-start")) continue;
+
+      const track = readAttr(tag.raw, "data-track-index");
+      if (!track) continue;
+      trackCounts.set(track, (trackCounts.get(track) ?? 0) + 1);
+    }
+
+    const findings: HyperframeLintFinding[] = [];
+    for (const [track, count] of trackCounts) {
+      if (count <= MAX_TIMED_ELEMENTS_PER_TRACK) continue;
+      const splitTarget = options.isSubComposition
+        ? "Move coherent scene groups into smaller .html files"
+        : "Move coherent scene groups into separate .html files under compositions/";
+      findings.push({
+        code: "timeline_track_too_dense",
+        severity: "warning",
+        message: `Track ${track} has ${count} timed elements in this HTML file. Smaller sub-compositions keep timelines easier to read, iterate on, and diff.`,
+        fixHint: `${splitTarget} and mount them from the parent with data-composition-src so the timeline stays easier to inspect, revise, and validate.`,
+      });
+    }
+
+    return findings;
+  },
+
+  // timed_element_missing_visibility_hidden
+  // fallow-ignore-next-line complexity
+  ({ tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const tag of tags) {
+      if (tag.name === "audio" || tag.name === "script" || tag.name === "style") continue;
+      if (!readAttr(tag.raw, "data-start")) continue;
+      if (readAttr(tag.raw, "data-composition-id")) continue;
+      if (readAttr(tag.raw, "data-composition-src")) continue;
+      const classAttr = readAttr(tag.raw, "class") || "";
+      const styleAttr = readAttr(tag.raw, "style") || "";
+      const hasClip = classAttr.split(/\s+/).includes("clip");
+      const hasHiddenStyle =
+        /visibility\s*:\s*hidden/i.test(styleAttr) || /opacity\s*:\s*0/i.test(styleAttr);
+      if (!hasClip && !hasHiddenStyle) {
+        const elementId = readAttr(tag.raw, "id") || undefined;
+        findings.push({
+          code: "timed_element_missing_visibility_hidden",
+          severity: "info",
+          message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has data-start but no class="clip", visibility:hidden, or opacity:0. Consider adding initial hidden state if the element should not be visible before its start time.`,
+          elementId,
+          fixHint:
+            'Add class="clip" (with CSS: .clip { visibility: hidden; }) or style="opacity:0" if the element should start hidden.',
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+    }
+    return findings;
+  },
+
+  // deprecated_data_layer + deprecated_data_end
+  // fallow-ignore-next-line complexity
+  ({ tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const tag of tags) {
+      if (readAttr(tag.raw, "data-layer") && !readAttr(tag.raw, "data-track-index")) {
+        const elementId = readAttr(tag.raw, "id") || undefined;
+        findings.push({
+          code: "deprecated_data_layer",
+          severity: "error",
+          message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses data-layer instead of data-track-index.`,
+          elementId,
+          fixHint: "Replace data-layer with data-track-index. The runtime reads data-track-index.",
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+      if (readAttr(tag.raw, "data-end") && !readAttr(tag.raw, "data-duration")) {
+        const elementId = readAttr(tag.raw, "id") || undefined;
+        findings.push({
+          code: "deprecated_data_end",
+          severity: "error",
+          message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses data-end without data-duration. Use data-duration in source HTML.`,
+          elementId,
+          fixHint:
+            "Replace data-end with data-duration. The compiler generates data-end from data-duration automatically.",
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+    }
+    return findings;
+  },
+
+  // split_data_attribute_selector
+  ({ scripts, styles }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const splitDataAttrSelectorPattern =
+      /\[data-composition-id=(["'])([^"'\]]+)\1\s+(data-[\w:-]+)=(["'])([^"'\]]*)\4\]/g;
+    const scan = (content: string) => {
+      splitDataAttrSelectorPattern.lastIndex = 0;
+      let match: RegExpExecArray | null;
+      while ((match = splitDataAttrSelectorPattern.exec(content)) !== null) {
+        const compId = match[2] ?? "";
+        const attrName = match[3] ?? "";
+        const attrValue = match[5] ?? "";
+        findings.push({
+          code: "split_data_attribute_selector",
+          severity: "error",
+          message:
+            `Selector "${match[0]}" combines two attributes inside one CSS attribute selector. ` +
+            "Browsers reject it, so GSAP timelines or querySelector calls will fail before registering.",
+          selector: match[0],
+          fixHint: `Use separate attribute selectors: [data-composition-id="${compId}"][${attrName}="${attrValue}"].`,
+          snippet: truncateSnippet(match[0]),
+        });
+      }
+    };
+    for (const style of styles) scan(style.content);
+    for (const script of scripts) scan(script.content);
+    return findings;
+  },
+
+  // template_literal_selector
+  ({ scripts }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const script of scripts) {
+      const templateLiteralSelectorPattern =
+        /(?:querySelector|querySelectorAll)\s*\(\s*`[^`]*\$\{[^}]+\}[^`]*`\s*\)/g;
+      let tlMatch: RegExpExecArray | null;
+      while ((tlMatch = templateLiteralSelectorPattern.exec(script.content)) !== null) {
+        findings.push({
+          code: "template_literal_selector",
+          severity: "error",
+          message:
+            "querySelector uses a template literal variable (e.g. `${compId}`). " +
+            "The HTML bundler's CSS parser crashes on these. Use a hardcoded string instead.",
+          fixHint:
+            "Replace the template literal variable with a hardcoded string. The bundler's CSS parser cannot handle interpolated variables in script content.",
+          snippet: truncateSnippet(tlMatch[0]),
+        });
+      }
+    }
+    return findings;
+  },
+
+  // timed_element_missing_clip_class
+  // fallow-ignore-next-line complexity
+  ({ tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const skipTags = new Set(["audio", "video", "script", "style", "template"]);
+    for (const tag of tags) {
+      if (skipTags.has(tag.name)) continue;
+      // Skip composition hosts
+      if (readAttr(tag.raw, "data-composition-id")) continue;
+      if (readAttr(tag.raw, "data-composition-src")) continue;
+
+      const hasStart = readAttr(tag.raw, "data-start") !== null;
+      const hasDuration = readAttr(tag.raw, "data-duration") !== null;
+      // data-track-index alone marks a layer container, not a time-bounded clip
+      if (!hasStart && !hasDuration) continue;
+
+      const classAttr = readAttr(tag.raw, "class") || "";
+      const hasClip = classAttr.split(/\s+/).includes("clip");
+      if (hasClip) continue;
+
+      const elementId = readAttr(tag.raw, "id") || undefined;
+      findings.push({
+        code: "timed_element_missing_clip_class",
+        severity: "error",
+        message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has timing attributes but no class="clip". The element will be visible for the entire composition instead of only during its scheduled time range.`,
+        elementId,
+        fixHint:
+          'Add class="clip" to the element. The HyperFrames runtime uses .clip to control visibility based on data-start/data-duration.',
+        snippet: truncateSnippet(tag.raw),
+      });
+    }
+    return findings;
+  },
+
+  // overlapping_clips_same_track
+  // fallow-ignore-next-line complexity
+  ({ tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+
+    type ClipInfo = { start: number; end: number; elementId?: string; snippet: string };
+    const trackMap = new Map<string, ClipInfo[]>();
+
+    for (const tag of tags) {
+      const startStr = readAttr(tag.raw, "data-start");
+      const durationStr = readAttr(tag.raw, "data-duration");
+      const trackStr = readAttr(tag.raw, "data-track-index");
+      if (!startStr || !durationStr || !trackStr) continue;
+
+      const start = Number(startStr);
+      const duration = Number(durationStr);
+      const track = trackStr;
+
+      // Skip non-numeric (relative timing references like "intro-comp")
+      if (Number.isNaN(start) || Number.isNaN(duration)) continue;
+
+      const clips = trackMap.get(track) || [];
+      clips.push({
+        start,
+        end: start + duration,
+        elementId: readAttr(tag.raw, "id") || undefined,
+        snippet: truncateSnippet(tag.raw) || "",
+      });
+      trackMap.set(track, clips);
+    }
+
+    for (const [track, clips] of trackMap) {
+      clips.sort((a, b) => a.start - b.start);
+      for (let i = 0; i < clips.length - 1; i++) {
+        const current = clips[i];
+        const next = clips[i + 1];
+        if (!current || !next) continue;
+        if (current.end > next.start) {
+          findings.push({
+            code: "overlapping_clips_same_track",
+            severity: "error",
+            message: `Track ${track}: clip ending at ${current.end}s overlaps with clip starting at ${next.start}s. Overlapping clips on the same track cause rendering conflicts.`,
+            fixHint:
+              "Adjust data-start or data-duration so clips on the same track do not overlap, or move one clip to a different data-track-index.",
+          });
+        }
+      }
+    }
+
+    return findings;
+  },
+
+  // root_composition_missing_data_start
+  ({ rootTag, options }) => {
+    const findings: HyperframeLintFinding[] = [];
+    if (options.isSubComposition) return findings;
+    if (!rootTag) return findings;
+    const compId = readAttr(rootTag.raw, "data-composition-id");
+    if (!compId) return findings;
+    const hasStart = readAttr(rootTag.raw, "data-start") !== null;
+    if (!hasStart) {
+      findings.push({
+        code: "root_composition_missing_data_start",
+        severity: "error",
+        message: `Root composition "${compId}" is missing data-start. The runtime needs data-start="0" on the root element to begin playback.`,
+        fixHint: 'Add data-start="0" to the root composition element.',
+        snippet: truncateSnippet(rootTag.raw),
+      });
+    }
+    return findings;
+  },
+
+  // standalone_composition_wrapped_in_template
+  ({ rawSource, options }) => {
+    const findings: HyperframeLintFinding[] = [];
+    if (options.isSubComposition) return findings;
+    const trimmed = rawSource.trimStart().toLowerCase();
+    if (trimmed.startsWith("<template")) {
+      findings.push({
+        code: "standalone_composition_wrapped_in_template",
+        severity: "error",
+        message:
+          "Root index.html is wrapped in a <template> tag. " +
+          "Only sub-compositions loaded via data-composition-src should use <template> wrappers. " +
+          "The runtime cannot play a standalone composition inside a template.",
+        fixHint:
+          "Remove the <template> wrapper. Use <!DOCTYPE html><html>...<div data-composition-id>...</div>...</html> instead.",
+      });
+    }
+    return findings;
+  },
+
+  // root_composition_missing_html_wrapper
+  ({ rawSource, rootTag, options }) => {
+    const findings: HyperframeLintFinding[] = [];
+    if (options.isSubComposition) return findings;
+    const trimmed = rawSource.trimStart().toLowerCase();
+    // Compositions inside <template> are caught by standalone_composition_wrapped_in_template
+    if (trimmed.startsWith("<template")) return findings;
+    const hasDoctype = trimmed.startsWith("<!doctype") || trimmed.startsWith("<html");
+    const hasComposition = rawSource.includes("data-composition-id");
+    if (hasComposition && !hasDoctype) {
+      findings.push({
+        code: "root_composition_missing_html_wrapper",
+        severity: "error",
+        message:
+          "Composition starts with a bare element instead of a proper HTML document. " +
+          "An index.html that contains data-composition-id but no <!DOCTYPE html>, <html>, or <body> " +
+          "is a fragment — browsers quirks-mode it, the preview server cannot load it, and " +
+          "the bundler will fail to inject runtime scripts.",
+        fixHint:
+          'Wrap the composition in <!DOCTYPE html><html><head><meta charset="UTF-8"></head><body>...</body></html>.',
+        snippet: rootTag ? truncateSnippet(rootTag.raw) : undefined,
+      });
+    }
+    return findings;
+  },
+
+  // requestanimationframe_in_composition
+  ({ scripts, rawSource, options }) => {
+    if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
+    const findings: HyperframeLintFinding[] = [];
+    for (const script of scripts) {
+      const stripped = stripJsComments(script.content);
+      if (/requestAnimationFrame\s*\(/.test(stripped)) {
+        findings.push({
+          code: "requestanimationframe_in_composition",
+          severity: "error",
+          message:
+            "`requestAnimationFrame` runs on wall-clock time, not the GSAP timeline. It will not sync with frame capture and may cause flickering or missed frames during rendering.",
+          fixHint:
+            "Use GSAP tweens or onUpdate callbacks instead of requestAnimationFrame for animation logic.",
+          snippet: truncateSnippet(script.content),
+        });
+      }
+    }
+    return findings;
+  },
+
+  // invalid_variable_values_json
+  // Host elements (`[data-composition-src]`) carry per-instance values via
+  // `data-variable-values`. The runtime swallows JSON errors silently and
+  // falls back to declared defaults, which masks typos. This rule surfaces
+  // the parse failure so authors notice before render time.
+  // fallow-ignore-next-line complexity
+  ({ tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const tag of tags) {
+      const raw = readJsonAttr(tag.raw, "data-variable-values");
+      if (!raw) continue;
+
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : "unknown";
+        findings.push({
+          code: "invalid_variable_values_json",
+          severity: "error",
+          message: `data-variable-values is not valid JSON (${reason}).`,
+          fixHint:
+            'Wrap the attribute value in single quotes and the JSON keys/values in double quotes, e.g. data-variable-values=\'{"title":"Hello"}\'.',
+          elementId: readAttr(tag.raw, "id") || undefined,
+          snippet: truncateSnippet(tag.raw),
+        });
+        continue;
+      }
+
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        findings.push({
+          code: "invalid_variable_values_json",
+          severity: "error",
+          message:
+            'data-variable-values must be a JSON object keyed by variable id (e.g. {"title":"Hello"}).',
+          fixHint:
+            "Replace the value with a JSON object whose keys are variable ids declared in the sub-composition's data-composition-variables.",
+          elementId: readAttr(tag.raw, "id") || undefined,
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+    }
+    return findings;
+  },
+
+  // invalid_composition_variables_declaration
+  // The runtime parses `data-composition-variables` and silently returns []
+  // on any structural problem. Surface JSON / shape failures so authors
+  // catch them at lint time rather than wondering why their `getVariables()`
+  // defaults aren't applied.
+  // fallow-ignore-next-line complexity
+  ({ source }) => {
+    const htmlTag = findHtmlTag(source);
+    if (!htmlTag) return [];
+    const raw = readJsonAttr(htmlTag.raw, "data-composition-variables");
+    if (!raw) return [];
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : "unknown";
+      return [
+        {
+          code: "invalid_composition_variables_declaration",
+          severity: "error",
+          message: `data-composition-variables is not valid JSON (${reason}).`,
+          fixHint:
+            'Provide a JSON array of variable declarations: data-composition-variables=\'[{"id":"title","type":"string","label":"Title","default":"Hello"}]\'.',
+          snippet: truncateSnippet(htmlTag.raw),
+        },
+      ];
+    }
+
+    if (!Array.isArray(parsed)) {
+      return [
+        {
+          code: "invalid_composition_variables_declaration",
+          severity: "error",
+          message: "data-composition-variables must be a JSON array of variable declarations.",
+          fixHint:
+            'Wrap declarations in [] and give each an id, type, label, and default: \'[{"id":"title","type":"string","label":"Title","default":"Hello"}]\'.',
+          snippet: truncateSnippet(htmlTag.raw),
+        },
+      ];
+    }
+
+    const findings: HyperframeLintFinding[] = [];
+    const knownTypes = new Set<string>(COMPOSITION_VARIABLE_TYPES);
+    for (let i = 0; i < parsed.length; i += 1) {
+      const entry = parsed[i];
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        findings.push({
+          code: "invalid_composition_variables_declaration",
+          severity: "error",
+          message: `data-composition-variables entry [${i}] must be an object with id, type, label, and default.`,
+          snippet: truncateSnippet(htmlTag.raw),
+        });
+        continue;
+      }
+      const e = entry as Record<string, unknown>;
+      const missing: string[] = [];
+      if (typeof e.id !== "string") missing.push("id");
+      if (typeof e.type !== "string" || !knownTypes.has(e.type)) missing.push("type");
+      if (typeof e.label !== "string") missing.push("label");
+      if (!("default" in e)) missing.push("default");
+      if (missing.length > 0) {
+        findings.push({
+          code: "invalid_composition_variables_declaration",
+          severity: "error",
+          message: `data-composition-variables entry [${i}] is missing or has invalid: ${missing.join(", ")}. Type must be one of string, number, color, boolean, enum, font, image.`,
+          snippet: truncateSnippet(htmlTag.raw),
+        });
+      }
+    }
+    return findings;
+  },
+
+  // subcomposition_blanks_before_host
+  // Warns when a full-bleed sub-composition slot ends before the host composition
+  // does, leaving the slot blank for the remainder (issue #1540). Scoped narrowly to
+  // the high-signal shape — a sole/dominant external mount starting at ~0 — so it
+  // stays silent on intentional short clips (an intro followed by other clips that
+  // carry the timeline forward).
+  // fallow-ignore-next-line complexity
+  ({ tags, rootTag }) => {
+    if (!rootTag) return [];
+    const rootDuration = Number(readAttr(rootTag.raw, "data-duration"));
+    if (!Number.isFinite(rootDuration) || rootDuration <= 0) return [];
+
+    // Two independent knobs that happen to share a 0.5s magnitude. Tuned for
+    // real hosts (tens to hundreds of seconds); on a very short host (~6s) the
+    // EPSILON slack would let a ~10% blank tail pass unflagged — acceptable
+    // because the silent-blank trap this rule targets only matters at scale.
+    const EPSILON = 0.5; // seconds; tolerance for "ends/covers near the host end"
+    const START_TOLERANCE = 0.5; // seconds; "starts at the composition start"
+    const round3 = (n: number) => Math.round(n * 1000) / 1000;
+
+    // Timed children of the root. An element with data-start but no usable
+    // data-duration is treated as covering the tail (end = Infinity), so an
+    // unknown-length sibling suppresses the warning rather than triggering it.
+    const timed = tags
+      .filter((tag) => tag.index !== rootTag.index && readAttr(tag.raw, "data-start") !== null)
+      .map((tag) => {
+        const start = Number(readAttr(tag.raw, "data-start")) || 0;
+        const dur = Number(readAttr(tag.raw, "data-duration"));
+        const end = Number.isFinite(dur) && dur > 0 ? start + dur : Infinity;
+        return { tag, start, end };
+      });
+
+    // `tags` is a flat list (no nesting depth), so a timed element nested
+    // *inside* a candidate slot is treated as a tail-covering sibling rather
+    // than a descendant. Acceptable: external src mounts are empty by
+    // convention (content is loaded from the linked file), so the only
+    // false-negative path is rare and matches the flat-tag scope of the
+    // sibling rules in this file.
+    const tailCovered = (exceptIndex: number) =>
+      timed.some((t) => t.tag.index !== exceptIndex && t.end >= rootDuration - EPSILON);
+
+    const findings: HyperframeLintFinding[] = [];
+    for (const t of timed) {
+      if (readAttr(t.tag.raw, "data-composition-src") === null) continue; // external slot only
+      if (t.start > START_TOLERANCE) continue; // must start at the composition start
+      if (!Number.isFinite(t.end)) continue; // known, finite slot length
+      if (t.end >= rootDuration - EPSILON) continue; // already fills the host window
+      if (tailCovered(t.tag.index)) continue; // another clip covers the tail — not full-bleed
+      const elementId = readAttr(t.tag.raw, "id") || undefined;
+      const gap = round3(rootDuration - t.end);
+      findings.push({
+        code: "subcomposition_blanks_before_host",
+        severity: "warning",
+        message: `<${t.tag.name}${elementId ? ` id="${elementId}"` : ""}> sub-composition ends at ${round3(t.end)}s but the composition runs to ${round3(rootDuration)}s — its slot will be blank for ~${gap}s.`,
+        elementId,
+        fixHint: `data-duration is the slot's visible window. Set this sub-composition's data-duration to ${round3(rootDuration - t.start)} to fill the host window, or add another clip to cover the remaining ~${gap}s.`,
+        snippet: truncateSnippet(t.tag.raw),
+      });
+    }
+    return findings;
+  },
+
+  // subcomposition_root_styled_by_class
+  // A sub-composition's <style> is scoped at render time to
+  // `[data-composition-id="<id>"] <selector>` so scenes inlined into one document
+  // can't leak styles into each other. A rule whose LEFTMOST selector is the ROOT
+  // element's own class (e.g. `.frame { ... }` on the same element that carries
+  // data-composition-id) therefore becomes a DESCENDANT selector that can never
+  // match the root — the whole scene renders unstyled (tiny text top-left, images
+  // at natural size). lint/validate/inspect evaluate the file in isolation (no
+  // scoping) and Studio previews each scene in its own iframe (no scoping), so the
+  // break is invisible until the composited MP4 render. Style the root via `#root`
+  // (the scoper special-cases the root id) and descendants via plain selectors,
+  // like the registry blocks — the runtime already scopes each scene by id, so a
+  // class namespace on the root is redundant.
+  ({ rootTag, rootCompositionId, styles, options }) => {
+    if (!options.isSubComposition) return [];
+    if (isRegistrySourceFile(options.filePath)) return [];
+    if (!rootTag || !rootCompositionId) return [];
+
+    const rootClasses = (readAttr(rootTag.raw, "class") || "").split(/\s+/).filter(Boolean);
+    if (rootClasses.length === 0) return [];
+
+    const offenders = rootClassStyledSelectors(styles, rootClasses);
+    if (offenders.length === 0) return [];
+
+    const example = offenders.slice(0, 3).join(", ");
+    return [
+      {
+        code: "subcomposition_root_styled_by_class",
+        severity: "error",
+        message:
+          `Root element has class="${rootClasses.join(" ")}" and is styled by ${offenders.length} rule(s) keyed off that class (e.g. ${example}). ` +
+          `At render, every sub-composition rule is scoped to [data-composition-id="${rootCompositionId}"] <selector>, so a selector whose leftmost part is the ROOT's own class becomes a descendant selector that cannot match the root — the scene renders unstyled (tiny text top-left, full-size images). ` +
+          `lint/validate/inspect and Studio's per-frame iframe preview do not scope, so this passes every static check and looks correct in preview.`,
+        selector: example,
+        fixHint: `Give the root id="root" and style it with \`#root { ... }\` plus plain descendant selectors (\`.kicker\`, \`#hero\`) — the runtime already scopes each sub-composition by data-composition-id, so a class namespace on the root is redundant and breaks under scoping.`,
+        snippet: truncateSnippet(rootTag.raw),
+      },
+    ];
+  },
+];
diff --git a/packages/lint/src/rules/core.test.ts b/packages/lint/src/rules/core.test.ts
new file mode 100644
index 0000000000..e30f8f74b1
--- /dev/null
+++ b/packages/lint/src/rules/core.test.ts
@@ -0,0 +1,730 @@
+import { describe, it, expect } from "vitest";
+import { lintHyperframeHtml } from "../hyperframeLinter.js";
+
+function compositionWithHead(headContent: string): string {
+  return `
+<html>
+<head>
+${headContent}
+</head>
+<body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
+  <script>window.__timelines = {};</script>
+</body>
+</html>`;
+}
+
+function compositionWithHeadBoundary(boundaryContent: string): string {
+  return `
+<html>
+<head>
+  <style>
+    body { margin: 0; }
+  </style>
+</head>
+${boundaryContent}
+<body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
+  <script>window.__timelines = {};</script>
+</body>
+</html>`;
+}
+
+function compositionWithBodyPrefix(prefixContent: string, rootContent = ""): string {
+  return `
+<html>
+<head>
+  <style>
+    body { margin: 0; }
+  </style>
+</head>
+<body>
+${prefixContent}
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+${rootContent}
+  </div>
+  <script>window.__timelines = {};</script>
+</body>
+</html>`;
+}
+
+function compositionWithImplicitBodyPrefix(prefixContent: string): string {
+  return `
+<html>
+<head>
+  <style>
+    body { margin: 0; }
+  </style>
+</head>
+${prefixContent}
+<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
+<script>window.__timelines = {};</script>
+</html>`;
+}
+
+function templateCompositionWithHead(headContent: string): string {
+  return `
+<template>
+  <html>
+    <head>
+${headContent}
+    </head>
+    <body>
+      <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
+    </body>
+  </html>
+</template>`;
+}
+
+describe("core rules", () => {
+  it("reports error when root is missing data-composition-id", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-width="1920" data-height="1080"></div>
+  <script>window.__timelines = {};</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "root_missing_composition_id");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+  });
+
+  it("reports error when root is missing data-width or data-height", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1"></div>
+  <script>window.__timelines = {};</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "root_missing_dimensions");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+  });
+
+  it("accepts body as the composition root", async () => {
+    const html = `
+<html><body data-composition-id="c1" data-width="1920" data-height="1080">
+  <div id="overlay-flash"></div>
+  <script>window.__timelines = window.__timelines || {};</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    expect(result.findings.find((f) => f.code === "root_missing_composition_id")).toBeUndefined();
+    expect(result.findings.find((f) => f.code === "root_missing_dimensions")).toBeUndefined();
+  });
+
+  it("reports error when timeline registry is missing", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080"></div>
+  <script>
+    const tl = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "missing_timeline_registry");
+    expect(finding).toBeDefined();
+  });
+
+  it("does not flag missing_timeline_registry on a sub-composition (inherits from host)", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080"></div>
+  <script>
+    const tl = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html, { isSubComposition: true });
+    const finding = result.findings.find((f) => f.code === "missing_timeline_registry");
+    expect(finding).toBeUndefined();
+  });
+
+  it("reports error for composition host missing data-composition-id", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="host1" data-composition-src="child.html"></div>
+  </div>
+  <script>window.__timelines = {};</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "host_missing_composition_id");
+    expect(finding).toBeDefined();
+  });
+
+  it("reports error when timeline registry is assigned without initializing", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="stage"></div>
+  </div>
+  <script>
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#stage", { opacity: 1, duration: 1 }, 0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "timeline_registry_missing_init");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.message).toContain("without initializing");
+  });
+
+  it("reports error when dot timeline registry is assigned without initializing", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="stage"></div>
+  </div>
+  <script>
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#stage", { opacity: 1, duration: 1 }, 0);
+    window.__timelines.c1 = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "timeline_registry_missing_init");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+  });
+
+  it("does not flag timeline assignment when init guard is present", async () => {
+    const validComposition = `
+<html>
+<body>
+  <div id="root" data-composition-id="comp-1" data-width="1920" data-height="1080">
+    <div id="stage"></div>
+  </div>
+  <script src="https://cdn.gsap.com/gsap.min.js"></script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#stage", { opacity: 1, duration: 1 }, 0);
+    window.__timelines["comp-1"] = tl;
+  </script>
+</body>
+</html>`;
+    const result = await lintHyperframeHtml(validComposition);
+    const finding = result.findings.find((f) => f.code === "timeline_registry_missing_init");
+    expect(finding).toBeUndefined();
+  });
+
+  it("reports error when CSS text is left outside a style block in the document head", async () => {
+    const html = compositionWithHead(`
+  <style>
+    body { margin: 0; }
+  </style>
+  </style>
+  /* Decorative Elements */
+  .particle {
+    position: absolute;
+    width: 4px;
+    height: 4px;
+    background: #fff;
+  }
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.message).toContain("<head>");
+    expect(finding?.snippet).toContain(".particle");
+  });
+
+  it("reports error when CSS variables leak between head and body", async () => {
+    const html = compositionWithHeadBoundary(`
+  --bg-color: #F5F1E8;
+  --text-color: #212121;
+}
+
+body {
+  background-color: var(--bg-color);
+  color: var(--text-color);
+}
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.message).toContain("<head>");
+    expect(finding?.snippet).toContain("body");
+  });
+
+  it("reports error when stray close tags leak between head and body", async () => {
+    const html = compositionWithHeadBoundary(`
+  </style>
+  </script>
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.snippet).toContain("</style>");
+  });
+
+  it("reports error when markdown code fences leak between head and body", async () => {
+    const html = compositionWithHeadBoundary(`
+  \`\`\`css
+  .particle {
+    color: white;
+  }
+  \`\`\`
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.snippet).toContain("```css");
+  });
+
+  it("reports error when CSS at-rules leak between head and body", async () => {
+    const html = compositionWithHeadBoundary(`
+  @media (min-width: 800px) {
+    .particle {
+      transform: scale(1.2);
+    }
+  }
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.snippet).toContain("@media");
+  });
+
+  it("does not report leaked text for valid script and style blocks around the head boundary", async () => {
+    const html = compositionWithHeadBoundary(`
+  <script>
+    window.__headReady = true;
+  </script>
+  <template>
+    <style>
+      .template-only { color: red; }
+    </style>
+  </template>
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeUndefined();
+  });
+
+  it("reports error when CSS text leaks before the composition root", async () => {
+    const html = compositionWithBodyPrefix(`
+  .orphan {
+    position: absolute;
+    inset: 0;
+  }
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.snippet).toContain(".orphan");
+  });
+
+  it("reports error when CSS text leaks before the composition root without an explicit body", async () => {
+    const html = compositionWithImplicitBodyPrefix(`
+  .implicit-body-orphan {
+    position: absolute;
+    inset: 0;
+  }
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.snippet).toContain(".implicit-body-orphan");
+  });
+
+  it("does not report leaked text for valid script and style blocks before the composition root", async () => {
+    const html = compositionWithBodyPrefix(`
+  <style>
+    .pre-root-helper { color: red; }
+  </style>
+  <script>
+    window.__preRootReady = true;
+  </script>
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not report CSS-looking educational text inside the composition root", async () => {
+    const html = compositionWithBodyPrefix(
+      "",
+      `
+    <pre>
+      body {
+        margin: 0;
+      }
+    </pre>
+`,
+    );
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeUndefined();
+  });
+
+  it("reports error when a stray style close tag is left in the document head", async () => {
+    const html = compositionWithHead(`
+  <style>
+    body { margin: 0; }
+  </style>
+  </style>
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.snippet).toContain("</style>");
+  });
+
+  it("reports error when a stray script close tag is left in the document head", async () => {
+    const html = compositionWithHead(`
+  <script>
+    window.__headReady = true;
+  </script>
+  </script>
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.snippet).toContain("</script>");
+  });
+
+  it("does not report leaked head text for valid closing tags with trailing whitespace", async () => {
+    const html = compositionWithHead(`
+  <style>
+    body { margin: 0; }
+  </style data-parser-error-close>
+  <script>
+    window.__headReady = true;
+  </script
+    data-parser-error-close>
+  <title>Particle Field</title	>
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeUndefined();
+  });
+
+  it("reports error when markdown code fences leak into the document head", async () => {
+    const withLanguage = compositionWithHead(`
+  \`\`\`css
+  .particle {
+    position: absolute;
+  }
+  \`\`\`
+`);
+    const withoutLanguage = compositionWithHead(`
+  \`\`\`
+  .particle {
+    position: absolute;
+  }
+  \`\`\`
+`);
+    const withTsxLanguage = compositionWithHead(`
+  \`\`\`tsx
+  export function Particle() {
+    return <div className="particle" />;
+  }
+  \`\`\`
+`);
+    const withLanguageResult = await lintHyperframeHtml(withLanguage);
+    const withoutLanguageResult = await lintHyperframeHtml(withoutLanguage);
+    const withTsxLanguageResult = await lintHyperframeHtml(withTsxLanguage);
+    const languageFinding = withLanguageResult.findings.find((f) => f.code === "head_leaked_text");
+    const unlabeledFinding = withoutLanguageResult.findings.find(
+      (f) => f.code === "head_leaked_text",
+    );
+    const tsxLanguageFinding = withTsxLanguageResult.findings.find(
+      (f) => f.code === "head_leaked_text",
+    );
+
+    expect(languageFinding).toBeDefined();
+    expect(languageFinding?.snippet).toContain("```css");
+    expect(unlabeledFinding).toBeDefined();
+    expect(unlabeledFinding?.snippet).toContain("```");
+    expect(tsxLanguageFinding).toBeDefined();
+    expect(tsxLanguageFinding?.snippet).toContain("```tsx");
+  });
+
+  it("reports error when CSS at-rules leak into the document head", async () => {
+    const html = compositionWithHead(`
+  @media (min-width: 800px) {
+    .particle {
+      transform: scale(1.2);
+    }
+  }
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.snippet).toContain("@media");
+  });
+
+  it("reports leaked CSS when a style block is unclosed in the document head", async () => {
+    const html = compositionWithHead(`
+  <style>
+    .particle {
+      color: white;
+    }
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.snippet).toContain(".particle");
+  });
+
+  it("does not report leaked head text for commented CSS", async () => {
+    const html = compositionWithHead(`
+  <!-- .particle { color: red; } -->
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not report leaked head text for valid noscript content", async () => {
+    const html = compositionWithHead(`
+  <noscript>
+    .no-js { display: block; }
+  </noscript>
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not report orphan CSS for valid head metadata and style blocks", async () => {
+    const html = compositionWithHead(`
+  <title>Particle Field</title>
+  <meta name="description" content="Particle field">
+  <link rel="preconnect" href="https://fonts.gstatic.com">
+  <base href="https://example.com/">
+  <style>
+    .particle {
+      position: absolute;
+      width: 4px;
+      height: 4px;
+    }
+  </style>
+`);
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeUndefined();
+  });
+
+  it("reports leaked head text inside template-wrapped sub-compositions", async () => {
+    const html = templateCompositionWithHead(`
+      </style>
+      .particle { color: white; }
+`);
+    const result = await lintHyperframeHtml(html, { isSubComposition: true });
+    const finding = result.findings.find((f) => f.code === "head_leaked_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.snippet).toContain(".particle");
+  });
+
+  describe("timeline_id_mismatch", () => {
+    it("accepts dot timeline registration", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="launch" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    window.__timelines.launch = tl;
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "timeline_id_mismatch");
+      expect(finding).toBeUndefined();
+    });
+
+    it("reports mismatched dot timeline registration", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="launch" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    window.__timelines.intro = tl;
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "timeline_id_mismatch");
+      expect(finding).toBeDefined();
+      expect(finding?.message).toContain('Timeline registered as "intro"');
+    });
+
+    it("accepts bracket timeline registration for hyphenated ids", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="product-launch" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    window.__timelines["product-launch"] = tl;
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "timeline_id_mismatch");
+      expect(finding).toBeUndefined();
+    });
+  });
+
+  it("warns when a timeline-visible element has no stable id for Studio editing", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <section class="clip hero-card" data-start="0" data-duration="3"></section>
+  </div>
+  <script>window.__timelines = {};</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "studio_missing_editable_id");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("warning");
+    expect(finding?.message).toContain('<section class="hero-card" data-start="0">');
+    expect(finding?.fixHint).toContain("stable, human-readable id");
+  });
+
+  it("does not warn about the composition root or timeline elements with ids", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0">
+    <section id="hero-card" class="clip hero-card" data-start="0" data-duration="3"></section>
+  </div>
+  <script>window.__timelines = {};</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "studio_missing_editable_id");
+    expect(finding).toBeUndefined();
+  });
+
+  describe("non_deterministic_code", () => {
+    it("detects Math.random() in script content", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const x = Math.random();
+    window.__timelines["c1"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "non_deterministic_code");
+      expect(finding).toBeDefined();
+      expect(finding?.severity).toBe("error");
+      expect(finding?.message).toContain("Math.random");
+    });
+
+    it("detects Date.now() in script content", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const ts = Date.now();
+    window.__timelines["c1"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "non_deterministic_code");
+      expect(finding).toBeDefined();
+      expect(finding?.severity).toBe("error");
+      expect(finding?.message).toContain("Date.now");
+    });
+
+    it("does not flag non-deterministic calls inside single-line comments", async () => {
+      const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    // const x = Math.random();
+    // Date.now() is not used here
+    window.__timelines["c1"] = gsap.timeline({ paused: true });
+  </script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "non_deterministic_code");
+      expect(finding).toBeUndefined();
+    });
+  });
+
+  describe("composition_self_attribute_selector", () => {
+    it("warns when inline CSS targets the root composition id", async () => {
+      const html = `
+<html><body>
+  <div id="scene" data-composition-id="scene" data-width="1920" data-height="1080">
+    <style>
+      [data-composition-id="scene"] .title { opacity: 0; }
+      [data-composition-id="other"] .title { color: red; }
+    </style>
+    <h1 class="title">Hello</h1>
+  </div>
+  <script>window.__timelines = {};</script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const findings = result.findings.filter(
+        (f) => f.code === "composition_self_attribute_selector",
+      );
+
+      expect(findings).toHaveLength(1);
+      expect(findings[0]?.severity).toBe("warning");
+      expect(findings[0]?.selector).toBe('[data-composition-id="scene"] .title');
+      expect(findings[0]?.fixHint).toContain("#scene");
+      expect(findings[0]?.fixHint).not.toContain("#556");
+    });
+
+    it("warns when external CSS targets the root composition id", async () => {
+      const html = `
+<html><body>
+  <div id="scene" data-composition-id="scene" data-width="1920" data-height="1080"></div>
+  <script>window.__timelines = {};</script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html, {
+        externalStyles: [
+          {
+            href: "scene.css",
+            content: '[data-composition-id="scene"] .title { opacity: 0; }',
+          },
+        ],
+      });
+      const finding = result.findings.find((f) => f.code === "composition_self_attribute_selector");
+
+      expect(finding).toBeDefined();
+      expect(finding?.selector).toBe('[data-composition-id="scene"] .title');
+    });
+
+    it("does not warn when CSS targets a different composition id", async () => {
+      const html = `
+<html><body>
+  <div id="scene" data-composition-id="scene" data-width="1920" data-height="1080">
+    <style>[data-composition-id="other"] .title { opacity: 0; }</style>
+  </div>
+  <script>window.__timelines = {};</script>
+</body></html>`;
+      const result = await lintHyperframeHtml(html);
+      const finding = result.findings.find((f) => f.code === "composition_self_attribute_selector");
+
+      expect(finding).toBeUndefined();
+    });
+  });
+});
diff --git a/packages/lint/src/rules/core.ts b/packages/lint/src/rules/core.ts
new file mode 100644
index 0000000000..6a7ec77ddb
--- /dev/null
+++ b/packages/lint/src/rules/core.ts
@@ -0,0 +1,475 @@
+import type { LintContext, HyperframeLintFinding } from "../context";
+import postcss from "postcss";
+import {
+  readAttr,
+  truncateSnippet,
+  stripJsComments,
+  extractCompositionIdsFromCss,
+  extractTimelineRegistryKeys,
+  getInlineScriptSyntaxError,
+  TIMELINE_REGISTRY_INIT_PATTERN,
+  TIMELINE_REGISTRY_ASSIGN_PATTERN,
+  INVALID_SCRIPT_CLOSE_PATTERN,
+} from "../utils";
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function selectorTargetsCompositionId(selector: string, compositionId: string): boolean {
+  const escaped = escapeRegExp(compositionId);
+  return new RegExp(
+    String.raw`\[\s*data-composition-id\s*=\s*(?:"${escaped}"|'${escaped}')\s*\]`,
+  ).test(selector);
+}
+
+function isStudioTimelineElement(tag: { raw: string; name: string }): boolean {
+  if (["script", "style", "link", "meta", "template", "noscript"].includes(tag.name)) {
+    return false;
+  }
+  return Boolean(
+    readAttr(tag.raw, "data-start") ||
+    readAttr(tag.raw, "data-track-index") ||
+    readAttr(tag.raw, "data-track") ||
+    readAttr(tag.raw, "data-composition-src") ||
+    readAttr(tag.raw, "data-composition-file"),
+  );
+}
+
+function describeStudioElement(tag: { raw: string; name: string }): string {
+  const parts = [`<${tag.name}`];
+  const className = readAttr(tag.raw, "class");
+  const compositionId = readAttr(tag.raw, "data-composition-id");
+  const dataStart = readAttr(tag.raw, "data-start");
+  const dataTrack = readAttr(tag.raw, "data-track-index") ?? readAttr(tag.raw, "data-track");
+
+  if (className) {
+    const primaryClass = className
+      .split(/\s+/)
+      .map((value) => value.trim())
+      .find((value) => value && value !== "clip");
+    if (primaryClass) parts.push(` class="${primaryClass}"`);
+  }
+  if (compositionId) parts.push(` data-composition-id="${compositionId}"`);
+  if (dataStart) parts.push(` data-start="${dataStart}"`);
+  if (dataTrack) parts.push(` data-track-index="${dataTrack}"`);
+  parts.push(">");
+  return parts.join("");
+}
+
+const HEAD_BLOCKS_TO_IGNORE_PATTERN =
+  /<(?:style|script|template|title|noscript)\b[^>]*>[\s\S]*?<\/(?:style|script|template|title|noscript)(?:\s[^>]*)?>/gi;
+const HTML_TAG_PATTERN = /<[^>]+>/g;
+const HEAD_CONTENT_PATTERN = /<head\b[^>]*>([\s\S]*?)(?:<\/head>|<body\b|$)/gi;
+const AFTER_HEAD_BEFORE_BODY_PATTERN = /<\/head(?:\s[^>]*)?>([\s\S]*?)(?=<body\b|$)/gi;
+const STRAY_HEAD_CLOSE_PATTERN = /<\/(?:style|script)(?:\s[^>]*)?>/i;
+const MARKDOWN_CODE_FENCE_PATTERN = /```[^\r\n`]*(?:\r?\n|$)[\s\S]*?```/i;
+const ORPHAN_CSS_AT_RULE_PATTERN =
+  /(?:^|\s)@(?:container|font-face|keyframes|layer|media|page|property|scope|supports)[^{<]*\{[\s\S]*?:[\s\S]*?\}/i;
+const ORPHAN_CSS_RULE_PATTERN =
+  /(?:^|\s)(?:\/\*[\s\S]*?\*\/\s*)?(?:@[a-z-]+[^{}<]*|[.#][\w-]+[^{}<]*|[a-z][\w-]*(?:\s+[.#:[\w-][^{}<]*)?)\s*\{[^{}]*:[^{}]*\}/i;
+
+function findCodeFenceLeak(headWithoutValidBlocks: string): string | null {
+  return MARKDOWN_CODE_FENCE_PATTERN.exec(headWithoutValidBlocks)?.[0] ?? null;
+}
+
+function findOrphanCssLeak(headContent: string): string | null {
+  const residualText = headContent
+    .replace(HEAD_BLOCKS_TO_IGNORE_PATTERN, " ")
+    .replace(HTML_TAG_PATTERN, " ");
+  return (
+    ORPHAN_CSS_AT_RULE_PATTERN.exec(residualText)?.[0] ??
+    ORPHAN_CSS_RULE_PATTERN.exec(residualText)?.[0] ??
+    null
+  );
+}
+
+function findStrayCloseLeak(headWithoutValidBlocks: string): string | null {
+  return STRAY_HEAD_CLOSE_PATTERN.exec(headWithoutValidBlocks)?.[0] ?? null;
+}
+
+function findLeakedTextInHeadContent(headContent: string): string | null {
+  const withoutValidBlocks = headContent.replace(HEAD_BLOCKS_TO_IGNORE_PATTERN, " ");
+  return (
+    findCodeFenceLeak(withoutValidBlocks) ??
+    findOrphanCssLeak(headContent) ??
+    findStrayCloseLeak(withoutValidBlocks)
+  );
+}
+
+function findLeakedTextInHead(rawSource: string): string | null {
+  const headMatches = [...rawSource.matchAll(HEAD_CONTENT_PATTERN)];
+  for (const match of headMatches) {
+    const leakedText = findLeakedTextInHeadContent(match[1] ?? "");
+    if (leakedText) return leakedText;
+  }
+  return null;
+}
+
+function findLeakedTextBetweenHeadAndBody(rawSource: string): string | null {
+  const boundaryMatches = [...rawSource.matchAll(AFTER_HEAD_BEFORE_BODY_PATTERN)];
+  for (const match of boundaryMatches) {
+    const leakedText = findLeakedTextInHeadContent(match[1] ?? "");
+    if (leakedText) return leakedText;
+  }
+  return null;
+}
+
+function findLeakedTextBeforeCompositionRoot(
+  source: string,
+  rootTag: LintContext["rootTag"],
+): string | null {
+  if (!rootTag || rootTag.name === "body") return null;
+  const bodyOpenMatch = /<body\b[^>]*>/i.exec(source);
+  const prefixStart = bodyOpenMatch ? bodyOpenMatch.index + bodyOpenMatch[0].length : 0;
+  const prefixEnd = rootTag.index;
+  if (prefixEnd <= prefixStart) return null;
+  return findLeakedTextInHeadContent(source.slice(prefixStart, prefixEnd));
+}
+
+export const coreRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
+  // root_missing_composition_id + root_missing_dimensions
+  ({ rootTag }) => {
+    const findings: HyperframeLintFinding[] = [];
+    if (!rootTag || !readAttr(rootTag.raw, "data-composition-id")) {
+      findings.push({
+        code: "root_missing_composition_id",
+        severity: "error",
+        message: "Root composition is missing `data-composition-id`.",
+        elementId: rootTag ? readAttr(rootTag.raw, "id") || undefined : undefined,
+        fixHint: "Add a stable `data-composition-id` to the entry composition wrapper.",
+        snippet: truncateSnippet(rootTag?.raw || ""),
+      });
+    }
+    if (!rootTag || !readAttr(rootTag.raw, "data-width") || !readAttr(rootTag.raw, "data-height")) {
+      findings.push({
+        code: "root_missing_dimensions",
+        severity: "error",
+        message: "Root composition is missing `data-width` or `data-height`.",
+        elementId: rootTag ? readAttr(rootTag.raw, "id") || undefined : undefined,
+        fixHint: "Set numeric `data-width` and `data-height` on the entry composition root.",
+        snippet: truncateSnippet(rootTag?.raw || ""),
+      });
+    }
+    return findings;
+  },
+
+  // head_leaked_text
+  ({ source, rootTag }) => {
+    const snippet =
+      findLeakedTextInHead(source) ??
+      findLeakedTextBetweenHeadAndBody(source) ??
+      findLeakedTextBeforeCompositionRoot(source, rootTag);
+    if (!snippet) return [];
+    return [
+      {
+        code: "head_leaked_text",
+        severity: "error",
+        message:
+          "Detected leaked code or CSS text around the document `<head>` or before the composition root. Browsers render this as visible text in the video.",
+        fixHint:
+          "Move CSS into a single `<style>...</style>` block and remove stray close tags, markdown fences, or code text from `<head>`, the `</head>`/`<body>` boundary, or the pre-root body prefix.",
+        snippet: truncateSnippet(snippet),
+      },
+    ];
+  },
+
+  // missing_timeline_registry + timeline_registry_missing_init
+  ({ source, rawSource, options }) => {
+    // Sub-compositions inherit window.__timelines from the host composition
+    if (options.isSubComposition || rawSource.trimStart().toLowerCase().startsWith("<template")) {
+      return [];
+    }
+    const findings: HyperframeLintFinding[] = [];
+    if (
+      !TIMELINE_REGISTRY_INIT_PATTERN.test(source) &&
+      !TIMELINE_REGISTRY_ASSIGN_PATTERN.test(source)
+    ) {
+      findings.push({
+        code: "missing_timeline_registry",
+        severity: "error",
+        message: "Missing `window.__timelines` registration.",
+        fixHint: "Register each composition timeline on `window.__timelines[compositionId]`.",
+      });
+    }
+    if (
+      TIMELINE_REGISTRY_ASSIGN_PATTERN.test(source) &&
+      !TIMELINE_REGISTRY_INIT_PATTERN.test(source)
+    ) {
+      findings.push({
+        code: "timeline_registry_missing_init",
+        severity: "error",
+        message:
+          "`window.__timelines[…] = …` is used without initializing `window.__timelines` first.",
+        fixHint:
+          "Add `window.__timelines = window.__timelines || {};` before any timeline assignment.",
+      });
+    }
+    return findings;
+  },
+
+  // timeline_id_mismatch
+  ({ source }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const htmlCompIds = new Set<string>();
+    const timelineRegKeys = new Set<string>();
+    const compIdRe = /data-composition-id\s*=\s*["']([^"']+)["']/gi;
+    let m: RegExpExecArray | null;
+    while ((m = compIdRe.exec(source)) !== null) {
+      if (m[1]) htmlCompIds.add(m[1]);
+    }
+    for (const key of extractTimelineRegistryKeys(source)) {
+      timelineRegKeys.add(key);
+    }
+    for (const key of timelineRegKeys) {
+      if (!htmlCompIds.has(key)) {
+        findings.push({
+          code: "timeline_id_mismatch",
+          severity: "error",
+          message: `Timeline registered as "${key}" but no element has data-composition-id="${key}". The runtime cannot auto-nest this timeline.`,
+          fixHint: `Change window.__timelines["${key}"] to match the data-composition-id attribute, or vice versa.`,
+        });
+      }
+    }
+    return findings;
+  },
+
+  // invalid_inline_script_syntax (malformed close tag)
+  ({ source }) => {
+    if (!INVALID_SCRIPT_CLOSE_PATTERN.test(source)) return [];
+    return [
+      {
+        code: "invalid_inline_script_syntax",
+        severity: "error",
+        message: "Detected malformed inline `<script>` closing syntax.",
+        fixHint: "Close inline scripts with a valid `</script>` tag.",
+      },
+    ];
+  },
+
+  // invalid_inline_script_syntax (JS parse error)
+  ({ scripts }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const script of scripts) {
+      const attrs = script.attrs || "";
+      if (
+        /\bsrc\s*=/.test(attrs) ||
+        /\btype\s*=\s*["'](?:application\/json|application\/hyperframes-slideshow\+json|importmap|module)["']/.test(
+          attrs,
+        )
+      )
+        continue;
+      const syntaxError = getInlineScriptSyntaxError(script.content);
+      if (!syntaxError) continue;
+      findings.push({
+        code: "invalid_inline_script_syntax",
+        severity: "error",
+        message: `Inline script has invalid syntax: ${syntaxError}`,
+        fixHint: "Fix the inline script syntax before render verification.",
+        snippet: truncateSnippet(script.content),
+      });
+    }
+    return findings;
+  },
+
+  // host_missing_composition_id
+  ({ tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const tag of tags) {
+      const src = readAttr(tag.raw, "data-composition-src");
+      if (!src) continue;
+      if (readAttr(tag.raw, "data-composition-id")) continue;
+      findings.push({
+        code: "host_missing_composition_id",
+        severity: "error",
+        message: `Composition host for "${src}" is missing \`data-composition-id\`.`,
+        elementId: readAttr(tag.raw, "id") || undefined,
+        fixHint: "Set `data-composition-id` on every `data-composition-src` host element.",
+        snippet: truncateSnippet(tag.raw),
+      });
+    }
+    return findings;
+  },
+
+  // scoped_css_missing_wrapper
+  ({ styles, compositionIds }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const scopedCssCompositionIds = new Set<string>();
+    for (const style of styles) {
+      for (const compId of extractCompositionIdsFromCss(style.content)) {
+        scopedCssCompositionIds.add(compId);
+      }
+    }
+    for (const compId of scopedCssCompositionIds) {
+      if (compositionIds.has(compId)) continue;
+      findings.push({
+        code: "scoped_css_missing_wrapper",
+        severity: "warning",
+        message: `Scoped CSS targets composition "${compId}" but no matching wrapper exists in this HTML.`,
+        selector: `[data-composition-id="${compId}"]`,
+        fixHint:
+          "Preserve the matching composition wrapper or align the CSS scope to an existing wrapper.",
+      });
+    }
+    return findings;
+  },
+
+  // composition_self_attribute_selector
+  ({ styles, rootCompositionId, rootTag }) => {
+    const findings: HyperframeLintFinding[] = [];
+    if (!rootCompositionId) return findings;
+    const seenSelectors = new Set<string>();
+    const rootId = readAttr(rootTag?.raw || "", "id");
+    for (const style of styles) {
+      let root: postcss.Root;
+      try {
+        root = postcss.parse(style.content);
+      } catch {
+        continue;
+      }
+      root.walkRules((rule) => {
+        for (const selector of rule.selectors) {
+          if (!selectorTargetsCompositionId(selector, rootCompositionId)) continue;
+          if (seenSelectors.has(selector)) continue;
+          seenSelectors.add(selector);
+          findings.push({
+            code: "composition_self_attribute_selector",
+            severity: "warning",
+            message:
+              "Selector matches the block's own id; will leak to sibling instances when the block is embedded twice.",
+            selector,
+            fixHint: rootId
+              ? `Use #${rootId} for clearer authoring intent and instance-isolated styling.`
+              : "Add a stable id to the composition root and use that id selector for clearer authoring intent and instance-isolated styling.",
+          });
+        }
+      });
+    }
+    return findings;
+  },
+
+  // studio_missing_editable_id
+  ({ tags, rootTag }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const tag of tags) {
+      if (rootTag && tag.index === rootTag.index) continue;
+      if (!isStudioTimelineElement(tag)) continue;
+      if (readAttr(tag.raw, "id")) continue;
+
+      const descriptor = describeStudioElement(tag);
+      findings.push({
+        code: "studio_missing_editable_id",
+        severity: "warning",
+        message: `${descriptor} has no id, so Studio cannot use a stable edit target for its timeline and canvas controls.`,
+        selector: readAttr(tag.raw, "data-composition-id")
+          ? `[data-composition-id="${readAttr(tag.raw, "data-composition-id")}"]`
+          : undefined,
+        fixHint:
+          'Add a stable, human-readable id such as id="hero-title" or id="scene-1-card" to every timeline-visible element you want agents or Studio to edit.',
+        snippet: truncateSnippet(tag.raw),
+      });
+    }
+    return findings;
+  },
+
+  // non_deterministic_code
+  ({ scripts }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const patterns: Array<{ pattern: RegExp; label: string; hint: string }> = [
+      {
+        pattern: /Math\.random\s*\(/,
+        label: "Math.random()",
+        hint: "Use a seeded PRNG (e.g. a simple mulberry32) so renders are deterministic across frames.",
+      },
+      {
+        pattern: /Date\.now\s*\(/,
+        label: "Date.now()",
+        hint: "Remove time-dependent code. Use GSAP timeline position instead of wall-clock time.",
+      },
+      {
+        pattern: /new\s+Date\s*\(/,
+        label: "new Date()",
+        hint: "Remove time-dependent code. Use GSAP timeline position instead of wall-clock time.",
+      },
+      {
+        pattern: /performance\.now\s*\(/,
+        label: "performance.now()",
+        hint: "Remove time-dependent code. Use GSAP timeline position instead of wall-clock time.",
+      },
+      {
+        pattern: /crypto\.getRandomValues\s*\(/,
+        label: "crypto.getRandomValues()",
+        hint: "Remove time-dependent code. Use a seeded PRNG for deterministic renders.",
+      },
+    ];
+
+    for (const script of scripts) {
+      const stripped = stripJsComments(script.content);
+      for (const { pattern, label, hint } of patterns) {
+        if (pattern.test(stripped)) {
+          findings.push({
+            code: "non_deterministic_code",
+            severity: "error",
+            message: `Script contains \`${label}\` which produces non-deterministic output. Renders may differ between frames or runs.`,
+            fixHint: hint,
+            snippet: truncateSnippet(script.content),
+          });
+        }
+      }
+    }
+    return findings;
+  },
+
+  // pointer_events_none
+  // fallow-ignore-next-line complexity
+  ({ tags, styles }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const reported = new Set<string>();
+
+    for (const tag of tags) {
+      if (["script", "style", "link", "meta", "template", "noscript"].includes(tag.name)) continue;
+      const inlineStyle = readAttr(tag.raw, "style") ?? "";
+      if (!/pointer-events\s*:\s*none/i.test(inlineStyle)) continue;
+      const id = readAttr(tag.raw, "id");
+      const key = id ?? tag.raw;
+      if (reported.has(key)) continue;
+      reported.add(key);
+      findings.push({
+        code: "pointer_events_none",
+        severity: "info",
+        message: `<${tag.name}${id ? ` id="${id}"` : ""}> has \`pointer-events: none\` in its inline style. Elements with this property are harder to select in the Studio preview.`,
+        elementId: id || undefined,
+        fixHint:
+          "If this element should be selectable in the Studio, remove `pointer-events: none` or move it to a wrapper that doesn't contain editable content.",
+        snippet: truncateSnippet(tag.raw),
+      });
+    }
+
+    for (const style of styles) {
+      let root: postcss.Root;
+      try {
+        root = postcss.parse(style.content);
+      } catch {
+        continue;
+      }
+      root.walkDecls("pointer-events", (decl) => {
+        if (decl.value.trim().toLowerCase() !== "none") return;
+        const rule = decl.parent;
+        if (!rule || rule.type !== "rule") return;
+        const selector = (rule as postcss.Rule).selector;
+        if (reported.has(selector)) return;
+        reported.add(selector);
+        findings.push({
+          code: "pointer_events_none",
+          severity: "info",
+          message: `\`${selector}\` sets \`pointer-events: none\`. Elements matching this selector are harder to select in the Studio preview.`,
+          selector,
+          fixHint:
+            "If these elements should be selectable in the Studio, remove `pointer-events: none` or move it to a wrapper that doesn't contain editable content.",
+        });
+      });
+    }
+
+    return findings;
+  },
+];
diff --git a/packages/lint/src/rules/fonts.test.ts b/packages/lint/src/rules/fonts.test.ts
new file mode 100644
index 0000000000..853781bd74
--- /dev/null
+++ b/packages/lint/src/rules/fonts.test.ts
@@ -0,0 +1,285 @@
+import { describe, it, expect } from "vitest";
+import { lintHyperframeHtml } from "../hyperframeLinter.js";
+
+async function findByCode(html: string, code: string, isSubComposition = true) {
+  const result = await lintHyperframeHtml(html, { isSubComposition });
+  return result.findings.filter((f) => f.code === code);
+}
+
+describe("font rules", () => {
+  describe("google_fonts_import", () => {
+    it("warns on @import url with fonts.googleapis.com without failing lint", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500&display=swap');</style>
+      </div>`;
+      const result = await lintHyperframeHtml(html, { isSubComposition: true });
+      const findings = result.findings.filter((f) => f.code === "google_fonts_import");
+      expect(findings).toHaveLength(1);
+      expect(findings[0]!.severity).toBe("warning");
+      expect(result.errorCount).toBe(0);
+    });
+
+    it("warns on <link> to fonts.googleapis.com", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter">
+      </div>`;
+      const findings = await findByCode(html, "google_fonts_import");
+      expect(findings).toHaveLength(1);
+      expect(findings[0]!.severity).toBe("warning");
+    });
+
+    it("does not flag local @font-face usage", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>@font-face { font-family: 'Inter'; src: url('../capture/assets/fonts/Inter.woff2'); }</style>
+      </div>`;
+      const findings = await findByCode(html, "google_fonts_import");
+      expect(findings).toHaveLength(0);
+    });
+
+    it("does not flag installed registry blocks that bundle Google Fonts", async () => {
+      const html =
+        `<!-- hyperframes-registry-item: my-block -->\n` +
+        `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter">
+      </div>`;
+      const findings = await findByCode(html, "google_fonts_import");
+      expect(findings).toHaveLength(0);
+    });
+  });
+
+  describe("system_font_will_alias", () => {
+    it("flags SF Mono as aliased to JetBrains Mono", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>code { font-family: 'SF Mono', monospace; }</style>
+      </div>`;
+      const findings = await findByCode(html, "system_font_will_alias");
+      expect(findings).toHaveLength(1);
+      expect(findings[0]!.severity).toBe("info");
+      expect(findings[0]!.message).toContain("JetBrains Mono");
+    });
+
+    it("flags Helvetica Neue as aliased to Inter", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>body { font-family: 'Helvetica Neue', sans-serif; }</style>
+      </div>`;
+      const findings = await findByCode(html, "system_font_will_alias");
+      expect(findings).toHaveLength(1);
+      expect(findings[0]!.message).toContain("Inter");
+    });
+
+    it("does not flag canonical font names", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>body { font-family: 'Inter', sans-serif; }</style>
+      </div>`;
+      const findings = await findByCode(html, "system_font_will_alias");
+      expect(findings).toHaveLength(0);
+    });
+
+    it("does not flag Roboto (canonical name)", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>body { font-family: 'Roboto', sans-serif; }</style>
+      </div>`;
+      const findings = await findByCode(html, "system_font_will_alias");
+      expect(findings).toHaveLength(0);
+    });
+
+    it("does not flag unknown fonts (handled by font_family_without_font_face)", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>body { font-family: 'Comic Sans MS', sans-serif; }</style>
+      </div>`;
+      const findings = await findByCode(html, "system_font_will_alias");
+      expect(findings).toHaveLength(0);
+    });
+
+    it("does not flag aliased fonts that have explicit @font-face", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>
+          @font-face { font-family: 'Menlo'; src: url('../fonts/menlo.woff2'); }
+          code { font-family: 'Menlo', monospace; }
+        </style>
+      </div>`;
+      const findings = await findByCode(html, "system_font_will_alias");
+      expect(findings).toHaveLength(0);
+    });
+
+    it("handles case-insensitive font names", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>body { font-family: 'VERDANA', sans-serif; }</style>
+      </div>`;
+      const findings = await findByCode(html, "system_font_will_alias");
+      expect(findings).toHaveLength(1);
+      expect(findings[0]!.message).toContain("Inter");
+    });
+
+    it("reports multiple aliased fonts in one finding", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>
+          body { font-family: 'Verdana', sans-serif; }
+          code { font-family: 'Consolas', monospace; }
+        </style>
+      </div>`;
+      const findings = await findByCode(html, "system_font_will_alias");
+      expect(findings).toHaveLength(1);
+      expect(findings[0]!.message).toContain("Inter");
+      expect(findings[0]!.message).toContain("JetBrains Mono");
+    });
+  });
+
+  describe("font_family_without_font_face", () => {
+    it("flags font-family used without @font-face", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>body { font-family: 'GT Walsheim', sans-serif; }</style>
+      </div>`;
+      const findings = await findByCode(html, "font_family_without_font_face");
+      expect(findings).toHaveLength(1);
+      expect(findings[0]!.message).toContain("gt walsheim");
+    });
+
+    it("does not flag when @font-face is declared", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>
+          @font-face { font-family: 'GT Walsheim'; src: url('../fonts/gt.woff2'); }
+          body { font-family: 'GT Walsheim', sans-serif; }
+        </style>
+      </div>`;
+      const findings = await findByCode(html, "font_family_without_font_face");
+      expect(findings).toHaveLength(0);
+    });
+
+    it("does not flag generic font families", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>body { font-family: monospace; }</style>
+      </div>`;
+      const findings = await findByCode(html, "font_family_without_font_face");
+      expect(findings).toHaveLength(0);
+    });
+
+    it("reports multiple missing families in one finding", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>
+          h1 { font-family: 'Aeonik', sans-serif; }
+          code { font-family: 'Feature Deck', monospace; }
+        </style>
+      </div>`;
+      const findings = await findByCode(html, "font_family_without_font_face");
+      expect(findings).toHaveLength(1);
+      expect(findings[0]!.message).toContain("aeonik");
+      expect(findings[0]!.message).toContain("feature deck");
+    });
+
+    it("does not flag fonts the producer has pre-bundled", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>
+          body { font-family: 'Inter', sans-serif; }
+          code { font-family: 'JetBrains Mono', monospace; }
+          h1 { font-family: 'Roboto', sans-serif; }
+        </style>
+      </div>`;
+      const findings = await findByCode(html, "font_family_without_font_face");
+      expect(findings).toHaveLength(0);
+    });
+
+    it("still flags Google-Fonts-only fonts not pre-bundled", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>body { font-family: 'Geist', sans-serif; }</style>
+      </div>`;
+      const findings = await findByCode(html, "font_family_without_font_face");
+      expect(findings).toHaveLength(1);
+      expect(findings[0]!.message).toContain("geist");
+    });
+
+    it("does not flag a non-bundled family when a Google Fonts link loads it", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Geist:wght@400;700&display=swap">
+        <style>body { font-family: 'Geist', sans-serif; }</style>
+      </div>`;
+      const result = await lintHyperframeHtml(html, { isSubComposition: true });
+      expect(result.findings.filter((f) => f.code === "google_fonts_import")).toHaveLength(1);
+      expect(
+        result.findings.filter((f) => f.code === "font_family_without_font_face"),
+      ).toHaveLength(0);
+      expect(result.errorCount).toBe(0);
+    });
+
+    it("parses unquoted Google Fonts link href values", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <link rel=stylesheet href=https://fonts.googleapis.com/css2?family=Geist:wght@400;700&display=swap>
+        <style>body { font-family: 'Geist', sans-serif; }</style>
+      </div>`;
+      const result = await lintHyperframeHtml(html, { isSubComposition: true });
+      expect(result.findings.filter((f) => f.code === "google_fonts_import")).toHaveLength(1);
+      expect(
+        result.findings.filter((f) => f.code === "font_family_without_font_face"),
+      ).toHaveLength(0);
+      expect(result.errorCount).toBe(0);
+    });
+
+    it("parses multiple Google Fonts family parameters and URL-encoded spaces", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>
+          @import url("https://fonts.googleapis.com/css2?family=Libre+Baskerville:wght@400;700&family=DM+Sans:ital,wght@0,400;1,700&display=swap");
+          h1 { font-family: 'Libre Baskerville', serif; }
+          body { font-family: 'DM Sans', sans-serif; }
+        </style>
+      </div>`;
+      const result = await lintHyperframeHtml(html, { isSubComposition: true });
+      expect(result.findings.filter((f) => f.code === "google_fonts_import")).toHaveLength(1);
+      expect(
+        result.findings.filter((f) => f.code === "font_family_without_font_face"),
+      ).toHaveLength(0);
+      expect(result.errorCount).toBe(0);
+    });
+
+    it("still flags non-bundled families not covered by the Google Fonts URL", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter">
+        <style>body { font-family: 'Geist', sans-serif; }</style>
+      </div>`;
+      const findings = await findByCode(html, "font_family_without_font_face");
+      expect(findings).toHaveLength(1);
+      expect(findings[0]!.message).toContain("geist");
+    });
+
+    it("is case-insensitive when matching @font-face to font-family", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>
+          @font-face { font-family: 'Inter'; src: url('../fonts/inter.woff2'); }
+          body { font-family: 'inter', sans-serif; }
+        </style>
+      </div>`;
+      const findings = await findByCode(html, "font_family_without_font_face");
+      expect(findings).toHaveLength(0);
+    });
+
+    it("ignores font-family inside @font-face blocks", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>
+          @font-face { font-family: 'CustomFont'; src: url('../fonts/custom.woff2'); }
+        </style>
+      </div>`;
+      const findings = await findByCode(html, "font_family_without_font_face");
+      expect(findings).toHaveLength(0);
+    });
+
+    it("does not flag installed registry blocks that declare fonts via Google Fonts", async () => {
+      const html =
+        `<!-- hyperframes-registry-item: my-block -->\n` +
+        `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>body { font-family: 'Poppins', sans-serif; }</style>
+      </div>`;
+      const findings = await findByCode(html, "font_family_without_font_face");
+      expect(findings).toHaveLength(0);
+    });
+
+    it("matches @font-face even when a CSS comment inside the block contains a brace (#1534)", async () => {
+      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+        <style>
+          @font-face { /* weight 400 } regular */ font-family: 'Noto Sans SC'; src: url('../fonts/noto-400.woff2'); }
+          .title { font-family: 'Noto Sans SC'; }
+        </style>
+      </div>`;
+      const findings = await findByCode(html, "font_family_without_font_face");
+      expect(findings).toHaveLength(0);
+    });
+  });
+});
diff --git a/packages/lint/src/rules/fonts.ts b/packages/lint/src/rules/fonts.ts
new file mode 100644
index 0000000000..63fea4e49e
--- /dev/null
+++ b/packages/lint/src/rules/fonts.ts
@@ -0,0 +1,222 @@
+import { FONT_ALIAS_KEYS, resolveAliasDisplayName } from "@hyperframes/core/fonts/aliases";
+import type { LintContext, HyperframeLintFinding } from "../context";
+import { isRegistrySourceFile, isRegistryInstalledFile } from "./composition";
+
+const GENERIC_FAMILIES = new Set([
+  "serif",
+  "sans-serif",
+  "monospace",
+  "cursive",
+  "fantasy",
+  "system-ui",
+  "ui-serif",
+  "ui-sans-serif",
+  "ui-monospace",
+  "ui-rounded",
+  "math",
+  "emoji",
+  "fangsong",
+  "inherit",
+  "initial",
+  "unset",
+  "revert",
+]);
+
+// A CSS comment can contain a `}` (e.g. `@font-face { /* 400 } regular */
+// font-family: 'X'; ... }`), which truncates the naive `@font-face\s*\{[^}]*\}`
+// block match at the comment's brace — so the rule never sees the real
+// `font-family` and reports a false-positive font_family_without_font_face.
+// Large/"framework" stylesheets hit this far more often than minimal ones,
+// which is why a simple <style> passes while a complex one fails. Strip
+// comments before scanning so a brace inside one cannot split a block. See #1534.
+function stripCssComments(css: string): string {
+  return css.replace(/\/\*[\s\S]*?\*\//g, " ");
+}
+
+function extractFontFaceFamilies(styles: Array<{ content: string }>): Set<string> {
+  const families = new Set<string>();
+  const fontFaceRe = /@font-face\s*\{[^}]*\}/gi;
+  const familyRe = /font-family\s*:\s*(['"]?)([^;'"]+)\1/i;
+  for (const style of styles) {
+    const content = stripCssComments(style.content);
+    let match: RegExpExecArray | null;
+    while ((match = fontFaceRe.exec(content)) !== null) {
+      const familyMatch = match[0].match(familyRe);
+      if (familyMatch?.[2]) {
+        families.add(familyMatch[2].trim().toLowerCase());
+      }
+    }
+  }
+  return families;
+}
+
+function extractUsedFontFamilies(styles: Array<{ content: string }>): string[] {
+  const used: string[] = [];
+  const seen = new Set<string>();
+  const propRe = /font-family\s*:\s*([^;}{]+)/gi;
+  for (const style of styles) {
+    const withoutFontFace = stripCssComments(style.content).replace(/@font-face\s*\{[^}]*\}/gi, "");
+    let match: RegExpExecArray | null;
+    while ((match = propRe.exec(withoutFontFace)) !== null) {
+      const stack = match[1]!;
+      for (const part of stack.split(",")) {
+        const name = part
+          .trim()
+          .replace(/^['"]|['"]$/g, "")
+          .trim()
+          .toLowerCase();
+        if (name && !GENERIC_FAMILIES.has(name) && !seen.has(name)) {
+          seen.add(name);
+          used.push(name);
+        }
+      }
+    }
+  }
+  return used;
+}
+
+function collectAliasedFonts(used: string[], declared: Set<string>): string[] {
+  const aliased: string[] = [];
+  for (const name of used) {
+    if (declared.has(name)) continue;
+    const displayName = resolveAliasDisplayName(name);
+    if (!displayName) continue;
+    if (displayName.toLowerCase() === name) continue;
+    aliased.push(`'${name}' → ${displayName}`);
+  }
+  return aliased;
+}
+
+function normalizeFontFamily(name: string): string | null {
+  const decoded = name.replace(/\+/g, " ").trim();
+  if (!decoded) return null;
+  try {
+    return decodeURIComponent(decoded).trim().toLowerCase() || null;
+  } catch {
+    return decoded.toLowerCase();
+  }
+}
+
+function extractGoogleFontFamiliesFromUrl(rawUrl: string): string[] {
+  const url = rawUrl.replace(/&amp;/gi, "&");
+  let parsed: URL;
+  try {
+    parsed = new URL(url, "https://fonts.googleapis.com");
+  } catch {
+    return [];
+  }
+
+  if (parsed.hostname.toLowerCase() !== "fonts.googleapis.com") return [];
+  const families: string[] = [];
+  for (const value of parsed.searchParams.getAll("family")) {
+    for (const familySpec of value.split("|")) {
+      const family = normalizeFontFamily(familySpec.split(":")[0] || "");
+      if (family) families.push(family);
+    }
+  }
+  return families;
+}
+
+function collectGoogleFontFamilies(
+  source: string,
+  styles: Array<{ content: string }>,
+): Set<string> {
+  const families = new Set<string>();
+  const addUrl = (url: string) => {
+    for (const family of extractGoogleFontFamiliesFromUrl(url)) families.add(family);
+  };
+
+  const linkHrefRe =
+    /<link\b[^>]*\bhref\s*=\s*(?:(["'])([^"']*fonts\.googleapis\.com[^"']*)\1|([^\s>]*fonts\.googleapis\.com[^\s>]*))[^>]*>/gi;
+  for (const match of source.matchAll(linkHrefRe)) {
+    const href = match[2] || match[3];
+    if (href) addUrl(href);
+  }
+
+  const importUrlRe =
+    /@import\s+(?:url\(\s*)?(["']?)([^"')\s]*fonts\.googleapis\.com[^"')\s]*)\1\s*\)?/gi;
+  for (const style of styles) {
+    for (const match of style.content.matchAll(importUrlRe)) {
+      if (match[2]) addUrl(match[2]);
+    }
+  }
+
+  return families;
+}
+
+export const fontRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
+  // google_fonts_import
+  ({ styles, source, rawSource, options }) => {
+    if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
+    const findings: HyperframeLintFinding[] = [];
+    const googleFontsInLink = /<link\b[^>]*fonts\.googleapis\.com[^>]*>/i.test(source);
+    const googleFontsInImport = styles.some((s) =>
+      /@import\s+url\s*\(\s*['"]?[^)]*fonts\.googleapis\.com/i.test(s.content),
+    );
+
+    if (googleFontsInLink || googleFontsInImport) {
+      findings.push({
+        code: "google_fonts_import",
+        severity: "warning",
+        message:
+          "Composition loads fonts from fonts.googleapis.com. The producer resolves Google Fonts " +
+          "during compile/render, but raw external font requests add latency and can fail before " +
+          "canonicalization. Prefer mapped family names or local @font-face declarations when possible.",
+        fixHint:
+          "For bundled fonts, remove the Google Fonts <link> or @import and keep the font-family " +
+          "declaration. For custom fonts, use @font-face { font-family: '...'; src: url('...woff2'); }.",
+      });
+    }
+    return findings;
+  },
+
+  // system_font_will_alias — inform when a font will be silently substituted
+  ({ styles, options }) => {
+    const declared = extractFontFaceFamilies(styles);
+    const used = extractUsedFontFamilies(styles);
+    const aliased = collectAliasedFonts(used, declared);
+    if (aliased.length === 0) return [];
+    // In distributed / Lambda renders system-font capture is disabled, so
+    // the alias substitution does NOT happen — elevate to a warning.
+    const severity = options.distributed ? ("warning" as const) : ("info" as const);
+    return [
+      {
+        code: "system_font_will_alias",
+        severity,
+        message:
+          `Font ${aliased.length === 1 ? "family" : "families"} will be substituted at render time: ${aliased.join(", ")}. ` +
+          (options.distributed
+            ? "In distributed/Lambda rendering system-font capture is disabled — these fonts will fall back to OS defaults. Embed explicit @font-face declarations instead."
+            : "The renderer maps these to bundled fonts for cross-platform consistency. " +
+              "Use the target font name directly for consistent preview and render results."),
+      },
+    ];
+  },
+
+  // font_family_without_font_face
+  ({ styles, source, rawSource, options }) => {
+    if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
+    const findings: HyperframeLintFinding[] = [];
+    const declared = extractFontFaceFamilies(styles);
+    const used = extractUsedFontFamilies(styles);
+    const googleFonts = collectGoogleFontFamilies(source, styles);
+
+    const undeclared = used.filter(
+      (name) => !declared.has(name) && !FONT_ALIAS_KEYS.has(name) && !googleFonts.has(name),
+    );
+    if (undeclared.length === 0) return findings;
+
+    findings.push({
+      code: "font_family_without_font_face",
+      severity: "error",
+      message:
+        `Font ${undeclared.length === 1 ? "family" : "families"} used without @font-face declaration: ${undeclared.join(", ")}. ` +
+        "These are not in the auto-resolved font list, so the renderer cannot supply them automatically. " +
+        "Text will fall back to a generic font, producing incorrect typography in the video.",
+      fixHint:
+        "Add @font-face { font-family: '...'; src: url('capture/assets/fonts/...woff2'); } " +
+        "for each font family, pointing to the captured .woff2 files.",
+    });
+    return findings;
+  },
+];
diff --git a/packages/lint/src/rules/gsap.test.ts b/packages/lint/src/rules/gsap.test.ts
new file mode 100644
index 0000000000..e9b46325a0
--- /dev/null
+++ b/packages/lint/src/rules/gsap.test.ts
@@ -0,0 +1,1318 @@
+// fallow-ignore-file code-duplication
+import { describe, it, expect } from "vitest";
+import { lintHyperframeHtml } from "../hyperframeLinter.js";
+
+describe("GSAP rules", () => {
+  it("errors when window.__timelines is registered BEFORE the fonts.ready build", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    var tl = gsap.timeline({ paused: true });
+    window.__timelines["c1"] = tl;
+    document.fonts.ready.then(function () {
+      tl.from("#editor", { opacity: 0, duration: 0.5 }, 0);
+    });
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find(
+      (f) => f.code === "gsap_timeline_registered_before_async_build",
+    );
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+  });
+
+  it("does NOT error when window.__timelines is registered AFTER the fonts.ready build", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    var tl = gsap.timeline({ paused: true });
+    document.fonts.ready.then(function () {
+      tl.from("#editor", { opacity: 0, duration: 0.5 }, 0);
+      window.__timelines["c1"] = tl;
+    });
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find(
+      (f) => f.code === "gsap_timeline_registered_before_async_build",
+    );
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT error when GSAP animates opacity on a clip element (by id)", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="overlay" class="clip" data-start="0" data-duration="5" data-track-index="0">
+      <h1>Hello</h1>
+    </div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#overlay", { opacity: 0, duration: 0.5 }, 4.0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT error when GSAP targets a clip element with safe properties (by class)", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="card" class="clip my-card" data-start="0" data-duration="5" data-track-index="0">
+      <p>Content</p>
+    </div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.from(".my-card", { y: 100, duration: 0.3 }, 0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT flag GSAP targeting a child of a clip element", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="overlay" class="clip" data-start="0" data-duration="5" data-track-index="0">
+      <h1 class="title">Hello</h1>
+    </div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to(".title", { opacity: 1, duration: 0.5 }, 0.5);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT flag GSAP targeting a nested selector like '#overlay .title'", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="overlay" class="clip" data-start="0" data-duration="5" data-track-index="0">
+      <h1 class="title">Hello</h1>
+    </div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#overlay .title", { opacity: 1, duration: 0.5 }, 0.5);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT error when GSAP targets a clip element with safe properties (class-only, no id)", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div class="clip scene-card" data-start="0" data-duration="5" data-track-index="0">
+      <p>Content</p>
+    </div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to(".scene-card", { y: -50, duration: 0.4 }, 0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
+    expect(finding).toBeUndefined();
+  });
+
+  it("errors when a full-frame transition flash starts visible before GSAP controls it", async () => {
+    const html = `
+<html><body data-composition-id="c1" data-width="1920" data-height="1080">
+  <div id="tr-flash-1" style="position:fixed;inset:0;background:#fff;pointer-events:none;z-index:990"></div>
+  <section class="clip" data-start="0" data-duration="8"><h1>Scene 1</h1></section>
+  <section class="clip" data-start="8" data-duration="8"><h1>Scene 2</h1></section>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#tr-flash-1", { opacity: 1, duration: 0.08 }, 7.92);
+    tl.to("#tr-flash-1", { opacity: 0, duration: 0.18 }, 8.00);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find(
+      (f) => f.code === "gsap_fullscreen_overlay_starts_visible",
+    );
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.selector).toBe("#tr-flash-1");
+    expect(finding?.message).toContain("blank/white video");
+  });
+
+  it("does not error when a full-frame transition flash is initially hidden", async () => {
+    const html = `
+<html><body data-composition-id="c1" data-width="1920" data-height="1080">
+  <div id="tr-flash-1" style="position:fixed;inset:0;background:#fff;opacity:0;pointer-events:none;z-index:990"></div>
+  <section class="clip" data-start="0" data-duration="8"><h1>Scene 1</h1></section>
+  <section class="clip" data-start="8" data-duration="8"><h1>Scene 2</h1></section>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#tr-flash-1", { opacity: 1, duration: 0.08 }, 7.92);
+    tl.to("#tr-flash-1", { opacity: 0, duration: 0.18 }, 8.00);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find(
+      (f) => f.code === "gsap_fullscreen_overlay_starts_visible",
+    );
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not error when GSAP hides a full-frame transition flash at frame zero", async () => {
+    const html = `
+<html><body data-composition-id="c1" data-width="1920" data-height="1080">
+  <div id="tr-flash-1" style="position:fixed;inset:0;background:#fff;pointer-events:none;z-index:990"></div>
+  <section class="clip" data-start="0" data-duration="8"><h1>Scene 1</h1></section>
+  <section class="clip" data-start="8" data-duration="8"><h1>Scene 2</h1></section>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.set("#tr-flash-1", { opacity: 0 }, 0);
+    tl.to("#tr-flash-1", { opacity: 1, duration: 0.08 }, 7.92);
+    tl.to("#tr-flash-1", { opacity: 0, duration: 0.18 }, 8.00);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find(
+      (f) => f.code === "gsap_fullscreen_overlay_starts_visible",
+    );
+    expect(finding).toBeUndefined();
+  });
+
+  it("reports one full-frame transition flash finding when multiple scripts touch it", async () => {
+    const html = `
+<html><body data-composition-id="c1" data-width="1920" data-height="1080">
+  <div id="tr-flash-1" style="position:fixed;inset:0;background:#fff;pointer-events:none;z-index:990"></div>
+  <section class="clip" data-start="0" data-duration="8"><h1>Scene 1</h1></section>
+  <section class="clip" data-start="8" data-duration="8"><h1>Scene 2</h1></section>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#tr-flash-1", { opacity: 1, duration: 0.08 }, 7.92);
+    tl.to("#tr-flash-1", { opacity: 0, duration: 0.18 }, 8.00);
+    window.__timelines["c1"] = tl;
+  </script>
+  <script>
+    const tl2 = gsap.timeline({ paused: true });
+    tl2.to("#tr-flash-1", { opacity: 1, duration: 0.08 }, 9.92);
+    tl2.to("#tr-flash-1", { opacity: 0, duration: 0.18 }, 10.00);
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    expect(
+      result.findings.filter((f) => f.code === "gsap_fullscreen_overlay_starts_visible"),
+    ).toHaveLength(1);
+  });
+
+  it("errors when a full-frame transition flash uses a GSAP from reveal", async () => {
+    const html = `
+<html><body data-composition-id="c1" data-width="1920" data-height="1080">
+  <div id="tr-flash-1" style="position:fixed;inset:0;background:#fff;pointer-events:none;z-index:990"></div>
+  <section class="clip" data-start="0" data-duration="8"><h1>Scene 1</h1></section>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.from("#tr-flash-1", { opacity: 0, duration: 0.18 }, 7.92);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find(
+      (f) => f.code === "gsap_fullscreen_overlay_starts_visible",
+    );
+    expect(finding).toBeDefined();
+    expect(finding?.selector).toBe("#tr-flash-1");
+  });
+
+  it("errors when a grouped GSAP selector targets a visible full-frame flash", async () => {
+    const html = `
+<html><body data-composition-id="c1" data-width="1920" data-height="1080">
+  <div id="tr-flash-1" style="position:fixed;inset:0;background:#fff;pointer-events:none;z-index:990"></div>
+  <div id="unused"></div>
+  <section class="clip" data-start="0" data-duration="8"><h1>Scene 1</h1></section>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#unused, #tr-flash-1", { opacity: 1, duration: 0.08 }, 7.92);
+    tl.to("#unused, #tr-flash-1", { opacity: 0, duration: 0.18 }, 8.00);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find(
+      (f) => f.code === "gsap_fullscreen_overlay_starts_visible",
+    );
+    expect(finding).toBeDefined();
+    expect(finding?.selector).toBe("#tr-flash-1");
+  });
+
+  it("errors when full-frame transition flash styles come from a style block", async () => {
+    const html = `
+<html><body data-composition-id="c1" data-width="1920" data-height="1080">
+  <style>
+    .tr-flash { position: fixed; inset: 0; background: #fff; pointer-events: none; z-index: 990; }
+  </style>
+  <div id="tr-flash-1" class="tr-flash"></div>
+  <section class="clip" data-start="0" data-duration="8"><h1>Scene 1</h1></section>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to(".tr-flash", { opacity: 1, duration: 0.08 }, 7.92);
+    tl.to(".tr-flash", { opacity: 0, duration: 0.18 }, 8.00);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find(
+      (f) => f.code === "gsap_fullscreen_overlay_starts_visible",
+    );
+    expect(finding).toBeDefined();
+    expect(finding?.selector).toBe(".tr-flash");
+  });
+
+  it("does NOT error when GSAP animates opacity on a clip element", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="title" class="clip" data-start="0" data-duration="5" data-track-index="0">
+      <h1>Title</h1>
+    </div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.from("#title", { opacity: 0, y: -50, duration: 0.5 }, 0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT error when GSAP animates transform props on a clip element", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="box" class="clip" data-start="0" data-duration="5" data-track-index="0">
+      <div>Box</div>
+    </div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#box", { scale: 1.2, x: 100, rotation: 45, duration: 0.5 }, 0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT require a local GSAP script for sub-compositions", async () => {
+    const html = `<template id="intro-template">
+  <div data-composition-id="intro" data-width="1920" data-height="1080">
+    <div class="title">Hello</div>
+    <script>
+      window.__timelines = window.__timelines || {};
+      const tl = gsap.timeline({ paused: true });
+      tl.from(".title", { opacity: 0, duration: 1 });
+      window.__timelines["intro"] = tl;
+    </script>
+  </div>
+</template>`;
+
+    const result = await lintHyperframeHtml(html, { isSubComposition: true });
+    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT require a local GSAP script when a template composition is linted in isolation", async () => {
+    const html = `<template id="intro-template">
+  <div data-composition-id="intro" data-width="1920" data-height="1080">
+    <div class="title">Hello</div>
+    <script>
+      window.__timelines = window.__timelines || {};
+      const tl = gsap.timeline({ paused: true });
+      tl.from(".title", { opacity: 0, duration: 1 });
+      window.__timelines["intro"] = tl;
+    </script>
+  </div>
+</template>`;
+
+    const result = await lintHyperframeHtml(html, { filePath: "compositions/intro.html" });
+    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
+    expect(finding).toBeUndefined();
+  });
+
+  it("ERRORS when GSAP animates visibility on a clip element", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="overlay" class="clip" data-start="0" data-duration="5" data-track-index="0">
+      <p>Overlay</p>
+    </div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#overlay", { visibility: "hidden", duration: 0.3 }, 2.0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.selector).toBe("#overlay");
+    expect(finding?.message).toContain("visibility");
+  });
+
+  it("ERRORS when GSAP animates display on a clip element", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="card" class="clip" data-start="0" data-duration="5" data-track-index="0">
+      <p>Card</p>
+    </div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#card", { display: "none", duration: 0.3 }, 3.0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.selector).toBe("#card");
+    expect(finding?.message).toContain("display");
+  });
+
+  it("ERRORS when GSAP tween mixes safe properties with visibility on a clip element", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="overlay" class="clip" data-start="0" data-duration="5" data-track-index="0">
+      <h1>Hello</h1>
+    </div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#overlay", { opacity: 0, visibility: "hidden", duration: 0.3 }, 2.0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.message).toContain("visibility");
+  });
+
+  it("warns when tl.to animates x on an element with CSS translateX", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="title" style=""></div>
+  </div>
+  <style>
+    #title { position: absolute; top: 240px; left: 50%; transform: translateX(-50%); }
+  </style>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#title", { x: 0, opacity: 1, duration: 0.4 }, 0.5);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.selector).toBe("#title");
+    expect(finding?.fixHint).toMatch(/fromTo/);
+    expect(finding?.fixHint).toMatch(/xPercent/);
+  });
+
+  it("warns when tl.to animates scale on an element with CSS scale transform", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="hero"></div>
+  </div>
+  <style>
+    #hero { transform: scale(0.8); opacity: 0; }
+  </style>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#hero", { opacity: 1, scale: 1, duration: 0.5 }, 1.0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.selector).toBe("#hero");
+  });
+
+  it("does NOT warn when tl.to targets element without CSS transform", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="card"></div>
+  </div>
+  <style>
+    #card { position: absolute; top: 100px; left: 100px; opacity: 0; }
+  </style>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#card", { x: 0, opacity: 1, duration: 0.3 }, 0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const conflict = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
+    expect(conflict).toBeUndefined();
+  });
+
+  it("does NOT warn when tl.fromTo targets element WITH CSS transform (author owns both ends)", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="title"></div>
+  </div>
+  <style>
+    #title { position: absolute; left: 50%; transform: translateX(-50%); }
+  </style>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.fromTo("#title", { xPercent: -50, x: -1000, opacity: 0 }, { xPercent: -50, x: 0, opacity: 1, duration: 0.4 }, 0.5);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const conflict = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
+    expect(conflict).toBeUndefined();
+  });
+
+  it("does NOT warn when tl.from targets element WITH CSS transform (from() owns start values)", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="badge"></div>
+  </div>
+  <style>
+    #badge { position: absolute; left: 50%; transform: translateX(-50%); }
+  </style>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.from("#badge", { xPercent: -50, x: -200, opacity: 0, duration: 0.4 }, 0.5);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const conflict = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
+    expect(conflict).toBeUndefined();
+  });
+
+  it("emits one warning when a combined CSS transform conflicts with multiple GSAP properties", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="hero"></div>
+  </div>
+  <style>
+    #hero { transform: translateX(-50%) scale(0.8); }
+  </style>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#hero", { x: 0, scale: 1, opacity: 1, duration: 0.5 }, 1.0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const conflicts = result.findings.filter((f) => f.code === "gsap_css_transform_conflict");
+    expect(conflicts).toHaveLength(1);
+    expect(conflicts[0]?.message).toMatch(/x\/scale|scale\/x/);
+  });
+
+  // --- Inline style transform detection tests ---
+
+  it("warns when inline style transform: translateX conflicts with GSAP x", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="centered" style="position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%);">Text</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#centered", { x: 0, y: 0, opacity: 1, duration: 0.4 }, 0.5);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
+    expect(finding).toBeDefined();
+    expect(finding?.selector).toBe("#centered");
+  });
+
+  it("warns when inline style transform: scale conflicts with GSAP scale", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="box" style="transform: scale(0.9);">Box</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#box", { scale: 1, duration: 0.5 }, 1.0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
+    expect(finding).toBeDefined();
+    expect(finding?.selector).toBe("#box");
+  });
+
+  it("does not false-positive on inline transform: rotate when GSAP uses rotation", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="spinner" style="transform: rotate(12deg);">Icon</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#spinner", { rotation: 360, duration: 1 }, 0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    // rotation doesn't conflict with rotate() — GSAP handles rotation separately
+    const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
+    expect(finding).toBeUndefined();
+  });
+
+  it("detects conflict via class selector when element has multiple classes", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div class="card hero" style="transform: translateX(-50%);">Card</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to(".hero", { x: 100, duration: 0.4 }, 0.5);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
+    expect(finding).toBeDefined();
+  });
+
+  it("handles both style block and inline style on same selector without crash", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="dual" style="transform: scale(0.5);">Dual</div>
+  </div>
+  <style>
+    #dual { transform: translateY(-50%); }
+  </style>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#dual", { y: 0, scale: 1, duration: 0.5 }, 0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const conflicts = result.findings.filter((f) => f.code === "gsap_css_transform_conflict");
+    expect(conflicts.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("detects conflict via a SCOPED descendant selector (tl.to)", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div class="lab">Label</div>
+  </div>
+  <style>
+    .lab { transform: translateX(-50%); }
+  </style>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#root .lab", { x: 40, opacity: 1, duration: 0.4 }, 0.5);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
+    expect(finding).toBeDefined();
+    expect(finding?.selector).toBe("#root .lab");
+  });
+
+  it("detects conflict via a standalone gsap.set with a GROUPED scoped selector", async () => {
+    // The exact shape that slipped through: centering seated with a standalone
+    // gsap.set on a grouped, #root-scoped selector, against a CSS class transform.
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div class="lab">A</div><div class="sub">B</div>
+  </div>
+  <style>
+    .lab { transform: translateX(-50%); }
+    .sub { transform: translateX(-50%); }
+  </style>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    gsap.set("#root .lab, #root .sub", { xPercent: -50 });
+    tl.to(".lab", { y: 0, opacity: 1, duration: 0.4 }, 0.5);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find(
+      (f) => f.code === "gsap_css_transform_conflict" && f.selector === "#root .lab, #root .sub",
+    );
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+  });
+
+  it("does NOT false-positive when a scoped selector targets a class WITHOUT a CSS transform", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div class="lab">Label</div>
+  </div>
+  <style>
+    .lab { opacity: 0; }
+  </style>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#root .lab", { x: 40, opacity: 1, duration: 0.4 }, 0.5);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const conflict = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
+    expect(conflict).toBeUndefined();
+  });
+
+  it("reports error when GSAP is used without a GSAP script tag", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#box", { x: 100, duration: 1 }, 0);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.message).toContain("GSAP");
+  });
+
+  it("does not report missing_gsap_script when GSAP CDN script is present", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></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("#box", { x: 100, duration: 1 }, 0);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not report missing_gsap_script when GSAP is bundled inline", async () => {
+    // Simulate a large inline GSAP bundle (>5KB) with GreenSock marker
+    const fakeGsapLib = "/* GreenSock GSAP */" + " ".repeat(6000);
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
+  <script>${fakeGsapLib}</script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#box", { x: 100, duration: 1 }, 0);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not report missing_gsap_script when producer inlined CDN script", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
+  <script>/* inlined: https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js */
+    !function(t,e){t.gsap=e()}(this,function(){return {}});
+  </script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#box", { x: 100, duration: 1 }, 0);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
+    expect(finding).toBeUndefined();
+  });
+
+  it("still reports missing_gsap_script for small inline scripts that use but don't bundle GSAP", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#box", { x: 100, duration: 1 }, 0);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+  });
+
+  it("errors on repeat: -1 (infinite repeat breaks capture engine)", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></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("#spinner", { rotation: 360, duration: 0.8, repeat: -1, ease: "none" }, 0);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_infinite_repeat");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.message).toContain("repeat: -1");
+  });
+
+  it("does not error on finite repeat values", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></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("#spinner", { rotation: 360, duration: 0.8, repeat: 4, ease: "none" }, 0);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_infinite_repeat");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not error on repeat: -1 inside JavaScript comments", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></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 });
+    // avoid repeat:-1 anywhere in user code
+    /*
+      This rule should still allow comments mentioning repeat: -1.
+    */
+    tl.to("#spinner", { rotation: 360, duration: 0.8, repeat: 4, ease: "none" }, 0);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_infinite_repeat");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT report overlapping_gsap_tweens when an object-target tween is interleaved (regression)", async () => {
+    // Regression: a non-DOM-targeting tween like `tl.to({ _: 0 }, …)` (used to
+    // anchor timeline duration) was matched by the regex but skipped by the
+    // parser, drifting the index and making the second tween "see" the first
+    // tween's selector — producing a phantom self-overlap warning.
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="a" class="clip" data-start="0" data-duration="5" data-track-index="0"></div>
+    <div id="b" class="clip" data-start="0" data-duration="5" data-track-index="1"></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({ _: 0 }, { _: 1, duration: 5, ease: "none" }, 0);
+    tl.to("#a", { opacity: 1, duration: 0.5 }, 0);
+    tl.to("#b", { opacity: 1, duration: 0.5 }, 1);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "overlapping_gsap_tweens");
+    expect(finding).toBeUndefined();
+  });
+
+  it("detects overlapping_gsap_tweens between variable-target tweens", async () => {
+    // Both tweens target the same element via a querySelector variable and their
+    // windows overlap on `opacity`. The structure-driven window builder must see
+    // through the variable target to flag the conflict.
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="hero" class="hero" data-start="0" data-duration="5" data-track-index="0"></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 });
+    const hero = document.querySelector("#hero");
+    tl.to(hero, { opacity: 1, duration: 1 }, 0);
+    tl.to(hero, { opacity: 0.5, duration: 1 }, 0.5);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "overlapping_gsap_tweens");
+    expect(finding).toBeDefined();
+  });
+
+  it("warns when an opacity exit ends at a clip start boundary without a hard kill", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0" data-duration="6">
+    <div id="scene-a" class="clip" data-start="0" data-duration="3" data-track-index="0">
+      <h1 id="headline">First beat</h1>
+    </div>
+    <div id="scene-b" class="clip" data-start="3" data-duration="3" data-track-index="0">
+      <h1>Second beat</h1>
+    </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("#headline", { opacity: 0, duration: 0.3 }, 2.7);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_exit_missing_hard_kill");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.selector).toBe("#headline");
+    expect(finding?.message).toContain("3.00s");
+  });
+
+  it("does not warn when a boundary exit has a matching hard kill", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0" data-duration="6">
+    <div id="scene-a" class="clip" data-start="0" data-duration="3" data-track-index="0">
+      <h1 id="headline">First beat</h1>
+    </div>
+    <div id="scene-b" class="clip" data-start="3" data-duration="3" data-track-index="0">
+      <h1>Second beat</h1>
+    </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("#headline", { opacity: 0, duration: 0.3 }, 2.7);
+    tl.set("#headline", { opacity: 0, visibility: "hidden" }, 3);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_exit_missing_hard_kill");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not match sub-composition exits against root clip boundaries", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="root" data-width="1920" data-height="1080" data-start="0" data-duration="6">
+    <div id="root-a" class="clip" data-start="0" data-duration="3" data-track-index="0"></div>
+    <div id="root-b" class="clip" data-start="3" data-duration="3" data-track-index="0"></div>
+  </div>
+  <div data-composition-id="sub" data-width="1920" data-height="1080" data-start="0" data-duration="4">
+    <div id="sub-a" class="clip" data-start="0" data-duration="2" data-track-index="0">
+      <h1 id="sub-title">Sub scene</h1>
+    </div>
+    <div id="sub-b" class="clip" data-start="2" data-duration="2" data-track-index="0"></div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#sub-title", { opacity: 0, duration: 0.3 }, 2.7);
+    window.__timelines["sub"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_exit_missing_hard_kill");
+    expect(finding).toBeUndefined();
+  });
+
+  it("uses the authored hidden property in hard-kill fix hints", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0" data-duration="6">
+    <div id="scene-a" class="clip" data-start="0" data-duration="3" data-track-index="0">
+      <h1 id="headline">First beat</h1>
+    </div>
+    <div id="scene-b" class="clip" data-start="3" data-duration="3" data-track-index="0">
+      <h1>Second beat</h1>
+    </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("#headline", { autoAlpha: 0, duration: 0.3 }, 2.7);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_exit_missing_hard_kill");
+    expect(finding?.fixHint).toContain("{ autoAlpha: 0 }");
+  });
+
+  it("does not false-positive on repeat: -10 (invalid GSAP but not infinite)", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080"></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("#box", { x: 100, duration: 1, repeat: -10 }, 0);
+    window.__timelines["main"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_infinite_repeat");
+    expect(finding).toBeUndefined();
+  });
+
+  it("errors when CSS opacity:0 + gsap.from({opacity:0}) — invisible forever", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="title" style="opacity: 0; font-size: 120px;">Hello</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.from("#title", { opacity: 0, y: 30, duration: 0.5 }, 0.2);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
+    expect(finding).toBeDefined();
+    expect(finding!.severity).toBe("error");
+    expect(finding!.selector).toBe("#title");
+  });
+
+  it("errors when style block has opacity:0 + gsap.from({opacity:0})", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="hero">Hello</div>
+  </div>
+  <style>
+    #hero { font-size: 200px; color: #fff; opacity: 0; }
+  </style>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.from("#hero", { opacity: 0, scale: 3.5, duration: 0.25, ease: "expo.out" }, 0.1);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
+    expect(finding).toBeDefined();
+  });
+
+  it("does NOT error when gsap.from({opacity:0}) and CSS has no opacity:0", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="title" style="font-size: 120px; color: #fff;">Hello</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.from("#title", { opacity: 0, y: 30, duration: 0.5 }, 0.2);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT error when gsap.fromTo({opacity:0}, {opacity:1}) — destination overrides CSS", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="title" style="opacity: 0; font-size: 120px;">Hello</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.fromTo("#title", { opacity: 0, y: 30 }, { opacity: 1, y: 0, duration: 0.5 }, 0.2);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT error when gsap.to() uses opacity:0 (exit animation)", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="title" style="opacity: 0;">Hello</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#title", { opacity: 0, duration: 0.5 }, 4.0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT error when gsap.from({opacity: 0.5}) — non-zero opacity is a valid reveal", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="ghost" style="opacity: 0;">Hello</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.from("#ghost", { opacity: 0.5, duration: 0.4 }, 0.1);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
+    expect(finding).toBeUndefined();
+  });
+
+  it("warns when gsap.timeline is created but not registered in __timelines", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="root" data-width="1920" data-height="1080">
+    <div id="box">Hello</div>
+  </div>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
+  <script>
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#box", { opacity: 0.5, duration: 2 });
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_timeline_not_registered");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+  });
+
+  it("does NOT warn when timeline is registered in __timelines", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="root" data-width="1920" data-height="1080">
+    <div id="box">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("#box", { opacity: 0.5, duration: 2 });
+    window.__timelines["root"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_timeline_not_registered");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT warn when timeline is registered with dot property syntax", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="root" data-width="1920" data-height="1080">
+    <div id="box">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("#box", { opacity: 0.5, duration: 2 });
+    window.__timelines.root = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_timeline_not_registered");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT warn for sub-compositions (template-based)", async () => {
+    const html = `
+<template>
+  <div data-composition-id="sub" data-width="1920" data-height="1080">
+    <div id="box">Hello</div>
+  </div>
+  <script>
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#box", { opacity: 0.5, duration: 2 });
+  </script>
+</template>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_timeline_not_registered");
+    expect(finding).toBeUndefined();
+  });
+
+  it("scene_layer_missing_visibility_kill: fires when multi-scene exit lacks hard kill", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="scene1"></div>
+    <div id="scene2"></div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#scene1", { opacity: 0, duration: 0.5 }, 2.0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "scene_layer_missing_visibility_kill");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.elementId).toBe("scene1");
+  });
+
+  it("scene_layer_missing_visibility_kill: DOES fire when kill is only in a comment (stripJsComments guard)", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="scene1"></div>
+    <div id="scene2"></div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    // tl.set("#scene1", { visibility: "hidden" }, 2.5);
+    tl.to("#scene1", { opacity: 0, duration: 0.5 }, 2.0);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "scene_layer_missing_visibility_kill");
+    expect(finding).toBeDefined();
+  });
+
+  it("scene_layer_missing_visibility_kill: does NOT fire when hard kill is present", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="scene1"></div>
+    <div id="scene2"></div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#scene1", { opacity: 0, duration: 0.5 }, 2.0);
+    tl.set("#scene1", { visibility: "hidden" }, 2.5);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "scene_layer_missing_visibility_kill");
+    expect(finding).toBeUndefined();
+  });
+});
diff --git a/packages/lint/src/rules/gsap.ts b/packages/lint/src/rules/gsap.ts
new file mode 100644
index 0000000000..ef792db500
--- /dev/null
+++ b/packages/lint/src/rules/gsap.ts
@@ -0,0 +1,1142 @@
+interface LintParsedGsap {
+  animations: Array<{
+    targetSelector: string;
+    method: string;
+    position: number | string;
+    properties: Record<string, number | string>;
+    duration?: number;
+    ease?: string;
+    extras?: Record<string, unknown>;
+  }>;
+  timelineVar: string;
+}
+
+// Use the acorn read parser: it resolves computed timelines (helpers, bounded
+// loops) so lint findings like overlapping_gsap_tweens reflect true positions
+// instead of all-collapsed-at-0. It's also browser-safe, so this keeps recast
+// out of the lint graph entirely. Dynamic import preserves the lazy load.
+async function loadParseGsapScript(): Promise<(script: string) => LintParsedGsap> {
+  const mod = await import("@hyperframes/parsers/gsap-parser-acorn");
+  return mod.parseGsapScriptAcorn as unknown as (script: string) => LintParsedGsap;
+}
+import type { LintContext } from "../context";
+import type { HyperframeLintFinding, LintRule } from "../types";
+import type { OpenTag } from "../utils";
+import {
+  readAttr,
+  truncateSnippet,
+  stripJsComments,
+  WINDOW_TIMELINE_ASSIGN_PATTERN,
+} from "../utils";
+
+// ── GSAP-specific types ────────────────────────────────────────────────────
+
+type GsapWindow = {
+  targetSelector: string;
+  position: number;
+  end: number;
+  properties: string[];
+  propertyValues: Record<string, string | number>;
+  overwriteAuto: boolean;
+  method: string;
+  raw: string;
+};
+
+type CompositionRange = {
+  id: string;
+  start: number;
+  end: number;
+};
+
+const SCENE_BOUNDARY_EPSILON_SECONDS = 0.05;
+
+// ── GSAP parsing utilities ─────────────────────────────────────────────────
+
+function countClassUsage(tags: OpenTag[]): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const tag of tags) {
+    const classAttr = readAttr(tag.raw, "class");
+    if (!classAttr) continue;
+    for (const className of classAttr.split(/\s+/).filter(Boolean)) {
+      counts.set(className, (counts.get(className) || 0) + 1);
+    }
+  }
+  return counts;
+}
+
+function readRegisteredTimelineCompositionId(script: string): string | null {
+  const match = script.match(WINDOW_TIMELINE_ASSIGN_PATTERN);
+  return match?.[1] || match?.[2] || null;
+}
+
+/** Strip a `__raw:` prefix the parser adds to unresolvable values. */
+function unwrapRaw(value: unknown): string | number | undefined {
+  if (typeof value === "number") return value;
+  if (typeof value !== "string") return undefined;
+  const code = value.startsWith("__raw:") ? value.slice(6) : value;
+  return code.replace(/^\s*["']|["']\s*$/g, "");
+}
+
+function extrasNumber(value: unknown): number {
+  const unwrapped = unwrapRaw(value);
+  const numeric = typeof unwrapped === "number" ? unwrapped : Number(unwrapped);
+  return Number.isFinite(numeric) ? numeric : 0;
+}
+
+/** A readable single-line snippet of a tween for finding messages. */
+function synthesizeWindowRaw(
+  timelineVar: string,
+  anim: LintParsedGsap["animations"][number],
+): string {
+  const entries = Object.entries(anim.properties).map(([k, v]) => {
+    if (typeof v === "string" && v.startsWith("__raw:")) return `${k}: ${v.slice(6)}`;
+    return `${k}: ${typeof v === "string" ? JSON.stringify(v) : v}`;
+  });
+  if (anim.duration !== undefined) entries.push(`duration: ${anim.duration}`);
+  if (anim.ease) entries.push(`ease: ${JSON.stringify(anim.ease)}`);
+  const pos = typeof anim.position === "number" ? anim.position : JSON.stringify(anim.position);
+  return `${timelineVar}.${anim.method}("${anim.targetSelector}", { ${entries.join(", ")} }, ${pos})`;
+}
+
+const gsapWindowsCache = new Map<string, GsapWindow[]>();
+
+async function cachedExtractGsapWindows(scriptContent: string): Promise<GsapWindow[]> {
+  const cached = gsapWindowsCache.get(scriptContent);
+  if (cached) return cached;
+  const windows = await extractGsapWindows(scriptContent);
+  gsapWindowsCache.set(scriptContent, windows);
+  return windows;
+}
+
+// fallow-ignore-next-line complexity
+async function extractGsapWindows(script: string): Promise<GsapWindow[]> {
+  if (!/gsap\.timeline/.test(script)) return [];
+  const parseGsapScript = await loadParseGsapScript();
+  const parsed = parseGsapScript(script);
+  if (parsed.animations.length === 0) return [];
+
+  const windows: GsapWindow[] = [];
+  for (const animation of parsed.animations) {
+    // Skip animations with string positions (e.g. "+=1", "<") — their absolute
+    // timing depends on runtime evaluation and can't be statically linted.
+    if (typeof animation.position !== "number") continue;
+    const repeat = extrasNumber(animation.extras?.repeat);
+    const cycleCount = repeat > 0 ? repeat + 1 : 1;
+    const effectiveDuration =
+      animation.method === "set" ? 0 : (animation.duration ?? 0) * cycleCount;
+    windows.push({
+      targetSelector: animation.targetSelector,
+      position: animation.position,
+      end: animation.position + effectiveDuration,
+      properties: Object.keys(animation.properties),
+      propertyValues: animation.properties,
+      overwriteAuto: unwrapRaw(animation.extras?.overwrite) === "auto",
+      method: animation.method,
+      raw: synthesizeWindowRaw(parsed.timelineVar, animation),
+    });
+  }
+  return windows;
+}
+
+function numberValue(value: string | number | undefined): number | null {
+  if (typeof value === "number") return value;
+  if (typeof value === "string" && value.trim()) {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : null;
+  }
+  return null;
+}
+
+function stringValue(value: string | number | undefined): string | null {
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return String(value);
+  return null;
+}
+
+function zeroValue(value: string | number | undefined): boolean {
+  if (typeof value === "number") return value === 0;
+  if (typeof value !== "string") return false;
+  return Number(value.trim()) === 0;
+}
+
+function isHiddenGsapState(values: Record<string, string | number>): boolean {
+  const visibility = stringValue(values.visibility)?.toLowerCase();
+  const display = stringValue(values.display)?.toLowerCase();
+  return (
+    zeroValue(values.opacity) ||
+    zeroValue(values.autoAlpha) ||
+    visibility === "hidden" ||
+    display === "none"
+  );
+}
+
+function oneValue(
+  values: Record<string, string | number>,
+  keys: string[],
+): string | number | undefined {
+  for (const key of keys) {
+    const value = values[key];
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+function isVisibleGsapState(values: Record<string, string | number>): boolean {
+  const opacity = oneValue(values, ["opacity", "autoAlpha"]);
+  if (typeof opacity === "number") return opacity > 0;
+  if (typeof opacity === "string" && opacity.trim()) {
+    const numeric = Number(opacity);
+    if (Number.isFinite(numeric)) return numeric > 0;
+  }
+
+  const visibility = stringValue(values.visibility)?.toLowerCase();
+  if (visibility === "visible" || visibility === "inherit") return true;
+
+  const display = stringValue(values.display)?.toLowerCase();
+  if (display && display !== "none") return true;
+
+  return false;
+}
+
+function makesOverlayVisible(win: GsapWindow): boolean {
+  if (win.method === "from" && isHiddenGsapState(win.propertyValues)) return true;
+  return isVisibleGsapState(win.propertyValues);
+}
+
+function isSceneBoundaryExit(win: GsapWindow): boolean {
+  if (win.end <= win.position) return false;
+  if (win.method !== "to" && win.method !== "fromTo") return false;
+  return isHiddenGsapState(win.propertyValues);
+}
+
+function isHardKillSet(win: GsapWindow, selector: string, boundary: number): boolean {
+  return (
+    win.method === "set" &&
+    win.targetSelector === selector &&
+    Math.abs(win.position - boundary) <= SCENE_BOUNDARY_EPSILON_SECONDS &&
+    isHiddenGsapState(win.propertyValues)
+  );
+}
+
+function hiddenStateLiteral(values: Record<string, string | number>): string {
+  if (zeroValue(values.autoAlpha)) return "{ autoAlpha: 0 }";
+  if (zeroValue(values.opacity)) return "{ opacity: 0 }";
+  if (stringValue(values.visibility)?.toLowerCase() === "hidden") return '{ visibility: "hidden" }';
+  if (stringValue(values.display)?.toLowerCase() === "none") return '{ display: "none" }';
+  return "{ opacity: 0 }";
+}
+
+function findTagEnd(source: string, tag: OpenTag): number {
+  const escapedTagName = tag.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`<\\/?${escapedTagName}\\b[^>]*>`, "gi");
+  pattern.lastIndex = tag.index;
+
+  let depth = 0;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(source)) !== null) {
+    const raw = match[0];
+    const isClosing = /^<\s*\//.test(raw);
+    const isSelfClosing = /\/\s*>$/.test(raw);
+    if (!isClosing && !isSelfClosing) depth += 1;
+    if (isClosing) depth -= 1;
+    if (depth === 0) return pattern.lastIndex;
+  }
+
+  return source.length;
+}
+
+function collectCompositionRanges(source: string, tags: OpenTag[]): CompositionRange[] {
+  return tags
+    .map((tag) => {
+      const id = readAttr(tag.raw, "data-composition-id");
+      if (!id) return null;
+      return {
+        id,
+        start: tag.index,
+        end: findTagEnd(source, tag),
+      };
+    })
+    .filter((range) => range !== null);
+}
+
+function findContainingCompositionId(tag: OpenTag, ranges: CompositionRange[]): string | null {
+  let match: CompositionRange | null = null;
+  for (const range of ranges) {
+    if (tag.index < range.start || tag.index >= range.end) continue;
+    if (!match || range.start >= match.start) match = range;
+  }
+  return match?.id || null;
+}
+
+function collectClipStartBoundariesByComposition(
+  source: string,
+  tags: OpenTag[],
+): Map<string, number[]> {
+  const ranges = collectCompositionRanges(source, tags);
+  const boundaries = new Map<string, Set<number>>();
+
+  for (const tag of tags) {
+    const classAttr = readAttr(tag.raw, "class") || "";
+    const classes = classAttr.split(/\s+/).filter(Boolean);
+    if (!classes.includes("clip")) continue;
+    const compositionId = findContainingCompositionId(tag, ranges);
+    if (!compositionId) continue;
+    const start = numberValue(readAttr(tag.raw, "data-start") ?? undefined);
+    if (start == null || start <= 0) continue;
+    const compositionBoundaries = boundaries.get(compositionId) ?? new Set<number>();
+    compositionBoundaries.add(start);
+    boundaries.set(compositionId, compositionBoundaries);
+  }
+
+  return new Map(
+    [...boundaries.entries()].map(([compositionId, values]) => [
+      compositionId,
+      [...values].sort((a, b) => a - b),
+    ]),
+  );
+}
+
+function findMatchingSceneBoundary(time: number, boundaries: number[]): number | null {
+  for (const boundary of boundaries) {
+    if (Math.abs(time - boundary) <= SCENE_BOUNDARY_EPSILON_SECONDS) return boundary;
+  }
+  return null;
+}
+
+function isSuspiciousGlobalSelector(selector: string): boolean {
+  if (!selector) return false;
+  if (selector.includes("[data-composition-id=")) return false;
+  if (selector.startsWith("#")) return false;
+  return selector.startsWith(".") || /^[a-z]/i.test(selector);
+}
+
+function getSingleClassSelector(selector: string): string | null {
+  const match = selector.trim().match(/^\.(?<name>[A-Za-z0-9_-]+)$/);
+  return match?.groups?.name || null;
+}
+
+function readStyleProperty(style: string, property: string): string | null {
+  const escapedProperty = property.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = style.match(new RegExp(`(?:^|;)\\s*${escapedProperty}\\s*:\\s*([^;]+)`, "i"));
+  return match?.[1]?.trim() || null;
+}
+
+function cssZero(value: string | null): boolean {
+  if (!value) return false;
+  return /^0(?:\.0+)?(?:px|%|vw|vh|rem|em)?$/i.test(value.trim());
+}
+
+function styleHasHiddenInitialState(style: string): boolean {
+  const opacity = readStyleProperty(style, "opacity");
+  if (opacity && Number(opacity) === 0) return true;
+  if (readStyleProperty(style, "visibility")?.toLowerCase() === "hidden") return true;
+  if (readStyleProperty(style, "display")?.toLowerCase() === "none") return true;
+  return false;
+}
+
+function styleHasOpaqueBackground(style: string): boolean {
+  const background =
+    readStyleProperty(style, "background") || readStyleProperty(style, "background-color");
+  if (!background) return false;
+  const normalized = background.toLowerCase().replace(/\s+/g, "");
+  if (normalized === "transparent" || normalized === "none") return false;
+  if (/rgba?\([^)]*,0(?:\.0+)?\)$/.test(normalized)) return false;
+  if (/hsla?\([^)]*,0(?:\.0+)?\)$/.test(normalized)) return false;
+  return true;
+}
+
+function styleLooksFullFrameOverlay(style: string): boolean {
+  const position = readStyleProperty(style, "position")?.toLowerCase();
+  if (position !== "fixed" && position !== "absolute") return false;
+  const coversFrame =
+    cssZero(readStyleProperty(style, "inset")) ||
+    (cssZero(readStyleProperty(style, "top")) &&
+      cssZero(readStyleProperty(style, "right")) &&
+      cssZero(readStyleProperty(style, "bottom")) &&
+      cssZero(readStyleProperty(style, "left")));
+  return coversFrame && styleHasOpaqueBackground(style);
+}
+
+function collectSimpleStyleRules(styles: LintContext["styles"]): Map<string, string> {
+  const rules = new Map<string, string>();
+  for (const style of styles) {
+    for (const [, selectorList, body] of style.content.matchAll(/([^{}]+)\{([^}]+)\}/g)) {
+      if (!selectorList || !body) continue;
+      for (const selector of selectorList.split(",")) {
+        const token = selector.trim();
+        if (!/^[#.][A-Za-z0-9_-]+$/.test(token)) continue;
+        rules.set(token, `${rules.get(token) || ""};${body}`);
+      }
+    }
+  }
+  return rules;
+}
+
+function tagSimpleSelectors(tag: OpenTag): string[] {
+  const selectors: string[] = [];
+  const id = readAttr(tag.raw, "id");
+  if (id) selectors.push(`#${id}`);
+  const classes = readAttr(tag.raw, "class")?.split(/\s+/).filter(Boolean) ?? [];
+  for (const className of classes) selectors.push(`.${className}`);
+  return selectors;
+}
+
+function combinedTagStyle(tag: OpenTag, styleRules: Map<string, string>): string {
+  const styles = [readAttr(tag.raw, "style") || ""];
+  for (const selector of tagSimpleSelectors(tag)) {
+    const ruleStyle = styleRules.get(selector);
+    if (ruleStyle) styles.push(ruleStyle);
+  }
+  return styles.filter(Boolean).join(";");
+}
+
+// fallow-ignore-next-line complexity
+function cssTransformToGsapProps(cssTransform: string): string | null {
+  const parts: string[] = [];
+
+  // translate(-50%, -50%) or translate(X, Y)
+  const translateMatch = cssTransform.match(
+    /translate\(\s*(-?[\d.]+)(%|px)?\s*,\s*(-?[\d.]+)(%|px)?\s*\)/,
+  );
+  if (translateMatch) {
+    const [, xVal, xUnit, yVal, yUnit] = translateMatch;
+    if (xUnit === "%") parts.push(`xPercent: ${xVal}`);
+    else parts.push(`x: ${xVal}`);
+    if (yUnit === "%") parts.push(`yPercent: ${yVal}`);
+    else parts.push(`y: ${yVal}`);
+  }
+
+  // translateX(-50%) or translateX(px)
+  const txMatch = cssTransform.match(/translateX\(\s*(-?[\d.]+)(%|px)?\s*\)/);
+  if (txMatch) {
+    const [, val, unit] = txMatch;
+    parts.push(unit === "%" ? `xPercent: ${val}` : `x: ${val}`);
+  }
+
+  // translateY(-50%) or translateY(px)
+  const tyMatch = cssTransform.match(/translateY\(\s*(-?[\d.]+)(%|px)?\s*\)/);
+  if (tyMatch) {
+    const [, val, unit] = tyMatch;
+    parts.push(unit === "%" ? `yPercent: ${val}` : `y: ${val}`);
+  }
+
+  // scale(N)
+  const scaleMatch = cssTransform.match(/scale\(\s*([\d.]+)\s*\)/);
+  if (scaleMatch) {
+    parts.push(`scale: ${scaleMatch[1]}`);
+  }
+
+  return parts.length > 0 ? parts.join(", ") : null;
+}
+
+// ── CSS-transform ↔ GSAP-transform conflict matching ─────────────────────────
+
+// Transform components that COMBINE with a CSS translate/scale on the same
+// element. GSAP bakes the element's existing CSS transform in when it seeks, so
+// these stack rather than override in the capture path (e.g. CSS translateX(-50%)
+// + xPercent:-50 renders as -100% — off-centre). `rotation` is excluded: it maps
+// to CSS rotate(), which this rule treats separately (no false positive on spin).
+const CONFLICTING_TRANSLATE_PROPS = ["x", "y", "xPercent", "yPercent"];
+const CONFLICTING_SCALE_PROPS = ["scale", "scaleX", "scaleY"];
+
+type GsapTransformCall = {
+  method: string;
+  selector: string;
+  properties: string[];
+  raw: string;
+};
+
+// Decompose a (possibly grouped / descendant / compound) GSAP target selector
+// into the simple `#id` / `.class` tokens of the elements it actually targets —
+// the RIGHTMOST compound of each comma group is the targeted element. This lets a
+// CSS rule keyed by a simple selector (`.m04-label`) match a scoped GSAP selector
+// (`"#root .m04-label, #root .m04-sub"`), which the prior exact-string lookup
+// missed — so every scoped/grouped selector slipped past the rule entirely.
+function targetedSelectorTokens(selector: string): Set<string> {
+  const tokens = new Set<string>();
+  for (const group of selector.split(",")) {
+    const compounds = group
+      .trim()
+      .split(/[\s>+~]+/)
+      .filter(Boolean);
+    const last = compounds[compounds.length - 1];
+    if (!last) continue;
+    const simple = last.match(/[#.][A-Za-z0-9_-]+/g);
+    if (simple) for (const token of simple) tokens.add(token);
+  }
+  return tokens;
+}
+
+// Find a CSS transform conflicting with a GSAP target selector: exact-string
+// match first (fast path + back-compat with the original behaviour), then a
+// token match so scoped/grouped/descendant selectors resolve to their class/id.
+function matchCssTransform(gsapSelector: string, cssMap: Map<string, string>): string | undefined {
+  if (cssMap.size === 0) return undefined;
+  const direct = cssMap.get(gsapSelector);
+  if (direct) return direct;
+  const tokens = targetedSelectorTokens(gsapSelector);
+  for (const [cssSelector, value] of cssMap) {
+    if (tokens.has(cssSelector)) return value;
+  }
+  return undefined;
+}
+
+// Scan for STANDALONE `gsap.set/to/from/fromTo("selector", { ...props })` calls.
+// The acorn timeline parser only captures calls rooted on the timeline var
+// (`tl.to`, `tl.set`, …); a top-level `gsap.set("#root .label", { xPercent: -50 })`
+// — a common way to seat shared base transforms before the timeline runs — is
+// invisible to it, so the conflict rule never saw it. Variable selectors
+// (`gsap.set(kicker, …)`) can't be resolved statically and are skipped.
+function extractStandaloneGsapTransformCalls(script: string): GsapTransformCall[] {
+  const calls: GsapTransformCall[] = [];
+  const pattern = /gsap\.(set|to|from|fromTo)\s*\(\s*(["'])([^"']+)\2\s*,\s*\{([^{}]*)\}/g;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(script)) !== null) {
+    const method = match[1] ?? "set";
+    const selector = match[3] ?? "";
+    const propsBody = match[4] ?? "";
+    const properties = [...propsBody.matchAll(/([A-Za-z_$][\w$]*)\s*:/g)].map((m) => m[1] ?? "");
+    calls.push({ method, selector, properties, raw: truncateSnippet(match[0]) ?? match[0] });
+  }
+  return calls;
+}
+
+// ── GSAP rules ─────────────────────────────────────────────────────────────
+
+// fallow-ignore-next-line complexity
+export const gsapRules: LintRule<LintContext>[] = [
+  // overlapping_gsap_tweens + gsap_animates_clip_element + unscoped_gsap_selector
+  // fallow-ignore-next-line complexity
+  async ({ source, tags, scripts, styles, rootCompositionId }) => {
+    const findings: HyperframeLintFinding[] = [];
+
+    // Build clip element selector map
+    type ClipInfo = { tag: string; id: string; classes: string };
+    const clipIds = new Map<string, ClipInfo>();
+    const clipClasses = new Map<string, ClipInfo>();
+    for (const tag of tags) {
+      const classAttr = readAttr(tag.raw, "class") || "";
+      const classes = classAttr.split(/\s+/).filter(Boolean);
+      if (!classes.includes("clip")) continue;
+      const id = readAttr(tag.raw, "id");
+      const info: ClipInfo = {
+        tag: tag.name,
+        id: id || "",
+        classes: classAttr,
+      };
+      if (id) clipIds.set(`#${id}`, info);
+      for (const cls of classes) {
+        if (cls !== "clip") clipClasses.set(`.${cls}`, info);
+      }
+    }
+
+    const classUsage = countClassUsage(tags);
+    const clipStartBoundariesByComposition = collectClipStartBoundariesByComposition(source, tags);
+    const styleRules = collectSimpleStyleRules(styles);
+    const reportedVisibleOverlayKeys = new Set<string>();
+
+    for (const script of scripts) {
+      const localTimelineCompId = readRegisteredTimelineCompositionId(script.content);
+      const gsapWindows = await cachedExtractGsapWindows(script.content);
+      const clipStartBoundaries =
+        clipStartBoundariesByComposition.get(localTimelineCompId || rootCompositionId || "") ?? [];
+
+      // overlapping_gsap_tweens
+      for (let i = 0; i < gsapWindows.length; i++) {
+        const left = gsapWindows[i];
+        if (!left) continue;
+        if (left.end <= left.position) continue;
+        for (let j = i + 1; j < gsapWindows.length; j++) {
+          const right = gsapWindows[j];
+          if (!right) continue;
+          if (right.end <= right.position) continue;
+          if (left.targetSelector !== right.targetSelector) continue;
+          const overlapStart = Math.max(left.position, right.position);
+          const overlapEnd = Math.min(left.end, right.end);
+          if (overlapEnd <= overlapStart) continue;
+          if (left.overwriteAuto || right.overwriteAuto) continue;
+          const sharedProperties = left.properties.filter((prop) =>
+            right.properties.includes(prop),
+          );
+          if (sharedProperties.length === 0) continue;
+          findings.push({
+            code: "overlapping_gsap_tweens",
+            severity: "warning",
+            message: `GSAP tweens overlap on "${left.targetSelector}" for ${sharedProperties.join(", ")} between ${overlapStart.toFixed(2)}s and ${overlapEnd.toFixed(2)}s.`,
+            selector: left.targetSelector,
+            fixHint: 'Shorten the earlier tween, move the later tween, or add `overwrite: "auto"`.',
+            snippet: truncateSnippet(`${left.raw}\n${right.raw}`),
+          });
+        }
+      }
+
+      // gsap_exit_missing_hard_kill
+      if (clipStartBoundaries.length > 0) {
+        for (const win of gsapWindows) {
+          if (!isSceneBoundaryExit(win)) continue;
+          const boundary = findMatchingSceneBoundary(win.end, clipStartBoundaries);
+          if (boundary == null) continue;
+          const hasHardKill = gsapWindows.some((candidate) =>
+            isHardKillSet(candidate, win.targetSelector, boundary),
+          );
+          if (hasHardKill) continue;
+
+          findings.push({
+            code: "gsap_exit_missing_hard_kill",
+            severity: "error",
+            message:
+              `GSAP exit on "${win.targetSelector}" ends at the ${boundary.toFixed(2)}s clip start boundary ` +
+              "without a matching tl.set hard kill. Non-linear seeking can land after the fade and leave stale visibility state.",
+            selector: win.targetSelector,
+            fixHint:
+              `Add \`tl.set("${win.targetSelector}", ${hiddenStateLiteral(win.propertyValues)}, ${boundary.toFixed(2)})\` ` +
+              "after the exit tween.",
+            snippet: truncateSnippet(win.raw),
+          });
+        }
+      }
+
+      // gsap_fullscreen_overlay_starts_visible
+      for (const tag of tags) {
+        const selectors = tagSimpleSelectors(tag);
+        if (selectors.length === 0) continue;
+        const overlayKey = readAttr(tag.raw, "id") || String(tag.index);
+        if (reportedVisibleOverlayKeys.has(overlayKey)) continue;
+        const authoredStyle = combinedTagStyle(tag, styleRules);
+        if (!authoredStyle || !styleLooksFullFrameOverlay(authoredStyle)) continue;
+        if (styleHasHiddenInitialState(authoredStyle)) continue;
+
+        const visibilityWindows = gsapWindows
+          .filter((win) => {
+            const tokens = targetedSelectorTokens(win.targetSelector);
+            if (!selectors.some((selector) => tokens.has(selector))) return false;
+            return win.properties.some((prop) =>
+              ["opacity", "autoAlpha", "visibility", "display"].includes(prop),
+            );
+          })
+          .sort((a, b) => a.position - b.position);
+        const startsHiddenAtZero = visibilityWindows.some(
+          (win) =>
+            win.position <= SCENE_BOUNDARY_EPSILON_SECONDS && isHiddenGsapState(win.propertyValues),
+        );
+        if (startsHiddenAtZero) continue;
+        const firstVisible = visibilityWindows.find((win) => makesOverlayVisible(win));
+        if (!firstVisible) continue;
+        const selector =
+          selectors.find((candidate) =>
+            targetedSelectorTokens(firstVisible.targetSelector).has(candidate),
+          ) ||
+          selectors[0] ||
+          tag.name;
+        const laterHidden = visibilityWindows.some(
+          (win) => win.position >= firstVisible.position && isHiddenGsapState(win.propertyValues),
+        );
+        if (firstVisible.method !== "from" && !laterHidden) continue;
+
+        reportedVisibleOverlayKeys.add(overlayKey);
+        findings.push({
+          code: "gsap_fullscreen_overlay_starts_visible",
+          severity: "error",
+          message:
+            `Full-frame overlay "${selector}" starts visible before its first GSAP opacity tween at ` +
+            `${firstVisible.position.toFixed(2)}s. It will cover earlier render frames, often as a blank/white video.`,
+          selector,
+          elementId: readAttr(tag.raw, "id") || undefined,
+          fixHint:
+            `Add \`opacity: 0\` to "${selector}" in CSS/inline styles, or add ` +
+            `\`tl.set("${selector}", { opacity: 0 }, 0)\` before the reveal tween.`,
+          snippet: truncateSnippet(firstVisible.raw),
+        });
+      }
+
+      // gsap_animates_clip_element — only error when GSAP animates visibility/display
+      for (const win of gsapWindows) {
+        const sel = win.targetSelector;
+        const clipInfo = clipIds.get(sel) || clipClasses.get(sel);
+        if (!clipInfo) continue;
+        const conflictingProps = win.properties.filter(
+          (p) => p === "visibility" || p === "display",
+        );
+        if (conflictingProps.length === 0) continue;
+        const elDesc = `<${clipInfo.tag}${clipInfo.id ? ` id="${clipInfo.id}"` : ""} class="${clipInfo.classes}">`;
+        findings.push({
+          code: "gsap_animates_clip_element",
+          severity: "error",
+          message: `GSAP animation sets ${conflictingProps.join(", ")} on a clip element. Selector "${sel}" resolves to element ${elDesc}. The framework manages clip visibility via ${conflictingProps.join("/")} — do not animate these properties on clip elements.`,
+          selector: sel,
+          elementId: clipInfo.id || undefined,
+          fixHint:
+            "Remove the visibility/display tween, or move the content into a child <div> and target that instead.",
+          snippet: truncateSnippet(win.raw),
+        });
+      }
+
+      // unscoped_gsap_selector
+      if (!localTimelineCompId || localTimelineCompId === rootCompositionId) continue;
+      for (const win of gsapWindows) {
+        if (!isSuspiciousGlobalSelector(win.targetSelector)) continue;
+        const className = getSingleClassSelector(win.targetSelector);
+        if (className && (classUsage.get(className) || 0) < 2) continue;
+        findings.push({
+          code: "unscoped_gsap_selector",
+          severity: "error",
+          message: `Timeline "${localTimelineCompId}" uses unscoped selector "${win.targetSelector}" that will target elements in ALL compositions when bundled, causing data loss (opacity, transforms, etc.).`,
+          selector: win.targetSelector,
+          fixHint: `Scope the selector: \`[data-composition-id="${localTimelineCompId}"] ${win.targetSelector}\` or use a unique id.`,
+          snippet: truncateSnippet(win.raw),
+        });
+      }
+    }
+    return findings;
+  },
+
+  // gsap_css_transform_conflict
+  // fallow-ignore-next-line complexity
+  async ({ styles, scripts, tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const cssTranslateSelectors = new Map<string, string>();
+    const cssScaleSelectors = new Map<string, string>();
+
+    // Check <style> blocks for transform rules
+    for (const style of styles) {
+      for (const [, selector, body] of style.content.matchAll(
+        /([#.][a-zA-Z0-9_-]+)\s*\{([^}]+)\}/g,
+      )) {
+        const tMatch = body?.match(/transform\s*:\s*([^;]+)/);
+        if (!tMatch || !tMatch[1]) continue;
+        const transformVal = tMatch[1].trim();
+        if (/translate/i.test(transformVal))
+          cssTranslateSelectors.set((selector ?? "").trim(), transformVal);
+        if (/scale/i.test(transformVal))
+          cssScaleSelectors.set((selector ?? "").trim(), transformVal);
+      }
+    }
+
+    // Also check inline style="..." attributes on tags
+    for (const tag of tags) {
+      const inlineStyle = readAttr(tag.raw, "style");
+      if (!inlineStyle) continue;
+      const tMatch = inlineStyle.match(/transform\s*:\s*([^;]+)/);
+      if (!tMatch || !tMatch[1]) continue;
+      const transformVal = tMatch[1].trim();
+      // Derive selectors from the tag's id and all classes
+      const id = readAttr(tag.raw, "id");
+      const classes = readAttr(tag.raw, "class")?.split(/\s+/).filter(Boolean) ?? [];
+      const selectors: string[] = [];
+      if (id) selectors.push(`#${id}`);
+      for (const cls of classes) selectors.push(`.${cls}`);
+      if (selectors.length === 0) continue;
+      for (const sel of selectors) {
+        if (/translate/i.test(transformVal) && !cssTranslateSelectors.has(sel))
+          cssTranslateSelectors.set(sel, transformVal);
+        if (/scale/i.test(transformVal) && !cssScaleSelectors.has(sel))
+          cssScaleSelectors.set(sel, transformVal);
+      }
+    }
+
+    if (cssTranslateSelectors.size === 0 && cssScaleSelectors.size === 0) return findings;
+
+    for (const script of scripts) {
+      if (!/gsap\.timeline/.test(script.content)) continue;
+      const windows = await cachedExtractGsapWindows(script.content);
+
+      // Two sources of transform-setting calls: timeline-rooted tweens (from the
+      // acorn parser) and standalone gsap.* calls (regex — the parser ignores
+      // these). Normalize both into one shape and run the same conflict check.
+      const calls: GsapTransformCall[] = [
+        ...windows.map((win) => ({
+          method: win.method,
+          selector: win.targetSelector,
+          properties: win.properties,
+          raw: win.raw,
+        })),
+        ...extractStandaloneGsapTransformCalls(stripJsComments(script.content)),
+      ];
+
+      type Conflict = { cssTransform: string; props: Set<string>; raw: string };
+      const conflicts = new Map<string, Conflict>();
+
+      for (const call of calls) {
+        // from() and fromTo() both supply explicit start values so GSAP owns
+        // the full transform from t=0, making the CSS conflict moot
+        if (call.method === "fromTo" || call.method === "from") continue;
+        const sel = call.selector;
+        const translateProps = call.properties.filter((p) =>
+          CONFLICTING_TRANSLATE_PROPS.includes(p),
+        );
+        const scaleProps = call.properties.filter((p) => CONFLICTING_SCALE_PROPS.includes(p));
+        const cssFromTranslate =
+          translateProps.length > 0 ? matchCssTransform(sel, cssTranslateSelectors) : undefined;
+        const cssFromScale =
+          scaleProps.length > 0 ? matchCssTransform(sel, cssScaleSelectors) : undefined;
+        if (!cssFromTranslate && !cssFromScale) continue;
+        const existing = conflicts.get(sel) ?? {
+          cssTransform: [cssFromTranslate, cssFromScale].filter(Boolean).join(" "),
+          props: new Set<string>(),
+          raw: call.raw,
+        };
+        for (const p of [...translateProps, ...scaleProps]) existing.props.add(p);
+        conflicts.set(sel, existing);
+      }
+
+      for (const [sel, { cssTransform, props, raw }] of conflicts) {
+        const propList = [...props].join("/");
+        const gsapEquivalent = cssTransformToGsapProps(cssTransform);
+        const fixHint = gsapEquivalent
+          ? `Remove \`transform: ${cssTransform}\` from CSS and replace with GSAP properties: ${gsapEquivalent}. ` +
+            `Example: tl.fromTo('${sel}', { ${gsapEquivalent} }, { ${gsapEquivalent}, ...yourAnimation }). ` +
+            `tl.fromTo is exempt from this rule.`
+          : `Remove the transform from CSS and use tl.fromTo('${sel}', ` +
+            `{ xPercent: -50, x: -1000 }, { xPercent: -50, x: 0 }) so GSAP owns ` +
+            `the full transform state. tl.fromTo is exempt from this rule.`;
+        findings.push({
+          code: "gsap_css_transform_conflict",
+          severity: "error",
+          message:
+            `"${sel}" has CSS \`transform: ${cssTransform}\` and a GSAP tween animates ` +
+            `${propList}. GSAP will overwrite the full CSS transform, discarding any ` +
+            `translateX(-50%) centering or CSS scale value.`,
+          selector: sel,
+          fixHint,
+          snippet: truncateSnippet(raw),
+        });
+      }
+    }
+    return findings;
+  },
+
+  // missing_gsap_script
+  ({ scripts, rawSource, options }) => {
+    const allScriptTexts = scripts.filter((s) => !/\bsrc\s*=/.test(s.attrs)).map((s) => s.content);
+    const allScriptSrcs = scripts
+      .map((s) => readAttr(`<script ${s.attrs}>`, "src") || "")
+      .filter(Boolean);
+    const canInheritGsapFromHost =
+      options.isSubComposition || rawSource.trimStart().toLowerCase().startsWith("<template");
+
+    const usesGsap = allScriptTexts.some((t) =>
+      /gsap\.(to|from|fromTo|timeline|set|registerPlugin)\b/.test(t),
+    );
+    const hasGsapScript = allScriptSrcs.some((src) => /gsap/i.test(src));
+    // Detect GSAP bundled inline (no src attribute). Match:
+    // - Producer's CDN-inlining comment: /* inlined: ...gsap... */
+    // - GSAP library internals: _gsScope, GreenSock, gsap.config
+    // - Large inline scripts (>5KB) that reference gsap (likely bundled library)
+    const hasInlineGsap = allScriptTexts.some(
+      (t) =>
+        /\/\*\s*inlined:.*gsap/i.test(t) ||
+        /\b_gsScope\b/.test(t) ||
+        /\bGreenSock\b/.test(t) ||
+        /\bgsap\.(config|defaults|version)\b/.test(t) ||
+        (t.length > 5000 && /\bgsap\b/i.test(t)),
+    );
+
+    if (!usesGsap || hasGsapScript || hasInlineGsap || canInheritGsapFromHost) return [];
+    return [
+      {
+        code: "missing_gsap_script",
+        severity: "error",
+        message: "Composition uses GSAP but no GSAP script is loaded. The animation will not run.",
+        fixHint:
+          'Add <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script> before your animation script.',
+      },
+    ];
+  },
+
+  // audio_reactive_single_tween_per_group
+  // fallow-ignore-next-line complexity
+  ({ scripts, styles }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const isCaptionFile = styles.some((s) => /\.caption[-_]?(?:group|word)/i.test(s.content));
+    if (!isCaptionFile) return findings;
+
+    for (const script of scripts) {
+      const content = script.content;
+      // Detect audio data loading
+      const hasAudioData = /AUDIO|audio[-_]?data|bands\[/.test(content);
+      if (!hasAudioData) continue;
+
+      // Detect caption group loop
+      const hasCaptionLoop = /forEach/.test(content) && /caption|group|cg-/.test(content);
+      if (!hasCaptionLoop) continue;
+
+      // Check if audio-reactive tweens are created at intervals (loop inside the group loop)
+      // vs a single tween per group (no inner time-sampling loop)
+      const hasInnerSamplingLoop =
+        /for\s*\(\s*var\s+\w+\s*=\s*group\.start/.test(content) ||
+        /for\s*\(\s*var\s+at\s*=/.test(content) ||
+        /while\s*\(\s*\w+\s*<\s*group\.end/.test(content);
+
+      if (!hasInnerSamplingLoop) {
+        // Check if there's at least a peak-based single tween (the minimal pattern)
+        const hasPeakTween =
+          /peak(?:Bass|Treble|Energy)/.test(content) && /group\.start/.test(content);
+        if (hasPeakTween) {
+          findings.push({
+            code: "audio_reactive_single_tween_per_group",
+            severity: "warning",
+            message:
+              "Audio-reactive captions use a single tween per group based on peak values. " +
+              "This sets one static value at group.start — not perceptible as audio reactivity.",
+            fixHint:
+              "Sample audio data at 100-200ms intervals throughout each group's lifetime " +
+              "(for loop from group.start to group.end) and create a tween at each sample " +
+              "point for visible pulsing.",
+          });
+        }
+      }
+    }
+    return findings;
+  },
+
+  // gsap_infinite_repeat
+  ({ scripts }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const script of scripts) {
+      const content = stripJsComments(script.content);
+      // Match repeat: -1 in GSAP tweens or timeline configs
+      const pattern = /repeat\s*:\s*-1(?!\d)/g;
+      let match: RegExpExecArray | null;
+      while ((match = pattern.exec(content)) !== null) {
+        const contextStart = Math.max(0, match.index - 60);
+        const contextEnd = Math.min(content.length, match.index + match[0].length + 60);
+        const snippet = content.slice(contextStart, contextEnd).trim();
+        findings.push({
+          code: "gsap_infinite_repeat",
+          severity: "error",
+          message:
+            "GSAP tween uses `repeat: -1` (infinite). Infinite repeats break the deterministic " +
+            "capture engine which seeks to exact frame times. Use a finite repeat count calculated " +
+            "from the composition duration: `repeat: Math.floor(duration / cycleDuration) - 1`.",
+          fixHint:
+            "Replace `repeat: -1` with a finite count, e.g. `repeat: Math.floor(totalDuration / singleCycleDuration) - 1`. " +
+            "Use Math.floor (not Math.ceil) to ensure the animation fits within the total duration.",
+          snippet: truncateSnippet(snippet),
+        });
+      }
+    }
+    return findings;
+  },
+
+  // gsap_repeat_ceil_overshoot
+  ({ scripts }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const script of scripts) {
+      const content = script.content;
+      // Match patterns like: repeat: Math.ceil(duration / X) - 1
+      // or repeat: Math.ceil(totalDuration / cycleDuration) - 1
+      const pattern = /repeat\s*:\s*Math\.ceil\s*\([^)]+\)\s*-\s*1/g;
+      let match: RegExpExecArray | null;
+      while ((match = pattern.exec(content)) !== null) {
+        const contextStart = Math.max(0, match.index - 40);
+        const contextEnd = Math.min(content.length, match.index + match[0].length + 40);
+        const snippet = content.slice(contextStart, contextEnd).trim();
+        findings.push({
+          code: "gsap_repeat_ceil_overshoot",
+          severity: "warning",
+          message:
+            "GSAP repeat calculation uses `Math.ceil` which can overshoot the composition duration. " +
+            "For example, Math.ceil(10.5 / 2) - 1 = 5 repeats → 6 cycles × 2s = 12s, exceeding 10.5s.",
+          fixHint:
+            "Use `Math.floor` instead of `Math.ceil` to ensure the animation fits within the duration: " +
+            "`repeat: Math.floor(totalDuration / cycleDuration) - 1`. " +
+            "Math.floor(10.5 / 2) - 1 = 4 repeats → 5 cycles × 2s = 10s ✓",
+          snippet: truncateSnippet(snippet),
+        });
+      }
+    }
+    return findings;
+  },
+
+  // scene_layer_missing_visibility_kill
+  ({ scripts, tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+
+    // Detect multi-scene compositions: multiple elements with "scene" in their id
+    const sceneElements = tags.filter((t) => {
+      const id = readAttr(t.raw, "id") || "";
+      return /^scene\d+$/i.test(id);
+    });
+    if (sceneElements.length < 2) return findings;
+
+    for (const script of scripts) {
+      const content = stripJsComments(script.content);
+      // For each scene, check if there's a visibility:hidden set after exit tweens
+      for (const tag of sceneElements) {
+        const id = readAttr(tag.raw, "id") || "";
+        // Check if this scene has exit tweens (opacity: 0)
+        const exitPattern = new RegExp(`["']#${id}["'][^)]*opacity\\s*:\\s*0`);
+        const hasExit = exitPattern.test(content);
+        if (!hasExit) continue;
+
+        // Check if there's a hard visibility kill
+        const killPattern = new RegExp(`["']#${id}["'][^)]*visibility\\s*:\\s*["']hidden["']`);
+        const hasKill = killPattern.test(content);
+        if (!hasKill) {
+          findings.push({
+            code: "scene_layer_missing_visibility_kill",
+            severity: "error",
+            elementId: id,
+            message:
+              `Scene layer "#${id}" exits via opacity tween but has no visibility: hidden hard kill. ` +
+              "When scrubbing or when tweens conflict, the scene may remain partially visible and overlap the next scene.",
+            fixHint: `Add \`tl.set("#${id}", { visibility: "hidden" }, <exit-end-time>)\` after the scene's exit tweens.`,
+          });
+        }
+      }
+    }
+    return findings;
+  },
+
+  // gsap_timeline_not_registered
+  ({ scripts, rawSource, options }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const canInheritFromHost =
+      options.isSubComposition || rawSource.trimStart().toLowerCase().startsWith("<template");
+
+    for (const script of scripts) {
+      const content = script.content;
+      if (!/gsap\.timeline/.test(content)) continue;
+      const hasRegistration = WINDOW_TIMELINE_ASSIGN_PATTERN.test(content);
+      if (hasRegistration || canInheritFromHost) continue;
+      findings.push({
+        code: "gsap_timeline_not_registered",
+        severity: "error",
+        message:
+          "GSAP timeline is created but never registered in window.__timelines. " +
+          "The runtime discovers timelines from this registry — without registration, " +
+          "animations will not play during preview or render.",
+        fixHint:
+          "Add `window.__timelines = window.__timelines || {};` and " +
+          '`window.__timelines["root"] = tl;` after creating the timeline (use the ' +
+          "composition's data-composition-id as the key).",
+      });
+    }
+    return findings;
+  },
+
+  // gsap_timeline_registered_before_async_build — registering window.__timelines[id]
+  // BEFORE the timeline is built inside document.fonts.ready (or any async callback)
+  // leaves an EMPTY timeline registered. The runtime's sub-composition readiness gate
+  // treats "key present" as "ready" and nests the child ONCE, while still empty — so the
+  // animation never renders when this composition is mounted as a sub-composition.
+  // Register only AFTER the build completes (the documented async-setup contract).
+  ({ scripts }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const script of scripts) {
+      const content = stripJsComments(script.content);
+      const regIdx = content.search(/window\s*\.\s*__timelines\s*\[/);
+      if (regIdx < 0) continue;
+      const fontsReadyIdx = content.search(/document\s*\.\s*fonts\s*\.\s*ready/);
+      if (fontsReadyIdx < 0) continue;
+      // Registering after the async boundary is the correct pattern — skip it.
+      if (regIdx >= fontsReadyIdx) continue;
+      // Confirm the build is actually deferred past the boundary (a tween/build call
+      // appears after document.fonts.ready), i.e. the registered timeline starts empty.
+      const tail = content.slice(fontsReadyIdx);
+      if (!/\.(?:to|from|fromTo)\s*\(|buildEffect\s*\(/.test(tail)) continue;
+      findings.push({
+        code: "gsap_timeline_registered_before_async_build",
+        severity: "error",
+        message:
+          "window.__timelines is assigned BEFORE the timeline is built inside " +
+          "document.fonts.ready. An empty timeline registered early gets nested empty " +
+          "when this composition is used as a sub-composition (the readiness gate treats " +
+          '"key present" as "ready" and never re-nests), so the animation renders blank.',
+        fixHint:
+          "Move the `window.__timelines[id] = tl;` assignment to the END of the " +
+          "document.fonts.ready callback, after the tweens are added. Optionally call " +
+          "window.__hfForceTimelineRebind() right after, to re-nest the populated timeline.",
+      });
+    }
+    return findings;
+  },
+
+  // gsap_from_opacity_noop — CSS opacity:0 + gsap.from({opacity:0}) = invisible forever
+  // fallow-ignore-next-line complexity
+  async ({ styles, scripts, tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const cssOpacityZeroSelectors = new Set<string>();
+
+    for (const style of styles) {
+      for (const [, selector, body] of style.content.matchAll(
+        /([#.][a-zA-Z0-9_-]+)\s*\{([^}]+)\}/g,
+      )) {
+        if (body && /opacity\s*:\s*0\s*[;}]/.test(body)) {
+          cssOpacityZeroSelectors.add((selector ?? "").trim());
+        }
+      }
+    }
+
+    for (const tag of tags) {
+      const inlineStyle = readAttr(tag.raw, "style");
+      if (!inlineStyle || !/opacity\s*:\s*0/.test(inlineStyle)) continue;
+      const id = readAttr(tag.raw, "id");
+      const classes = readAttr(tag.raw, "class")?.split(/\s+/).filter(Boolean) ?? [];
+      if (id) cssOpacityZeroSelectors.add(`#${id}`);
+      for (const cls of classes) cssOpacityZeroSelectors.add(`.${cls}`);
+    }
+
+    if (cssOpacityZeroSelectors.size === 0) return findings;
+
+    for (const script of scripts) {
+      if (!/gsap\.timeline/.test(script.content)) continue;
+      const windows = await cachedExtractGsapWindows(script.content);
+
+      for (const win of windows) {
+        if (win.method !== "from") continue;
+        if (!win.properties.includes("opacity")) continue;
+        // Only a noop when the tween animates FROM 0 (same as the CSS value)
+        if (win.propertyValues["opacity"] !== 0) continue;
+        const sel = win.targetSelector;
+        const cssKey = sel.startsWith("#") || sel.startsWith(".") ? sel : `#${sel}`;
+        if (!cssOpacityZeroSelectors.has(cssKey)) continue;
+
+        findings.push({
+          code: "gsap_from_opacity_noop",
+          severity: "error",
+          message:
+            `"${sel}" has CSS \`opacity: 0\` and a gsap.${win.method}() that also sets opacity to 0. ` +
+            `gsap.from() animates FROM the specified value TO the current CSS value — ` +
+            `since CSS is already 0, the element animates from 0→0 and never becomes visible.`,
+          selector: sel,
+          fixHint:
+            `Remove \`opacity: 0\` from the CSS/inline style on "${sel}". ` +
+            `Let gsap.from({opacity: 0}) handle the initial hidden state — ` +
+            `it will animate FROM 0 TO the CSS value (1 by default).`,
+          snippet: truncateSnippet(win.raw),
+        });
+      }
+    }
+    return findings;
+  },
+
+  // gsap_group_selector_keyframes
+  ({ scripts }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const script of scripts) {
+      const content = stripJsComments(script.content);
+      const pattern = /\.(?:to|from|fromTo)\(\s*["']([^"']+,\s*[^"']+)["']\s*,\s*\{[^}]*keyframes/g;
+      let match: RegExpExecArray | null;
+      while ((match = pattern.exec(content)) !== null) {
+        const selector = match[1]!;
+        const count = selector.split(",").length;
+        const contextStart = Math.max(0, match.index - 20);
+        const contextEnd = Math.min(content.length, match.index + match[0].length + 40);
+        findings.push({
+          code: "gsap_group_selector_keyframes",
+          severity: "warning",
+          message:
+            `GSAP tween targets ${count} elements with shared keyframes ("${truncateSnippet(selector, 60)}"). ` +
+            `Editing one element's keyframes in Studio will affect all ${count} elements. ` +
+            `Split into individual tweens for per-element keyframe control.`,
+          fixHint:
+            `Replace the group selector with individual tl.to() calls per element, ` +
+            `each with their own keyframes object.`,
+          snippet: truncateSnippet(content.slice(contextStart, contextEnd)),
+        });
+      }
+    }
+    return findings;
+  },
+];
diff --git a/packages/lint/src/rules/media.test.ts b/packages/lint/src/rules/media.test.ts
new file mode 100644
index 0000000000..5a38bf02c5
--- /dev/null
+++ b/packages/lint/src/rules/media.test.ts
@@ -0,0 +1,251 @@
+import { describe, it, expect } from "vitest";
+import { lintHyperframeHtml } from "../hyperframeLinter.js";
+
+describe("media rules", () => {
+  it("reports error for duplicate media ids", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <video id="v1" src="a.mp4" data-start="0" data-duration="5"></video>
+    <video id="v1" src="b.mp4" data-start="0" data-duration="3"></video>
+  </div>
+  <script>window.__timelines = {};</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "duplicate_media_id");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.elementId).toBe("v1");
+  });
+
+  it("reports error for audio with data-start but no id", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <audio data-start="0" data-duration="10" src="narration.wav"></audio>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "media_missing_id");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.message).toContain("SILENT");
+  });
+
+  it("reports error for video with data-start but no id", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <video data-start="0" data-duration="10" src="clip.mp4" muted playsinline></video>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "media_missing_id");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.message).toContain("FROZEN");
+  });
+
+  it("does not flag media elements that have id", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <audio id="a1" data-start="0" data-duration="10" src="narration.wav"></audio>
+    <video id="v1" data-start="0" data-duration="10" src="clip.mp4" muted playsinline></video>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "media_missing_id");
+    expect(finding).toBeUndefined();
+  });
+
+  it("reports warning for media with preload=none", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <video id="v1" data-start="0" data-duration="10" src="clip.mp4" muted playsinline preload="none"></video>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "media_preload_none");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("warning");
+  });
+
+  it("reports error for media with id but no src", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <audio id="a1" data-start="0" data-duration="10"></audio>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "media_missing_src");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+  });
+
+  it("reports error for media with src but no data-start", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <video id="demo-video" src="clip.mp4" muted playsinline></video>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "media_missing_data_start");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.elementId).toBe("demo-video");
+  });
+
+  it("allows audible video clips to omit muted when data-has-audio is true", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <video id="demo-video" data-start="0" data-duration="5" data-has-audio="true" src="clip.mp4" playsinline></video>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    expect(result.findings.find((f) => f.code === "video_missing_muted")).toBeUndefined();
+    expect(
+      result.findings.find((f) => f.code === "video_muted_with_declared_audio"),
+    ).toBeUndefined();
+  });
+
+  it("reports error for videos that declare audio while muted", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <video id="demo-video" data-start="0" data-duration="5" data-has-audio="true" src="clip.mp4" muted playsinline></video>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "video_muted_with_declared_audio");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.elementId).toBe("demo-video");
+  });
+
+  it("does NOT flag <video> as nested in a void element with data-start (regression)", async () => {
+    // Regression: void elements like <img> have no closing tag, so the previous
+    // implementation kept them on the parent stack indefinitely and flagged any
+    // later <video> with data-start as "nested" inside them.
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <img id="hdr-img" src="hdr.png" data-start="0" data-duration="5" data-track-index="0" />
+    <video id="hdr-vid" src="clip.mp4" data-start="5" data-duration="5" data-track-index="1" muted playsinline></video>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "video_nested_in_timed_element");
+    expect(finding).toBeUndefined();
+  });
+
+  it("reports imperative play() control on managed media ids", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <video id="demo-video" data-start="0" data-duration="5" src="clip.mp4" muted playsinline></video>
+  </div>
+  <script>
+    const video = document.getElementById("demo-video");
+    video.play();
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "imperative_media_control");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.elementId).toBe("demo-video");
+  });
+
+  it("reports imperative currentTime writes on query-selected managed media", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <video id="demo-video" data-start="0" data-duration="5" src="clip.mp4" muted playsinline></video>
+  </div>
+  <script>
+    const demo = document.querySelector("#demo-video");
+    demo.currentTime = 1.5;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "imperative_media_control");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+  });
+
+  it("reports imperative muted/play control on class-selected media without ids", async () => {
+    const html = `
+<template id="scene-template">
+  <div data-composition-id="scene" data-width="1920" data-height="1080">
+    <video class="demo-video" src="clip.mp4" muted playsinline></video>
+    <script>
+      const vid = document.querySelector('[data-composition-id="scene"] .demo-video');
+      if (vid) { vid.muted = true; vid.play(); }
+    </script>
+  </div>
+</template>`;
+    const result = await lintHyperframeHtml(html, { filePath: "compositions/scene.html" });
+    const imperativeFindings = result.findings.filter((f) => f.code === "imperative_media_control");
+    expect(imperativeFindings.length).toBe(2);
+    expect(imperativeFindings.some((f) => f.snippet === "vid.muted =")).toBe(true);
+    expect(imperativeFindings.some((f) => f.snippet === "vid.play(")).toBe(true);
+  });
+
+  it("does not flag play() on non-media elements", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="panel"></div>
+  </div>
+  <script>
+    const panel = document.getElementById("panel");
+    panel.play?.();
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "imperative_media_control");
+    expect(finding).toBeUndefined();
+  });
+
+  it("flags <video> inside a sub-composition (media must be a host-root child)", async () => {
+    const html = `<template id="scene-template">
+  <div id="root" data-composition-id="scene" data-width="1920" data-height="1080">
+    <video id="v1" src="clip.mp4" data-start="0" data-duration="5" muted playsinline></video>
+    <script>window.__timelines = window.__timelines || {}; window.__timelines["scene"] = gsap.timeline({ paused: true });</script>
+  </div>
+</template>`;
+    const result = await lintHyperframeHtml(html, { isSubComposition: true });
+    const finding = result.findings.find((f) => f.code === "media_in_subcomposition");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+    expect(finding?.elementId).toBe("v1");
+    expect(finding?.message).toContain("sub-composition");
+  });
+
+  it("does not flag media in a host-root (non-sub) composition", async () => {
+    const html = `
+<html><body>
+  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
+    <video id="v1" src="clip.mp4" data-start="0" data-duration="5" muted playsinline></video>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "media_in_subcomposition");
+    expect(finding).toBeUndefined();
+  });
+});
diff --git a/packages/lint/src/rules/media.ts b/packages/lint/src/rules/media.ts
new file mode 100644
index 0000000000..03d5f53bfa
--- /dev/null
+++ b/packages/lint/src/rules/media.ts
@@ -0,0 +1,526 @@
+import type { LintContext, HyperframeLintFinding } from "../context";
+import { readAttr, truncateSnippet, isMediaTag } from "../utils";
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function hasAttrName(tagSource: string, attr: string): boolean {
+  const escaped = escapeRegExp(attr);
+  const attrs = tagSource.replace(/^<\s*[a-z][\w:-]*/i, "");
+  return new RegExp(`(?:^|\\s)${escaped}(?:\\s*=|\\s|/?>)`, "i").test(attrs);
+}
+
+function classNamesFromAttr(classAttr: string | null): string[] {
+  if (!classAttr) return [];
+  return classAttr.split(/\s+/).filter(Boolean);
+}
+
+type MediaSelectorIndex = {
+  ids: Set<string>;
+  classes: Set<string>;
+  hasVideo: boolean;
+  hasAudio: boolean;
+};
+
+function selectorTargetsManagedMedia(selector: string, mediaIndex: MediaSelectorIndex): boolean {
+  const normalized = selector.trim();
+  if (!normalized) return false;
+  if (mediaIndex.hasVideo && /\bvideo\b/i.test(normalized)) return true;
+  if (mediaIndex.hasAudio && /\baudio\b/i.test(normalized)) return true;
+  for (const mediaId of mediaIndex.ids) {
+    const escapedId = escapeRegExp(mediaId);
+    if (
+      new RegExp(`#${escapedId}(?![\\w-])`).test(normalized) ||
+      normalized.includes(`[id="${mediaId}"]`) ||
+      normalized.includes(`[id='${mediaId}']`)
+    ) {
+      return true;
+    }
+  }
+  for (const className of mediaIndex.classes) {
+    if (new RegExp(`\\.${escapeRegExp(className)}(?![\\w-])`).test(normalized)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function findImperativeMediaControlFindings(ctx: LintContext): HyperframeLintFinding[] {
+  const findings: HyperframeLintFinding[] = [];
+  const mediaTags = ctx.tags.filter((tag) => tag.name === "video" || tag.name === "audio");
+  const mediaIndex: MediaSelectorIndex = {
+    ids: new Set(
+      mediaTags.map((tag) => readAttr(tag.raw, "id")).filter((id): id is string => Boolean(id)),
+    ),
+    classes: new Set(mediaTags.flatMap((tag) => classNamesFromAttr(readAttr(tag.raw, "class")))),
+    hasVideo: mediaTags.some((tag) => tag.name === "video"),
+    hasAudio: mediaTags.some((tag) => tag.name === "audio"),
+  };
+
+  if (mediaTags.length === 0 || ctx.scripts.length === 0) return findings;
+
+  for (const script of ctx.scripts) {
+    const mediaVars = new Map<string, string | undefined>();
+    const assignmentPatterns = [
+      {
+        pattern:
+          /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)/g,
+        variableIndex: 1,
+        targetIndex: 2,
+      },
+      {
+        pattern:
+          /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:document|window\.document)\.querySelector\(\s*(["'])([\s\S]*?)\2\s*\)/g,
+        variableIndex: 1,
+        targetIndex: 3,
+      },
+    ];
+
+    for (const { pattern, variableIndex, targetIndex } of assignmentPatterns) {
+      let match: RegExpExecArray | null;
+      while ((match = pattern.exec(script.content)) !== null) {
+        const variableName = match[variableIndex];
+        const target = match[targetIndex];
+        if (!variableName || !target) continue;
+        if (mediaIndex.ids.has(target) || selectorTargetsManagedMedia(target, mediaIndex)) {
+          mediaVars.set(variableName, mediaIndex.ids.has(target) ? target : undefined);
+        }
+      }
+    }
+
+    const directIdPatterns = [
+      {
+        pattern:
+          /\b(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)\.play\s*\(/g,
+        kind: "play()",
+        targetIndex: 1,
+      },
+      {
+        pattern:
+          /\b(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)\.pause\s*\(/g,
+        kind: "pause()",
+        targetIndex: 1,
+      },
+      {
+        pattern:
+          /\b(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)\.currentTime\s*=/g,
+        kind: "currentTime",
+        targetIndex: 1,
+      },
+      {
+        pattern:
+          /\b(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)\.muted\s*=/g,
+        kind: "muted assignment",
+        targetIndex: 1,
+      },
+      {
+        pattern:
+          /\b(?:document|window\.document)\.querySelector\(\s*(["'])([\s\S]*?)\1\s*\)\.play\s*\(/g,
+        kind: "play()",
+        targetIndex: 2,
+      },
+      {
+        pattern:
+          /\b(?:document|window\.document)\.querySelector\(\s*(["'])([\s\S]*?)\1\s*\)\.pause\s*\(/g,
+        kind: "pause()",
+        targetIndex: 2,
+      },
+      {
+        pattern:
+          /\b(?:document|window\.document)\.querySelector\(\s*(["'])([\s\S]*?)\1\s*\)\.currentTime\s*=/g,
+        kind: "currentTime",
+        targetIndex: 2,
+      },
+      {
+        pattern:
+          /\b(?:document|window\.document)\.querySelector\(\s*(["'])([\s\S]*?)\1\s*\)\.muted\s*=/g,
+        kind: "muted assignment",
+        targetIndex: 2,
+      },
+    ];
+
+    for (const { pattern, kind, targetIndex } of directIdPatterns) {
+      let match: RegExpExecArray | null;
+      while ((match = pattern.exec(script.content)) !== null) {
+        const target = match[targetIndex];
+        if (!target) continue;
+        const elementId = mediaIndex.ids.has(target)
+          ? target
+          : selectorTargetsManagedMedia(target, mediaIndex)
+            ? undefined
+            : null;
+        if (elementId === null) continue;
+        findings.push({
+          code: "imperative_media_control",
+          severity: "error",
+          message: `Inline <script> imperatively controls managed media via ${kind}. HyperFrames must own media play/pause/seek to keep preview, timeline, and renders deterministic.`,
+          elementId: elementId || undefined,
+          fixHint:
+            "Remove imperative media play/pause/currentTime/muted control. Express timing with data-start/data-duration and media offsets like data-media-start or data-playback-start instead.",
+          snippet: truncateSnippet(match[0]),
+        });
+      }
+    }
+
+    for (const [variableName, elementId] of mediaVars) {
+      const escapedVar = escapeRegExp(variableName);
+      const variablePatterns = [
+        { pattern: new RegExp(`\\b${escapedVar}\\.play\\s*\\(`, "g"), kind: "play()" },
+        { pattern: new RegExp(`\\b${escapedVar}\\.pause\\s*\\(`, "g"), kind: "pause()" },
+        { pattern: new RegExp(`\\b${escapedVar}\\.currentTime\\s*=`, "g"), kind: "currentTime" },
+        {
+          pattern: new RegExp(`\\b${escapedVar}\\.muted\\s*=`, "g"),
+          kind: "muted assignment",
+        },
+      ];
+      for (const { pattern, kind } of variablePatterns) {
+        let match: RegExpExecArray | null;
+        while ((match = pattern.exec(script.content)) !== null) {
+          findings.push({
+            code: "imperative_media_control",
+            severity: "error",
+            message: `Inline <script> imperatively controls managed media via ${kind}. HyperFrames must own media play/pause/seek to keep preview, timeline, and renders deterministic.`,
+            elementId,
+            fixHint:
+              "Remove imperative media play/pause/currentTime/muted control. Express timing with data-start/data-duration and media offsets like data-media-start or data-playback-start instead.",
+            snippet: truncateSnippet(match[0]),
+          });
+        }
+      }
+    }
+  }
+
+  return findings;
+}
+
+export const mediaRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
+  // duplicate_media_id + duplicate_media_discovery_risk
+  ({ tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const mediaById = new Map<string, typeof tags>();
+    const mediaFingerprintCounts = new Map<string, number>();
+
+    for (const tag of tags) {
+      if (!isMediaTag(tag.name)) continue;
+      const elementId = readAttr(tag.raw, "id");
+      if (elementId) {
+        const existing = mediaById.get(elementId) || [];
+        existing.push(tag);
+        mediaById.set(elementId, existing);
+      }
+      const fingerprint = [
+        tag.name,
+        readAttr(tag.raw, "src") || "",
+        readAttr(tag.raw, "data-start") || "",
+        readAttr(tag.raw, "data-duration") || "",
+      ].join("|");
+      mediaFingerprintCounts.set(fingerprint, (mediaFingerprintCounts.get(fingerprint) || 0) + 1);
+    }
+
+    for (const [elementId, mediaTags] of mediaById) {
+      if (mediaTags.length < 2) continue;
+      findings.push({
+        code: "duplicate_media_id",
+        severity: "error",
+        message: `Media id "${elementId}" is defined multiple times.`,
+        elementId,
+        fixHint:
+          "Give each media element a unique id so preview and producer discover the same media graph.",
+        snippet: truncateSnippet(mediaTags[0]?.raw || ""),
+      });
+    }
+
+    for (const [fingerprint, count] of mediaFingerprintCounts) {
+      if (count < 2) continue;
+      const [tagName, src, dataStart, dataDuration] = fingerprint.split("|");
+      findings.push({
+        code: "duplicate_media_discovery_risk",
+        severity: "warning",
+        message: `Detected ${count} matching ${tagName} entries with the same source/start/duration.`,
+        fixHint: "Avoid duplicated media nodes that can be discovered twice during compilation.",
+        snippet: truncateSnippet(
+          `${tagName} src=${src} data-start=${dataStart} data-duration=${dataDuration}`,
+        ),
+      });
+    }
+    return findings;
+  },
+
+  // video_missing_muted
+  ({ tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const tag of tags) {
+      if (tag.name !== "video") continue;
+      const hasMuted = hasAttrName(tag.raw, "muted");
+      const hasDeclaredAudio = readAttr(tag.raw, "data-has-audio") === "true";
+      if (!hasMuted && !hasDeclaredAudio && readAttr(tag.raw, "data-start")) {
+        const elementId = readAttr(tag.raw, "id") || undefined;
+        findings.push({
+          code: "video_missing_muted",
+          severity: "error",
+          message: `<video${elementId ? ` id="${elementId}"` : ""}> has data-start but is not muted. Mark audible videos with data-has-audio="true"; otherwise keep video muted and use a separate <audio> element for sound.`,
+          elementId,
+          fixHint:
+            'Add the `muted` attribute for silent video, or add data-has-audio="true" when the video track should contribute audio.',
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+      if (hasMuted && hasDeclaredAudio) {
+        const elementId = readAttr(tag.raw, "id") || undefined;
+        findings.push({
+          code: "video_muted_with_declared_audio",
+          severity: "error",
+          message: `<video${elementId ? ` id="${elementId}"` : ""}> declares data-has-audio="true" but also has muted. Studio preview will silence the video audio.`,
+          elementId,
+          fixHint:
+            'Remove the `muted` attribute if this video should be audible, or remove data-has-audio="true" and use data-volume="0" for silent visual video.',
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+    }
+    return findings;
+  },
+
+  // video_nested_in_timed_element
+  ({ source, tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+    // HTML5 void elements cannot contain children, so they can never be a
+    // parent of a nested <video>. Skipping them avoids false positives where
+    // the linter looks for `</img>` and never finds it.
+    const voidElements = new Set([
+      "area",
+      "base",
+      "br",
+      "col",
+      "embed",
+      "hr",
+      "img",
+      "input",
+      "link",
+      "meta",
+      "source",
+      "track",
+      "wbr",
+    ]);
+    const timedTagPositions: Array<{ name: string; start: number; id?: string }> = [];
+    for (const tag of tags) {
+      if (tag.name === "video" || tag.name === "audio") continue;
+      if (voidElements.has(tag.name)) continue;
+      // Skip the composition root — it uses data-start as a playback anchor, not as a clip timer
+      if (readAttr(tag.raw, "data-composition-id")) continue;
+      if (readAttr(tag.raw, "data-start")) {
+        timedTagPositions.push({
+          name: tag.name,
+          start: tag.index,
+          id: readAttr(tag.raw, "id") || undefined,
+        });
+      }
+    }
+    for (const tag of tags) {
+      if (tag.name !== "video") continue;
+      if (!readAttr(tag.raw, "data-start")) continue;
+      for (const parent of timedTagPositions) {
+        if (parent.start < tag.index) {
+          const parentClosePattern = new RegExp(`</${parent.name}>`, "gi");
+          const between = source.substring(parent.start, tag.index);
+          if (!parentClosePattern.test(between)) {
+            findings.push({
+              code: "video_nested_in_timed_element",
+              severity: "error",
+              message: `<video> with data-start is nested inside <${parent.name}${parent.id ? ` id="${parent.id}"` : ""}> which also has data-start. The framework cannot manage playback of nested media — video will be FROZEN in renders.`,
+              elementId: readAttr(tag.raw, "id") || undefined,
+              fixHint:
+                "Move the <video> to be a direct child of the stage, or remove data-start from the wrapper div (use it as a non-timed visual container).",
+              snippet: truncateSnippet(tag.raw),
+            });
+            break;
+          }
+        }
+      }
+    }
+    return findings;
+  },
+
+  // media_in_subcomposition — <video>/<audio> only render as a DIRECT child of the host
+  // root (index.html). Inside a sub-composition <template> the runtime never seeks/decodes
+  // them, so they render BLANK/black in preview and renders — and the other lint/validate
+  // passes otherwise miss it (only a per-frame snapshot reveals the blank panel).
+  ({ tags, options }) => {
+    const findings: HyperframeLintFinding[] = [];
+    if (!options.isSubComposition) return findings;
+    for (const tag of tags) {
+      if (tag.name !== "video" && tag.name !== "audio") continue;
+      const elementId = readAttr(tag.raw, "id") || undefined;
+      findings.push({
+        code: "media_in_subcomposition",
+        severity: "error",
+        message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> is inside a sub-composition. The runtime only drives media that is a DIRECT child of the host root (index.html); media inside a sub-comp <template> is never seeked/decoded and renders BLANK/black in preview and renders.`,
+        elementId,
+        fixHint:
+          "Move the media OUT of the sub-composition: place the <video>/<audio> as a direct child of #root in index.html, positioned over the scene, and drive any per-scene motion on the MAIN timeline at global time (a sub-comp timeline cannot reach host elements). See composition-patterns.md archetype B.",
+        snippet: truncateSnippet(tag.raw),
+      });
+    }
+    return findings;
+  },
+
+  // self_closing_media_tag
+  ({ source }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const selfClosingMediaRe = /<(audio|video)\b[^>]*\/>/gi;
+    let scMatch: RegExpExecArray | null;
+    while ((scMatch = selfClosingMediaRe.exec(source)) !== null) {
+      const tagName = scMatch[1] || "audio";
+      const elementId = readAttr(scMatch[0], "id") || undefined;
+      findings.push({
+        code: "self_closing_media_tag",
+        severity: "error",
+        message: `Self-closing <${tagName}/> is invalid HTML. The browser will leave the tag open, swallowing all subsequent elements as invisible fallback content. This makes compositions INVISIBLE.`,
+        elementId,
+        fixHint: `Change <${tagName} .../> to <${tagName} ...></${tagName}> — media elements MUST have explicit closing tags.`,
+        snippet: truncateSnippet(scMatch[0]),
+      });
+    }
+    return findings;
+  },
+
+  // placeholder_media_url
+  ({ tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const PLACEHOLDER_DOMAINS =
+      /\b(placehold\.co|placeholder\.com|placekitten\.com|picsum\.photos|example\.com|via\.placeholder\.com|dummyimage\.com)\b/i;
+    for (const tag of tags) {
+      if (!isMediaTag(tag.name)) continue;
+      const src = readAttr(tag.raw, "src");
+      if (!src) continue;
+      if (PLACEHOLDER_DOMAINS.test(src)) {
+        const elementId = readAttr(tag.raw, "id") || undefined;
+        findings.push({
+          code: "placeholder_media_url",
+          severity: "error",
+          message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses a placeholder URL that will 404 at render time: ${src.slice(0, 80)}`,
+          elementId,
+          fixHint: "Replace with a real media URL. Placeholder domains will 404 at render time.",
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+    }
+    return findings;
+  },
+
+  // base64_media_prohibited
+  ({ source }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const base64MediaRe =
+      /src\s*=\s*["'](data:(?:audio|video)\/[^;]+;base64,([A-Za-z0-9+/=]{20,}))["']/gi;
+    let b64Match: RegExpExecArray | null;
+    while ((b64Match = base64MediaRe.exec(source)) !== null) {
+      const sample = (b64Match[2] || "").slice(0, 200);
+      const uniqueChars = new Set(sample.replace(/[A-Za-z0-9+/=]/g, (c) => c)).size;
+      const dataSize = Math.round(((b64Match[2] || "").length * 3) / 4);
+      const isSuspicious = uniqueChars < 15 || (dataSize > 1000 && dataSize < 50000);
+      findings.push({
+        code: "base64_media_prohibited",
+        severity: "error",
+        message: `Inline base64 audio/video detected (${(dataSize / 1024).toFixed(0)} KB)${isSuspicious ? " — likely fabricated data" : ""}. Base64 media is prohibited — it bloats file size and breaks rendering.`,
+        fixHint:
+          "Use a relative path (assets/music.mp3) or HTTPS URL for the audio/video src. Never embed media as base64.",
+        snippet: truncateSnippet((b64Match[1] ?? "").slice(0, 80) + "..."),
+      });
+    }
+    return findings;
+  },
+
+  // media_missing_data_start + media_missing_id + media_missing_src + media_preload_none
+  ({ tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const tag of tags) {
+      if (tag.name !== "video" && tag.name !== "audio") continue;
+      const hasDataStart = readAttr(tag.raw, "data-start");
+      const hasId = readAttr(tag.raw, "id");
+      const hasSrc = readAttr(tag.raw, "src");
+      if (hasSrc && !hasDataStart) {
+        findings.push({
+          code: "media_missing_data_start",
+          severity: "error",
+          message: `<${tag.name}${hasId ? ` id="${hasId}"` : ""}> has src but no data-start. HyperFrames cannot own playback for untimed media, so preview and render behavior can diverge.`,
+          elementId: hasId || undefined,
+          fixHint: `Add data-start="0" (or the intended start time) and data-duration if the clip should stop before the source ends.`,
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+      if (hasDataStart && !hasId) {
+        findings.push({
+          code: "media_missing_id",
+          severity: "error",
+          message: `<${tag.name}> has data-start but no id attribute. The renderer requires id to discover media elements — this ${tag.name === "audio" ? "audio will be SILENT" : "video will be FROZEN"} in renders.`,
+          fixHint: `Add a unique id attribute: <${tag.name} id="my-${tag.name}" ...>`,
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+      if (hasDataStart && hasId && !hasSrc) {
+        findings.push({
+          code: "media_missing_src",
+          severity: "error",
+          message: `<${tag.name} id="${hasId}"> has data-start but no src attribute. The renderer cannot load this media.`,
+          elementId: hasId,
+          fixHint: `Add a src attribute to the <${tag.name}> element directly. If using <source> children, the renderer still requires src on the parent element.`,
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+      if (readAttr(tag.raw, "preload") === "none") {
+        findings.push({
+          code: "media_preload_none",
+          severity: "warning",
+          message: `<${tag.name}${hasId ? ` id="${hasId}"` : ""}> has preload="none" which prevents the renderer from loading this media. The compiler strips it for renders, but preview may also have issues.`,
+          elementId: hasId || undefined,
+          fixHint: `Remove preload="none" or change to preload="auto". The framework manages media loading.`,
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+    }
+    return findings;
+  },
+
+  // video_audio_double_source — catches audible <video> paired with a separate
+  // <audio> pointing to the same file, which causes double playback at runtime
+  ({ tags }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const videoSources = new Map<string, { id?: string; raw: string }>();
+    const audioSources = new Map<string, { id?: string; raw: string }>();
+
+    for (const tag of tags) {
+      if (!readAttr(tag.raw, "data-start")) continue;
+      const src = readAttr(tag.raw, "src");
+      if (!src) continue;
+      const elementId = readAttr(tag.raw, "id") || undefined;
+      if (tag.name === "video") {
+        const isMuted = hasAttrName(tag.raw, "muted");
+        if (!isMuted) {
+          videoSources.set(src, { id: elementId, raw: tag.raw });
+        }
+      } else if (tag.name === "audio") {
+        audioSources.set(src, { id: elementId, raw: tag.raw });
+      }
+    }
+
+    for (const [src, audioInfo] of audioSources) {
+      const videoInfo = videoSources.get(src);
+      if (!videoInfo) continue;
+      findings.push({
+        code: "video_audio_double_source",
+        severity: "error",
+        message: `<audio${audioInfo.id ? ` id="${audioInfo.id}"` : ""}> and <video${videoInfo.id ? ` id="${videoInfo.id}"` : ""}> both point to the same source. The unmuted video already provides audio — the duplicate <audio> will cause double playback and echo.`,
+        elementId: audioInfo.id,
+        fixHint:
+          "Either mute the video (add `muted` attribute) and keep the separate <audio>, or remove the <audio> element and let the video provide its own audio track.",
+        snippet: truncateSnippet(audioInfo.raw),
+      });
+    }
+    return findings;
+  },
+
+  // imperative_media_control
+  findImperativeMediaControlFindings,
+];
diff --git a/packages/lint/src/rules/slideshow.test.ts b/packages/lint/src/rules/slideshow.test.ts
new file mode 100644
index 0000000000..8b7ed69464
--- /dev/null
+++ b/packages/lint/src/rules/slideshow.test.ts
@@ -0,0 +1,73 @@
+import { describe, it, expect } from "vitest";
+import { lintHyperframeHtml } from "../hyperframeLinter.js";
+
+async function findSlideshow(html: string) {
+  const result = await lintHyperframeHtml(html, { isSubComposition: true });
+  return result.findings.filter((f) => f.code.startsWith("slideshow_"));
+}
+
+describe("slideshow lint rule", () => {
+  it("passes a composition with no slideshow island", async () => {
+    const html = `<div data-composition-id="c" data-width="1920" data-height="1080">
+      <div id="a" class="clip" data-start="0" data-duration="5"></div>
+    </div>`;
+    expect(await findSlideshow(html)).toEqual([]);
+  });
+
+  it("passes a valid island where sceneId resolves to a data-composition-id scene", async () => {
+    const html = `<div data-composition-id="c" data-width="1920" data-height="1080">
+      <div data-composition-id="a" data-start="0" data-duration="5"></div>
+      <script type="application/hyperframes-slideshow+json">{"slides":[{"sceneId":"a"}]}</script>
+    </div>`;
+    expect(await findSlideshow(html)).toEqual([]);
+  });
+
+  it("flags a sceneId that matches only a .clip[id] (not a data-composition-id)", async () => {
+    const html = `<div data-composition-id="c" data-width="1920" data-height="1080">
+      <div id="a" class="clip" data-start="0" data-duration="5"></div>
+      <script type="application/hyperframes-slideshow+json">{"slides":[{"sceneId":"a"}]}</script>
+    </div>`;
+    const findings = await findSlideshow(html);
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings[0]?.message).toContain("a");
+  });
+
+  it("flags an unresolved sceneId", async () => {
+    const html = `<div data-composition-id="c" data-width="1920" data-height="1080">
+      <div id="a" class="clip" data-start="0" data-duration="5"></div>
+      <script type="application/hyperframes-slideshow+json">{"slides":[{"sceneId":"ghost"}]}</script>
+    </div>`;
+    const findings = await findSlideshow(html);
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings[0]!.message).toContain("ghost");
+  });
+
+  it("flags invalid JSON in the island", async () => {
+    const html = `<div data-composition-id="c" data-width="1920" data-height="1080">
+      <script type="application/hyperframes-slideshow+json">NOT_JSON</script>
+    </div>`;
+    const findings = await findSlideshow(html);
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings[0]!.code).toBe("slideshow_invalid");
+  });
+
+  it("passes when sceneId resolves to a data-composition-id element (no .clip[id])", async () => {
+    const html = `<div data-composition-id="c" data-width="1920" data-height="1080">
+      <div data-composition-id="scene-a" data-start="0" data-duration="5"></div>
+      <script type="application/hyperframes-slideshow+json">{"slides":[{"sceneId":"scene-a"}]}</script>
+    </div>`;
+    expect(await findSlideshow(html)).toEqual([]);
+  });
+
+  it("flags a hotspot targeting an unknown sequence", async () => {
+    const html = `<div data-composition-id="c" data-width="1920" data-height="1080">
+      <div data-composition-id="a" data-start="0" data-duration="5"></div>
+      <script type="application/hyperframes-slideshow+json">${JSON.stringify({
+        slides: [{ sceneId: "a", hotspots: [{ id: "h1", label: "Go", target: "no-such-seq" }] }],
+      })}</script>
+    </div>`;
+    const findings = await findSlideshow(html);
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings[0]!.message).toContain("no-such-seq");
+  });
+});
diff --git a/packages/lint/src/rules/slideshow.ts b/packages/lint/src/rules/slideshow.ts
new file mode 100644
index 0000000000..5580dc66ad
--- /dev/null
+++ b/packages/lint/src/rules/slideshow.ts
@@ -0,0 +1,85 @@
+import type { LintContext, HyperframeLintFinding } from "../context";
+import type { LintRule } from "../types";
+import { readAttr } from "../utils";
+import {
+  parseSlideshowManifest,
+  resolveSlideshow,
+  isSceneLikeCompositionId,
+} from "@hyperframes/core/slideshow";
+
+type Scene = { id: string; start: number; duration: number };
+
+function parseTiming(raw: string): { start: number; duration: number } | null {
+  const startStr = readAttr(raw, "data-start");
+  if (startStr === null) return null;
+  const start = Number(startStr);
+  if (!Number.isFinite(start)) return null;
+
+  const durationStr = readAttr(raw, "data-duration");
+  if (durationStr !== null) {
+    const duration = Number(durationStr);
+    if (Number.isFinite(duration)) return { start, duration };
+  }
+  const endStr = readAttr(raw, "data-end") ?? readAttr(raw, "data-hf-authored-end");
+  if (endStr !== null) {
+    const end = Number(endStr);
+    if (Number.isFinite(end) && end > start) return { start, duration: end - start };
+  }
+  return null;
+}
+
+function collectCompositionIdScenes(ctx: LintContext, seen: Set<string>, out: Scene[]): void {
+  for (const tag of ctx.tags) {
+    const compositionId = readAttr(tag.raw, "data-composition-id");
+    if (!compositionId || !isSceneLikeCompositionId(compositionId) || seen.has(compositionId))
+      continue;
+    const timing = parseTiming(tag.raw);
+    if (!timing || timing.duration <= 0) continue;
+    seen.add(compositionId);
+    out.push({ id: compositionId, ...timing });
+  }
+}
+
+function extractScenesFromClips(ctx: LintContext): Scene[] {
+  const seen = new Set<string>();
+  const scenes: Scene[] = [];
+  collectCompositionIdScenes(ctx, seen, scenes);
+  return scenes;
+}
+
+export const slideshowRules: LintRule<LintContext>[] = [
+  (ctx) => {
+    const findings: HyperframeLintFinding[] = [];
+
+    let manifest;
+    try {
+      manifest = parseSlideshowManifest(ctx.source);
+    } catch (e) {
+      findings.push({
+        code: "slideshow_invalid",
+        severity: "error",
+        message: `Slideshow island contains invalid JSON or structure: ${e instanceof Error ? e.message : String(e)}`,
+        fixHint:
+          'Ensure the <script type="application/hyperframes-slideshow+json"> block contains valid JSON matching the SlideshowManifest schema.',
+      });
+      return findings;
+    }
+
+    if (!manifest) return findings;
+
+    const scenes = extractScenesFromClips(ctx);
+    const { errors } = resolveSlideshow(manifest, scenes);
+
+    for (const error of errors) {
+      findings.push({
+        code: "slideshow_unresolved_ref",
+        severity: "error",
+        message: `Slideshow manifest error: ${error}`,
+        fixHint:
+          "Ensure every sceneId in the slideshow island matches the data-composition-id of a scene element in the composition, or provide explicit startTime/endTime.",
+      });
+    }
+
+    return findings;
+  },
+];
diff --git a/packages/lint/src/rules/textures.test.ts b/packages/lint/src/rules/textures.test.ts
new file mode 100644
index 0000000000..c9505fa10a
--- /dev/null
+++ b/packages/lint/src/rules/textures.test.ts
@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest";
+import { lintHyperframeHtml } from "../hyperframeLinter.js";
+
+function baseHtml(body: string, style = ""): string {
+  return `<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    ${body}
+  </div>
+  <style>${style}</style>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+}
+
+const textureCss = `
+.hf-texture-text {
+  color: #fff;
+  -webkit-mask-size: var(--mask-size, cover);
+  mask-size: var(--mask-size, cover);
+}
+.hf-texture-lava {
+  -webkit-mask-image: url("masks/lava.png");
+  mask-image: url("masks/lava.png");
+}
+`;
+
+describe("texture rules", () => {
+  it("does not warn for a valid texture mask text usage", async () => {
+    const html = baseHtml(
+      '<div class="shadow"><div class="hf-texture-text hf-texture-lava">TEXT</div></div>',
+      `${textureCss}.shadow { filter: drop-shadow(1px 2px 1px rgba(0,0,0,.48)); }`,
+    );
+
+    const result = await lintHyperframeHtml(html);
+
+    expect(result.findings.filter((finding) => finding.code.startsWith("texture_"))).toEqual([]);
+  });
+
+  it("warns when a material class is used without hf-texture-text", async () => {
+    const html = baseHtml('<div class="hf-texture-lava">TEXT</div>', textureCss);
+
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((item) => item.code === "texture_class_missing_base");
+
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("warning");
+    expect(finding?.fixHint).toContain("hf-texture-text");
+  });
+
+  it("warns when hf-texture-text has no material class or custom mask image", async () => {
+    const html = baseHtml('<div class="hf-texture-text">TEXT</div>', textureCss);
+
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((item) => item.code === "texture_text_missing_mask");
+
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("warning");
+  });
+
+  it("allows hf-texture-text with an inline custom mask image", async () => {
+    const html = baseHtml(
+      '<div class="hf-texture-text" style="-webkit-mask-image:url(custom.png); mask-image:url(custom.png)">TEXT</div>',
+      textureCss,
+    );
+
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((item) => item.code === "texture_text_missing_mask");
+
+    expect(finding).toBeUndefined();
+  });
+
+  it("warns when a texture material class is not defined by local CSS", async () => {
+    const html = baseHtml('<div class="hf-texture-text hf-texture-marbel">TEXT</div>', textureCss);
+
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((item) => item.code === "texture_class_unknown");
+
+    expect(finding).toBeDefined();
+    expect(finding?.message).toContain("hf-texture-marbel");
+  });
+
+  it("warns when drop-shadow is applied inline to the textured text element", async () => {
+    const html = baseHtml(
+      '<div class="hf-texture-text hf-texture-lava" style="filter: drop-shadow(1px 2px 1px black)">TEXT</div>',
+      textureCss,
+    );
+
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((item) => item.code === "texture_drop_shadow_on_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.fixHint).toContain("wrapper");
+  });
+
+  it("warns when drop-shadow is applied by CSS directly to hf-texture-text", async () => {
+    const html = baseHtml(
+      '<div class="hf-texture-text hf-texture-lava">TEXT</div>',
+      `${textureCss}.hf-texture-text { filter: drop-shadow(1px 2px 1px black); }`,
+    );
+
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((item) => item.code === "texture_drop_shadow_on_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.selector).toBe(".hf-texture-text");
+  });
+
+  it("warns when drop-shadow targets a material class before the mask rule is declared", async () => {
+    const html = baseHtml(
+      '<div class="hf-texture-text hf-texture-lava">TEXT</div>',
+      `.hf-texture-lava { filter: drop-shadow(1px 2px 1px black); }
+       ${textureCss}`,
+    );
+
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((item) => item.code === "texture_drop_shadow_on_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.selector).toBe(".hf-texture-lava");
+  });
+
+  it("warns when drop-shadow targets another class on the textured text element", async () => {
+    const html = baseHtml(
+      '<div class="hf-texture-text hf-texture-lava headline">TEXT</div>',
+      `${textureCss}.headline { filter: drop-shadow(1px 2px 1px black); }`,
+    );
+
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((item) => item.code === "texture_drop_shadow_on_text");
+
+    expect(finding).toBeDefined();
+    expect(finding?.selector).toBe(".headline");
+  });
+
+  it("does not warn when another-class drop-shadow selector needs an unmatched ancestor", async () => {
+    const html = baseHtml(
+      '<div class="hf-texture-text hf-texture-lava headline">TEXT</div>',
+      `${textureCss}.card .headline { filter: drop-shadow(1px 2px 1px black); }`,
+    );
+
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((item) => item.code === "texture_drop_shadow_on_text");
+
+    expect(finding).toBeUndefined();
+  });
+});
diff --git a/packages/lint/src/rules/textures.ts b/packages/lint/src/rules/textures.ts
new file mode 100644
index 0000000000..1ab1d7f92d
--- /dev/null
+++ b/packages/lint/src/rules/textures.ts
@@ -0,0 +1,226 @@
+import postcss from "postcss";
+import type { LintContext, HyperframeLintFinding, OpenTag } from "../context";
+import { readAttr, truncateSnippet } from "../utils";
+
+const TEXTURE_BASE_CLASS = "hf-texture-text";
+const TEXTURE_CLASS_PREFIX = "hf-texture-";
+
+type DropShadowRule = {
+  selector: string;
+  directlyTargetsTexture: boolean;
+};
+
+function classNames(tag: OpenTag): string[] {
+  return (readAttr(tag.raw, "class") ?? "").split(/\s+/).filter(Boolean);
+}
+
+function isTextureMaterialClass(className: string): boolean {
+  return className.startsWith(TEXTURE_CLASS_PREFIX) && className !== TEXTURE_BASE_CLASS;
+}
+
+function hasInlineMaskImage(tag: OpenTag): boolean {
+  const style = readAttr(tag.raw, "style") ?? "";
+  return /\b(?:-webkit-)?mask-image\s*:/i.test(style);
+}
+
+function hasInlineDropShadow(tag: OpenTag): boolean {
+  const style = readAttr(tag.raw, "style") ?? "";
+  return /\bfilter\s*:\s*[^;]*\bdrop-shadow\s*\(/i.test(style);
+}
+
+function classNamesInSelector(selector: string): string[] {
+  const classes = new Set<string>();
+  const pattern = /\.([A-Za-z_][\w-]*)/g;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(selector)) !== null) {
+    const className = match[1];
+    if (!className) continue;
+    classes.add(className);
+  }
+  return [...classes];
+}
+
+function textureClassesInSelector(selector: string): string[] {
+  return classNamesInSelector(selector).filter(isTextureMaterialClass);
+}
+
+function simpleSelectorMatchesTag(selector: string, tag: OpenTag, tagClasses: string[]): boolean {
+  const trimmed = selector.trim();
+  const simpleSelectorPattern = /^(?:[A-Za-z][\w-]*)?(?:\.[A-Za-z_][\w-]*)+$/;
+  if (!simpleSelectorPattern.test(trimmed)) return false;
+
+  const typeMatch = /^([A-Za-z][\w-]*)/.exec(trimmed);
+  if (typeMatch && typeMatch[1]!.toLowerCase() !== tag.name) return false;
+
+  const selectorClasses = classNamesInSelector(trimmed);
+  return (
+    selectorClasses.length > 0 &&
+    selectorClasses.every((className) => tagClasses.includes(className))
+  );
+}
+
+function collectTextureCss(styles: LintContext["styles"]): {
+  definedTextureClasses: Set<string>;
+  dropShadowRules: DropShadowRule[];
+} {
+  const definedTextureClasses = new Set<string>();
+  const dropShadowRules: DropShadowRule[] = [];
+  const roots: postcss.Root[] = [];
+
+  for (const style of styles) {
+    let root: postcss.Root;
+    try {
+      root = postcss.parse(style.content);
+    } catch {
+      continue;
+    }
+    roots.push(root);
+
+    // fallow-ignore-next-line complexity
+    root.walkRules((rule) => {
+      const selectors = rule.selectors ?? [];
+      let hasMaskImage = false;
+
+      for (const node of rule.nodes ?? []) {
+        if (node.type !== "decl") continue;
+        const prop = node.prop.toLowerCase();
+        if (prop === "mask-image" || prop === "-webkit-mask-image") hasMaskImage = true;
+      }
+
+      if (hasMaskImage) {
+        for (const selector of selectors) {
+          for (const className of textureClassesInSelector(selector)) {
+            definedTextureClasses.add(className);
+          }
+        }
+      }
+    });
+  }
+
+  for (const root of roots) {
+    // fallow-ignore-next-line complexity
+    root.walkRules((rule) => {
+      const selectors = rule.selectors ?? [];
+      let hasDropShadow = false;
+
+      for (const node of rule.nodes ?? []) {
+        if (node.type !== "decl") continue;
+        if (node.prop.toLowerCase() === "filter" && /\bdrop-shadow\s*\(/i.test(node.value)) {
+          hasDropShadow = true;
+        }
+      }
+
+      if (hasDropShadow) {
+        for (const selector of selectors) {
+          const targetsBaseClass = /\.hf-texture-text\b/.test(selector);
+          const targetsDefinedTextureClass = textureClassesInSelector(selector).some((className) =>
+            definedTextureClasses.has(className),
+          );
+          dropShadowRules.push({
+            selector,
+            directlyTargetsTexture: targetsBaseClass || targetsDefinedTextureClass,
+          });
+        }
+      }
+    });
+  }
+
+  return { definedTextureClasses, dropShadowRules };
+}
+
+// fallow-ignore-next-line complexity
+export const textureRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
+  ({ tags, styles }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const { definedTextureClasses, dropShadowRules } = collectTextureCss(styles);
+
+    for (const { selector, directlyTargetsTexture } of dropShadowRules) {
+      if (!directlyTargetsTexture) continue;
+      findings.push({
+        code: "texture_drop_shadow_on_text",
+        severity: "warning",
+        message: "Drop shadow is applied directly to textured text.",
+        selector,
+        fixHint:
+          "Wrap the textured text and apply `filter: drop-shadow(...)` to the wrapper, not the `hf-texture-text` element.",
+      });
+    }
+
+    for (const tag of tags) {
+      if (tag.name === "style" || tag.name === "script") continue;
+
+      const classes = classNames(tag);
+      if (classes.length === 0) continue;
+
+      const hasBaseClass = classes.includes(TEXTURE_BASE_CLASS);
+      const textureClasses = classes.filter(isTextureMaterialClass);
+
+      if (textureClasses.length > 0 && !hasBaseClass) {
+        findings.push({
+          code: "texture_class_missing_base",
+          severity: "warning",
+          message: `Texture material class \`${textureClasses[0]}\` is used without \`${TEXTURE_BASE_CLASS}\`.`,
+          elementId: readAttr(tag.raw, "id") || undefined,
+          fixHint: `Add \`${TEXTURE_BASE_CLASS}\` alongside the material class, for example \`class="${TEXTURE_BASE_CLASS} ${textureClasses[0]}"\`.`,
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+
+      if (hasBaseClass && textureClasses.length === 0 && !hasInlineMaskImage(tag)) {
+        findings.push({
+          code: "texture_text_missing_mask",
+          severity: "warning",
+          message: `\`${TEXTURE_BASE_CLASS}\` is used without a texture material class or custom mask image.`,
+          elementId: readAttr(tag.raw, "id") || undefined,
+          fixHint:
+            "Add a material class such as `hf-texture-lava`, or set `mask-image` and `-webkit-mask-image` on the element.",
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+
+      for (const textureClass of textureClasses) {
+        if (definedTextureClasses.has(textureClass)) continue;
+        findings.push({
+          code: "texture_class_unknown",
+          severity: "error",
+          message: `Texture material class \`${textureClass}\` is not defined by local CSS.`,
+          elementId: readAttr(tag.raw, "id") || undefined,
+          fixHint:
+            "Paste the Texture Mask Text component `<style>...</style>` block into the composition, or fix the texture class typo.",
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+
+      if (hasBaseClass) {
+        for (const rule of dropShadowRules) {
+          if (rule.directlyTargetsTexture) continue;
+          if (!simpleSelectorMatchesTag(rule.selector, tag, classes)) continue;
+          findings.push({
+            code: "texture_drop_shadow_on_text",
+            severity: "warning",
+            message: "Drop shadow is applied directly to textured text.",
+            selector: rule.selector,
+            elementId: readAttr(tag.raw, "id") || undefined,
+            fixHint:
+              "Wrap the textured text and apply `filter: drop-shadow(...)` to the wrapper, not the `hf-texture-text` element.",
+            snippet: truncateSnippet(tag.raw),
+          });
+        }
+      }
+
+      if (hasBaseClass && hasInlineDropShadow(tag)) {
+        findings.push({
+          code: "texture_drop_shadow_on_text",
+          severity: "warning",
+          message: "Drop shadow is applied directly to textured text.",
+          elementId: readAttr(tag.raw, "id") || undefined,
+          fixHint:
+            "Wrap the textured text and apply `filter: drop-shadow(...)` to the wrapper, not the `hf-texture-text` element.",
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+    }
+
+    return findings;
+  },
+];
diff --git a/packages/lint/src/types.ts b/packages/lint/src/types.ts
new file mode 100644
index 0000000000..8911566f93
--- /dev/null
+++ b/packages/lint/src/types.ts
@@ -0,0 +1,40 @@
+export type HyperframeLintSeverity = "error" | "warning" | "info";
+
+export type HyperframeLintFinding = {
+  code: string;
+  severity: HyperframeLintSeverity;
+  message: string;
+  file?: string;
+  selector?: string;
+  elementId?: string;
+  fixHint?: string;
+  snippet?: string;
+};
+
+export type HyperframeLintResult = {
+  ok: boolean;
+  errorCount: number;
+  warningCount: number;
+  infoCount: number;
+  findings: HyperframeLintFinding[];
+};
+
+export type HyperframeLinterOptions = {
+  filePath?: string;
+  isSubComposition?: boolean;
+  externalStyles?: Array<{ href: string; content: string }>;
+  /**
+   * Set to `true` when linting compositions destined for distributed / Lambda
+   * rendering, where system-font capture (`allowSystemFontCapture`) is
+   * disabled.  When `true`, the `system_font_will_alias` rule is elevated from
+   * `"info"` to `"warning"` because the alias substitution will NOT happen at
+   * render time — the font will silently fall back to whatever the OS provides.
+   */
+  distributed?: boolean;
+};
+
+// A rule is a function: receives parsed context, returns zero or more findings.
+// Rules may be async (e.g. when lazy-loading heavy dependencies like recast).
+export type LintRule<TContext> = (
+  ctx: TContext,
+) => HyperframeLintFinding[] | Promise<HyperframeLintFinding[]>;
diff --git a/packages/lint/src/utils.ts b/packages/lint/src/utils.ts
new file mode 100644
index 0000000000..21c24ce6e5
--- /dev/null
+++ b/packages/lint/src/utils.ts
@@ -0,0 +1,300 @@
+// Shared types, regex constants, and utility functions used across lint rule modules.
+// Nothing in this file should emit findings — it only parses and extracts.
+
+export type OpenTag = {
+  raw: string;
+  name: string;
+  attrs: string;
+  index: number;
+};
+
+export type ExtractedBlock = {
+  attrs: string;
+  content: string;
+  raw: string;
+  index: number;
+};
+
+const TAG_PATTERN = /<([a-z][\w:-]*)(\s[^<>]*?)?>/gi;
+export const STYLE_BLOCK_PATTERN = /<style\b([^>]*)>([\s\S]*?)<\/style>/gi;
+export const SCRIPT_BLOCK_PATTERN = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
+const COMPOSITION_ID_IN_CSS_PATTERN = /\[data-composition-id=["']([^"']+)["']\]/g;
+export const TIMELINE_REGISTRY_INIT_PATTERN =
+  /window\.__timelines\s*=\s*window\.__timelines\s*\|\|\s*\{\}|window\.__timelines\s*=\s*\{\}|window\.__timelines\s*\?\?=\s*\{\}/i;
+export const TIMELINE_REGISTRY_ASSIGN_PATTERN =
+  /window\.__timelines(?:\[[^\]]+\]|\.[A-Za-z_$][\w$]*)\s*=/i;
+export const WINDOW_TIMELINE_ASSIGN_PATTERN =
+  /window\.__timelines(?:\[\s*["']([^"']+)["']\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*=\s*([A-Za-z_$][\w$]*)/i;
+export const INVALID_SCRIPT_CLOSE_PATTERN = /<script[^>]*>[\s\S]*?<\s*\/\s*script(?!>)/i;
+
+const TIMELINE_REGISTRY_KEY_PATTERN =
+  /window\.__timelines(?:\[\s*["']([^"']+)["']\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*=/g;
+
+export function extractOpenTags(source: string): OpenTag[] {
+  const tags: OpenTag[] = [];
+  let match: RegExpExecArray | null;
+  const pattern = new RegExp(TAG_PATTERN.source, TAG_PATTERN.flags);
+  while ((match = pattern.exec(source)) !== null) {
+    const raw = match[0];
+    if (raw.startsWith("</") || raw.startsWith("<!")) continue;
+    tags.push({
+      raw,
+      name: (match[1] || "").toLowerCase(),
+      attrs: match[2] || "",
+      index: match.index,
+    });
+  }
+  return tags;
+}
+
+export function extractBlocks(source: string, pattern: RegExp): ExtractedBlock[] {
+  const blocks: ExtractedBlock[] = [];
+  let match: RegExpExecArray | null;
+  const p = new RegExp(pattern.source, pattern.flags);
+  while ((match = p.exec(source)) !== null) {
+    blocks.push({
+      attrs: match[1] || "",
+      content: match[2] || "",
+      raw: match[0],
+      index: match.index,
+    });
+  }
+  return blocks;
+}
+
+/**
+ * Find the `<html>` open tag in the source. Distinct from `findRootTag`,
+ * which returns the first element inside `<body>` — the latter is "the
+ * composition's visible root", whereas `<html>` is where document-level
+ * metadata like `data-composition-variables` lives.
+ */
+export function findHtmlTag(source: string): OpenTag | null {
+  const match = /<html\b([^<>]*)>/i.exec(source);
+  if (!match) return null;
+  return {
+    raw: match[0],
+    name: "html",
+    attrs: match[1] ?? "",
+    index: match.index,
+  };
+}
+
+export function findRootTag(source: string): OpenTag | null {
+  const bodyOpenMatch = /<body\b([^>]*)>/i.exec(source);
+  const bodyCloseMatch = /<\/body>/i.exec(source);
+  if (
+    bodyOpenMatch &&
+    (readAttr(bodyOpenMatch[0], "data-composition-id") ||
+      readAttr(bodyOpenMatch[0], "data-width") ||
+      readAttr(bodyOpenMatch[0], "data-height"))
+  ) {
+    return {
+      raw: bodyOpenMatch[0],
+      name: "body",
+      attrs: bodyOpenMatch[1] ?? "",
+      index: bodyOpenMatch.index,
+    };
+  }
+  const bodyStart = bodyOpenMatch ? bodyOpenMatch.index + bodyOpenMatch[0].length : 0;
+  const bodyEnd =
+    bodyOpenMatch && bodyCloseMatch && bodyCloseMatch.index > bodyStart
+      ? bodyCloseMatch.index
+      : source.length;
+  const bodyContent = bodyOpenMatch ? source.slice(bodyStart, bodyEnd) : source;
+  const bodyTags = extractOpenTags(bodyContent);
+  for (const tag of bodyTags) {
+    if (["script", "style", "meta", "link", "title"].includes(tag.name)) continue;
+    return { ...tag, index: tag.index + bodyStart };
+  }
+  return null;
+}
+
+export function readAttr(tagSource: string, attr: string): string | null {
+  if (!tagSource) return null;
+  const escaped = attr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = tagSource.match(new RegExp(`\\b${escaped}\\s*=\\s*["']([^"']+)["']`, "i"));
+  return match?.[1] || null;
+}
+
+/**
+ * Read an attribute that may legitimately contain the opposite quote
+ * character. `readAttr` truncates `data-variable-values='{"title":"Hello"}'`
+ * at the first internal `"` because its `[^"']+` class excludes both quote
+ * types. This variant alternates: a double-quoted value never contains an
+ * unescaped `"`, and a single-quoted value never contains an unescaped `'`,
+ * so each branch can use a quote-specific class.
+ *
+ * Use for attributes whose values are JSON or otherwise carry the opposite
+ * quote character. Existing single-token attributes (`id`, `class`, etc.)
+ * stick with `readAttr` for consistency with the rest of the lint code.
+ */
+export function readJsonAttr(tagSource: string, attr: string): string | null {
+  if (!tagSource) return null;
+  const escaped = attr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = tagSource.match(new RegExp(`\\b${escaped}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, "i"));
+  if (!match) return null;
+  return match[1] ?? match[2] ?? null;
+}
+
+export function collectCompositionIds(tags: OpenTag[]): Set<string> {
+  const ids = new Set<string>();
+  for (const tag of tags) {
+    const compId = readAttr(tag.raw, "data-composition-id");
+    if (compId) ids.add(compId);
+  }
+  return ids;
+}
+
+export function extractCompositionIdsFromCss(css: string): string[] {
+  const ids = new Set<string>();
+  let match: RegExpExecArray | null;
+  const pattern = new RegExp(
+    COMPOSITION_ID_IN_CSS_PATTERN.source,
+    COMPOSITION_ID_IN_CSS_PATTERN.flags,
+  );
+  while ((match = pattern.exec(css)) !== null) {
+    if (match[1]) ids.add(match[1]);
+  }
+  return [...ids];
+}
+
+export function extractTimelineRegistryKeys(source: string): string[] {
+  const keys = new Set<string>();
+  let match: RegExpExecArray | null;
+  const pattern = new RegExp(
+    TIMELINE_REGISTRY_KEY_PATTERN.source,
+    TIMELINE_REGISTRY_KEY_PATTERN.flags,
+  );
+  while ((match = pattern.exec(source)) !== null) {
+    const key = match[1] ?? match[2];
+    if (key) keys.add(key);
+  }
+  return [...keys];
+}
+
+export function getInlineScriptSyntaxError(source: string): string | null {
+  if (!source.trim()) return null;
+  try {
+    // eslint-disable-next-line no-new-func
+    new Function(source);
+    return null;
+  } catch (error) {
+    if (error instanceof Error) return error.message;
+    return String(error);
+  }
+}
+
+// fallow-ignore-next-line complexity
+export function stripJsComments(source: string): string {
+  let out = "";
+  let i = 0;
+  let quote: "'" | '"' | "`" | null = null;
+  let escaped = false;
+
+  while (i < source.length) {
+    const ch = source[i] ?? "";
+    const next = source[i + 1] ?? "";
+
+    if (quote) {
+      out += ch;
+      if (escaped) {
+        escaped = false;
+      } else if (ch === "\\") {
+        escaped = true;
+      } else if (ch === quote) {
+        quote = null;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (ch === "'" || ch === '"' || ch === "`") {
+      quote = ch;
+      out += ch;
+      i += 1;
+      continue;
+    }
+
+    if (ch === "/" && next === "/") {
+      out += "  ";
+      i += 2;
+      while (i < source.length && source[i] !== "\n" && source[i] !== "\r") {
+        out += " ";
+        i += 1;
+      }
+      continue;
+    }
+
+    if (ch === "/" && next === "*") {
+      out += "  ";
+      i += 2;
+      while (i < source.length) {
+        const blockCh = source[i] ?? "";
+        const blockNext = source[i + 1] ?? "";
+        if (blockCh === "*" && blockNext === "/") {
+          out += "  ";
+          i += 2;
+          break;
+        }
+        out += blockCh === "\n" || blockCh === "\r" ? blockCh : " ";
+        i += 1;
+      }
+      continue;
+    }
+
+    out += ch;
+    i += 1;
+  }
+
+  return out;
+}
+
+// One linear pass that drops every `<!-- … -->` region. Uses indexOf, not a
+// `/<!--[\s\S]*?-->/` regex: that pattern backtracks O(n²) on inputs with many
+// unterminated "<!--" (CodeQL js/polynomial-redos). An unterminated "<!--" with
+// no closing "-->" is kept verbatim, matching the prior regex's no-match behavior.
+function stripHtmlCommentsOnce(source: string): string {
+  let out = "";
+  let i = 0;
+  for (;;) {
+    const start = source.indexOf("<!--", i);
+    if (start < 0) return out + source.slice(i);
+    const end = source.indexOf("-->", start + 4);
+    if (end < 0) return out + source.slice(i);
+    out += source.slice(i, start);
+    i = end + 3;
+  }
+}
+
+// Strip HTML comments to a fixpoint. A single pass is not enough: deleting one
+// comment can splice adjacent markers into a fresh, complete <!-- … --> (e.g.
+// "<<!-- -->!-- … -->" → "<!-- … -->"), which would otherwise survive and let a
+// commented-out <template>/tag hijack the linter's tag scan.
+export function stripHtmlComments(source: string): string {
+  let out = source;
+  for (let prev = ""; prev !== out; ) {
+    prev = out;
+    out = stripHtmlCommentsOnce(out);
+  }
+  return out;
+}
+
+export function extractScriptTextsAndSrcs(scripts: ExtractedBlock[]): {
+  texts: string[];
+  srcs: string[];
+} {
+  const texts = scripts.filter((s) => !/\bsrc\s*=/.test(s.attrs)).map((s) => s.content);
+  const srcs = scripts.map((s) => readAttr(`<script ${s.attrs}>`, "src") || "").filter(Boolean);
+  return { texts, srcs };
+}
+
+export function isMediaTag(tagName: string): boolean {
+  return tagName === "video" || tagName === "audio" || tagName === "img";
+}
+
+export function truncateSnippet(value: string, maxLength = 220): string | undefined {
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (!normalized) return undefined;
+  if (normalized.length <= maxLength) return normalized;
+  return `${normalized.slice(0, maxLength - 3)}...`;
+}
diff --git a/packages/lint/tsconfig.json b/packages/lint/tsconfig.json
new file mode 100644
index 0000000000..96f38bce00
--- /dev/null
+++ b/packages/lint/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
diff --git a/packages/lint/tsup.config.ts b/packages/lint/tsup.config.ts
new file mode 100644
index 0000000000..f5380e58e2
--- /dev/null
+++ b/packages/lint/tsup.config.ts
@@ -0,0 +1,14 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: { index: "src/index.ts" },
+  format: ["esm"],
+  outDir: "dist",
+  target: "node22",
+  platform: "node",
+  bundle: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  dts: true,
+});
diff --git a/packages/lint/vitest.config.ts b/packages/lint/vitest.config.ts
new file mode 100644
index 0000000000..dc1fee04c8
--- /dev/null
+++ b/packages/lint/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+    environment: "jsdom",
+  },
+});
diff --git a/packages/producer/package.json b/packages/producer/package.json
index 8f53d19e30..972ff59d7b 100644
--- a/packages/producer/package.json
+++ b/packages/producer/package.json
@@ -70,6 +70,7 @@
     "@hono/node-server": "^1.13.0",
     "@hyperframes/core": "workspace:^",
     "@hyperframes/engine": "workspace:^",
+    "@hyperframes/lint": "workspace:^",
     "hono": "^4.6.0",
     "linkedom": "^0.18.12",
     "postcss": "^8.4.0",
diff --git a/packages/producer/src/services/hyperframeLint.ts b/packages/producer/src/services/hyperframeLint.ts
index 426bced4e6..8f59e2516a 100644
--- a/packages/producer/src/services/hyperframeLint.ts
+++ b/packages/producer/src/services/hyperframeLint.ts
@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { resolve, join } from "node:path";
-import { lintHyperframeHtml, type HyperframeLintResult } from "@hyperframes/core/lint";
+import { lintHyperframeHtml, type HyperframeLintResult } from "@hyperframes/lint";
 
 export interface PreparedHyperframeLintInput {
   entryFile: string;
diff --git a/scripts/set-version.ts b/scripts/set-version.ts
index e43348e2b3..b2c021f0c3 100644
--- a/scripts/set-version.ts
+++ b/scripts/set-version.ts
@@ -22,6 +22,7 @@ import { CLI_SEMVER_PATTERN } from "./cli-options.ts";
 
 const PACKAGES = [
   "packages/parsers",
+  "packages/lint",
   "packages/core",
   "packages/engine",
   "packages/player",

From f80036c83169ea97cd9713950fe347163b6ddbd9 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Fri, 26 Jun 2026 21:41:28 -0400
Subject: [PATCH 2/6] fix: restore postcss-selector-parser in core
 (sourceMutation.ts still uses it)

---
 packages/core/package.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/core/package.json b/packages/core/package.json
index 41f7f30d63..14a4cbf749 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -357,7 +357,8 @@
     "@hyperframes/parsers": "workspace:*",
     "bpm-detective": "^2.0.5",
     "linkedom": "^0.18.12",
-    "postcss": "^8.5.8"
+    "postcss": "^8.5.8",
+    "postcss-selector-parser": "^7.1.2"
   },
   "devDependencies": {
     "@types/jsdom": "^28.0.0",

From 642907fab8d85866346e9158e656819f4ac3033f Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Fri, 26 Jun 2026 21:56:02 -0400
Subject: [PATCH 3/6] fix(ci): add parsers+lint to Dockerfile and build before
 preview tests

---
 .github/workflows/preview-regression.yml | 3 ++-
 Dockerfile.test                          | 4 +++-
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/preview-regression.yml b/.github/workflows/preview-regression.yml
index 5ee4f10030..02e39db660 100644
--- a/.github/workflows/preview-regression.yml
+++ b/.github/workflows/preview-regression.yml
@@ -37,6 +37,7 @@ jobs:
             preview:
               - "packages/core/**"
               - "packages/parsers/**"
+              - "packages/lint/**"
               - "packages/player/**"
               - "packages/studio/**"
               - "packages/cli/**"
@@ -76,7 +77,7 @@ jobs:
 
       - name: Build workspace packages (required for vite config loading)
         run: |
-          bun run --filter '@hyperframes/parsers' build
+          bun run --filter '@hyperframes/{parsers,lint}' build
           bun run --cwd packages/core build
 
       - name: Run Studio preview routing regression
diff --git a/Dockerfile.test b/Dockerfile.test
index 5748109914..2320ac902d 100644
--- a/Dockerfile.test
+++ b/Dockerfile.test
@@ -75,6 +75,7 @@ ENV PATH="/root/.bun/bin:$PATH"
 # lockfile change and fails.
 COPY package.json bun.lock ./
 COPY packages/parsers/package.json packages/parsers/package.json
+COPY packages/lint/package.json packages/lint/package.json
 COPY packages/core/package.json packages/core/package.json
 COPY packages/engine/package.json packages/engine/package.json
 COPY packages/player/package.json packages/player/package.json
@@ -90,12 +91,13 @@ RUN bun install --frozen-lockfile
 
 # Copy source
 COPY packages/parsers/ packages/parsers/
+COPY packages/lint/ packages/lint/
 COPY packages/core/ packages/core/
 COPY packages/engine/ packages/engine/
 COPY packages/producer/ packages/producer/
 
 # Build workspace packages so "node" export conditions resolve to built dist
-RUN bun run --filter '@hyperframes/parsers' build \
+RUN bun run --filter '@hyperframes/{parsers,lint}' build \
     && bun run --cwd packages/core build
 
 # Build core runtime artifacts (needed by renderer)

From b8029491c06f87d012f26deb338fac4cdc92ac69 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Fri, 26 Jun 2026 21:59:19 -0400
Subject: [PATCH 4/6] chore: update bun.lock after restoring
 postcss-selector-parser dep

---
 bun.lock | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/bun.lock b/bun.lock
index 3d83ce6005..1dfc2b8cab 100644
--- a/bun.lock
+++ b/bun.lock
@@ -110,6 +110,7 @@
         "bpm-detective": "^2.0.5",
         "linkedom": "^0.18.12",
         "postcss": "^8.5.8",
+        "postcss-selector-parser": "^7.1.2",
       },
       "devDependencies": {
         "@types/jsdom": "^28.0.0",
@@ -1835,7 +1836,7 @@
 
     "postcss-nested": ["postcss-nested@6.2.0", "", { "dependencies": { "postcss-selector-parser": "^6.1.1" }, "peerDependencies": { "postcss": "^8.2.14" } }, "sha512-HQbt28KulC5AJzG+cZtj9kvKB93CFCdLvog1WFLf1D+xmMvPGlBstkpTEZfK5+AN9hfJocyBFCNiqyS48bpgzQ=="],
 
-    "postcss-selector-parser": ["postcss-selector-parser@6.1.2", "", { "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" } }, "sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg=="],
+    "postcss-selector-parser": ["postcss-selector-parser@7.1.4", "", { "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" } }, "sha512-HeP7D2wyhkR+XaK6v4W8oRF62Dsz4flyuczALJp61GckGm42u1saSSJ/0auvcBqxs3jMRFEcPK34At/0JBKdOg=="],
 
     "postcss-value-parser": ["postcss-value-parser@4.2.0", "", {}, "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ=="],
 
@@ -2233,6 +2234,8 @@
 
     "path-scurry/minipass": ["minipass@7.1.3", "", {}, "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A=="],
 
+    "postcss-nested/postcss-selector-parser": ["postcss-selector-parser@6.1.2", "", { "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" } }, "sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg=="],
+
     "proxy-agent/agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
 
     "proxy-agent/https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
@@ -2249,6 +2252,8 @@
 
     "tailwindcss/jiti": ["jiti@1.21.7", "", { "bin": { "jiti": "bin/jiti.js" } }, "sha512-/imKNG4EbWNrVjoNC/1H5/9GFy+tqjGBHCaSsN+P2RnPqjsLmv6UD3Ej+Kj8nBWaRAwyk7kK5ZUc+OEatnTR3A=="],
 
+    "tailwindcss/postcss-selector-parser": ["postcss-selector-parser@6.1.2", "", { "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" } }, "sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg=="],
+
     "tar/minipass": ["minipass@7.1.3", "", {}, "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A=="],
 
     "teeny-request/http-proxy-agent": ["http-proxy-agent@5.0.0", "", { "dependencies": { "@tootallnate/once": "2", "agent-base": "6", "debug": "4" } }, "sha512-n2hY8YdoRE1i7r6M0w9DIw5GgZN0G25P8zLCRQ8rjXtTU3vsNFBI/vWK/UIeE6g5MUUz6avwAPXmL6Fy9D/90w=="],

From 199c02382408e9f288baeb9e8bbe63edd8612245 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Fri, 26 Jun 2026 23:11:02 -0400
Subject: [PATCH 5/6] test(cli): update lintProject test for string-dir
 signature from @hyperframes/lint

---
 packages/cli/src/utils/lintProject.test.ts | 86 ++++++++++------------
 1 file changed, 40 insertions(+), 46 deletions(-)

diff --git a/packages/cli/src/utils/lintProject.test.ts b/packages/cli/src/utils/lintProject.test.ts
index aec22d15e2..2491b947aa 100644
--- a/packages/cli/src/utils/lintProject.test.ts
+++ b/packages/cli/src/utils/lintProject.test.ts
@@ -3,7 +3,6 @@ import { mkdirSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { lintProject, shouldBlockRender } from "./lintProject.js";
-import type { ProjectDir } from "./project.js";
 
 function tmpProject(name: string): string {
   return mkdtempSync(join(tmpdir(), `hf-test-${name}-`));
@@ -37,7 +36,7 @@ function htmlWithPreloadNone(): string {
 
 let dirs: string[] = [];
 
-function makeProject(indexHtml: string, subComps?: Record<string, string>): ProjectDir {
+function makeProject(indexHtml: string, subComps?: Record<string, string>): string {
   const dir = tmpProject("lint");
   dirs.push(dir);
   writeFileSync(join(dir, "index.html"), indexHtml);
@@ -48,7 +47,7 @@ function makeProject(indexHtml: string, subComps?: Record<string, string>): Proj
       writeFileSync(join(compsDir, name), html);
     }
   }
-  return { dir, name: "test-project", indexPath: join(dir, "index.html") };
+  return dir;
 }
 
 afterEach(() => {
@@ -108,12 +107,7 @@ describe("lintProject", () => {
 </template>`;
     writeFileSync(join(framesDir, "04-mechanism.html"), frameHtml);
 
-    const project: ProjectDir = {
-      dir,
-      name: "test-project",
-      indexPath: join(dir, "index.html"),
-    };
-    const { results } = await lintProject(project);
+    const { results } = await lintProject(dir);
 
     const frameResult = results.find((r) => r.file === "compositions/frames/04-mechanism.html");
     expect(frameResult).toBeDefined();
@@ -146,7 +140,7 @@ describe("lintProject", () => {
 </body></html>`,
     });
     writeFileSync(
-      join(project.dir, "compositions", "scene.css"),
+      join(project, "compositions", "scene.css"),
       '[data-composition-id="scene"] .title { opacity: 0; }',
     );
 
@@ -169,7 +163,7 @@ describe("lintProject", () => {
 </body></html>`,
     });
     writeFileSync(
-      join(project.dir, "compositions", decodeURIComponent(encodedFilename)),
+      join(project, "compositions", decodeURIComponent(encodedFilename)),
       '[data-composition-id="scene"] .title { opacity: 0; }',
     );
 
@@ -227,7 +221,7 @@ describe("lintProject", () => {
       "captions.html": validHtml("captions"),
     });
     // Add a non-HTML file
-    writeFileSync(join(project.dir, "compositions", "readme.txt"), "not html");
+    writeFileSync(join(project, "compositions", "readme.txt"), "not html");
 
     const { results } = await lintProject(project);
 
@@ -270,7 +264,7 @@ function validHtmlWithMaskImageUrl(url: string): string {
 describe("audio_file_without_element", () => {
   it("warns when audio file exists but no <audio> element", async () => {
     const project = makeProject(validHtml());
-    writeFileSync(join(project.dir, "music.mp3"), "fake");
+    writeFileSync(join(project, "music.mp3"), "fake");
 
     const { totalWarnings, results } = await lintProject(project);
 
@@ -285,7 +279,7 @@ describe("audio_file_without_element", () => {
 
   it("does not warn when audio file exists and <audio> element is present", async () => {
     const project = makeProject(validHtmlWithAudio());
-    writeFileSync(join(project.dir, "song.mp3"), "fake");
+    writeFileSync(join(project, "song.mp3"), "fake");
 
     const { results } = await lintProject(project);
 
@@ -308,8 +302,8 @@ describe("audio_file_without_element", () => {
 
   it("detects multiple audio file extensions", async () => {
     const project = makeProject(validHtml());
-    writeFileSync(join(project.dir, "narration.wav"), "fake");
-    writeFileSync(join(project.dir, "bgm.ogg"), "fake");
+    writeFileSync(join(project, "narration.wav"), "fake");
+    writeFileSync(join(project, "bgm.ogg"), "fake");
 
     const { results } = await lintProject(project);
 
@@ -325,7 +319,7 @@ describe("audio_file_without_element", () => {
     const project = makeProject(validHtml(), {
       "captions.html": validHtmlWithAudio("captions"),
     });
-    writeFileSync(join(project.dir, "song.mp3"), "fake");
+    writeFileSync(join(project, "song.mp3"), "fake");
 
     const { results } = await lintProject(project);
 
@@ -354,7 +348,7 @@ describe("audio_src_not_found", () => {
 
   it("does not error when <audio> src file exists", async () => {
     const project = makeProject(validHtmlWithAudio());
-    writeFileSync(join(project.dir, "song.mp3"), "fake");
+    writeFileSync(join(project, "song.mp3"), "fake");
 
     const { results } = await lintProject(project);
 
@@ -404,8 +398,8 @@ describe("audio_src_not_found", () => {
   <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
 </body></html>`;
     const project = makeProject(html);
-    mkdirSync(join(project.dir, "assets"), { recursive: true });
-    writeFileSync(join(project.dir, "assets", "bgm.mp3"), "fake");
+    mkdirSync(join(project, "assets"), { recursive: true });
+    writeFileSync(join(project, "assets", "bgm.mp3"), "fake");
 
     const { results } = await lintProject(project);
 
@@ -419,8 +413,8 @@ describe("audio_src_not_found", () => {
     const encodedFilename =
       "%D9%87%D9%86%D8%A7%20%D9%85%D8%B1%D9%88%D8%A7%20-%20%D9%85%D8%A8%D8%A7%D8%B1%D9%83.mp4";
     const project = makeProject(validHtmlWithAudioSrc(`assets/${encodedFilename}`));
-    mkdirSync(join(project.dir, "assets"), { recursive: true });
-    writeFileSync(join(project.dir, "assets", decodeURIComponent(encodedFilename)), "fake");
+    mkdirSync(join(project, "assets"), { recursive: true });
+    writeFileSync(join(project, "assets", decodeURIComponent(encodedFilename)), "fake");
 
     const { results } = await lintProject(project);
 
@@ -433,8 +427,8 @@ describe("audio_src_not_found", () => {
   it("does not error for malformed percent sequences that are literal filenames", async () => {
     const filename = "100%-discount.mp4";
     const project = makeProject(validHtmlWithAudioSrc(`assets/${filename}`));
-    mkdirSync(join(project.dir, "assets"), { recursive: true });
-    writeFileSync(join(project.dir, "assets", filename), "fake");
+    mkdirSync(join(project, "assets"), { recursive: true });
+    writeFileSync(join(project, "assets", filename), "fake");
 
     const { results } = await lintProject(project);
 
@@ -483,8 +477,8 @@ describe("audio_src_not_found", () => {
   <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");
+    mkdirSync(join(project, "assets"), { recursive: true });
+    writeFileSync(join(project, "assets", "bgm.mp3"), "fake");
 
     const { results } = await lintProject(project);
 
@@ -630,8 +624,8 @@ describe("missing_local_asset", () => {
   <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
 </body></html>`;
     const project = makeProject(html);
-    writeFileSync(join(project.dir, "hero.png"), "fake");
-    writeFileSync(join(project.dir, "clip.mp4"), "fake");
+    writeFileSync(join(project, "hero.png"), "fake");
+    writeFileSync(join(project, "clip.mp4"), "fake");
 
     const { results } = await lintProject(project);
 
@@ -647,8 +641,8 @@ describe("missing_local_asset", () => {
   <script>window.__timelines = window.__timelines || {}; window.__timelines["scene"] = gsap.timeline({ paused: true });</script>
 </body></html>`;
     const project = makeProject(validHtml(), { "scene.html": subComp });
-    mkdirSync(join(project.dir, "assets"), { recursive: true });
-    writeFileSync(join(project.dir, "assets", "foo.png"), "fake");
+    mkdirSync(join(project, "assets"), { recursive: true });
+    writeFileSync(join(project, "assets", "foo.png"), "fake");
 
     const { results } = await lintProject(project);
 
@@ -766,8 +760,8 @@ describe("texture_mask_asset_not_found", () => {
   <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
 </body></html>`;
     const project = makeProject(html);
-    mkdirSync(join(project.dir, "masks"), { recursive: true });
-    writeFileSync(join(project.dir, "masks", "lava.png"), "fake");
+    mkdirSync(join(project, "masks"), { recursive: true });
+    writeFileSync(join(project, "masks", "lava.png"), "fake");
 
     const { results } = await lintProject(project);
     const finding = results[0]?.result.findings.find(
@@ -787,11 +781,11 @@ describe("texture_mask_asset_not_found", () => {
 </body></html>`,
     });
     writeFileSync(
-      join(project.dir, "compositions", "scene.css"),
+      join(project, "compositions", "scene.css"),
       '.hf-texture-lava { mask-image: url("masks/lava.png"); }',
     );
-    mkdirSync(join(project.dir, "compositions", "masks"), { recursive: true });
-    writeFileSync(join(project.dir, "compositions", "masks", "lava.png"), "fake");
+    mkdirSync(join(project, "compositions", "masks"), { recursive: true });
+    writeFileSync(join(project, "compositions", "masks", "lava.png"), "fake");
 
     const { results } = await lintProject(project);
     const finding = results[0]?.result.findings.find(
@@ -812,7 +806,7 @@ describe("texture_mask_asset_not_found", () => {
 </body></html>`,
     });
     writeFileSync(
-      join(project.dir, "compositions", decodeURIComponent(encodedFilename)),
+      join(project, "compositions", decodeURIComponent(encodedFilename)),
       '.hf-texture-lava { mask-image: url("masks/missing.png"); }',
     );
 
@@ -839,10 +833,10 @@ describe("texture_mask_asset_not_found", () => {
   <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
 </body></html>`;
     const project = makeProject(html);
-    mkdirSync(join(project.dir, "assets", "texture-mask-text", "masks"), {
+    mkdirSync(join(project, "assets", "texture-mask-text", "masks"), {
       recursive: true,
     });
-    writeFileSync(join(project.dir, "assets", "texture-mask-text", "masks", "lava.png"), "fake");
+    writeFileSync(join(project, "assets", "texture-mask-text", "masks", "lava.png"), "fake");
 
     const { results } = await lintProject(project);
     const finding = results[0]?.result.findings.find(
@@ -855,8 +849,8 @@ describe("texture_mask_asset_not_found", () => {
   it("does not error for percent-encoded non-Latin mask filenames that exist on disk", async () => {
     const encodedFilename = "%E6%97%A5%E6%9C%AC%E8%AA%9E.png";
     const project = makeProject(validHtmlWithMaskImageUrl(`assets/${encodedFilename}`));
-    mkdirSync(join(project.dir, "assets"), { recursive: true });
-    writeFileSync(join(project.dir, "assets", decodeURIComponent(encodedFilename)), "fake");
+    mkdirSync(join(project, "assets"), { recursive: true });
+    writeFileSync(join(project, "assets", decodeURIComponent(encodedFilename)), "fake");
 
     const { results } = await lintProject(project);
     const finding = results[0]?.result.findings.find(
@@ -884,7 +878,7 @@ describe("multiple_root_compositions", () => {
   it("fires when two HTML files have data-composition-id", async () => {
     const project = makeProject(validHtml());
     writeFileSync(
-      join(project.dir, "scaffold.html"),
+      join(project, "scaffold.html"),
       '<div data-composition-id="scaffold" data-width="1920" data-height="1080" data-duration="10"></div>',
     );
     const { totalErrors, results } = await lintProject(project);
@@ -909,7 +903,7 @@ describe("multiple_root_compositions", () => {
   it("ignores root-level caption-skin.html source files", async () => {
     const project = makeProject(validHtml());
     writeFileSync(
-      join(project.dir, "caption-skin.html"),
+      join(project, "caption-skin.html"),
       '<div data-composition-id="captions" data-width="0" data-height="0"></div>',
     );
     const { results } = await lintProject(project);
@@ -921,7 +915,7 @@ describe("multiple_root_compositions", () => {
 
   it("ignores HTML files without data-composition-id", async () => {
     const project = makeProject(validHtml());
-    writeFileSync(join(project.dir, "readme.html"), "<html><body>Not a composition</body></html>");
+    writeFileSync(join(project, "readme.html"), "<html><body>Not a composition</body></html>");
     const { results } = await lintProject(project);
     const finding = results[0]?.result.findings.find(
       (f) => f.code === "multiple_root_compositions",
@@ -979,7 +973,7 @@ describe("duplicate_audio_track", () => {
     const project = makeProject(validHtmlWithAudio(), {
       "scene.html": validHtmlWithAudio("scene"),
     });
-    writeFileSync(join(project.dir, "song.mp3"), "fake");
+    writeFileSync(join(project, "song.mp3"), "fake");
     const { results } = await lintProject(project);
     const finding = results[0]?.result.findings.find((f) => f.code === "duplicate_audio_track");
     expect(finding).toBeUndefined();
@@ -1024,8 +1018,8 @@ describe("duplicate_audio_track", () => {
   <script>window.__timelines = window.__timelines || {}; window.__timelines["scene"] = gsap.timeline({ paused: true });</script>
 </body></html>`,
     });
-    writeFileSync(join(project.dir, "song.mp3"), "fake");
-    writeFileSync(join(project.dir, "music.wav"), "fake");
+    writeFileSync(join(project, "song.mp3"), "fake");
+    writeFileSync(join(project, "music.wav"), "fake");
     const { results } = await lintProject(project);
     const finding = results[0]?.result.findings.find((f) => f.code === "duplicate_audio_track");
     // song.mp3@0 (from validHtmlWithAudio, no data-duration → Infinity) and music.wav@5-25 overlap

From 3c46e38abf8e8d921e02304cddde8c4dea626b50 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 27 Jun 2026 00:15:31 -0400
Subject: [PATCH 6/6] refactor(core): single-source the lint engine in
 @hyperframes/lint

Delete core's byte-identical copy of the lint rule engine and re-point
staticGuard at @hyperframes/lint, so the render-time render-gate and the
studio preview share one rule engine instead of two copies that could
silently diverge. Back-compat preserved via the @hyperframes/core/lint stub.

Addresses review feedback on the dual-copy footgun.
---
 packages/core/src/compiler/staticGuard.ts     |    2 +-
 packages/core/src/index.test.ts               |    8 +-
 packages/core/src/index.ts                    |    5 +-
 packages/core/src/lint/context.ts             |   66 -
 .../core/src/lint/hyperframeLinter.test.ts    |  124 --
 packages/core/src/lint/hyperframeLinter.ts    |  155 --
 packages/core/src/lint/rules/adapters.test.ts |  144 --
 packages/core/src/lint/rules/adapters.ts      |   55 -
 packages/core/src/lint/rules/captions.test.ts |  166 ---
 packages/core/src/lint/rules/captions.ts      |  271 ----
 .../core/src/lint/rules/composition.test.ts   | 1104 --------------
 packages/core/src/lint/rules/composition.ts   |  723 ---------
 packages/core/src/lint/rules/core.test.ts     |  730 ---------
 packages/core/src/lint/rules/core.ts          |  475 ------
 packages/core/src/lint/rules/fonts.test.ts    |  285 ----
 packages/core/src/lint/rules/fonts.ts         |  222 ---
 packages/core/src/lint/rules/gsap.test.ts     | 1318 -----------------
 packages/core/src/lint/rules/gsap.ts          | 1142 --------------
 packages/core/src/lint/rules/media.test.ts    |  251 ----
 packages/core/src/lint/rules/media.ts         |  526 -------
 .../core/src/lint/rules/slideshow.test.ts     |   73 -
 packages/core/src/lint/rules/slideshow.ts     |   82 -
 packages/core/src/lint/rules/textures.test.ts |  145 --
 packages/core/src/lint/rules/textures.ts      |  226 ---
 packages/core/src/lint/types.ts               |   40 -
 packages/core/src/lint/utils.ts               |  300 ----
 26 files changed, 11 insertions(+), 8627 deletions(-)
 delete mode 100644 packages/core/src/lint/context.ts
 delete mode 100644 packages/core/src/lint/hyperframeLinter.test.ts
 delete mode 100644 packages/core/src/lint/hyperframeLinter.ts
 delete mode 100644 packages/core/src/lint/rules/adapters.test.ts
 delete mode 100644 packages/core/src/lint/rules/adapters.ts
 delete mode 100644 packages/core/src/lint/rules/captions.test.ts
 delete mode 100644 packages/core/src/lint/rules/captions.ts
 delete mode 100644 packages/core/src/lint/rules/composition.test.ts
 delete mode 100644 packages/core/src/lint/rules/composition.ts
 delete mode 100644 packages/core/src/lint/rules/core.test.ts
 delete mode 100644 packages/core/src/lint/rules/core.ts
 delete mode 100644 packages/core/src/lint/rules/fonts.test.ts
 delete mode 100644 packages/core/src/lint/rules/fonts.ts
 delete mode 100644 packages/core/src/lint/rules/gsap.test.ts
 delete mode 100644 packages/core/src/lint/rules/gsap.ts
 delete mode 100644 packages/core/src/lint/rules/media.test.ts
 delete mode 100644 packages/core/src/lint/rules/media.ts
 delete mode 100644 packages/core/src/lint/rules/slideshow.test.ts
 delete mode 100644 packages/core/src/lint/rules/slideshow.ts
 delete mode 100644 packages/core/src/lint/rules/textures.test.ts
 delete mode 100644 packages/core/src/lint/rules/textures.ts
 delete mode 100644 packages/core/src/lint/types.ts
 delete mode 100644 packages/core/src/lint/utils.ts

diff --git a/packages/core/src/compiler/staticGuard.ts b/packages/core/src/compiler/staticGuard.ts
index a5fd791a8f..568a6133a6 100644
--- a/packages/core/src/compiler/staticGuard.ts
+++ b/packages/core/src/compiler/staticGuard.ts
@@ -1,4 +1,4 @@
-import { lintHyperframeHtml } from "../lint/hyperframeLinter";
+import { lintHyperframeHtml } from "@hyperframes/lint";
 
 export type HyperframeStaticFailureReason =
   | "missing_composition_id"
diff --git a/packages/core/src/index.test.ts b/packages/core/src/index.test.ts
index 1ceb5bc9d2..e6792aa2a9 100644
--- a/packages/core/src/index.test.ts
+++ b/packages/core/src/index.test.ts
@@ -128,8 +128,12 @@ describe("@hyperframes/core public API exports", () => {
   });
 
   describe("lint exports", () => {
-    it("exports lintHyperframeHtml", () => {
-      expect(typeof core.lintHyperframeHtml).toBe("function");
+    it("exposes lintHyperframeHtml via the @hyperframes/core/lint back-compat stub", async () => {
+      // Lint moved to @hyperframes/lint; core's main entry no longer re-exports
+      // it (that would cycle through the lint package). The subpath stub keeps
+      // existing @hyperframes/core/lint imports working.
+      const lint = await import("./lint/index.js");
+      expect(typeof lint.lintHyperframeHtml).toBe("function");
     });
   });
 
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index e71b76f8bb..42ca299622 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -138,7 +138,10 @@ export {
   MEDIA_DURATION_CLAMP_EPSILON_SECONDS,
 } from "./compiler/timingCompiler";
 
-// Lint — import from @hyperframes/lint directly
+// Lint moved to @hyperframes/lint. Import lint APIs from @hyperframes/lint
+// directly, or via the back-compat stub at @hyperframes/core/lint. Not
+// re-exported here — doing so would cycle core's main entry through the lint
+// package (which imports core utilities back).
 export {
   rewriteAssetPaths,
   rewriteAssetPath,
diff --git a/packages/core/src/lint/context.ts b/packages/core/src/lint/context.ts
deleted file mode 100644
index 7ee0d75164..0000000000
--- a/packages/core/src/lint/context.ts
+++ /dev/null
@@ -1,66 +0,0 @@
-import type { HyperframeLintFinding, HyperframeLinterOptions } from "./types";
-import {
-  extractBlocks,
-  extractOpenTags,
-  findRootTag,
-  collectCompositionIds,
-  readAttr,
-  stripHtmlComments,
-  STYLE_BLOCK_PATTERN,
-  SCRIPT_BLOCK_PATTERN,
-} from "./utils";
-import type { OpenTag, ExtractedBlock } from "./utils";
-
-export type { OpenTag, ExtractedBlock };
-
-export type LintContext = {
-  source: string;
-  rawSource: string;
-  tags: OpenTag[];
-  styles: ExtractedBlock[];
-  scripts: ExtractedBlock[];
-  compositionIds: Set<string>;
-  rootTag: OpenTag | null;
-  rootCompositionId: string | null;
-  options: HyperframeLinterOptions;
-};
-
-// Re-export for convenience so rule modules only need one import for the finding type
-export type { HyperframeLintFinding };
-
-export function buildLintContext(html: string, options: HyperframeLinterOptions = {}): LintContext {
-  const rawSource = html || "";
-  // Strip HTML comments before scanning so a commented-out <template> or tag can't
-  // hijack the boundary match below. Linear + fixpoint (see stripHtmlComments) to
-  // stay ReDoS-free and catch markers that re-form when a comment is removed.
-  let source = stripHtmlComments(rawSource);
-  const templateMatch = source.match(/<template[^>]*>([\s\S]*)<\/template>/i);
-  if (templateMatch?.[1]) source = templateMatch[1];
-
-  const tags = extractOpenTags(source);
-  const styles = [
-    ...extractBlocks(source, STYLE_BLOCK_PATTERN),
-    ...(options.externalStyles ?? []).map((style) => ({
-      attrs: `href="${style.href}"`,
-      content: style.content,
-      raw: style.content,
-      index: -1,
-    })),
-  ];
-  const scripts = extractBlocks(source, SCRIPT_BLOCK_PATTERN);
-  const compositionIds = collectCompositionIds(tags);
-  const rootTag = findRootTag(source);
-  const rootCompositionId = readAttr(rootTag?.raw || "", "data-composition-id");
-
-  return {
-    source,
-    rawSource,
-    tags,
-    styles,
-    scripts,
-    compositionIds,
-    rootTag,
-    rootCompositionId,
-    options,
-  };
-}
diff --git a/packages/core/src/lint/hyperframeLinter.test.ts b/packages/core/src/lint/hyperframeLinter.test.ts
deleted file mode 100644
index 8590bc41c5..0000000000
--- a/packages/core/src/lint/hyperframeLinter.test.ts
+++ /dev/null
@@ -1,124 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { lintHyperframeHtml } from "./hyperframeLinter.js";
-
-describe("lintHyperframeHtml — orchestrator", () => {
-  const validComposition = `
-<html>
-<body>
-  <div id="root" data-composition-id="comp-1" data-width="1920" data-height="1080" data-start="0">
-    <div id="stage"></div>
-  </div>
-  <script src="https://cdn.gsap.com/gsap.min.js"></script>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#stage", { opacity: 1, duration: 1 }, 0);
-    window.__timelines["comp-1"] = tl;
-  </script>
-</body>
-</html>`;
-
-  it("reports no errors for a valid composition", async () => {
-    const result = await lintHyperframeHtml(validComposition);
-    expect(result.ok).toBe(true);
-    expect(result.errorCount).toBe(0);
-  });
-
-  it("attaches filePath to findings when option is set", async () => {
-    const html = "<html><body><div></div></body></html>";
-    const result = await lintHyperframeHtml(html, { filePath: "test.html" });
-    for (const finding of result.findings) {
-      expect(finding.file).toBe("test.html");
-    }
-  });
-
-  it("deduplicates identical findings", async () => {
-    const html = `
-<html><body>
-  <div id="root"></div>
-  <script>const tl = gsap.timeline();</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const codes = result.findings.map((f) => `${f.code}|${f.message}`);
-    const uniqueCodes = [...new Set(codes)];
-    expect(codes.length).toBe(uniqueCodes.length);
-  });
-
-  it("strips <template> wrapper before linting composition files", async () => {
-    const html = `<template id="my-comp-template">
-  <div data-composition-id="my-comp" data-width="1920" data-height="1080"
-       style="position:relative;width:1920px;height:1080px;">
-    <div id="stage"></div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#stage", { opacity: 1, duration: 1 }, 0);
-    window.__timelines["my-comp"] = tl;
-  </script>
-</template>`;
-    const result = await lintHyperframeHtml(html, { filePath: "compositions/my-comp.html" });
-    const missing = result.findings.filter(
-      (f) => f.code === "missing-composition-id" || f.code === "missing-dimensions",
-    );
-    expect(missing).toHaveLength(0);
-  });
-
-  it("ignores comments that mention template tags before the real template", async () => {
-    const html = `<!doctype html>
-<html>
-  <head>
-    <!-- Authoring note: styles and scripts live inside <template>. -->
-  </head>
-  <body>
-    <template id="my-comp-template">
-      <style>#root { width: 1920px; height: 1080px; }</style>
-      <div data-composition-id="my-comp" data-width="1920" data-height="1080">
-        <div id="stage"></div>
-      </div>
-      <script>
-        window.__timelines = window.__timelines || {};
-        const tl = gsap.timeline({ paused: true });
-        tl.to("#stage", { opacity: 1, duration: 1 }, 0);
-        window.__timelines["my-comp"] = tl;
-      </script>
-    </template>
-  </body>
-</html>`;
-    const result = await lintHyperframeHtml(html, { filePath: "compositions/my-comp.html" });
-    const rootFindings = result.findings.filter(
-      (f) => f.code === "root_missing_composition_id" || f.code === "root_missing_dimensions",
-    );
-    expect(rootFindings).toHaveLength(0);
-  });
-
-  it("strips comments whose markers re-form after one pass (no decoy template survives)", async () => {
-    // Adjacent comment markers: removing the inner `<!-- -->` in a single pass
-    // re-joins `<` + `!-- … -->` into a fresh, complete `<!-- … -->` that a lone
-    // global replace leaves behind — surfacing a decoy <template> with no
-    // composition-id. A fixpoint strip removes it; this guards that behavior.
-    const html = `<!doctype html>
-<html>
-  <body>
-    <<!-- -->!-- <template id="decoy-template"></template> -->
-    <template id="my-comp-template">
-      <style>#root { width: 1920px; height: 1080px; }</style>
-      <div data-composition-id="my-comp" data-width="1920" data-height="1080">
-        <div id="stage"></div>
-      </div>
-      <script>
-        window.__timelines = window.__timelines || {};
-        const tl = gsap.timeline({ paused: true });
-        tl.to("#stage", { opacity: 1, duration: 1 }, 0);
-        window.__timelines["my-comp"] = tl;
-      </script>
-    </template>
-  </body>
-</html>`;
-    const result = await lintHyperframeHtml(html, { filePath: "compositions/my-comp.html" });
-    const rootFindings = result.findings.filter(
-      (f) => f.code === "root_missing_composition_id" || f.code === "root_missing_dimensions",
-    );
-    expect(rootFindings).toHaveLength(0);
-  });
-});
diff --git a/packages/core/src/lint/hyperframeLinter.ts b/packages/core/src/lint/hyperframeLinter.ts
deleted file mode 100644
index 1dc88067c6..0000000000
--- a/packages/core/src/lint/hyperframeLinter.ts
+++ /dev/null
@@ -1,155 +0,0 @@
-import type { HyperframeLintFinding, HyperframeLintResult, HyperframeLinterOptions } from "./types";
-import { buildLintContext } from "./context";
-import { readAttr, truncateSnippet } from "./utils";
-import { coreRules } from "./rules/core";
-import { mediaRules } from "./rules/media";
-import { gsapRules } from "./rules/gsap";
-import { captionRules } from "./rules/captions";
-import { compositionRules } from "./rules/composition";
-import { adapterRules } from "./rules/adapters";
-import { textureRules } from "./rules/textures";
-import { fontRules } from "./rules/fonts";
-import { slideshowRules } from "./rules/slideshow";
-
-const ALL_RULES = [
-  ...coreRules,
-  ...mediaRules,
-  ...gsapRules,
-  ...captionRules,
-  ...compositionRules,
-  ...adapterRules,
-  ...textureRules,
-  ...fontRules,
-  ...slideshowRules,
-];
-
-export async function lintHyperframeHtml(
-  html: string,
-  options: HyperframeLinterOptions = {},
-): Promise<HyperframeLintResult> {
-  const ctx = buildLintContext(html, options);
-  const findings: HyperframeLintFinding[] = [];
-  const seen = new Set<string>();
-
-  for (const rule of ALL_RULES) {
-    for (const finding of await Promise.resolve(rule(ctx))) {
-      const dedupeKey = [
-        finding.code,
-        finding.severity,
-        finding.selector || "",
-        finding.elementId || "",
-        finding.message,
-      ].join("|");
-      if (seen.has(dedupeKey)) continue;
-      seen.add(dedupeKey);
-      findings.push(options.filePath ? { ...finding, file: options.filePath } : finding);
-    }
-  }
-
-  const errorCount = findings.filter((f) => f.severity === "error").length;
-  const warningCount = findings.filter((f) => f.severity === "warning").length;
-  const infoCount = findings.filter((f) => f.severity === "info").length;
-
-  return {
-    ok: errorCount === 0,
-    errorCount,
-    warningCount,
-    infoCount,
-    findings,
-  };
-}
-
-// ── Async media URL accessibility checker ─────────────────────────────────
-
-function extractMediaUrls(html: string): Array<{
-  url: string;
-  tagName: string;
-  elementId?: string;
-  snippet: string;
-}> {
-  const results: Array<{
-    url: string;
-    tagName: string;
-    elementId?: string;
-    snippet: string;
-  }> = [];
-  const tagRe = /<(video|audio|img|source)\b[^>]*>/gi;
-  let match: RegExpExecArray | null;
-  while ((match = tagRe.exec(html)) !== null) {
-    const tagName = (match[1] ?? "").toLowerCase();
-    const raw = match[0];
-    const src = readAttr(raw, "src");
-    if (!src) continue;
-    if (/^https?:\/\//i.test(src)) {
-      results.push({
-        url: src,
-        tagName,
-        elementId: readAttr(raw, "id") || undefined,
-        snippet: truncateSnippet(raw) ?? "",
-      });
-    }
-  }
-  return results;
-}
-
-/**
- * Async lint pass: HEAD-checks every remote media URL in the HTML.
- * Returns findings for URLs that are unreachable (non-2xx status or network error).
- *
- * Call this after `lintHyperframeHtml()` and merge the findings.
- *
- * @param timeoutMs - per-request timeout (default 8000ms)
- */
-export async function lintMediaUrls(
-  html: string,
-  options: { timeoutMs?: number } = {},
-): Promise<HyperframeLintFinding[]> {
-  const urls = extractMediaUrls(html);
-  if (urls.length === 0) return [];
-
-  const timeout = options.timeoutMs ?? 8000;
-  const findings: HyperframeLintFinding[] = [];
-
-  const seen = new Set<string>();
-  const unique = urls.filter((u) => {
-    if (seen.has(u.url)) return false;
-    seen.add(u.url);
-    return true;
-  });
-
-  const checks = unique.map(async ({ url, tagName, elementId, snippet }) => {
-    try {
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), timeout);
-      const resp = await fetch(url, {
-        method: "HEAD",
-        signal: controller.signal,
-        redirect: "follow",
-      });
-      clearTimeout(timer);
-      if (!resp.ok) {
-        findings.push({
-          code: "inaccessible_media_url",
-          severity: "error",
-          message: `<${tagName}${elementId ? ` id="${elementId}"` : ""}> references a URL that returned HTTP ${resp.status}: ${url.slice(0, 100)}`,
-          elementId,
-          fixHint: "This URL is not accessible. Replace with a valid, reachable media URL.",
-          snippet,
-        });
-      }
-    } catch (err) {
-      const reason = err instanceof Error ? err.name : "unknown";
-      findings.push({
-        code: "inaccessible_media_url",
-        severity: "error",
-        message: `<${tagName}${elementId ? ` id="${elementId}"` : ""}> references an unreachable URL (${reason}): ${url.slice(0, 100)}`,
-        elementId,
-        fixHint: "This URL is not accessible. Replace with a valid, reachable media URL.",
-        snippet,
-      });
-    }
-  });
-
-  await Promise.all(checks);
-  return findings;
-}
diff --git a/packages/core/src/lint/rules/adapters.test.ts b/packages/core/src/lint/rules/adapters.test.ts
deleted file mode 100644
index d28e49abc9..0000000000
--- a/packages/core/src/lint/rules/adapters.test.ts
+++ /dev/null
@@ -1,144 +0,0 @@
-// fallow-ignore-file code-duplication
-import { describe, it, expect } from "vitest";
-import { lintHyperframeHtml } from "../hyperframeLinter.js";
-
-describe("adapter rules", () => {
-  it("reports error when GSAP is used without a GSAP script tag", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#box", { x: 100, duration: 1 }, 0);
-    window.__timelines["main"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.message).toContain("GSAP");
-  });
-
-  it("does not report missing_gsap_script when GSAP CDN script is present", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></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("#box", { x: 100, duration: 1 }, 0);
-    window.__timelines["main"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
-    expect(finding).toBeUndefined();
-  });
-
-  it("reports error when Lottie container exists without a Lottie script tag", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080">
-    <div id="lottie-player" data-lottie-src="animation.json"></div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["main"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "missing_lottie_script");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.message).toContain("Lottie");
-  });
-
-  it("reports error when lottie.loadAnimation is used without a Lottie script tag", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["main"] = gsap.timeline({ paused: true });
-    lottie.loadAnimation({ container: document.getElementById('lottie'), path: 'anim.json' });
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "missing_lottie_script");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-  });
-
-  it("does not report missing_lottie_script when Lottie CDN script is present", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080">
-    <div id="lottie-player" data-lottie-src="animation.json"></div>
-  </div>
-  <script src="https://cdn.jsdelivr.net/npm/lottie-web@5/build/player/lottie.min.js"></script>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["main"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "missing_lottie_script");
-    expect(finding).toBeUndefined();
-  });
-
-  it("reports error when Three.js is used without a Three.js script tag", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["main"] = gsap.timeline({ paused: true });
-    const scene = new THREE.Scene();
-    const renderer = new THREE.WebGLRenderer();
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "missing_three_script");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.message).toContain("Three.js");
-  });
-
-  it("does not report missing_three_script when Three.js CDN script is present", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
-  <script src="https://cdn.jsdelivr.net/npm/three@0.160/build/three.min.js"></script>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["main"] = gsap.timeline({ paused: true });
-    const scene = new THREE.Scene();
-    const renderer = new THREE.WebGLRenderer();
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "missing_three_script");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does not report any adapter errors for composition with no adapter usage", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080">
-    <div id="content">Hello World</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["main"] = { totalDuration: function() { return 3; } };
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const adapterFindings = result.findings.filter((f) =>
-      ["missing_gsap_script", "missing_lottie_script", "missing_three_script"].includes(f.code),
-    );
-    expect(adapterFindings).toHaveLength(0);
-  });
-});
diff --git a/packages/core/src/lint/rules/adapters.ts b/packages/core/src/lint/rules/adapters.ts
deleted file mode 100644
index 2a9b05bc28..0000000000
--- a/packages/core/src/lint/rules/adapters.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-import type { LintContext, HyperframeLintFinding } from "../context";
-import { readAttr, extractScriptTextsAndSrcs } from "../utils";
-
-export const adapterRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
-  // missing_lottie_script
-  ({ tags, scripts }) => {
-    const { texts, srcs } = extractScriptTextsAndSrcs(scripts);
-
-    const hasLottieAttr = tags.some((t) => readAttr(t.raw, "data-lottie-src") !== null);
-    const usesLottieApi = texts.some((t) =>
-      /lottie\.(loadAnimation|setSpeed|play|stop|destroy)\b/.test(t),
-    );
-    const hasLottieScript = srcs.some((src) => /lottie/i.test(src));
-
-    if (!(hasLottieAttr || usesLottieApi) || hasLottieScript) return [];
-    return [
-      {
-        code: "missing_lottie_script",
-        severity: "error",
-        message:
-          "Composition uses Lottie but no Lottie script is loaded. The animation will not render.",
-        fixHint:
-          'Add <script src="https://cdn.jsdelivr.net/npm/lottie-web@5/build/player/lottie.min.js"></script> before your Lottie code.',
-      },
-    ];
-  },
-
-  // missing_three_script
-  ({ scripts }) => {
-    const { texts, srcs } = extractScriptTextsAndSrcs(scripts);
-
-    const usesThree = texts.some((t) => /\bTHREE\./.test(t));
-    const hasThreeScript = srcs.some((src) => /three/i.test(src));
-    const hasThreeImportMap = texts.some(
-      (t) =>
-        /["']three["']/.test(t) &&
-        /importmap/.test(scripts.find((s) => s.content === t)?.attrs || ""),
-    );
-    const hasThreeModuleImport = texts.some(
-      (t) => /\bimport\b.*['"]three['"]/.test(t) || /\bfrom\s+['"]three['"]/.test(t),
-    );
-
-    if (!usesThree || hasThreeScript || hasThreeImportMap || hasThreeModuleImport) return [];
-    return [
-      {
-        code: "missing_three_script",
-        severity: "error",
-        message:
-          "Composition uses Three.js but no Three.js script is loaded. The 3D scene will not render.",
-        fixHint:
-          'Add <script src="https://cdn.jsdelivr.net/npm/three@0.160/build/three.min.js"></script> before your Three.js code.',
-      },
-    ];
-  },
-];
diff --git a/packages/core/src/lint/rules/captions.test.ts b/packages/core/src/lint/rules/captions.test.ts
deleted file mode 100644
index 6977acb6e6..0000000000
--- a/packages/core/src/lint/rules/captions.test.ts
+++ /dev/null
@@ -1,166 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { lintHyperframeHtml } from "../hyperframeLinter.js";
-
-describe("caption rules", () => {
-  it("warns when caption exit has no hard kill tl.set", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="captions" data-width="1920" data-height="1080">
-    <div id="caption-container"></div>
-    <script>
-      window.__timelines = window.__timelines || {};
-      var tl = gsap.timeline({ paused: true });
-      GROUPS.forEach(function(group, gi) {
-        var groupEl = document.createElement("div");
-        groupEl.id = "cg-" + gi;
-        tl.set(groupEl, { opacity: 1 }, group.start);
-        tl.to(groupEl, { opacity: 0, duration: 0.12 }, group.end - 0.12);
-      });
-      window.__timelines["captions"] = tl;
-    </script>
-  </div>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "caption_exit_missing_hard_kill");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-  });
-
-  it("does not warn when caption exit has hard kill tl.set", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="captions" data-width="1920" data-height="1080">
-    <div id="caption-container"></div>
-    <script>
-      window.__timelines = window.__timelines || {};
-      var tl = gsap.timeline({ paused: true });
-      GROUPS.forEach(function(group, gi) {
-        var groupEl = document.createElement("div");
-        groupEl.id = "cg-" + gi;
-        tl.set(groupEl, { opacity: 1 }, group.start);
-        tl.to(groupEl, { opacity: 0, duration: 0.12 }, group.end - 0.12);
-        tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end);
-      });
-      window.__timelines["captions"] = tl;
-    </script>
-  </div>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "caption_exit_missing_hard_kill");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does not warn for generic GSAP opacity exits in non-caption loops", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080">
-    <script>
-      window.__timelines = window.__timelines || {};
-      var tl = gsap.timeline({ paused: true });
-      var sceneCaption = document.querySelector("#scene-caption");
-      CARDS.forEach(function(group, gi) {
-        var groupEl = document.createElement("div");
-        groupEl.id = "card-" + gi;
-        tl.to(groupEl, { opacity: 0, duration: 0.12 }, 2);
-      });
-      window.__timelines["main"] = tl;
-    </script>
-  </div>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "caption_exit_missing_hard_kill");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does not warn on a content frame that only mentions karaoke in a comment", async () => {
-    const html = `<template id="06-one-platform-template">
-  <div id="root" data-composition-id="06-one-platform" data-width="1920" data-height="1080">
-    <script>
-      window.__timelines = window.__timelines || {};
-      var tl = gsap.timeline({ paused: true });
-      // "Minutes, not weeks" lands with a karaoke-style keyword glow
-      SCREENS.forEach(function (s, i) {
-        var el = document.getElementById("screen-" + i);
-        tl.to(el, { y: -40, opacity: 0, duration: 0.3 }, i * 1.3);
-      });
-      window.__timelines["06-one-platform"] = tl;
-    </script>
-  </div>
-</template>`;
-    const result = await lintHyperframeHtml(html, { isSubComposition: true });
-    const finding = result.findings.find((f) => f.code === "caption_exit_missing_hard_kill");
-    expect(finding).toBeUndefined();
-  });
-
-  it("warns when caption group has nowrap without max-width", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="captions" data-width="1920" data-height="1080">
-    <style>
-      .caption-group {
-        position: absolute;
-        white-space: nowrap;
-        text-align: center;
-      }
-    </style>
-    <script>
-      window.__timelines = window.__timelines || {};
-      var tl = gsap.timeline({ paused: true });
-      window.__timelines["captions"] = tl;
-    </script>
-  </div>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "caption_text_overflow_risk");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("warning");
-  });
-
-  it("does not warn when caption group has nowrap with max-width", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="captions" data-width="1920" data-height="1080">
-    <style>
-      .caption-group {
-        position: absolute;
-        white-space: nowrap;
-        max-width: 1600px;
-        overflow: hidden;
-      }
-    </style>
-    <script>
-      window.__timelines = window.__timelines || {};
-      var tl = gsap.timeline({ paused: true });
-      window.__timelines["captions"] = tl;
-    </script>
-  </div>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find(
-      (f) => f.code === "caption_text_overflow_risk" && f.severity === "warning",
-    );
-    expect(finding).toBeUndefined();
-  });
-
-  it("warns when caption container uses position: relative", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="captions" data-width="1920" data-height="1080">
-    <style>
-      .caption-group {
-        position: relative;
-      }
-    </style>
-    <script>
-      window.__timelines = window.__timelines || {};
-      var tl = gsap.timeline({ paused: true });
-      window.__timelines["captions"] = tl;
-    </script>
-  </div>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "caption_container_relative_position");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-  });
-});
diff --git a/packages/core/src/lint/rules/captions.ts b/packages/core/src/lint/rules/captions.ts
deleted file mode 100644
index 21af66d0e7..0000000000
--- a/packages/core/src/lint/rules/captions.ts
+++ /dev/null
@@ -1,271 +0,0 @@
-import type { LintContext, HyperframeLintFinding } from "../context";
-
-/** Extract a bracket-balanced array literal starting at the `[` found by `varMatch`. */
-// fallow-ignore-next-line complexity
-function extractArrayLiteral(src: string, varMatch: RegExpExecArray): string | null {
-  const openIdx = varMatch.index + varMatch[0].length - 1;
-  let depth = 0;
-  let inStr = false;
-  let strChar = "";
-  for (let i = openIdx; i < src.length; i++) {
-    const c = src[i]!;
-    if (inStr) {
-      if (c === "\\") {
-        i++;
-        continue;
-      }
-      if (c === strChar) inStr = false;
-    } else if (c === '"' || c === "'") {
-      inStr = true;
-      strChar = c;
-    } else if (c === "[") {
-      depth++;
-    } else if (c === "]") {
-      depth--;
-      if (depth === 0) return src.slice(openIdx, i + 1);
-    }
-  }
-  return null;
-}
-
-export const captionRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
-  // caption_exit_missing_hard_kill
-  ({ scripts, styles, options, rootCompositionId }) => {
-    const findings: HyperframeLintFinding[] = [];
-    // Only the ACTUAL captions composition. A content frame that merely mentions
-    // "karaoke" / "caption-*" in a comment (or uses an unrelated forEach + opacity:0
-    // screen-swap) is NOT captions — gating here prevents the false positive that fired
-    // on a content frame whose only caption signal was a descriptive comment.
-    const isCaptionComposition =
-      Boolean(options.filePath && /caption/i.test(options.filePath)) ||
-      rootCompositionId === "captions" ||
-      styles.some((s) => /\.caption[-_]?(?:group|word|line|block)\b|\.cg-/.test(s.content));
-    if (!isCaptionComposition) return findings;
-    for (const script of scripts) {
-      const content = script.content;
-      const hasExitTween = /\.to\s*\([^,]+,\s*\{[^}]*opacity\s*:\s*0/.test(content);
-      const hasHardKill =
-        /\.set\s*\([^,]+,\s*\{[^}]*(?:visibility\s*:\s*["']hidden["']|opacity\s*:\s*0)/.test(
-          content,
-        );
-      const hasCaptionLoop =
-        /forEach|\.forEach\s*\(/.test(content) &&
-        /karaoke|caption[-_]?(?:group|word|line|block)|cg-/.test(content);
-      if (hasCaptionLoop && hasExitTween && !hasHardKill) {
-        findings.push({
-          code: "caption_exit_missing_hard_kill",
-          severity: "error",
-          message:
-            "Caption exit animations (tl.to with opacity: 0) detected without a hard tl.set kill. " +
-            "Exit tweens can fail when karaoke word-level tweens conflict, leaving captions stuck on screen.",
-          fixHint:
-            'Add `tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end)` after every ' +
-            "exit tl.to animation as a deterministic kill.",
-        });
-      }
-    }
-    return findings;
-  },
-
-  // caption_text_overflow_risk
-  ({ styles }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const style of styles) {
-      const captionBlocks = style.content.matchAll(
-        /(\.caption[-_]?(?:group|container|text|line|word)|#caption[-_]?container)\s*\{([^}]+)\}/gi,
-      );
-      for (const [, selector, body] of captionBlocks) {
-        if (!body) continue;
-        const hasNowrap = /white-space\s*:\s*nowrap/i.test(body);
-        const hasMaxWidth = /max-width/i.test(body);
-        if (hasNowrap && !hasMaxWidth) {
-          findings.push({
-            code: "caption_text_overflow_risk",
-            severity: "warning",
-            selector: (selector ?? "").trim(),
-            message: `Caption selector "${(selector ?? "").trim()}" has white-space: nowrap but no max-width. Long phrases will clip off-screen.`,
-            fixHint:
-              "Add max-width: 1600px (landscape) or max-width: 900px (portrait) and overflow: hidden.",
-          });
-        }
-      }
-    }
-    return findings;
-  },
-
-  // caption_transcript_not_inline
-  // fallow-ignore-next-line complexity
-  ({ scripts, styles, options }) => {
-    const findings: HyperframeLintFinding[] = [];
-    // Only check files that look like caption compositions
-    const isCaptionFile =
-      (options.filePath && /caption/i.test(options.filePath)) ||
-      styles.some((s) => /\.caption[-_]?(?:group|word)/i.test(s.content));
-    if (!isCaptionFile) return findings;
-
-    const allScript = scripts.map((s) => s.content).join("\n");
-    const hasInlineTranscript = /(?:const|let|var)\s+(?:TRANSCRIPT|script)\s*=\s*\[/.test(
-      allScript,
-    );
-    const hasFetchTranscript = /fetch\s*\(\s*["'][^"']*transcript/i.test(allScript);
-
-    if (!hasInlineTranscript && hasFetchTranscript) {
-      findings.push({
-        code: "caption_transcript_not_inline",
-        severity: "error",
-        message:
-          "Captions composition loads transcript via fetch(). The studio caption editor " +
-          "requires an inline `var TRANSCRIPT = [...]` array to detect and edit captions.",
-        fixHint:
-          'Embed the transcript as `var TRANSCRIPT = [{ "text": "...", "start": 0, "end": 1 }, ...]` ' +
-          "with JSON-quoted property keys. See the captions skill for details.",
-      });
-    }
-
-    if (hasInlineTranscript) {
-      // Verify the inline transcript can be parsed.
-      // Use a balanced-bracket scan instead of a regex to correctly handle
-      // nested arrays (e.g. word-level timing arrays inside each entry).
-      const varStart = /(?:const|let|var)\s+(?:TRANSCRIPT|script)\s*=\s*\[/.exec(allScript);
-      const transcriptJson = varStart ? extractArrayLiteral(allScript, varStart) : null;
-      if (transcriptJson) {
-        try {
-          JSON.parse(transcriptJson);
-        } catch {
-          findings.push({
-            code: "caption_transcript_parse_error",
-            severity: "error",
-            message:
-              "Inline TRANSCRIPT array is not valid JSON. The studio caption editor may fail " +
-              "to parse it. Common cause: unquoted property keys with apostrophes in text.",
-            fixHint:
-              'Use JSON-quoted keys: { "text": "don\'t", "start": 0, "end": 1 } instead of ' +
-              '{ text: "don\'t", start: 0, end: 1 }.',
-          });
-        }
-      }
-    }
-
-    return findings;
-  },
-
-  // caption_container_relative_position
-  ({ styles }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const style of styles) {
-      const captionBlocks = style.content.matchAll(
-        /(\.caption[-_]?(?:group|container|text|line)|#caption[-_]?container)\s*\{([^}]+)\}/gi,
-      );
-      for (const [, selector, body] of captionBlocks) {
-        if (!body) continue;
-        if (/position\s*:\s*relative/i.test(body)) {
-          findings.push({
-            code: "caption_container_relative_position",
-            severity: "error",
-            selector: (selector ?? "").trim(),
-            message: `Caption selector "${(selector ?? "").trim()}" uses position: relative which causes overflow and breaks caption stacking.`,
-            fixHint: "Use position: absolute for all caption elements.",
-          });
-        }
-      }
-    }
-    return findings;
-  },
-
-  // caption_overflow_clips_scaled_words
-  ({ styles, scripts }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const hasScaledWords = scripts.some(
-      (s) => /scale\s*:\s*1\.[2-9]/.test(s.content) && /caption|word|cg-/.test(s.content),
-    );
-    if (!hasScaledWords) return findings;
-
-    for (const style of styles) {
-      const captionBlocks = style.content.matchAll(
-        /(\.caption[-_]?(?:group|container)|#caption[-_]?(?:layer|container))\s*\{([^}]+)\}/gi,
-      );
-      for (const [, selector, body] of captionBlocks) {
-        if (!body) continue;
-        if (/overflow\s*:\s*hidden/i.test(body)) {
-          findings.push({
-            code: "caption_overflow_clips_scaled_words",
-            severity: "error",
-            selector: (selector ?? "").trim(),
-            message: `"${(selector ?? "").trim()}" has overflow: hidden but GSAP scales caption words above 1.0x. Scaled emphasis words and their glow effects will be clipped.`,
-            fixHint:
-              "Use overflow: visible on caption containers. Rely on fitTextFontSize with reduced maxWidth to prevent overflow instead.",
-          });
-        }
-      }
-    }
-    return findings;
-  },
-
-  // caption_textshadow_on_group_container
-  ({ scripts, styles }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const isCaptionFile = styles.some((s) => /\.caption[-_]?(?:group|word)/i.test(s.content));
-    if (!isCaptionFile) return findings;
-
-    for (const script of scripts) {
-      // Detect textShadow tweened on a group container (div with child word spans)
-      const groupShadowPattern =
-        /\.to\s*\(\s*(?:div|groupEl|el|captionEl|document\.getElementById\s*\(\s*["']cg-)\s*[^,]*,\s*\{[^}]*textShadow/g;
-      // Also catch selector-based targeting of group containers
-      const selectorShadowPattern =
-        /\.to\s*\(\s*["'](?:#cg-\d+|\.caption[-_]?group)["']\s*,\s*\{[^}]*textShadow/g;
-      if (groupShadowPattern.test(script.content) || selectorShadowPattern.test(script.content)) {
-        findings.push({
-          code: "caption_textshadow_on_group_container",
-          severity: "warning",
-          message:
-            "textShadow is tweened on a caption group container. When children have semi-transparent " +
-            "color (e.g., inactive karaoke words at rgba opacity), the glow renders as a visible " +
-            "rectangle behind the entire group.",
-          fixHint:
-            "Apply textShadow to individual active word elements instead of the group container. " +
-            "Use scale on the group for bass-reactive pulsing.",
-        });
-      }
-    }
-    return findings;
-  },
-
-  // caption_fittext_scale_mismatch
-  // fallow-ignore-next-line complexity
-  ({ scripts }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const script of scripts) {
-      const content = script.content;
-      const fitTextMatch = content.match(/fitTextFontSize\s*\([^)]*maxWidth\s*:\s*(\d+)/);
-      if (!fitTextMatch) continue;
-      const maxWidth = parseInt(fitTextMatch[1] ?? "0", 10);
-      if (!maxWidth) continue;
-
-      // Find max scale on caption words
-      const scaleMatches = [...content.matchAll(/scale\s*:\s*(1\.\d+)/g)];
-      const captionContext = /caption|word|cg-|karaoke/i.test(content);
-      if (!captionContext || scaleMatches.length === 0) continue;
-
-      let maxScale = 1;
-      for (const m of scaleMatches) {
-        const val = parseFloat(m[1] ?? "1");
-        if (val > maxScale) maxScale = val;
-      }
-
-      // Check if maxWidth * maxScale exceeds safe bounds (1920 - reasonable margins)
-      const effectiveWidth = maxWidth * maxScale;
-      if (effectiveWidth > 1760) {
-        findings.push({
-          code: "caption_fittext_scale_mismatch",
-          severity: "warning",
-          message:
-            `fitTextFontSize uses maxWidth: ${maxWidth}px but emphasis words scale up to ${maxScale}x. ` +
-            `Effective width ${Math.round(effectiveWidth)}px may overflow the composition (1920px minus margins).`,
-          fixHint: `Reduce maxWidth to ${Math.floor(1700 / maxScale)}px to leave headroom for scaled emphasis words.`,
-        });
-      }
-    }
-    return findings;
-  },
-];
diff --git a/packages/core/src/lint/rules/composition.test.ts b/packages/core/src/lint/rules/composition.test.ts
deleted file mode 100644
index 6e308a2a84..0000000000
--- a/packages/core/src/lint/rules/composition.test.ts
+++ /dev/null
@@ -1,1104 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { lintHyperframeHtml } from "../hyperframeLinter.js";
-
-describe("composition rules", () => {
-  describe("subcomposition guidance", () => {
-    it("warns when any HTML composition file is over 300 lines", async () => {
-      const html = Array.from({ length: 301 }, (_, i) =>
-        i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
-      ).join("\n");
-
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-      });
-      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
-      expect(finding).toBeDefined();
-      expect(finding?.severity).toBe("warning");
-    });
-
-    it("does not warn when an HTML composition file is exactly 300 lines", async () => {
-      const html = Array.from({ length: 300 }, (_, i) =>
-        i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
-      ).join("\n");
-
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not count a final trailing newline as an extra physical line", async () => {
-      const html =
-        Array.from({ length: 300 }, (_, i) =>
-          i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
-        ).join("\n") + "\n";
-
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not count inline style block internals as structural lines", async () => {
-      const style = `<style>\n${Array.from({ length: 320 }, (_, i) => `.rule-${i} { color: red; }`).join("\n")}\n</style>`;
-      const html = `<!doctype html>
-<html>
-  <head>${style}</head>
-  <body>
-    <div data-composition-id="main" data-start="0" data-duration="1">TEXT</div>
-  </body>
-</html>`;
-
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not warn for large registry source block files", async () => {
-      const html = Array.from({ length: 301 }, (_, i) =>
-        i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
-      ).join("\n");
-
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/registry/blocks/data-chart/data-chart.html",
-      });
-      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
-      expect(finding).toBeUndefined();
-    });
-
-    it("warns for large installed block composition files", async () => {
-      const html = Array.from({ length: 301 }, (_, i) =>
-        i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
-      ).join("\n");
-
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/data-chart.html",
-      });
-      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
-      expect(finding).toBeDefined();
-      expect(finding?.severity).toBe("warning");
-    });
-
-    it("does not warn for large registry-installed block composition files", async () => {
-      const html =
-        "<!-- hyperframes-registry-item: data-chart -->\n" +
-        Array.from({ length: 300 }, (_, i) =>
-          i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
-        ).join("\n");
-
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/data-chart.html",
-      });
-      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
-      expect(finding).toBeUndefined();
-    });
-
-    it("uses nested split copy for large sub-composition files", async () => {
-      const html = Array.from({ length: 301 }, (_, i) =>
-        i === 0 ? "<html><body>" : `<!-- filler ${i} -->`,
-      ).join("\n");
-
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-        isSubComposition: true,
-      });
-      const finding = result.findings.find((f) => f.code === "composition_file_too_large");
-      expect(finding?.fixHint).toContain("Split this sub-composition further");
-    });
-
-    it("warns when more than 3 timed elements share the same track", async () => {
-      const html = `<!DOCTYPE html>
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0">
-    <div class="clip" data-start="0" data-duration="1" data-track-index="0">A</div>
-    <div class="clip" data-start="1" data-duration="1" data-track-index="0">B</div>
-    <div class="clip" data-start="2" data-duration="1" data-track-index="0">C</div>
-    <div class="clip" data-start="3" data-duration="1" data-track-index="0">D</div>
-  </div>
-</body></html>`;
-
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-      });
-      const finding = result.findings.find((f) => f.code === "timeline_track_too_dense");
-      expect(finding).toBeDefined();
-      expect(finding?.severity).toBe("warning");
-      expect(finding?.message).toContain("Track 0 has 4 timed elements");
-    });
-
-    it("does not warn when 3 timed elements share the same track", async () => {
-      const html = `<!DOCTYPE html>
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0">
-    <div class="clip" data-start="0" data-duration="1" data-track-index="0">A</div>
-    <div class="clip" data-start="1" data-duration="1" data-track-index="0">B</div>
-    <div class="clip" data-start="2" data-duration="1" data-track-index="0">C</div>
-  </div>
-</body></html>`;
-
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      const finding = result.findings.find((f) => f.code === "timeline_track_too_dense");
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not warn when timed elements are split across tracks", async () => {
-      const html = `<!DOCTYPE html>
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0">
-    <div class="clip" data-start="0" data-duration="1" data-track-index="0">A</div>
-    <div class="clip" data-start="1" data-duration="1" data-track-index="0">B</div>
-    <div class="clip" data-start="2" data-duration="1" data-track-index="1">C</div>
-    <div class="clip" data-start="3" data-duration="1" data-track-index="1">D</div>
-  </div>
-</body></html>`;
-
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      const finding = result.findings.find((f) => f.code === "timeline_track_too_dense");
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not count timed media or script/style tags as dense track elements", async () => {
-      const html = `<!DOCTYPE html>
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0">
-    <audio data-start="0" data-duration="1" data-track-index="0"></audio>
-    <audio data-start="1" data-duration="1" data-track-index="0"></audio>
-    <video muted data-start="2" data-duration="1" data-track-index="0"></video>
-    <script data-start="3" data-duration="1" data-track-index="0"></script>
-    <style data-start="4" data-duration="1" data-track-index="0"></style>
-  </div>
-</body></html>`;
-
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      const finding = result.findings.find((f) => f.code === "timeline_track_too_dense");
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not count root composition or mounted sub-compositions as dense elements", async () => {
-      const html = `<!DOCTYPE html>
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-track-index="0">
-    <div data-composition-id="a" data-composition-src="compositions/a.html" data-start="0" data-duration="1" data-track-index="0"></div>
-    <div data-composition-id="b" data-composition-src="compositions/b.html" data-start="1" data-duration="1" data-track-index="0"></div>
-    <div data-composition-id="c" data-composition-src="compositions/c.html" data-start="2" data-duration="1" data-track-index="0"></div>
-    <div data-composition-id="d" data-composition-src="compositions/d.html" data-start="3" data-duration="1" data-track-index="0"></div>
-  </div>
-</body></html>`;
-
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      const finding = result.findings.find((f) => f.code === "timeline_track_too_dense");
-      expect(finding).toBeUndefined();
-    });
-  });
-
-  it("reports error when querySelector uses template literal variable", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080">
-    <div class="chart"></div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const compId = "main";
-    const el = document.querySelector(\`[data-composition-id="\${compId}"] .chart\`);
-    const tl = gsap.timeline({ paused: true });
-    window.__timelines["main"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "template_literal_selector");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-  });
-
-  it("reports error for querySelectorAll with template literal variable", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const id = "main";
-    document.querySelectorAll(\`[data-composition-id="\${id}"] .item\`);
-    const tl = gsap.timeline({ paused: true });
-    window.__timelines["main"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "template_literal_selector");
-    expect(finding).toBeDefined();
-  });
-
-  it("does not report error for hardcoded querySelector strings", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080">
-    <div class="chart"></div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const el = document.querySelector('[data-composition-id="main"] .chart');
-    const tl = gsap.timeline({ paused: true });
-    window.__timelines["main"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "template_literal_selector");
-    expect(finding).toBeUndefined();
-  });
-
-  it("reports error when a selector combines data attributes in one bracket", async () => {
-    const html = `
-<template id="scene-template">
-  <div data-composition-id="scene" data-start="0" data-width="1920" data-height="1080">
-    <style>
-      [data-composition-id="scene" data-start="0"] .title { opacity: 0; }
-    </style>
-    <script>
-      window.__timelines = window.__timelines || {};
-      const title = document.querySelector('[data-composition-id="scene" data-start="0"] .title');
-      const tl = gsap.timeline({ paused: true });
-      tl.to('[data-composition-id="scene" data-start="0"]', { opacity: 0, duration: 0.5 }, 4);
-      window.__timelines["scene"] = tl;
-    </script>
-  </div>
-</template>`;
-    const result = await lintHyperframeHtml(html, { filePath: "compositions/scene.html" });
-    const findings = result.findings.filter((f) => f.code === "split_data_attribute_selector");
-    expect(findings.length).toBe(1);
-    expect(findings[0]?.severity).toBe("error");
-    expect(findings[0]?.fixHint).toContain('[data-composition-id="scene"][data-start="0"]');
-  });
-
-  describe("timed_element_missing_clip_class", () => {
-    it("flags element with data-start but no class='clip'", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="box" data-start="0" data-duration="2">Hello</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["c1"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "timed_element_missing_clip_class");
-      expect(finding).toBeDefined();
-      expect(finding?.severity).toBe("error");
-    });
-
-    it("does not flag element that has class='clip'", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="box" class="clip" data-start="0" data-duration="2">Hello</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["c1"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "timed_element_missing_clip_class");
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not flag audio or video elements", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <audio data-start="0" data-duration="5" src="music.mp3"></audio>
-    <video data-start="0" data-duration="5" src="clip.mp4"></video>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["c1"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "timed_element_missing_clip_class");
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not flag element with only data-track-index (layer container, no timing)", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="layer" data-track-index="0">
-      <div id="box" class="clip" data-start="0" data-duration="2">Hello</div>
-    </div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["c1"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "timed_element_missing_clip_class");
-      expect(finding).toBeUndefined();
-    });
-  });
-
-  describe("overlapping_clips_same_track", () => {
-    it("flags overlapping clips on the same track", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div class="clip" data-start="0" data-duration="3" data-track-index="0">A</div>
-    <div class="clip" data-start="2" data-duration="3" data-track-index="0">B</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["c1"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "overlapping_clips_same_track");
-      expect(finding).toBeDefined();
-      expect(finding?.severity).toBe("error");
-    });
-
-    it("does not flag clips on different tracks", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div class="clip" data-start="0" data-duration="3" data-track-index="0">A</div>
-    <div class="clip" data-start="1" data-duration="3" data-track-index="1">B</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["c1"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "overlapping_clips_same_track");
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not flag sequential clips on the same track", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div class="clip" data-start="0" data-duration="2" data-track-index="0">A</div>
-    <div class="clip" data-start="2" data-duration="2" data-track-index="0">B</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["c1"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "overlapping_clips_same_track");
-      expect(finding).toBeUndefined();
-    });
-  });
-
-  describe("root_composition_missing_html_wrapper", () => {
-    it("flags bare composition div as error", async () => {
-      // Exact scenario from the screenshot — bare div with composition attributes, no HTML wrapper
-      const html = `<div
-  id="comp-main"
-  data-composition-id="no-limits"
-  data-start="0"
-  data-duration="15"
-  data-width="1920"
-  data-height="1080"
->
-  <!-- Sub-composition: the visual spectacle -->
-  <div
-    id="el-visuals"
-    data-composition-id="visuals"
-    data-composition-src="compositions/visuals.html"
-    data-duration="15"
-    data-track-index="0"
-  ></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 });
-    window.__timelines["no-limits"] = tl;
-  </script>
-</div>`;
-      const result = await lintHyperframeHtml(html, { filePath: "index.html" });
-      const finding = result.findings.find(
-        (f) => f.code === "root_composition_missing_html_wrapper",
-      );
-      expect(finding).toBeDefined();
-      expect(finding?.severity).toBe("error");
-      expect(result.ok).toBe(false);
-    });
-
-    it("does not flag properly wrapped HTML composition", async () => {
-      const html = `<!DOCTYPE html>
-<html><head><meta charset="UTF-8"></head><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10">
-    <div class="clip" data-start="0" data-duration="5">Hello</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["main"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find(
-        (f) => f.code === "root_composition_missing_html_wrapper",
-      );
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not flag composition starting with <html> (no doctype)", async () => {
-      const html = `<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="5"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["main"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find(
-        (f) => f.code === "root_composition_missing_html_wrapper",
-      );
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not flag sub-compositions", async () => {
-      const html = `<div data-composition-id="sub" data-width="1920" data-height="1080">
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["sub"] = gsap.timeline({ paused: true });
-  </script>
-</div>`;
-      const result = await lintHyperframeHtml(html, { isSubComposition: true });
-      const finding = result.findings.find(
-        (f) => f.code === "root_composition_missing_html_wrapper",
-      );
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not flag HTML without composition attributes", async () => {
-      const html = `<div id="hello"><p>Not a composition</p></div>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find(
-        (f) => f.code === "root_composition_missing_html_wrapper",
-      );
-      expect(finding).toBeUndefined();
-    });
-
-    it("includes root tag snippet in finding", async () => {
-      const html = `<div data-composition-id="bare" data-width="1920" data-height="1080">
-  <script>
-    window.__timelines = window.__timelines || {};
-    window.__timelines["bare"] = gsap.timeline({ paused: true });
-  </script>
-</div>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find(
-        (f) => f.code === "root_composition_missing_html_wrapper",
-      );
-      expect(finding).toBeDefined();
-      expect(finding?.snippet).toContain("data-composition-id");
-    });
-  });
-
-  describe("standalone_composition_wrapped_in_template", () => {
-    it("flags root index.html wrapped in template", async () => {
-      const html = `<template id="main-template">
-  <div data-composition-id="main" data-width="1920" data-height="1080">
-    <script>
-      window.__timelines = window.__timelines || {};
-      window.__timelines["main"] = gsap.timeline({ paused: true });
-    </script>
-  </div>
-</template>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find(
-        (f) => f.code === "standalone_composition_wrapped_in_template",
-      );
-      expect(finding).toBeDefined();
-      expect(finding?.severity).toBe("error");
-    });
-
-    it("does not flag sub-compositions in template", async () => {
-      const html = `<template id="sub-template">
-  <div data-composition-id="sub" data-width="1920" data-height="1080">
-    <script>
-      window.__timelines = window.__timelines || {};
-      window.__timelines["sub"] = gsap.timeline({ paused: true });
-    </script>
-  </div>
-</template>`;
-      const result = await lintHyperframeHtml(html, { isSubComposition: true });
-      const finding = result.findings.find(
-        (f) => f.code === "standalone_composition_wrapped_in_template",
-      );
-      expect(finding).toBeUndefined();
-    });
-  });
-
-  describe("requestanimationframe_in_composition", () => {
-    it("flags requestAnimationFrame usage in script content", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    requestAnimationFrame(() => { console.log("tick"); });
-    window.__timelines["c1"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find(
-        (f) => f.code === "requestanimationframe_in_composition",
-      );
-      expect(finding).toBeDefined();
-      expect(finding?.severity).toBe("error");
-    });
-
-    it("does not flag requestAnimationFrame in comments", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    // requestAnimationFrame(() => { });
-    window.__timelines["c1"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find(
-        (f) => f.code === "requestanimationframe_in_composition",
-      );
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not flag installed registry blocks that use rAF (e.g. particle effects)", async () => {
-      const html =
-        `<!-- hyperframes-registry-item: particles -->\n` +
-        `<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    requestAnimationFrame(function loop() { requestAnimationFrame(loop); });
-    window.__timelines["c1"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find(
-        (f) => f.code === "requestanimationframe_in_composition",
-      );
-      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", async () => {
-      // 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 = await 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)", async () => {
-      // 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 = await 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();
-    });
-  });
-
-  describe("root_composition_missing_data_start", () => {
-    it("does not warn for template-wrapped sub-composition files", async () => {
-      const html = `
-<template id="foo-template">
-  <div data-composition-id="foo" data-width="1920" data-height="1080">
-    <div class="clip" data-start="0" data-duration="1"></div>
-  </div>
-</template>`;
-      const result = await lintHyperframeHtml(html, { isSubComposition: true });
-      const finding = result.findings.find((f) => f.code === "root_composition_missing_data_start");
-      expect(finding).toBeUndefined();
-    });
-  });
-
-  describe("invalid_variable_values_json", () => {
-    it("warns when data-variable-values is unparseable JSON", async () => {
-      const html = `<html><body>
-<div data-composition-id="card-1" data-composition-src="card.html" data-variable-values='{not json'></div>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "invalid_variable_values_json");
-      expect(finding).toBeDefined();
-      expect(finding?.severity).toBe("error");
-    });
-
-    it("warns when data-variable-values is a JSON array (must be an object)", async () => {
-      const html = `<html><body>
-<div data-composition-src="card.html" data-variable-values='[1,2,3]'></div>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "invalid_variable_values_json");
-      expect(finding).toBeDefined();
-      expect(finding?.message).toMatch(/must be a JSON object/);
-    });
-
-    it("warns when data-variable-values is a JSON string (must be an object)", async () => {
-      const html = `<html><body>
-<div data-composition-src="card.html" data-variable-values='"hello"'></div>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "invalid_variable_values_json");
-      expect(finding).toBeDefined();
-    });
-
-    it("does not warn for a valid JSON object", async () => {
-      const html = `<html><body>
-<div data-composition-src="card.html" data-variable-values='{"title":"Hello","count":3}'></div>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "invalid_variable_values_json");
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not warn when data-variable-values is absent", async () => {
-      const html = `<html><body>
-<div data-composition-src="card.html"></div>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "invalid_variable_values_json");
-      expect(finding).toBeUndefined();
-    });
-  });
-
-  describe("invalid_composition_variables_declaration", () => {
-    it("warns when data-composition-variables is unparseable JSON", async () => {
-      const html = `<html data-composition-variables='[{not json'><body><div data-composition-id="x"></div></body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find(
-        (f) => f.code === "invalid_composition_variables_declaration",
-      );
-      expect(finding).toBeDefined();
-    });
-
-    it("warns when data-composition-variables is not an array", async () => {
-      const html = `<html data-composition-variables='{"title":"Hello"}'><body><div data-composition-id="x"></div></body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find(
-        (f) => f.code === "invalid_composition_variables_declaration",
-      );
-      expect(finding).toBeDefined();
-      expect(finding?.message).toMatch(/array of variable declarations/);
-    });
-
-    it("warns per-entry when an entry is missing required fields", async () => {
-      const html = `<html data-composition-variables='[{"id":"ok","type":"string","label":"Ok","default":"x"},{"id":"bad"}]'><body><div data-composition-id="x"></div></body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const findings = result.findings.filter(
-        (f) => f.code === "invalid_composition_variables_declaration",
-      );
-      expect(findings.length).toBe(1);
-      expect(findings[0]?.message).toMatch(/\[1\]/);
-      expect(findings[0]?.message).toMatch(/type|label|default/);
-    });
-
-    it("warns when a declaration uses an unknown type", async () => {
-      const html = `<html data-composition-variables='[{"id":"x","type":"date","label":"X","default":"y"}]'><body><div data-composition-id="x"></div></body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find(
-        (f) => f.code === "invalid_composition_variables_declaration",
-      );
-      expect(finding).toBeDefined();
-      expect(finding?.message).toMatch(/type/);
-    });
-
-    it("does not warn for a fully valid declarations array", async () => {
-      const html = `<html data-composition-variables='[
-        {"id":"title","type":"string","label":"Title","default":"Hello"},
-        {"id":"count","type":"number","label":"Count","default":3},
-        {"id":"theme","type":"enum","label":"Theme","default":"light","options":[{"value":"light","label":"Light"}]}
-      ]'><body><div data-composition-id="x"></div></body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find(
-        (f) => f.code === "invalid_composition_variables_declaration",
-      );
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not warn when data-composition-variables is absent", async () => {
-      const html = `<html><body><div data-composition-id="x"></div></body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find(
-        (f) => f.code === "invalid_composition_variables_declaration",
-      );
-      expect(finding).toBeUndefined();
-    });
-  });
-
-  describe("invalid_parent_traversal_in_asset_path", () => {
-    const RULE_CODE = "invalid_parent_traversal_in_asset_path";
-
-    it("errors when an <img> src uses ../capture/", async () => {
-      const html = `<html><body>
-        <div data-composition-id="x">
-          <img src="../capture/assets/logo.svg" alt="logo">
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-      });
-      const finding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(finding).toBeDefined();
-      expect(finding?.severity).toBe("error");
-      expect(finding?.message).toContain("../capture/");
-    });
-
-    it("errors when a <video> src uses ../assets/ (HF#1698 shape)", async () => {
-      const html = `<html><body>
-        <div data-composition-id="x">
-          <video src="../assets/clip.mp4" muted></video>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-      });
-      const finding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(finding).toBeDefined();
-      expect(finding?.severity).toBe("error");
-      expect(finding?.message).toContain("../assets/");
-    });
-
-    it("errors when a <video> src uses ../../assets/ from a nested compositions/frames/ file", async () => {
-      const html = `<html><body>
-        <div data-composition-id="x">
-          <video src="../../assets/clip.mp4" muted></video>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/frames/scene.html",
-      });
-      const finding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(finding).toBeDefined();
-      expect(finding?.message).toContain("../../assets/");
-    });
-
-    it("errors when a <link> href uses ../fonts/", async () => {
-      const html = `<html><head>
-        <link rel="stylesheet" href="../fonts/brand.css">
-      </head><body>
-        <div data-composition-id="x"></div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-      });
-      const finding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(finding).toBeDefined();
-      expect(finding?.message).toContain("../fonts/");
-    });
-
-    it("errors when a CSS url() uses ../assets/ in a <style> block (counts all occurrences)", async () => {
-      const html = `<html><body>
-        <style>
-          @font-face { font-family: 'Brand'; src: url('../fonts/Brand.woff2'); }
-          .hero { background-image: url('../assets/hero.png'); }
-        </style>
-        <div data-composition-id="x"></div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-      });
-      const finding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(finding).toBeDefined();
-      expect(finding?.message).toContain("2 asset path(s)");
-    });
-
-    it("errors when an inline style url() uses ../assets/", async () => {
-      const html = `<html><body>
-        <div data-composition-id="x">
-          <div style="background-image: url('../assets/hero.png');"></div>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-      });
-      const finding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(finding).toBeDefined();
-      expect(finding?.message).toContain("../assets/");
-    });
-
-    it("does not flag root-relative capture/ paths", async () => {
-      const html = `<html><body>
-        <div data-composition-id="x">
-          <img src="capture/assets/logo.svg" alt="logo">
-        </div>
-        <style>.hero { background-image: url('capture/assets/hero.png'); }</style>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-      });
-      const finding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not flag plain relative asset paths (e.g. assets/x.mp4)", async () => {
-      const html = `<html><body>
-        <div data-composition-id="x">
-          <video src="assets/x.mp4" muted></video>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-      });
-      const finding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not flag absolute URLs", async () => {
-      const html = `<html><body>
-        <div data-composition-id="x">
-          <img src="https://example.com/foo.png">
-          <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
-          <style>.hero { background-image: url('https://example.com/hero.png'); }</style>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-      });
-      const finding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not flag data: URIs", async () => {
-      const html = `<html><body>
-        <div data-composition-id="x">
-          <img src="data:image/png;base64,iVBORw0KGgo=">
-          <style>.hero { background-image: url('data:image/svg+xml,%3Csvg/%3E'); }</style>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-      });
-      const finding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not flag root-relative absolute paths (e.g. /absolute/path.mp4)", async () => {
-      const html = `<html><body>
-        <div data-composition-id="x">
-          <video src="/absolute/path.mp4" muted></video>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-      });
-      const finding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(finding).toBeUndefined();
-    });
-
-    it('does not flag hash refs (e.g. href="#anchor")', async () => {
-      const html = `<html><body>
-        <div data-composition-id="x">
-          <a href="#section">jump</a>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-      });
-      const finding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not flag registry source block files", async () => {
-      const html = `<html><body>
-        <div data-composition-id="x">
-          <img src="../assets/should-be-ignored.png">
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/registry/blocks/data-chart/data-chart.html",
-      });
-      const finding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not flag installed registry blocks", async () => {
-      const html = `<!-- hyperframes-registry-item: data-chart -->\n<html><body>
-        <div data-composition-id="x">
-          <img src="../assets/should-be-ignored.png">
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/data-chart.html",
-      });
-      const finding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(finding).toBeUndefined();
-    });
-
-    it("does not regress under the old code (invalid_capture_path) — the rule was renamed", async () => {
-      const html = `<html><body>
-        <div data-composition-id="x">
-          <img src="../capture/assets/logo.svg" alt="logo">
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        filePath: "/project/compositions/scene.html",
-      });
-      // The old code is gone; the new code subsumes it.
-      const oldFinding = result.findings.find((f) => f.code === "invalid_capture_path");
-      expect(oldFinding).toBeUndefined();
-      const newFinding = result.findings.find((f) => f.code === RULE_CODE);
-      expect(newFinding).toBeDefined();
-    });
-  });
-
-  describe("subcomposition_blanks_before_host", () => {
-    const find = (findings: Array<{ code: string }>) =>
-      findings.find((f) => f.code === "subcomposition_blanks_before_host");
-
-    it("fires on the issue #1540 shape (child shorter than host)", async () => {
-      const html = `<html><body>
-        <div id="root" data-composition-id="main" data-start="0" data-duration="331.224" data-width="1920" data-height="1080">
-          <div id="decision-tree-comp" data-composition-id="decision-tree" data-composition-src="compositions/decision_tree.html" data-start="0" data-duration="15"></div>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      const finding = find(result.findings);
-      expect(finding).toBeDefined();
-      expect(finding?.severity).toBe("warning");
-      expect(finding?.message).toContain("blank");
-      expect(finding?.message).toContain("331.224");
-    });
-
-    it("fires when the mount starts within the start tolerance", async () => {
-      const html = `<html><body>
-        <div id="root" data-composition-id="main" data-start="0" data-duration="60">
-          <div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0.3" data-duration="15"></div>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      expect(find(result.findings)).toBeDefined();
-    });
-
-    it("fires at exactly the start tolerance boundary (start=0.5)", async () => {
-      const html = `<html><body>
-        <div id="root" data-composition-id="main" data-start="0" data-duration="60">
-          <div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0.5" data-duration="15"></div>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      expect(find(result.findings)).toBeDefined();
-    });
-
-    it("stays silent on an intentional short intro followed by another clip", async () => {
-      const html = `<html><body>
-        <div id="root" data-composition-id="main" data-start="0" data-duration="60">
-          <div data-composition-id="intro" data-composition-src="compositions/intro.html" data-start="0" data-duration="15"></div>
-          <div data-composition-id="body" data-composition-src="compositions/body.html" data-start="15" data-duration="45"></div>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      expect(find(result.findings)).toBeUndefined();
-    });
-
-    it("stays silent when the child matches the host window", async () => {
-      const html = `<html><body>
-        <div id="root" data-composition-id="main" data-start="0" data-duration="15">
-          <div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0" data-duration="15"></div>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      expect(find(result.findings)).toBeUndefined();
-    });
-
-    it("stays silent when the child is longer than the host", async () => {
-      const html = `<html><body>
-        <div id="root" data-composition-id="main" data-start="0" data-duration="15">
-          <div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0" data-duration="30"></div>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      expect(find(result.findings)).toBeUndefined();
-    });
-
-    it("stays silent for a non-sub-composition timed element", async () => {
-      const html = `<html><body>
-        <div id="root" data-composition-id="main" data-start="0" data-duration="60">
-          <div class="clip" data-start="0" data-duration="15"></div>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      expect(find(result.findings)).toBeUndefined();
-    });
-
-    it("stays silent when the root has no numeric data-duration", async () => {
-      const html = `<html><body>
-        <div id="root" data-composition-id="main" data-start="0">
-          <div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0" data-duration="15"></div>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      expect(find(result.findings)).toBeUndefined();
-    });
-
-    it("stays silent for a late-starting clip", async () => {
-      const html = `<html><body>
-        <div id="root" data-composition-id="main" data-start="0" data-duration="60">
-          <div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="40" data-duration="5"></div>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      expect(find(result.findings)).toBeUndefined();
-    });
-
-    it("stays silent when an unknown-duration sibling covers the tail", async () => {
-      const html = `<html><body>
-        <div id="root" data-composition-id="main" data-start="0" data-duration="60">
-          <div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0" data-duration="15"></div>
-          <div class="clip" data-start="0"></div>
-        </div>
-      </body></html>`;
-      const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
-      expect(find(result.findings)).toBeUndefined();
-    });
-  });
-});
diff --git a/packages/core/src/lint/rules/composition.ts b/packages/core/src/lint/rules/composition.ts
deleted file mode 100644
index 19e20fd0c3..0000000000
--- a/packages/core/src/lint/rules/composition.ts
+++ /dev/null
@@ -1,723 +0,0 @@
-import type { LintContext, HyperframeLintFinding, ExtractedBlock } from "../context";
-import { findHtmlTag, readAttr, readJsonAttr, stripJsComments, truncateSnippet } from "../utils";
-import { COMPOSITION_VARIABLE_TYPES } from "../../core.types";
-
-// Agent guidance thresholds: warning-only nudges for files/tracks that become hard
-// to inspect and revise reliably in a single composition.
-const MAX_COMPOSITION_LINES = 300;
-const MAX_TIMED_ELEMENTS_PER_TRACK = 3;
-const TRACK_DENSITY_EXEMPT_TAGS = new Set(["audio", "script", "style", "video"]);
-
-function countPhysicalLines(source: string): number {
-  if (source.length === 0) return 0;
-
-  const normalized = source.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-  const withoutFinalNewline = normalized.endsWith("\n") ? normalized.slice(0, -1) : normalized;
-  return withoutFinalNewline.split("\n").length;
-}
-
-function countStructuralLines(source: string): number {
-  return countPhysicalLines(source.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "<style></style>"));
-}
-
-export function isRegistrySourceFile(filePath?: string): boolean {
-  if (!filePath) return false;
-
-  const normalized = filePath.replace(/\\/g, "/");
-  return /(?:^|\/)registry\/blocks\/([^/]+)\/\1\.html$/i.test(normalized);
-}
-
-export function isRegistryInstalledFile(rawSource: string): boolean {
-  return /^\s*<!--\s*hyperframes-registry-item:[^>]*-->/i.test(rawSource.slice(0, 512));
-}
-
-function isCompositionRootOrMount(rawTag: string): boolean {
-  return Boolean(
-    readAttr(rawTag, "data-composition-id") || readAttr(rawTag, "data-composition-src"),
-  );
-}
-
-// Asset references inside CSS `url(...)`/`url("...")`/`url('...')` functions.
-// Returns the inner path without quotes; comments are stripped first so
-// `/* url(foo) */` is ignored. Bare `url()` and `data:` are excluded by the
-// rules that consume this — the helper just yields raw URL values.
-function extractCssUrlReferences(css: string): string[] {
-  const out: string[] = [];
-  const noComments = css.replace(/\/\*[\s\S]*?\*\//g, "");
-  const urlPattern = /\burl\(\s*(["']?)([^)"']+)\1\s*\)/g;
-  let m: RegExpExecArray | null;
-  while ((m = urlPattern.exec(noComments)) !== null) {
-    const raw = (m[2] ?? "").trim();
-    if (raw) out.push(raw);
-  }
-  return out;
-}
-
-// Top-level CSS selectors (comma-split) in a stylesheet, skipping at-rule headers
-// (@media/@keyframes/...) and keyframe stops. Heuristic — the lint layer has no
-// full CSS parser, and rules elsewhere in this file scan CSS the same way.
-function extractCssSelectors(css: string): string[] {
-  const out: string[] = [];
-  const noComments = css.replace(/\/\*[\s\S]*?\*\//g, "");
-  const ruleHeader = /([^{}]+)\{/g;
-  let m: RegExpExecArray | null;
-  while ((m = ruleHeader.exec(noComments)) !== null) {
-    const header = (m[1] ?? "").trim();
-    if (!header || header.startsWith("@")) continue;
-    for (const sel of header.split(",")) {
-      const s = sel.trim();
-      if (s) out.push(s);
-    }
-  }
-  return out;
-}
-
-// Class tokens in a selector's leftmost compound (before the first descendant /
-// child / sibling combinator). `.frame .title` → ["frame"]; `.a.b > .c` → ["a","b"].
-function leftmostCompoundClasses(selector: string): string[] {
-  const leftmost = selector.trim().split(/[\s>+~]+/)[0] ?? "";
-  return (leftmost.match(/\.([\w-]+)/g) ?? []).map((c) => c.slice(1));
-}
-
-// Distinct selectors across all <style> blocks whose leftmost compound keys off one
-// of the root element's own classes — the ones that break under id-scoping.
-function rootClassStyledSelectors(styles: ExtractedBlock[], rootClasses: string[]): string[] {
-  const offenders: string[] = [];
-  for (const style of styles) {
-    for (const selector of extractCssSelectors(style.content)) {
-      const hitsRoot = leftmostCompoundClasses(selector).some((c) => rootClasses.includes(c));
-      if (hitsRoot && !offenders.includes(selector)) offenders.push(selector);
-    }
-  }
-  return offenders;
-}
-
-export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
-  // invalid_parent_traversal_in_asset_path — catches `../` traversal in src,
-  // href, inline-style url(), and <style> url() asset references on
-  // compositions. Sub-compositions live under compositions/ but are served
-  // with the project root as their base URL, so any `../`-traversing path
-  // climbs above the project root and 404s in Studio preview. Renders
-  // tolerate it because the server-side bundler rewrites `../foo` against
-  // each sub-composition's source path; the runtime now mirrors that fallback
-  // (see rewriteSubCompositionAssetPaths in runtime/compositionLoader.ts), but
-  // the authoring-time signal is still wrong — flag it at lint time so the
-  // baked path is plain root-relative and matches what the bundler emits.
-  //
-  // Mirrors the runtime fallback's surface: `[src]` / `[href]` attribute
-  // values, `[style]` inline url(), and `<style>` block url() references.
-  // Skips absolute URLs (http(s)://, //, data:, /-prefixed root-relative),
-  // hash anchors, and plain relative paths (`assets/x.mp4`) — only `../`
-  // traversal is flagged. Subsumes the older `../capture/`-specific rule.
-  // fallow-ignore-next-line complexity
-  ({ tags, styles, rawSource, options }) => {
-    if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
-
-    const offenders: string[] = [];
-    const collect = (value: string | null) => {
-      if (!value) return;
-      const trimmed = value.trim();
-      if (!trimmed.startsWith("../") && trimmed !== "..") return;
-      offenders.push(trimmed);
-    };
-
-    for (const tag of tags) {
-      collect(readAttr(tag.raw, "src"));
-      collect(readAttr(tag.raw, "href"));
-      // Use readJsonAttr for `style` — inline url('...') values contain the
-      // opposite quote, which readAttr's [^"']+ class would truncate.
-      const styleAttr = readJsonAttr(tag.raw, "style");
-      if (styleAttr) {
-        for (const url of extractCssUrlReferences(styleAttr)) collect(url);
-      }
-    }
-    for (const style of styles) {
-      for (const url of extractCssUrlReferences(style.content)) collect(url);
-    }
-
-    if (offenders.length === 0) return [];
-
-    // Group counts by leading path token (e.g. ../capture/, ../assets/, ../../assets/)
-    // so the message names the offending prefixes instead of a bare count.
-    const prefixCounts = new Map<string, number>();
-    for (const path of offenders) {
-      const prefix = path.match(/^(?:\.\.\/)+[^/]+\//)?.[0] ?? path;
-      prefixCounts.set(prefix, (prefixCounts.get(prefix) ?? 0) + 1);
-    }
-    const prefixSummary = Array.from(prefixCounts.entries())
-      .sort(([, a], [, b]) => b - a)
-      .map(([prefix, count]) => (count > 1 ? `${prefix} (${count})` : prefix))
-      .join(", ");
-
-    return [
-      {
-        code: "invalid_parent_traversal_in_asset_path",
-        severity: "error",
-        message:
-          `Found ${offenders.length} asset path(s) traversing above the project root with "../" ` +
-          `(${prefixSummary}). Renders rewrite this against each sub-composition's source path, but Studio preview and other live consumers resolve against the project root and 404.`,
-        fixHint:
-          'Use plain root-relative paths (e.g. "assets/...", "capture/...", "fonts/...") — compositions are served with the project root as their base URL, so paths must be root-relative, not relative to the compositions/ directory.',
-      },
-    ];
-  },
-
-  // composition_file_too_large
-  ({ rawSource, options }) => {
-    if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
-
-    const lineCount = countStructuralLines(rawSource);
-    if (lineCount <= MAX_COMPOSITION_LINES) return [];
-
-    const splitTarget = options.isSubComposition
-      ? "Split this sub-composition further into smaller .html files"
-      : "Split coherent scenes or layers into separate .html files under compositions/";
-
-    return [
-      {
-        code: "composition_file_too_large",
-        severity: "warning",
-        message: `This HTML composition file has ${lineCount} lines. Smaller sub-compositions are easier to read, iterate on, and diff.`,
-        fixHint: `${splitTarget}, then mount them from the parent with data-composition-src so each file stays small enough to inspect, revise, and validate independently.`,
-      },
-    ];
-  },
-
-  // timeline_track_too_dense
-  // fallow-ignore-next-line complexity
-  ({ tags, options }) => {
-    const trackCounts = new Map<string, number>();
-    for (const tag of tags) {
-      if (TRACK_DENSITY_EXEMPT_TAGS.has(tag.name)) continue;
-      if (isCompositionRootOrMount(tag.raw)) continue;
-      if (!readAttr(tag.raw, "data-start")) continue;
-
-      const track = readAttr(tag.raw, "data-track-index");
-      if (!track) continue;
-      trackCounts.set(track, (trackCounts.get(track) ?? 0) + 1);
-    }
-
-    const findings: HyperframeLintFinding[] = [];
-    for (const [track, count] of trackCounts) {
-      if (count <= MAX_TIMED_ELEMENTS_PER_TRACK) continue;
-      const splitTarget = options.isSubComposition
-        ? "Move coherent scene groups into smaller .html files"
-        : "Move coherent scene groups into separate .html files under compositions/";
-      findings.push({
-        code: "timeline_track_too_dense",
-        severity: "warning",
-        message: `Track ${track} has ${count} timed elements in this HTML file. Smaller sub-compositions keep timelines easier to read, iterate on, and diff.`,
-        fixHint: `${splitTarget} and mount them from the parent with data-composition-src so the timeline stays easier to inspect, revise, and validate.`,
-      });
-    }
-
-    return findings;
-  },
-
-  // timed_element_missing_visibility_hidden
-  // fallow-ignore-next-line complexity
-  ({ tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const tag of tags) {
-      if (tag.name === "audio" || tag.name === "script" || tag.name === "style") continue;
-      if (!readAttr(tag.raw, "data-start")) continue;
-      if (readAttr(tag.raw, "data-composition-id")) continue;
-      if (readAttr(tag.raw, "data-composition-src")) continue;
-      const classAttr = readAttr(tag.raw, "class") || "";
-      const styleAttr = readAttr(tag.raw, "style") || "";
-      const hasClip = classAttr.split(/\s+/).includes("clip");
-      const hasHiddenStyle =
-        /visibility\s*:\s*hidden/i.test(styleAttr) || /opacity\s*:\s*0/i.test(styleAttr);
-      if (!hasClip && !hasHiddenStyle) {
-        const elementId = readAttr(tag.raw, "id") || undefined;
-        findings.push({
-          code: "timed_element_missing_visibility_hidden",
-          severity: "info",
-          message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has data-start but no class="clip", visibility:hidden, or opacity:0. Consider adding initial hidden state if the element should not be visible before its start time.`,
-          elementId,
-          fixHint:
-            'Add class="clip" (with CSS: .clip { visibility: hidden; }) or style="opacity:0" if the element should start hidden.',
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-    }
-    return findings;
-  },
-
-  // deprecated_data_layer + deprecated_data_end
-  // fallow-ignore-next-line complexity
-  ({ tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const tag of tags) {
-      if (readAttr(tag.raw, "data-layer") && !readAttr(tag.raw, "data-track-index")) {
-        const elementId = readAttr(tag.raw, "id") || undefined;
-        findings.push({
-          code: "deprecated_data_layer",
-          severity: "error",
-          message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses data-layer instead of data-track-index.`,
-          elementId,
-          fixHint: "Replace data-layer with data-track-index. The runtime reads data-track-index.",
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-      if (readAttr(tag.raw, "data-end") && !readAttr(tag.raw, "data-duration")) {
-        const elementId = readAttr(tag.raw, "id") || undefined;
-        findings.push({
-          code: "deprecated_data_end",
-          severity: "error",
-          message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses data-end without data-duration. Use data-duration in source HTML.`,
-          elementId,
-          fixHint:
-            "Replace data-end with data-duration. The compiler generates data-end from data-duration automatically.",
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-    }
-    return findings;
-  },
-
-  // split_data_attribute_selector
-  ({ scripts, styles }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const splitDataAttrSelectorPattern =
-      /\[data-composition-id=(["'])([^"'\]]+)\1\s+(data-[\w:-]+)=(["'])([^"'\]]*)\4\]/g;
-    const scan = (content: string) => {
-      splitDataAttrSelectorPattern.lastIndex = 0;
-      let match: RegExpExecArray | null;
-      while ((match = splitDataAttrSelectorPattern.exec(content)) !== null) {
-        const compId = match[2] ?? "";
-        const attrName = match[3] ?? "";
-        const attrValue = match[5] ?? "";
-        findings.push({
-          code: "split_data_attribute_selector",
-          severity: "error",
-          message:
-            `Selector "${match[0]}" combines two attributes inside one CSS attribute selector. ` +
-            "Browsers reject it, so GSAP timelines or querySelector calls will fail before registering.",
-          selector: match[0],
-          fixHint: `Use separate attribute selectors: [data-composition-id="${compId}"][${attrName}="${attrValue}"].`,
-          snippet: truncateSnippet(match[0]),
-        });
-      }
-    };
-    for (const style of styles) scan(style.content);
-    for (const script of scripts) scan(script.content);
-    return findings;
-  },
-
-  // template_literal_selector
-  ({ scripts }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const script of scripts) {
-      const templateLiteralSelectorPattern =
-        /(?:querySelector|querySelectorAll)\s*\(\s*`[^`]*\$\{[^}]+\}[^`]*`\s*\)/g;
-      let tlMatch: RegExpExecArray | null;
-      while ((tlMatch = templateLiteralSelectorPattern.exec(script.content)) !== null) {
-        findings.push({
-          code: "template_literal_selector",
-          severity: "error",
-          message:
-            "querySelector uses a template literal variable (e.g. `${compId}`). " +
-            "The HTML bundler's CSS parser crashes on these. Use a hardcoded string instead.",
-          fixHint:
-            "Replace the template literal variable with a hardcoded string. The bundler's CSS parser cannot handle interpolated variables in script content.",
-          snippet: truncateSnippet(tlMatch[0]),
-        });
-      }
-    }
-    return findings;
-  },
-
-  // timed_element_missing_clip_class
-  // fallow-ignore-next-line complexity
-  ({ tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const skipTags = new Set(["audio", "video", "script", "style", "template"]);
-    for (const tag of tags) {
-      if (skipTags.has(tag.name)) continue;
-      // Skip composition hosts
-      if (readAttr(tag.raw, "data-composition-id")) continue;
-      if (readAttr(tag.raw, "data-composition-src")) continue;
-
-      const hasStart = readAttr(tag.raw, "data-start") !== null;
-      const hasDuration = readAttr(tag.raw, "data-duration") !== null;
-      // data-track-index alone marks a layer container, not a time-bounded clip
-      if (!hasStart && !hasDuration) continue;
-
-      const classAttr = readAttr(tag.raw, "class") || "";
-      const hasClip = classAttr.split(/\s+/).includes("clip");
-      if (hasClip) continue;
-
-      const elementId = readAttr(tag.raw, "id") || undefined;
-      findings.push({
-        code: "timed_element_missing_clip_class",
-        severity: "error",
-        message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has timing attributes but no class="clip". The element will be visible for the entire composition instead of only during its scheduled time range.`,
-        elementId,
-        fixHint:
-          'Add class="clip" to the element. The HyperFrames runtime uses .clip to control visibility based on data-start/data-duration.',
-        snippet: truncateSnippet(tag.raw),
-      });
-    }
-    return findings;
-  },
-
-  // overlapping_clips_same_track
-  // fallow-ignore-next-line complexity
-  ({ tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-
-    type ClipInfo = { start: number; end: number; elementId?: string; snippet: string };
-    const trackMap = new Map<string, ClipInfo[]>();
-
-    for (const tag of tags) {
-      const startStr = readAttr(tag.raw, "data-start");
-      const durationStr = readAttr(tag.raw, "data-duration");
-      const trackStr = readAttr(tag.raw, "data-track-index");
-      if (!startStr || !durationStr || !trackStr) continue;
-
-      const start = Number(startStr);
-      const duration = Number(durationStr);
-      const track = trackStr;
-
-      // Skip non-numeric (relative timing references like "intro-comp")
-      if (Number.isNaN(start) || Number.isNaN(duration)) continue;
-
-      const clips = trackMap.get(track) || [];
-      clips.push({
-        start,
-        end: start + duration,
-        elementId: readAttr(tag.raw, "id") || undefined,
-        snippet: truncateSnippet(tag.raw) || "",
-      });
-      trackMap.set(track, clips);
-    }
-
-    for (const [track, clips] of trackMap) {
-      clips.sort((a, b) => a.start - b.start);
-      for (let i = 0; i < clips.length - 1; i++) {
-        const current = clips[i];
-        const next = clips[i + 1];
-        if (!current || !next) continue;
-        if (current.end > next.start) {
-          findings.push({
-            code: "overlapping_clips_same_track",
-            severity: "error",
-            message: `Track ${track}: clip ending at ${current.end}s overlaps with clip starting at ${next.start}s. Overlapping clips on the same track cause rendering conflicts.`,
-            fixHint:
-              "Adjust data-start or data-duration so clips on the same track do not overlap, or move one clip to a different data-track-index.",
-          });
-        }
-      }
-    }
-
-    return findings;
-  },
-
-  // root_composition_missing_data_start
-  ({ rootTag, options }) => {
-    const findings: HyperframeLintFinding[] = [];
-    if (options.isSubComposition) return findings;
-    if (!rootTag) return findings;
-    const compId = readAttr(rootTag.raw, "data-composition-id");
-    if (!compId) return findings;
-    const hasStart = readAttr(rootTag.raw, "data-start") !== null;
-    if (!hasStart) {
-      findings.push({
-        code: "root_composition_missing_data_start",
-        severity: "error",
-        message: `Root composition "${compId}" is missing data-start. The runtime needs data-start="0" on the root element to begin playback.`,
-        fixHint: 'Add data-start="0" to the root composition element.',
-        snippet: truncateSnippet(rootTag.raw),
-      });
-    }
-    return findings;
-  },
-
-  // standalone_composition_wrapped_in_template
-  ({ rawSource, options }) => {
-    const findings: HyperframeLintFinding[] = [];
-    if (options.isSubComposition) return findings;
-    const trimmed = rawSource.trimStart().toLowerCase();
-    if (trimmed.startsWith("<template")) {
-      findings.push({
-        code: "standalone_composition_wrapped_in_template",
-        severity: "error",
-        message:
-          "Root index.html is wrapped in a <template> tag. " +
-          "Only sub-compositions loaded via data-composition-src should use <template> wrappers. " +
-          "The runtime cannot play a standalone composition inside a template.",
-        fixHint:
-          "Remove the <template> wrapper. Use <!DOCTYPE html><html>...<div data-composition-id>...</div>...</html> instead.",
-      });
-    }
-    return findings;
-  },
-
-  // root_composition_missing_html_wrapper
-  ({ rawSource, rootTag, options }) => {
-    const findings: HyperframeLintFinding[] = [];
-    if (options.isSubComposition) return findings;
-    const trimmed = rawSource.trimStart().toLowerCase();
-    // Compositions inside <template> are caught by standalone_composition_wrapped_in_template
-    if (trimmed.startsWith("<template")) return findings;
-    const hasDoctype = trimmed.startsWith("<!doctype") || trimmed.startsWith("<html");
-    const hasComposition = rawSource.includes("data-composition-id");
-    if (hasComposition && !hasDoctype) {
-      findings.push({
-        code: "root_composition_missing_html_wrapper",
-        severity: "error",
-        message:
-          "Composition starts with a bare element instead of a proper HTML document. " +
-          "An index.html that contains data-composition-id but no <!DOCTYPE html>, <html>, or <body> " +
-          "is a fragment — browsers quirks-mode it, the preview server cannot load it, and " +
-          "the bundler will fail to inject runtime scripts.",
-        fixHint:
-          'Wrap the composition in <!DOCTYPE html><html><head><meta charset="UTF-8"></head><body>...</body></html>.',
-        snippet: rootTag ? truncateSnippet(rootTag.raw) : undefined,
-      });
-    }
-    return findings;
-  },
-
-  // requestanimationframe_in_composition
-  ({ scripts, rawSource, options }) => {
-    if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
-    const findings: HyperframeLintFinding[] = [];
-    for (const script of scripts) {
-      const stripped = stripJsComments(script.content);
-      if (/requestAnimationFrame\s*\(/.test(stripped)) {
-        findings.push({
-          code: "requestanimationframe_in_composition",
-          severity: "error",
-          message:
-            "`requestAnimationFrame` runs on wall-clock time, not the GSAP timeline. It will not sync with frame capture and may cause flickering or missed frames during rendering.",
-          fixHint:
-            "Use GSAP tweens or onUpdate callbacks instead of requestAnimationFrame for animation logic.",
-          snippet: truncateSnippet(script.content),
-        });
-      }
-    }
-    return findings;
-  },
-
-  // invalid_variable_values_json
-  // Host elements (`[data-composition-src]`) carry per-instance values via
-  // `data-variable-values`. The runtime swallows JSON errors silently and
-  // falls back to declared defaults, which masks typos. This rule surfaces
-  // the parse failure so authors notice before render time.
-  // fallow-ignore-next-line complexity
-  ({ tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const tag of tags) {
-      const raw = readJsonAttr(tag.raw, "data-variable-values");
-      if (!raw) continue;
-
-      let parsed: unknown;
-      try {
-        parsed = JSON.parse(raw);
-      } catch (err) {
-        const reason = err instanceof Error ? err.message : "unknown";
-        findings.push({
-          code: "invalid_variable_values_json",
-          severity: "error",
-          message: `data-variable-values is not valid JSON (${reason}).`,
-          fixHint:
-            'Wrap the attribute value in single quotes and the JSON keys/values in double quotes, e.g. data-variable-values=\'{"title":"Hello"}\'.',
-          elementId: readAttr(tag.raw, "id") || undefined,
-          snippet: truncateSnippet(tag.raw),
-        });
-        continue;
-      }
-
-      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        findings.push({
-          code: "invalid_variable_values_json",
-          severity: "error",
-          message:
-            'data-variable-values must be a JSON object keyed by variable id (e.g. {"title":"Hello"}).',
-          fixHint:
-            "Replace the value with a JSON object whose keys are variable ids declared in the sub-composition's data-composition-variables.",
-          elementId: readAttr(tag.raw, "id") || undefined,
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-    }
-    return findings;
-  },
-
-  // invalid_composition_variables_declaration
-  // The runtime parses `data-composition-variables` and silently returns []
-  // on any structural problem. Surface JSON / shape failures so authors
-  // catch them at lint time rather than wondering why their `getVariables()`
-  // defaults aren't applied.
-  // fallow-ignore-next-line complexity
-  ({ source }) => {
-    const htmlTag = findHtmlTag(source);
-    if (!htmlTag) return [];
-    const raw = readJsonAttr(htmlTag.raw, "data-composition-variables");
-    if (!raw) return [];
-
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(raw);
-    } catch (err) {
-      const reason = err instanceof Error ? err.message : "unknown";
-      return [
-        {
-          code: "invalid_composition_variables_declaration",
-          severity: "error",
-          message: `data-composition-variables is not valid JSON (${reason}).`,
-          fixHint:
-            'Provide a JSON array of variable declarations: data-composition-variables=\'[{"id":"title","type":"string","label":"Title","default":"Hello"}]\'.',
-          snippet: truncateSnippet(htmlTag.raw),
-        },
-      ];
-    }
-
-    if (!Array.isArray(parsed)) {
-      return [
-        {
-          code: "invalid_composition_variables_declaration",
-          severity: "error",
-          message: "data-composition-variables must be a JSON array of variable declarations.",
-          fixHint:
-            'Wrap declarations in [] and give each an id, type, label, and default: \'[{"id":"title","type":"string","label":"Title","default":"Hello"}]\'.',
-          snippet: truncateSnippet(htmlTag.raw),
-        },
-      ];
-    }
-
-    const findings: HyperframeLintFinding[] = [];
-    const knownTypes = new Set<string>(COMPOSITION_VARIABLE_TYPES);
-    for (let i = 0; i < parsed.length; i += 1) {
-      const entry = parsed[i];
-      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-        findings.push({
-          code: "invalid_composition_variables_declaration",
-          severity: "error",
-          message: `data-composition-variables entry [${i}] must be an object with id, type, label, and default.`,
-          snippet: truncateSnippet(htmlTag.raw),
-        });
-        continue;
-      }
-      const e = entry as Record<string, unknown>;
-      const missing: string[] = [];
-      if (typeof e.id !== "string") missing.push("id");
-      if (typeof e.type !== "string" || !knownTypes.has(e.type)) missing.push("type");
-      if (typeof e.label !== "string") missing.push("label");
-      if (!("default" in e)) missing.push("default");
-      if (missing.length > 0) {
-        findings.push({
-          code: "invalid_composition_variables_declaration",
-          severity: "error",
-          message: `data-composition-variables entry [${i}] is missing or has invalid: ${missing.join(", ")}. Type must be one of string, number, color, boolean, enum, font, image.`,
-          snippet: truncateSnippet(htmlTag.raw),
-        });
-      }
-    }
-    return findings;
-  },
-
-  // subcomposition_blanks_before_host
-  // Warns when a full-bleed sub-composition slot ends before the host composition
-  // does, leaving the slot blank for the remainder (issue #1540). Scoped narrowly to
-  // the high-signal shape — a sole/dominant external mount starting at ~0 — so it
-  // stays silent on intentional short clips (an intro followed by other clips that
-  // carry the timeline forward).
-  // fallow-ignore-next-line complexity
-  ({ tags, rootTag }) => {
-    if (!rootTag) return [];
-    const rootDuration = Number(readAttr(rootTag.raw, "data-duration"));
-    if (!Number.isFinite(rootDuration) || rootDuration <= 0) return [];
-
-    // Two independent knobs that happen to share a 0.5s magnitude. Tuned for
-    // real hosts (tens to hundreds of seconds); on a very short host (~6s) the
-    // EPSILON slack would let a ~10% blank tail pass unflagged — acceptable
-    // because the silent-blank trap this rule targets only matters at scale.
-    const EPSILON = 0.5; // seconds; tolerance for "ends/covers near the host end"
-    const START_TOLERANCE = 0.5; // seconds; "starts at the composition start"
-    const round3 = (n: number) => Math.round(n * 1000) / 1000;
-
-    // Timed children of the root. An element with data-start but no usable
-    // data-duration is treated as covering the tail (end = Infinity), so an
-    // unknown-length sibling suppresses the warning rather than triggering it.
-    const timed = tags
-      .filter((tag) => tag.index !== rootTag.index && readAttr(tag.raw, "data-start") !== null)
-      .map((tag) => {
-        const start = Number(readAttr(tag.raw, "data-start")) || 0;
-        const dur = Number(readAttr(tag.raw, "data-duration"));
-        const end = Number.isFinite(dur) && dur > 0 ? start + dur : Infinity;
-        return { tag, start, end };
-      });
-
-    // `tags` is a flat list (no nesting depth), so a timed element nested
-    // *inside* a candidate slot is treated as a tail-covering sibling rather
-    // than a descendant. Acceptable: external src mounts are empty by
-    // convention (content is loaded from the linked file), so the only
-    // false-negative path is rare and matches the flat-tag scope of the
-    // sibling rules in this file.
-    const tailCovered = (exceptIndex: number) =>
-      timed.some((t) => t.tag.index !== exceptIndex && t.end >= rootDuration - EPSILON);
-
-    const findings: HyperframeLintFinding[] = [];
-    for (const t of timed) {
-      if (readAttr(t.tag.raw, "data-composition-src") === null) continue; // external slot only
-      if (t.start > START_TOLERANCE) continue; // must start at the composition start
-      if (!Number.isFinite(t.end)) continue; // known, finite slot length
-      if (t.end >= rootDuration - EPSILON) continue; // already fills the host window
-      if (tailCovered(t.tag.index)) continue; // another clip covers the tail — not full-bleed
-      const elementId = readAttr(t.tag.raw, "id") || undefined;
-      const gap = round3(rootDuration - t.end);
-      findings.push({
-        code: "subcomposition_blanks_before_host",
-        severity: "warning",
-        message: `<${t.tag.name}${elementId ? ` id="${elementId}"` : ""}> sub-composition ends at ${round3(t.end)}s but the composition runs to ${round3(rootDuration)}s — its slot will be blank for ~${gap}s.`,
-        elementId,
-        fixHint: `data-duration is the slot's visible window. Set this sub-composition's data-duration to ${round3(rootDuration - t.start)} to fill the host window, or add another clip to cover the remaining ~${gap}s.`,
-        snippet: truncateSnippet(t.tag.raw),
-      });
-    }
-    return findings;
-  },
-
-  // subcomposition_root_styled_by_class
-  // A sub-composition's <style> is scoped at render time to
-  // `[data-composition-id="<id>"] <selector>` so scenes inlined into one document
-  // can't leak styles into each other. A rule whose LEFTMOST selector is the ROOT
-  // element's own class (e.g. `.frame { ... }` on the same element that carries
-  // data-composition-id) therefore becomes a DESCENDANT selector that can never
-  // match the root — the whole scene renders unstyled (tiny text top-left, images
-  // at natural size). lint/validate/inspect evaluate the file in isolation (no
-  // scoping) and Studio previews each scene in its own iframe (no scoping), so the
-  // break is invisible until the composited MP4 render. Style the root via `#root`
-  // (the scoper special-cases the root id) and descendants via plain selectors,
-  // like the registry blocks — the runtime already scopes each scene by id, so a
-  // class namespace on the root is redundant.
-  ({ rootTag, rootCompositionId, styles, options }) => {
-    if (!options.isSubComposition) return [];
-    if (isRegistrySourceFile(options.filePath)) return [];
-    if (!rootTag || !rootCompositionId) return [];
-
-    const rootClasses = (readAttr(rootTag.raw, "class") || "").split(/\s+/).filter(Boolean);
-    if (rootClasses.length === 0) return [];
-
-    const offenders = rootClassStyledSelectors(styles, rootClasses);
-    if (offenders.length === 0) return [];
-
-    const example = offenders.slice(0, 3).join(", ");
-    return [
-      {
-        code: "subcomposition_root_styled_by_class",
-        severity: "error",
-        message:
-          `Root element has class="${rootClasses.join(" ")}" and is styled by ${offenders.length} rule(s) keyed off that class (e.g. ${example}). ` +
-          `At render, every sub-composition rule is scoped to [data-composition-id="${rootCompositionId}"] <selector>, so a selector whose leftmost part is the ROOT's own class becomes a descendant selector that cannot match the root — the scene renders unstyled (tiny text top-left, full-size images). ` +
-          `lint/validate/inspect and Studio's per-frame iframe preview do not scope, so this passes every static check and looks correct in preview.`,
-        selector: example,
-        fixHint: `Give the root id="root" and style it with \`#root { ... }\` plus plain descendant selectors (\`.kicker\`, \`#hero\`) — the runtime already scopes each sub-composition by data-composition-id, so a class namespace on the root is redundant and breaks under scoping.`,
-        snippet: truncateSnippet(rootTag.raw),
-      },
-    ];
-  },
-];
diff --git a/packages/core/src/lint/rules/core.test.ts b/packages/core/src/lint/rules/core.test.ts
deleted file mode 100644
index e30f8f74b1..0000000000
--- a/packages/core/src/lint/rules/core.test.ts
+++ /dev/null
@@ -1,730 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { lintHyperframeHtml } from "../hyperframeLinter.js";
-
-function compositionWithHead(headContent: string): string {
-  return `
-<html>
-<head>
-${headContent}
-</head>
-<body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
-  <script>window.__timelines = {};</script>
-</body>
-</html>`;
-}
-
-function compositionWithHeadBoundary(boundaryContent: string): string {
-  return `
-<html>
-<head>
-  <style>
-    body { margin: 0; }
-  </style>
-</head>
-${boundaryContent}
-<body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
-  <script>window.__timelines = {};</script>
-</body>
-</html>`;
-}
-
-function compositionWithBodyPrefix(prefixContent: string, rootContent = ""): string {
-  return `
-<html>
-<head>
-  <style>
-    body { margin: 0; }
-  </style>
-</head>
-<body>
-${prefixContent}
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-${rootContent}
-  </div>
-  <script>window.__timelines = {};</script>
-</body>
-</html>`;
-}
-
-function compositionWithImplicitBodyPrefix(prefixContent: string): string {
-  return `
-<html>
-<head>
-  <style>
-    body { margin: 0; }
-  </style>
-</head>
-${prefixContent}
-<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
-<script>window.__timelines = {};</script>
-</html>`;
-}
-
-function templateCompositionWithHead(headContent: string): string {
-  return `
-<template>
-  <html>
-    <head>
-${headContent}
-    </head>
-    <body>
-      <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
-    </body>
-  </html>
-</template>`;
-}
-
-describe("core rules", () => {
-  it("reports error when root is missing data-composition-id", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-width="1920" data-height="1080"></div>
-  <script>window.__timelines = {};</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "root_missing_composition_id");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-  });
-
-  it("reports error when root is missing data-width or data-height", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1"></div>
-  <script>window.__timelines = {};</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "root_missing_dimensions");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-  });
-
-  it("accepts body as the composition root", async () => {
-    const html = `
-<html><body data-composition-id="c1" data-width="1920" data-height="1080">
-  <div id="overlay-flash"></div>
-  <script>window.__timelines = window.__timelines || {};</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    expect(result.findings.find((f) => f.code === "root_missing_composition_id")).toBeUndefined();
-    expect(result.findings.find((f) => f.code === "root_missing_dimensions")).toBeUndefined();
-  });
-
-  it("reports error when timeline registry is missing", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080"></div>
-  <script>
-    const tl = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "missing_timeline_registry");
-    expect(finding).toBeDefined();
-  });
-
-  it("does not flag missing_timeline_registry on a sub-composition (inherits from host)", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080"></div>
-  <script>
-    const tl = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html, { isSubComposition: true });
-    const finding = result.findings.find((f) => f.code === "missing_timeline_registry");
-    expect(finding).toBeUndefined();
-  });
-
-  it("reports error for composition host missing data-composition-id", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="host1" data-composition-src="child.html"></div>
-  </div>
-  <script>window.__timelines = {};</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "host_missing_composition_id");
-    expect(finding).toBeDefined();
-  });
-
-  it("reports error when timeline registry is assigned without initializing", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="stage"></div>
-  </div>
-  <script>
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#stage", { opacity: 1, duration: 1 }, 0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "timeline_registry_missing_init");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.message).toContain("without initializing");
-  });
-
-  it("reports error when dot timeline registry is assigned without initializing", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="stage"></div>
-  </div>
-  <script>
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#stage", { opacity: 1, duration: 1 }, 0);
-    window.__timelines.c1 = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "timeline_registry_missing_init");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-  });
-
-  it("does not flag timeline assignment when init guard is present", async () => {
-    const validComposition = `
-<html>
-<body>
-  <div id="root" data-composition-id="comp-1" data-width="1920" data-height="1080">
-    <div id="stage"></div>
-  </div>
-  <script src="https://cdn.gsap.com/gsap.min.js"></script>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#stage", { opacity: 1, duration: 1 }, 0);
-    window.__timelines["comp-1"] = tl;
-  </script>
-</body>
-</html>`;
-    const result = await lintHyperframeHtml(validComposition);
-    const finding = result.findings.find((f) => f.code === "timeline_registry_missing_init");
-    expect(finding).toBeUndefined();
-  });
-
-  it("reports error when CSS text is left outside a style block in the document head", async () => {
-    const html = compositionWithHead(`
-  <style>
-    body { margin: 0; }
-  </style>
-  </style>
-  /* Decorative Elements */
-  .particle {
-    position: absolute;
-    width: 4px;
-    height: 4px;
-    background: #fff;
-  }
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.message).toContain("<head>");
-    expect(finding?.snippet).toContain(".particle");
-  });
-
-  it("reports error when CSS variables leak between head and body", async () => {
-    const html = compositionWithHeadBoundary(`
-  --bg-color: #F5F1E8;
-  --text-color: #212121;
-}
-
-body {
-  background-color: var(--bg-color);
-  color: var(--text-color);
-}
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.message).toContain("<head>");
-    expect(finding?.snippet).toContain("body");
-  });
-
-  it("reports error when stray close tags leak between head and body", async () => {
-    const html = compositionWithHeadBoundary(`
-  </style>
-  </script>
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.snippet).toContain("</style>");
-  });
-
-  it("reports error when markdown code fences leak between head and body", async () => {
-    const html = compositionWithHeadBoundary(`
-  \`\`\`css
-  .particle {
-    color: white;
-  }
-  \`\`\`
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.snippet).toContain("```css");
-  });
-
-  it("reports error when CSS at-rules leak between head and body", async () => {
-    const html = compositionWithHeadBoundary(`
-  @media (min-width: 800px) {
-    .particle {
-      transform: scale(1.2);
-    }
-  }
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.snippet).toContain("@media");
-  });
-
-  it("does not report leaked text for valid script and style blocks around the head boundary", async () => {
-    const html = compositionWithHeadBoundary(`
-  <script>
-    window.__headReady = true;
-  </script>
-  <template>
-    <style>
-      .template-only { color: red; }
-    </style>
-  </template>
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeUndefined();
-  });
-
-  it("reports error when CSS text leaks before the composition root", async () => {
-    const html = compositionWithBodyPrefix(`
-  .orphan {
-    position: absolute;
-    inset: 0;
-  }
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.snippet).toContain(".orphan");
-  });
-
-  it("reports error when CSS text leaks before the composition root without an explicit body", async () => {
-    const html = compositionWithImplicitBodyPrefix(`
-  .implicit-body-orphan {
-    position: absolute;
-    inset: 0;
-  }
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.snippet).toContain(".implicit-body-orphan");
-  });
-
-  it("does not report leaked text for valid script and style blocks before the composition root", async () => {
-    const html = compositionWithBodyPrefix(`
-  <style>
-    .pre-root-helper { color: red; }
-  </style>
-  <script>
-    window.__preRootReady = true;
-  </script>
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeUndefined();
-  });
-
-  it("does not report CSS-looking educational text inside the composition root", async () => {
-    const html = compositionWithBodyPrefix(
-      "",
-      `
-    <pre>
-      body {
-        margin: 0;
-      }
-    </pre>
-`,
-    );
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeUndefined();
-  });
-
-  it("reports error when a stray style close tag is left in the document head", async () => {
-    const html = compositionWithHead(`
-  <style>
-    body { margin: 0; }
-  </style>
-  </style>
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.snippet).toContain("</style>");
-  });
-
-  it("reports error when a stray script close tag is left in the document head", async () => {
-    const html = compositionWithHead(`
-  <script>
-    window.__headReady = true;
-  </script>
-  </script>
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.snippet).toContain("</script>");
-  });
-
-  it("does not report leaked head text for valid closing tags with trailing whitespace", async () => {
-    const html = compositionWithHead(`
-  <style>
-    body { margin: 0; }
-  </style data-parser-error-close>
-  <script>
-    window.__headReady = true;
-  </script
-    data-parser-error-close>
-  <title>Particle Field</title	>
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeUndefined();
-  });
-
-  it("reports error when markdown code fences leak into the document head", async () => {
-    const withLanguage = compositionWithHead(`
-  \`\`\`css
-  .particle {
-    position: absolute;
-  }
-  \`\`\`
-`);
-    const withoutLanguage = compositionWithHead(`
-  \`\`\`
-  .particle {
-    position: absolute;
-  }
-  \`\`\`
-`);
-    const withTsxLanguage = compositionWithHead(`
-  \`\`\`tsx
-  export function Particle() {
-    return <div className="particle" />;
-  }
-  \`\`\`
-`);
-    const withLanguageResult = await lintHyperframeHtml(withLanguage);
-    const withoutLanguageResult = await lintHyperframeHtml(withoutLanguage);
-    const withTsxLanguageResult = await lintHyperframeHtml(withTsxLanguage);
-    const languageFinding = withLanguageResult.findings.find((f) => f.code === "head_leaked_text");
-    const unlabeledFinding = withoutLanguageResult.findings.find(
-      (f) => f.code === "head_leaked_text",
-    );
-    const tsxLanguageFinding = withTsxLanguageResult.findings.find(
-      (f) => f.code === "head_leaked_text",
-    );
-
-    expect(languageFinding).toBeDefined();
-    expect(languageFinding?.snippet).toContain("```css");
-    expect(unlabeledFinding).toBeDefined();
-    expect(unlabeledFinding?.snippet).toContain("```");
-    expect(tsxLanguageFinding).toBeDefined();
-    expect(tsxLanguageFinding?.snippet).toContain("```tsx");
-  });
-
-  it("reports error when CSS at-rules leak into the document head", async () => {
-    const html = compositionWithHead(`
-  @media (min-width: 800px) {
-    .particle {
-      transform: scale(1.2);
-    }
-  }
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.snippet).toContain("@media");
-  });
-
-  it("reports leaked CSS when a style block is unclosed in the document head", async () => {
-    const html = compositionWithHead(`
-  <style>
-    .particle {
-      color: white;
-    }
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.snippet).toContain(".particle");
-  });
-
-  it("does not report leaked head text for commented CSS", async () => {
-    const html = compositionWithHead(`
-  <!-- .particle { color: red; } -->
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeUndefined();
-  });
-
-  it("does not report leaked head text for valid noscript content", async () => {
-    const html = compositionWithHead(`
-  <noscript>
-    .no-js { display: block; }
-  </noscript>
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeUndefined();
-  });
-
-  it("does not report orphan CSS for valid head metadata and style blocks", async () => {
-    const html = compositionWithHead(`
-  <title>Particle Field</title>
-  <meta name="description" content="Particle field">
-  <link rel="preconnect" href="https://fonts.gstatic.com">
-  <base href="https://example.com/">
-  <style>
-    .particle {
-      position: absolute;
-      width: 4px;
-      height: 4px;
-    }
-  </style>
-`);
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeUndefined();
-  });
-
-  it("reports leaked head text inside template-wrapped sub-compositions", async () => {
-    const html = templateCompositionWithHead(`
-      </style>
-      .particle { color: white; }
-`);
-    const result = await lintHyperframeHtml(html, { isSubComposition: true });
-    const finding = result.findings.find((f) => f.code === "head_leaked_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.snippet).toContain(".particle");
-  });
-
-  describe("timeline_id_mismatch", () => {
-    it("accepts dot timeline registration", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="launch" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    window.__timelines.launch = tl;
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "timeline_id_mismatch");
-      expect(finding).toBeUndefined();
-    });
-
-    it("reports mismatched dot timeline registration", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="launch" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    window.__timelines.intro = tl;
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "timeline_id_mismatch");
-      expect(finding).toBeDefined();
-      expect(finding?.message).toContain('Timeline registered as "intro"');
-    });
-
-    it("accepts bracket timeline registration for hyphenated ids", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="product-launch" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    window.__timelines["product-launch"] = tl;
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "timeline_id_mismatch");
-      expect(finding).toBeUndefined();
-    });
-  });
-
-  it("warns when a timeline-visible element has no stable id for Studio editing", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <section class="clip hero-card" data-start="0" data-duration="3"></section>
-  </div>
-  <script>window.__timelines = {};</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "studio_missing_editable_id");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("warning");
-    expect(finding?.message).toContain('<section class="hero-card" data-start="0">');
-    expect(finding?.fixHint).toContain("stable, human-readable id");
-  });
-
-  it("does not warn about the composition root or timeline elements with ids", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0">
-    <section id="hero-card" class="clip hero-card" data-start="0" data-duration="3"></section>
-  </div>
-  <script>window.__timelines = {};</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "studio_missing_editable_id");
-    expect(finding).toBeUndefined();
-  });
-
-  describe("non_deterministic_code", () => {
-    it("detects Math.random() in script content", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const x = Math.random();
-    window.__timelines["c1"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "non_deterministic_code");
-      expect(finding).toBeDefined();
-      expect(finding?.severity).toBe("error");
-      expect(finding?.message).toContain("Math.random");
-    });
-
-    it("detects Date.now() in script content", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const ts = Date.now();
-    window.__timelines["c1"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "non_deterministic_code");
-      expect(finding).toBeDefined();
-      expect(finding?.severity).toBe("error");
-      expect(finding?.message).toContain("Date.now");
-    });
-
-    it("does not flag non-deterministic calls inside single-line comments", async () => {
-      const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    // const x = Math.random();
-    // Date.now() is not used here
-    window.__timelines["c1"] = gsap.timeline({ paused: true });
-  </script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "non_deterministic_code");
-      expect(finding).toBeUndefined();
-    });
-  });
-
-  describe("composition_self_attribute_selector", () => {
-    it("warns when inline CSS targets the root composition id", async () => {
-      const html = `
-<html><body>
-  <div id="scene" data-composition-id="scene" data-width="1920" data-height="1080">
-    <style>
-      [data-composition-id="scene"] .title { opacity: 0; }
-      [data-composition-id="other"] .title { color: red; }
-    </style>
-    <h1 class="title">Hello</h1>
-  </div>
-  <script>window.__timelines = {};</script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const findings = result.findings.filter(
-        (f) => f.code === "composition_self_attribute_selector",
-      );
-
-      expect(findings).toHaveLength(1);
-      expect(findings[0]?.severity).toBe("warning");
-      expect(findings[0]?.selector).toBe('[data-composition-id="scene"] .title');
-      expect(findings[0]?.fixHint).toContain("#scene");
-      expect(findings[0]?.fixHint).not.toContain("#556");
-    });
-
-    it("warns when external CSS targets the root composition id", async () => {
-      const html = `
-<html><body>
-  <div id="scene" data-composition-id="scene" data-width="1920" data-height="1080"></div>
-  <script>window.__timelines = {};</script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html, {
-        externalStyles: [
-          {
-            href: "scene.css",
-            content: '[data-composition-id="scene"] .title { opacity: 0; }',
-          },
-        ],
-      });
-      const finding = result.findings.find((f) => f.code === "composition_self_attribute_selector");
-
-      expect(finding).toBeDefined();
-      expect(finding?.selector).toBe('[data-composition-id="scene"] .title');
-    });
-
-    it("does not warn when CSS targets a different composition id", async () => {
-      const html = `
-<html><body>
-  <div id="scene" data-composition-id="scene" data-width="1920" data-height="1080">
-    <style>[data-composition-id="other"] .title { opacity: 0; }</style>
-  </div>
-  <script>window.__timelines = {};</script>
-</body></html>`;
-      const result = await lintHyperframeHtml(html);
-      const finding = result.findings.find((f) => f.code === "composition_self_attribute_selector");
-
-      expect(finding).toBeUndefined();
-    });
-  });
-});
diff --git a/packages/core/src/lint/rules/core.ts b/packages/core/src/lint/rules/core.ts
deleted file mode 100644
index 6a7ec77ddb..0000000000
--- a/packages/core/src/lint/rules/core.ts
+++ /dev/null
@@ -1,475 +0,0 @@
-import type { LintContext, HyperframeLintFinding } from "../context";
-import postcss from "postcss";
-import {
-  readAttr,
-  truncateSnippet,
-  stripJsComments,
-  extractCompositionIdsFromCss,
-  extractTimelineRegistryKeys,
-  getInlineScriptSyntaxError,
-  TIMELINE_REGISTRY_INIT_PATTERN,
-  TIMELINE_REGISTRY_ASSIGN_PATTERN,
-  INVALID_SCRIPT_CLOSE_PATTERN,
-} from "../utils";
-
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function selectorTargetsCompositionId(selector: string, compositionId: string): boolean {
-  const escaped = escapeRegExp(compositionId);
-  return new RegExp(
-    String.raw`\[\s*data-composition-id\s*=\s*(?:"${escaped}"|'${escaped}')\s*\]`,
-  ).test(selector);
-}
-
-function isStudioTimelineElement(tag: { raw: string; name: string }): boolean {
-  if (["script", "style", "link", "meta", "template", "noscript"].includes(tag.name)) {
-    return false;
-  }
-  return Boolean(
-    readAttr(tag.raw, "data-start") ||
-    readAttr(tag.raw, "data-track-index") ||
-    readAttr(tag.raw, "data-track") ||
-    readAttr(tag.raw, "data-composition-src") ||
-    readAttr(tag.raw, "data-composition-file"),
-  );
-}
-
-function describeStudioElement(tag: { raw: string; name: string }): string {
-  const parts = [`<${tag.name}`];
-  const className = readAttr(tag.raw, "class");
-  const compositionId = readAttr(tag.raw, "data-composition-id");
-  const dataStart = readAttr(tag.raw, "data-start");
-  const dataTrack = readAttr(tag.raw, "data-track-index") ?? readAttr(tag.raw, "data-track");
-
-  if (className) {
-    const primaryClass = className
-      .split(/\s+/)
-      .map((value) => value.trim())
-      .find((value) => value && value !== "clip");
-    if (primaryClass) parts.push(` class="${primaryClass}"`);
-  }
-  if (compositionId) parts.push(` data-composition-id="${compositionId}"`);
-  if (dataStart) parts.push(` data-start="${dataStart}"`);
-  if (dataTrack) parts.push(` data-track-index="${dataTrack}"`);
-  parts.push(">");
-  return parts.join("");
-}
-
-const HEAD_BLOCKS_TO_IGNORE_PATTERN =
-  /<(?:style|script|template|title|noscript)\b[^>]*>[\s\S]*?<\/(?:style|script|template|title|noscript)(?:\s[^>]*)?>/gi;
-const HTML_TAG_PATTERN = /<[^>]+>/g;
-const HEAD_CONTENT_PATTERN = /<head\b[^>]*>([\s\S]*?)(?:<\/head>|<body\b|$)/gi;
-const AFTER_HEAD_BEFORE_BODY_PATTERN = /<\/head(?:\s[^>]*)?>([\s\S]*?)(?=<body\b|$)/gi;
-const STRAY_HEAD_CLOSE_PATTERN = /<\/(?:style|script)(?:\s[^>]*)?>/i;
-const MARKDOWN_CODE_FENCE_PATTERN = /```[^\r\n`]*(?:\r?\n|$)[\s\S]*?```/i;
-const ORPHAN_CSS_AT_RULE_PATTERN =
-  /(?:^|\s)@(?:container|font-face|keyframes|layer|media|page|property|scope|supports)[^{<]*\{[\s\S]*?:[\s\S]*?\}/i;
-const ORPHAN_CSS_RULE_PATTERN =
-  /(?:^|\s)(?:\/\*[\s\S]*?\*\/\s*)?(?:@[a-z-]+[^{}<]*|[.#][\w-]+[^{}<]*|[a-z][\w-]*(?:\s+[.#:[\w-][^{}<]*)?)\s*\{[^{}]*:[^{}]*\}/i;
-
-function findCodeFenceLeak(headWithoutValidBlocks: string): string | null {
-  return MARKDOWN_CODE_FENCE_PATTERN.exec(headWithoutValidBlocks)?.[0] ?? null;
-}
-
-function findOrphanCssLeak(headContent: string): string | null {
-  const residualText = headContent
-    .replace(HEAD_BLOCKS_TO_IGNORE_PATTERN, " ")
-    .replace(HTML_TAG_PATTERN, " ");
-  return (
-    ORPHAN_CSS_AT_RULE_PATTERN.exec(residualText)?.[0] ??
-    ORPHAN_CSS_RULE_PATTERN.exec(residualText)?.[0] ??
-    null
-  );
-}
-
-function findStrayCloseLeak(headWithoutValidBlocks: string): string | null {
-  return STRAY_HEAD_CLOSE_PATTERN.exec(headWithoutValidBlocks)?.[0] ?? null;
-}
-
-function findLeakedTextInHeadContent(headContent: string): string | null {
-  const withoutValidBlocks = headContent.replace(HEAD_BLOCKS_TO_IGNORE_PATTERN, " ");
-  return (
-    findCodeFenceLeak(withoutValidBlocks) ??
-    findOrphanCssLeak(headContent) ??
-    findStrayCloseLeak(withoutValidBlocks)
-  );
-}
-
-function findLeakedTextInHead(rawSource: string): string | null {
-  const headMatches = [...rawSource.matchAll(HEAD_CONTENT_PATTERN)];
-  for (const match of headMatches) {
-    const leakedText = findLeakedTextInHeadContent(match[1] ?? "");
-    if (leakedText) return leakedText;
-  }
-  return null;
-}
-
-function findLeakedTextBetweenHeadAndBody(rawSource: string): string | null {
-  const boundaryMatches = [...rawSource.matchAll(AFTER_HEAD_BEFORE_BODY_PATTERN)];
-  for (const match of boundaryMatches) {
-    const leakedText = findLeakedTextInHeadContent(match[1] ?? "");
-    if (leakedText) return leakedText;
-  }
-  return null;
-}
-
-function findLeakedTextBeforeCompositionRoot(
-  source: string,
-  rootTag: LintContext["rootTag"],
-): string | null {
-  if (!rootTag || rootTag.name === "body") return null;
-  const bodyOpenMatch = /<body\b[^>]*>/i.exec(source);
-  const prefixStart = bodyOpenMatch ? bodyOpenMatch.index + bodyOpenMatch[0].length : 0;
-  const prefixEnd = rootTag.index;
-  if (prefixEnd <= prefixStart) return null;
-  return findLeakedTextInHeadContent(source.slice(prefixStart, prefixEnd));
-}
-
-export const coreRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
-  // root_missing_composition_id + root_missing_dimensions
-  ({ rootTag }) => {
-    const findings: HyperframeLintFinding[] = [];
-    if (!rootTag || !readAttr(rootTag.raw, "data-composition-id")) {
-      findings.push({
-        code: "root_missing_composition_id",
-        severity: "error",
-        message: "Root composition is missing `data-composition-id`.",
-        elementId: rootTag ? readAttr(rootTag.raw, "id") || undefined : undefined,
-        fixHint: "Add a stable `data-composition-id` to the entry composition wrapper.",
-        snippet: truncateSnippet(rootTag?.raw || ""),
-      });
-    }
-    if (!rootTag || !readAttr(rootTag.raw, "data-width") || !readAttr(rootTag.raw, "data-height")) {
-      findings.push({
-        code: "root_missing_dimensions",
-        severity: "error",
-        message: "Root composition is missing `data-width` or `data-height`.",
-        elementId: rootTag ? readAttr(rootTag.raw, "id") || undefined : undefined,
-        fixHint: "Set numeric `data-width` and `data-height` on the entry composition root.",
-        snippet: truncateSnippet(rootTag?.raw || ""),
-      });
-    }
-    return findings;
-  },
-
-  // head_leaked_text
-  ({ source, rootTag }) => {
-    const snippet =
-      findLeakedTextInHead(source) ??
-      findLeakedTextBetweenHeadAndBody(source) ??
-      findLeakedTextBeforeCompositionRoot(source, rootTag);
-    if (!snippet) return [];
-    return [
-      {
-        code: "head_leaked_text",
-        severity: "error",
-        message:
-          "Detected leaked code or CSS text around the document `<head>` or before the composition root. Browsers render this as visible text in the video.",
-        fixHint:
-          "Move CSS into a single `<style>...</style>` block and remove stray close tags, markdown fences, or code text from `<head>`, the `</head>`/`<body>` boundary, or the pre-root body prefix.",
-        snippet: truncateSnippet(snippet),
-      },
-    ];
-  },
-
-  // missing_timeline_registry + timeline_registry_missing_init
-  ({ source, rawSource, options }) => {
-    // Sub-compositions inherit window.__timelines from the host composition
-    if (options.isSubComposition || rawSource.trimStart().toLowerCase().startsWith("<template")) {
-      return [];
-    }
-    const findings: HyperframeLintFinding[] = [];
-    if (
-      !TIMELINE_REGISTRY_INIT_PATTERN.test(source) &&
-      !TIMELINE_REGISTRY_ASSIGN_PATTERN.test(source)
-    ) {
-      findings.push({
-        code: "missing_timeline_registry",
-        severity: "error",
-        message: "Missing `window.__timelines` registration.",
-        fixHint: "Register each composition timeline on `window.__timelines[compositionId]`.",
-      });
-    }
-    if (
-      TIMELINE_REGISTRY_ASSIGN_PATTERN.test(source) &&
-      !TIMELINE_REGISTRY_INIT_PATTERN.test(source)
-    ) {
-      findings.push({
-        code: "timeline_registry_missing_init",
-        severity: "error",
-        message:
-          "`window.__timelines[…] = …` is used without initializing `window.__timelines` first.",
-        fixHint:
-          "Add `window.__timelines = window.__timelines || {};` before any timeline assignment.",
-      });
-    }
-    return findings;
-  },
-
-  // timeline_id_mismatch
-  ({ source }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const htmlCompIds = new Set<string>();
-    const timelineRegKeys = new Set<string>();
-    const compIdRe = /data-composition-id\s*=\s*["']([^"']+)["']/gi;
-    let m: RegExpExecArray | null;
-    while ((m = compIdRe.exec(source)) !== null) {
-      if (m[1]) htmlCompIds.add(m[1]);
-    }
-    for (const key of extractTimelineRegistryKeys(source)) {
-      timelineRegKeys.add(key);
-    }
-    for (const key of timelineRegKeys) {
-      if (!htmlCompIds.has(key)) {
-        findings.push({
-          code: "timeline_id_mismatch",
-          severity: "error",
-          message: `Timeline registered as "${key}" but no element has data-composition-id="${key}". The runtime cannot auto-nest this timeline.`,
-          fixHint: `Change window.__timelines["${key}"] to match the data-composition-id attribute, or vice versa.`,
-        });
-      }
-    }
-    return findings;
-  },
-
-  // invalid_inline_script_syntax (malformed close tag)
-  ({ source }) => {
-    if (!INVALID_SCRIPT_CLOSE_PATTERN.test(source)) return [];
-    return [
-      {
-        code: "invalid_inline_script_syntax",
-        severity: "error",
-        message: "Detected malformed inline `<script>` closing syntax.",
-        fixHint: "Close inline scripts with a valid `</script>` tag.",
-      },
-    ];
-  },
-
-  // invalid_inline_script_syntax (JS parse error)
-  ({ scripts }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const script of scripts) {
-      const attrs = script.attrs || "";
-      if (
-        /\bsrc\s*=/.test(attrs) ||
-        /\btype\s*=\s*["'](?:application\/json|application\/hyperframes-slideshow\+json|importmap|module)["']/.test(
-          attrs,
-        )
-      )
-        continue;
-      const syntaxError = getInlineScriptSyntaxError(script.content);
-      if (!syntaxError) continue;
-      findings.push({
-        code: "invalid_inline_script_syntax",
-        severity: "error",
-        message: `Inline script has invalid syntax: ${syntaxError}`,
-        fixHint: "Fix the inline script syntax before render verification.",
-        snippet: truncateSnippet(script.content),
-      });
-    }
-    return findings;
-  },
-
-  // host_missing_composition_id
-  ({ tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const tag of tags) {
-      const src = readAttr(tag.raw, "data-composition-src");
-      if (!src) continue;
-      if (readAttr(tag.raw, "data-composition-id")) continue;
-      findings.push({
-        code: "host_missing_composition_id",
-        severity: "error",
-        message: `Composition host for "${src}" is missing \`data-composition-id\`.`,
-        elementId: readAttr(tag.raw, "id") || undefined,
-        fixHint: "Set `data-composition-id` on every `data-composition-src` host element.",
-        snippet: truncateSnippet(tag.raw),
-      });
-    }
-    return findings;
-  },
-
-  // scoped_css_missing_wrapper
-  ({ styles, compositionIds }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const scopedCssCompositionIds = new Set<string>();
-    for (const style of styles) {
-      for (const compId of extractCompositionIdsFromCss(style.content)) {
-        scopedCssCompositionIds.add(compId);
-      }
-    }
-    for (const compId of scopedCssCompositionIds) {
-      if (compositionIds.has(compId)) continue;
-      findings.push({
-        code: "scoped_css_missing_wrapper",
-        severity: "warning",
-        message: `Scoped CSS targets composition "${compId}" but no matching wrapper exists in this HTML.`,
-        selector: `[data-composition-id="${compId}"]`,
-        fixHint:
-          "Preserve the matching composition wrapper or align the CSS scope to an existing wrapper.",
-      });
-    }
-    return findings;
-  },
-
-  // composition_self_attribute_selector
-  ({ styles, rootCompositionId, rootTag }) => {
-    const findings: HyperframeLintFinding[] = [];
-    if (!rootCompositionId) return findings;
-    const seenSelectors = new Set<string>();
-    const rootId = readAttr(rootTag?.raw || "", "id");
-    for (const style of styles) {
-      let root: postcss.Root;
-      try {
-        root = postcss.parse(style.content);
-      } catch {
-        continue;
-      }
-      root.walkRules((rule) => {
-        for (const selector of rule.selectors) {
-          if (!selectorTargetsCompositionId(selector, rootCompositionId)) continue;
-          if (seenSelectors.has(selector)) continue;
-          seenSelectors.add(selector);
-          findings.push({
-            code: "composition_self_attribute_selector",
-            severity: "warning",
-            message:
-              "Selector matches the block's own id; will leak to sibling instances when the block is embedded twice.",
-            selector,
-            fixHint: rootId
-              ? `Use #${rootId} for clearer authoring intent and instance-isolated styling.`
-              : "Add a stable id to the composition root and use that id selector for clearer authoring intent and instance-isolated styling.",
-          });
-        }
-      });
-    }
-    return findings;
-  },
-
-  // studio_missing_editable_id
-  ({ tags, rootTag }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const tag of tags) {
-      if (rootTag && tag.index === rootTag.index) continue;
-      if (!isStudioTimelineElement(tag)) continue;
-      if (readAttr(tag.raw, "id")) continue;
-
-      const descriptor = describeStudioElement(tag);
-      findings.push({
-        code: "studio_missing_editable_id",
-        severity: "warning",
-        message: `${descriptor} has no id, so Studio cannot use a stable edit target for its timeline and canvas controls.`,
-        selector: readAttr(tag.raw, "data-composition-id")
-          ? `[data-composition-id="${readAttr(tag.raw, "data-composition-id")}"]`
-          : undefined,
-        fixHint:
-          'Add a stable, human-readable id such as id="hero-title" or id="scene-1-card" to every timeline-visible element you want agents or Studio to edit.',
-        snippet: truncateSnippet(tag.raw),
-      });
-    }
-    return findings;
-  },
-
-  // non_deterministic_code
-  ({ scripts }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const patterns: Array<{ pattern: RegExp; label: string; hint: string }> = [
-      {
-        pattern: /Math\.random\s*\(/,
-        label: "Math.random()",
-        hint: "Use a seeded PRNG (e.g. a simple mulberry32) so renders are deterministic across frames.",
-      },
-      {
-        pattern: /Date\.now\s*\(/,
-        label: "Date.now()",
-        hint: "Remove time-dependent code. Use GSAP timeline position instead of wall-clock time.",
-      },
-      {
-        pattern: /new\s+Date\s*\(/,
-        label: "new Date()",
-        hint: "Remove time-dependent code. Use GSAP timeline position instead of wall-clock time.",
-      },
-      {
-        pattern: /performance\.now\s*\(/,
-        label: "performance.now()",
-        hint: "Remove time-dependent code. Use GSAP timeline position instead of wall-clock time.",
-      },
-      {
-        pattern: /crypto\.getRandomValues\s*\(/,
-        label: "crypto.getRandomValues()",
-        hint: "Remove time-dependent code. Use a seeded PRNG for deterministic renders.",
-      },
-    ];
-
-    for (const script of scripts) {
-      const stripped = stripJsComments(script.content);
-      for (const { pattern, label, hint } of patterns) {
-        if (pattern.test(stripped)) {
-          findings.push({
-            code: "non_deterministic_code",
-            severity: "error",
-            message: `Script contains \`${label}\` which produces non-deterministic output. Renders may differ between frames or runs.`,
-            fixHint: hint,
-            snippet: truncateSnippet(script.content),
-          });
-        }
-      }
-    }
-    return findings;
-  },
-
-  // pointer_events_none
-  // fallow-ignore-next-line complexity
-  ({ tags, styles }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const reported = new Set<string>();
-
-    for (const tag of tags) {
-      if (["script", "style", "link", "meta", "template", "noscript"].includes(tag.name)) continue;
-      const inlineStyle = readAttr(tag.raw, "style") ?? "";
-      if (!/pointer-events\s*:\s*none/i.test(inlineStyle)) continue;
-      const id = readAttr(tag.raw, "id");
-      const key = id ?? tag.raw;
-      if (reported.has(key)) continue;
-      reported.add(key);
-      findings.push({
-        code: "pointer_events_none",
-        severity: "info",
-        message: `<${tag.name}${id ? ` id="${id}"` : ""}> has \`pointer-events: none\` in its inline style. Elements with this property are harder to select in the Studio preview.`,
-        elementId: id || undefined,
-        fixHint:
-          "If this element should be selectable in the Studio, remove `pointer-events: none` or move it to a wrapper that doesn't contain editable content.",
-        snippet: truncateSnippet(tag.raw),
-      });
-    }
-
-    for (const style of styles) {
-      let root: postcss.Root;
-      try {
-        root = postcss.parse(style.content);
-      } catch {
-        continue;
-      }
-      root.walkDecls("pointer-events", (decl) => {
-        if (decl.value.trim().toLowerCase() !== "none") return;
-        const rule = decl.parent;
-        if (!rule || rule.type !== "rule") return;
-        const selector = (rule as postcss.Rule).selector;
-        if (reported.has(selector)) return;
-        reported.add(selector);
-        findings.push({
-          code: "pointer_events_none",
-          severity: "info",
-          message: `\`${selector}\` sets \`pointer-events: none\`. Elements matching this selector are harder to select in the Studio preview.`,
-          selector,
-          fixHint:
-            "If these elements should be selectable in the Studio, remove `pointer-events: none` or move it to a wrapper that doesn't contain editable content.",
-        });
-      });
-    }
-
-    return findings;
-  },
-];
diff --git a/packages/core/src/lint/rules/fonts.test.ts b/packages/core/src/lint/rules/fonts.test.ts
deleted file mode 100644
index 853781bd74..0000000000
--- a/packages/core/src/lint/rules/fonts.test.ts
+++ /dev/null
@@ -1,285 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { lintHyperframeHtml } from "../hyperframeLinter.js";
-
-async function findByCode(html: string, code: string, isSubComposition = true) {
-  const result = await lintHyperframeHtml(html, { isSubComposition });
-  return result.findings.filter((f) => f.code === code);
-}
-
-describe("font rules", () => {
-  describe("google_fonts_import", () => {
-    it("warns on @import url with fonts.googleapis.com without failing lint", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500&display=swap');</style>
-      </div>`;
-      const result = await lintHyperframeHtml(html, { isSubComposition: true });
-      const findings = result.findings.filter((f) => f.code === "google_fonts_import");
-      expect(findings).toHaveLength(1);
-      expect(findings[0]!.severity).toBe("warning");
-      expect(result.errorCount).toBe(0);
-    });
-
-    it("warns on <link> to fonts.googleapis.com", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter">
-      </div>`;
-      const findings = await findByCode(html, "google_fonts_import");
-      expect(findings).toHaveLength(1);
-      expect(findings[0]!.severity).toBe("warning");
-    });
-
-    it("does not flag local @font-face usage", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>@font-face { font-family: 'Inter'; src: url('../capture/assets/fonts/Inter.woff2'); }</style>
-      </div>`;
-      const findings = await findByCode(html, "google_fonts_import");
-      expect(findings).toHaveLength(0);
-    });
-
-    it("does not flag installed registry blocks that bundle Google Fonts", async () => {
-      const html =
-        `<!-- hyperframes-registry-item: my-block -->\n` +
-        `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter">
-      </div>`;
-      const findings = await findByCode(html, "google_fonts_import");
-      expect(findings).toHaveLength(0);
-    });
-  });
-
-  describe("system_font_will_alias", () => {
-    it("flags SF Mono as aliased to JetBrains Mono", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>code { font-family: 'SF Mono', monospace; }</style>
-      </div>`;
-      const findings = await findByCode(html, "system_font_will_alias");
-      expect(findings).toHaveLength(1);
-      expect(findings[0]!.severity).toBe("info");
-      expect(findings[0]!.message).toContain("JetBrains Mono");
-    });
-
-    it("flags Helvetica Neue as aliased to Inter", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>body { font-family: 'Helvetica Neue', sans-serif; }</style>
-      </div>`;
-      const findings = await findByCode(html, "system_font_will_alias");
-      expect(findings).toHaveLength(1);
-      expect(findings[0]!.message).toContain("Inter");
-    });
-
-    it("does not flag canonical font names", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>body { font-family: 'Inter', sans-serif; }</style>
-      </div>`;
-      const findings = await findByCode(html, "system_font_will_alias");
-      expect(findings).toHaveLength(0);
-    });
-
-    it("does not flag Roboto (canonical name)", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>body { font-family: 'Roboto', sans-serif; }</style>
-      </div>`;
-      const findings = await findByCode(html, "system_font_will_alias");
-      expect(findings).toHaveLength(0);
-    });
-
-    it("does not flag unknown fonts (handled by font_family_without_font_face)", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>body { font-family: 'Comic Sans MS', sans-serif; }</style>
-      </div>`;
-      const findings = await findByCode(html, "system_font_will_alias");
-      expect(findings).toHaveLength(0);
-    });
-
-    it("does not flag aliased fonts that have explicit @font-face", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>
-          @font-face { font-family: 'Menlo'; src: url('../fonts/menlo.woff2'); }
-          code { font-family: 'Menlo', monospace; }
-        </style>
-      </div>`;
-      const findings = await findByCode(html, "system_font_will_alias");
-      expect(findings).toHaveLength(0);
-    });
-
-    it("handles case-insensitive font names", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>body { font-family: 'VERDANA', sans-serif; }</style>
-      </div>`;
-      const findings = await findByCode(html, "system_font_will_alias");
-      expect(findings).toHaveLength(1);
-      expect(findings[0]!.message).toContain("Inter");
-    });
-
-    it("reports multiple aliased fonts in one finding", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>
-          body { font-family: 'Verdana', sans-serif; }
-          code { font-family: 'Consolas', monospace; }
-        </style>
-      </div>`;
-      const findings = await findByCode(html, "system_font_will_alias");
-      expect(findings).toHaveLength(1);
-      expect(findings[0]!.message).toContain("Inter");
-      expect(findings[0]!.message).toContain("JetBrains Mono");
-    });
-  });
-
-  describe("font_family_without_font_face", () => {
-    it("flags font-family used without @font-face", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>body { font-family: 'GT Walsheim', sans-serif; }</style>
-      </div>`;
-      const findings = await findByCode(html, "font_family_without_font_face");
-      expect(findings).toHaveLength(1);
-      expect(findings[0]!.message).toContain("gt walsheim");
-    });
-
-    it("does not flag when @font-face is declared", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>
-          @font-face { font-family: 'GT Walsheim'; src: url('../fonts/gt.woff2'); }
-          body { font-family: 'GT Walsheim', sans-serif; }
-        </style>
-      </div>`;
-      const findings = await findByCode(html, "font_family_without_font_face");
-      expect(findings).toHaveLength(0);
-    });
-
-    it("does not flag generic font families", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>body { font-family: monospace; }</style>
-      </div>`;
-      const findings = await findByCode(html, "font_family_without_font_face");
-      expect(findings).toHaveLength(0);
-    });
-
-    it("reports multiple missing families in one finding", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>
-          h1 { font-family: 'Aeonik', sans-serif; }
-          code { font-family: 'Feature Deck', monospace; }
-        </style>
-      </div>`;
-      const findings = await findByCode(html, "font_family_without_font_face");
-      expect(findings).toHaveLength(1);
-      expect(findings[0]!.message).toContain("aeonik");
-      expect(findings[0]!.message).toContain("feature deck");
-    });
-
-    it("does not flag fonts the producer has pre-bundled", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>
-          body { font-family: 'Inter', sans-serif; }
-          code { font-family: 'JetBrains Mono', monospace; }
-          h1 { font-family: 'Roboto', sans-serif; }
-        </style>
-      </div>`;
-      const findings = await findByCode(html, "font_family_without_font_face");
-      expect(findings).toHaveLength(0);
-    });
-
-    it("still flags Google-Fonts-only fonts not pre-bundled", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>body { font-family: 'Geist', sans-serif; }</style>
-      </div>`;
-      const findings = await findByCode(html, "font_family_without_font_face");
-      expect(findings).toHaveLength(1);
-      expect(findings[0]!.message).toContain("geist");
-    });
-
-    it("does not flag a non-bundled family when a Google Fonts link loads it", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Geist:wght@400;700&display=swap">
-        <style>body { font-family: 'Geist', sans-serif; }</style>
-      </div>`;
-      const result = await lintHyperframeHtml(html, { isSubComposition: true });
-      expect(result.findings.filter((f) => f.code === "google_fonts_import")).toHaveLength(1);
-      expect(
-        result.findings.filter((f) => f.code === "font_family_without_font_face"),
-      ).toHaveLength(0);
-      expect(result.errorCount).toBe(0);
-    });
-
-    it("parses unquoted Google Fonts link href values", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <link rel=stylesheet href=https://fonts.googleapis.com/css2?family=Geist:wght@400;700&display=swap>
-        <style>body { font-family: 'Geist', sans-serif; }</style>
-      </div>`;
-      const result = await lintHyperframeHtml(html, { isSubComposition: true });
-      expect(result.findings.filter((f) => f.code === "google_fonts_import")).toHaveLength(1);
-      expect(
-        result.findings.filter((f) => f.code === "font_family_without_font_face"),
-      ).toHaveLength(0);
-      expect(result.errorCount).toBe(0);
-    });
-
-    it("parses multiple Google Fonts family parameters and URL-encoded spaces", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>
-          @import url("https://fonts.googleapis.com/css2?family=Libre+Baskerville:wght@400;700&family=DM+Sans:ital,wght@0,400;1,700&display=swap");
-          h1 { font-family: 'Libre Baskerville', serif; }
-          body { font-family: 'DM Sans', sans-serif; }
-        </style>
-      </div>`;
-      const result = await lintHyperframeHtml(html, { isSubComposition: true });
-      expect(result.findings.filter((f) => f.code === "google_fonts_import")).toHaveLength(1);
-      expect(
-        result.findings.filter((f) => f.code === "font_family_without_font_face"),
-      ).toHaveLength(0);
-      expect(result.errorCount).toBe(0);
-    });
-
-    it("still flags non-bundled families not covered by the Google Fonts URL", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter">
-        <style>body { font-family: 'Geist', sans-serif; }</style>
-      </div>`;
-      const findings = await findByCode(html, "font_family_without_font_face");
-      expect(findings).toHaveLength(1);
-      expect(findings[0]!.message).toContain("geist");
-    });
-
-    it("is case-insensitive when matching @font-face to font-family", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>
-          @font-face { font-family: 'Inter'; src: url('../fonts/inter.woff2'); }
-          body { font-family: 'inter', sans-serif; }
-        </style>
-      </div>`;
-      const findings = await findByCode(html, "font_family_without_font_face");
-      expect(findings).toHaveLength(0);
-    });
-
-    it("ignores font-family inside @font-face blocks", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>
-          @font-face { font-family: 'CustomFont'; src: url('../fonts/custom.woff2'); }
-        </style>
-      </div>`;
-      const findings = await findByCode(html, "font_family_without_font_face");
-      expect(findings).toHaveLength(0);
-    });
-
-    it("does not flag installed registry blocks that declare fonts via Google Fonts", async () => {
-      const html =
-        `<!-- hyperframes-registry-item: my-block -->\n` +
-        `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>body { font-family: 'Poppins', sans-serif; }</style>
-      </div>`;
-      const findings = await findByCode(html, "font_family_without_font_face");
-      expect(findings).toHaveLength(0);
-    });
-
-    it("matches @font-face even when a CSS comment inside the block contains a brace (#1534)", async () => {
-      const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
-        <style>
-          @font-face { /* weight 400 } regular */ font-family: 'Noto Sans SC'; src: url('../fonts/noto-400.woff2'); }
-          .title { font-family: 'Noto Sans SC'; }
-        </style>
-      </div>`;
-      const findings = await findByCode(html, "font_family_without_font_face");
-      expect(findings).toHaveLength(0);
-    });
-  });
-});
diff --git a/packages/core/src/lint/rules/fonts.ts b/packages/core/src/lint/rules/fonts.ts
deleted file mode 100644
index 37ab682a2a..0000000000
--- a/packages/core/src/lint/rules/fonts.ts
+++ /dev/null
@@ -1,222 +0,0 @@
-import { FONT_ALIAS_KEYS, resolveAliasDisplayName } from "../../fonts/aliases";
-import type { LintContext, HyperframeLintFinding } from "../context";
-import { isRegistrySourceFile, isRegistryInstalledFile } from "./composition";
-
-const GENERIC_FAMILIES = new Set([
-  "serif",
-  "sans-serif",
-  "monospace",
-  "cursive",
-  "fantasy",
-  "system-ui",
-  "ui-serif",
-  "ui-sans-serif",
-  "ui-monospace",
-  "ui-rounded",
-  "math",
-  "emoji",
-  "fangsong",
-  "inherit",
-  "initial",
-  "unset",
-  "revert",
-]);
-
-// A CSS comment can contain a `}` (e.g. `@font-face { /* 400 } regular */
-// font-family: 'X'; ... }`), which truncates the naive `@font-face\s*\{[^}]*\}`
-// block match at the comment's brace — so the rule never sees the real
-// `font-family` and reports a false-positive font_family_without_font_face.
-// Large/"framework" stylesheets hit this far more often than minimal ones,
-// which is why a simple <style> passes while a complex one fails. Strip
-// comments before scanning so a brace inside one cannot split a block. See #1534.
-function stripCssComments(css: string): string {
-  return css.replace(/\/\*[\s\S]*?\*\//g, " ");
-}
-
-function extractFontFaceFamilies(styles: Array<{ content: string }>): Set<string> {
-  const families = new Set<string>();
-  const fontFaceRe = /@font-face\s*\{[^}]*\}/gi;
-  const familyRe = /font-family\s*:\s*(['"]?)([^;'"]+)\1/i;
-  for (const style of styles) {
-    const content = stripCssComments(style.content);
-    let match: RegExpExecArray | null;
-    while ((match = fontFaceRe.exec(content)) !== null) {
-      const familyMatch = match[0].match(familyRe);
-      if (familyMatch?.[2]) {
-        families.add(familyMatch[2].trim().toLowerCase());
-      }
-    }
-  }
-  return families;
-}
-
-function extractUsedFontFamilies(styles: Array<{ content: string }>): string[] {
-  const used: string[] = [];
-  const seen = new Set<string>();
-  const propRe = /font-family\s*:\s*([^;}{]+)/gi;
-  for (const style of styles) {
-    const withoutFontFace = stripCssComments(style.content).replace(/@font-face\s*\{[^}]*\}/gi, "");
-    let match: RegExpExecArray | null;
-    while ((match = propRe.exec(withoutFontFace)) !== null) {
-      const stack = match[1]!;
-      for (const part of stack.split(",")) {
-        const name = part
-          .trim()
-          .replace(/^['"]|['"]$/g, "")
-          .trim()
-          .toLowerCase();
-        if (name && !GENERIC_FAMILIES.has(name) && !seen.has(name)) {
-          seen.add(name);
-          used.push(name);
-        }
-      }
-    }
-  }
-  return used;
-}
-
-function collectAliasedFonts(used: string[], declared: Set<string>): string[] {
-  const aliased: string[] = [];
-  for (const name of used) {
-    if (declared.has(name)) continue;
-    const displayName = resolveAliasDisplayName(name);
-    if (!displayName) continue;
-    if (displayName.toLowerCase() === name) continue;
-    aliased.push(`'${name}' → ${displayName}`);
-  }
-  return aliased;
-}
-
-function normalizeFontFamily(name: string): string | null {
-  const decoded = name.replace(/\+/g, " ").trim();
-  if (!decoded) return null;
-  try {
-    return decodeURIComponent(decoded).trim().toLowerCase() || null;
-  } catch {
-    return decoded.toLowerCase();
-  }
-}
-
-function extractGoogleFontFamiliesFromUrl(rawUrl: string): string[] {
-  const url = rawUrl.replace(/&amp;/gi, "&");
-  let parsed: URL;
-  try {
-    parsed = new URL(url, "https://fonts.googleapis.com");
-  } catch {
-    return [];
-  }
-
-  if (parsed.hostname.toLowerCase() !== "fonts.googleapis.com") return [];
-  const families: string[] = [];
-  for (const value of parsed.searchParams.getAll("family")) {
-    for (const familySpec of value.split("|")) {
-      const family = normalizeFontFamily(familySpec.split(":")[0] || "");
-      if (family) families.push(family);
-    }
-  }
-  return families;
-}
-
-function collectGoogleFontFamilies(
-  source: string,
-  styles: Array<{ content: string }>,
-): Set<string> {
-  const families = new Set<string>();
-  const addUrl = (url: string) => {
-    for (const family of extractGoogleFontFamiliesFromUrl(url)) families.add(family);
-  };
-
-  const linkHrefRe =
-    /<link\b[^>]*\bhref\s*=\s*(?:(["'])([^"']*fonts\.googleapis\.com[^"']*)\1|([^\s>]*fonts\.googleapis\.com[^\s>]*))[^>]*>/gi;
-  for (const match of source.matchAll(linkHrefRe)) {
-    const href = match[2] || match[3];
-    if (href) addUrl(href);
-  }
-
-  const importUrlRe =
-    /@import\s+(?:url\(\s*)?(["']?)([^"')\s]*fonts\.googleapis\.com[^"')\s]*)\1\s*\)?/gi;
-  for (const style of styles) {
-    for (const match of style.content.matchAll(importUrlRe)) {
-      if (match[2]) addUrl(match[2]);
-    }
-  }
-
-  return families;
-}
-
-export const fontRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
-  // google_fonts_import
-  ({ styles, source, rawSource, options }) => {
-    if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
-    const findings: HyperframeLintFinding[] = [];
-    const googleFontsInLink = /<link\b[^>]*fonts\.googleapis\.com[^>]*>/i.test(source);
-    const googleFontsInImport = styles.some((s) =>
-      /@import\s+url\s*\(\s*['"]?[^)]*fonts\.googleapis\.com/i.test(s.content),
-    );
-
-    if (googleFontsInLink || googleFontsInImport) {
-      findings.push({
-        code: "google_fonts_import",
-        severity: "warning",
-        message:
-          "Composition loads fonts from fonts.googleapis.com. The producer resolves Google Fonts " +
-          "during compile/render, but raw external font requests add latency and can fail before " +
-          "canonicalization. Prefer mapped family names or local @font-face declarations when possible.",
-        fixHint:
-          "For bundled fonts, remove the Google Fonts <link> or @import and keep the font-family " +
-          "declaration. For custom fonts, use @font-face { font-family: '...'; src: url('...woff2'); }.",
-      });
-    }
-    return findings;
-  },
-
-  // system_font_will_alias — inform when a font will be silently substituted
-  ({ styles, options }) => {
-    const declared = extractFontFaceFamilies(styles);
-    const used = extractUsedFontFamilies(styles);
-    const aliased = collectAliasedFonts(used, declared);
-    if (aliased.length === 0) return [];
-    // In distributed / Lambda renders system-font capture is disabled, so
-    // the alias substitution does NOT happen — elevate to a warning.
-    const severity = options.distributed ? ("warning" as const) : ("info" as const);
-    return [
-      {
-        code: "system_font_will_alias",
-        severity,
-        message:
-          `Font ${aliased.length === 1 ? "family" : "families"} will be substituted at render time: ${aliased.join(", ")}. ` +
-          (options.distributed
-            ? "In distributed/Lambda rendering system-font capture is disabled — these fonts will fall back to OS defaults. Embed explicit @font-face declarations instead."
-            : "The renderer maps these to bundled fonts for cross-platform consistency. " +
-              "Use the target font name directly for consistent preview and render results."),
-      },
-    ];
-  },
-
-  // font_family_without_font_face
-  ({ styles, source, rawSource, options }) => {
-    if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
-    const findings: HyperframeLintFinding[] = [];
-    const declared = extractFontFaceFamilies(styles);
-    const used = extractUsedFontFamilies(styles);
-    const googleFonts = collectGoogleFontFamilies(source, styles);
-
-    const undeclared = used.filter(
-      (name) => !declared.has(name) && !FONT_ALIAS_KEYS.has(name) && !googleFonts.has(name),
-    );
-    if (undeclared.length === 0) return findings;
-
-    findings.push({
-      code: "font_family_without_font_face",
-      severity: "error",
-      message:
-        `Font ${undeclared.length === 1 ? "family" : "families"} used without @font-face declaration: ${undeclared.join(", ")}. ` +
-        "These are not in the auto-resolved font list, so the renderer cannot supply them automatically. " +
-        "Text will fall back to a generic font, producing incorrect typography in the video.",
-      fixHint:
-        "Add @font-face { font-family: '...'; src: url('capture/assets/fonts/...woff2'); } " +
-        "for each font family, pointing to the captured .woff2 files.",
-    });
-    return findings;
-  },
-];
diff --git a/packages/core/src/lint/rules/gsap.test.ts b/packages/core/src/lint/rules/gsap.test.ts
deleted file mode 100644
index e9b46325a0..0000000000
--- a/packages/core/src/lint/rules/gsap.test.ts
+++ /dev/null
@@ -1,1318 +0,0 @@
-// fallow-ignore-file code-duplication
-import { describe, it, expect } from "vitest";
-import { lintHyperframeHtml } from "../hyperframeLinter.js";
-
-describe("GSAP rules", () => {
-  it("errors when window.__timelines is registered BEFORE the fonts.ready build", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    var tl = gsap.timeline({ paused: true });
-    window.__timelines["c1"] = tl;
-    document.fonts.ready.then(function () {
-      tl.from("#editor", { opacity: 0, duration: 0.5 }, 0);
-    });
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find(
-      (f) => f.code === "gsap_timeline_registered_before_async_build",
-    );
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-  });
-
-  it("does NOT error when window.__timelines is registered AFTER the fonts.ready build", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    var tl = gsap.timeline({ paused: true });
-    document.fonts.ready.then(function () {
-      tl.from("#editor", { opacity: 0, duration: 0.5 }, 0);
-      window.__timelines["c1"] = tl;
-    });
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find(
-      (f) => f.code === "gsap_timeline_registered_before_async_build",
-    );
-    expect(finding).toBeUndefined();
-  });
-
-  it("does NOT error when GSAP animates opacity on a clip element (by id)", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="overlay" class="clip" data-start="0" data-duration="5" data-track-index="0">
-      <h1>Hello</h1>
-    </div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#overlay", { opacity: 0, duration: 0.5 }, 4.0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does NOT error when GSAP targets a clip element with safe properties (by class)", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="card" class="clip my-card" data-start="0" data-duration="5" data-track-index="0">
-      <p>Content</p>
-    </div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.from(".my-card", { y: 100, duration: 0.3 }, 0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does NOT flag GSAP targeting a child of a clip element", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="overlay" class="clip" data-start="0" data-duration="5" data-track-index="0">
-      <h1 class="title">Hello</h1>
-    </div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to(".title", { opacity: 1, duration: 0.5 }, 0.5);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does NOT flag GSAP targeting a nested selector like '#overlay .title'", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="overlay" class="clip" data-start="0" data-duration="5" data-track-index="0">
-      <h1 class="title">Hello</h1>
-    </div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#overlay .title", { opacity: 1, duration: 0.5 }, 0.5);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does NOT error when GSAP targets a clip element with safe properties (class-only, no id)", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div class="clip scene-card" data-start="0" data-duration="5" data-track-index="0">
-      <p>Content</p>
-    </div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to(".scene-card", { y: -50, duration: 0.4 }, 0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
-    expect(finding).toBeUndefined();
-  });
-
-  it("errors when a full-frame transition flash starts visible before GSAP controls it", async () => {
-    const html = `
-<html><body data-composition-id="c1" data-width="1920" data-height="1080">
-  <div id="tr-flash-1" style="position:fixed;inset:0;background:#fff;pointer-events:none;z-index:990"></div>
-  <section class="clip" data-start="0" data-duration="8"><h1>Scene 1</h1></section>
-  <section class="clip" data-start="8" data-duration="8"><h1>Scene 2</h1></section>
-  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#tr-flash-1", { opacity: 1, duration: 0.08 }, 7.92);
-    tl.to("#tr-flash-1", { opacity: 0, duration: 0.18 }, 8.00);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find(
-      (f) => f.code === "gsap_fullscreen_overlay_starts_visible",
-    );
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.selector).toBe("#tr-flash-1");
-    expect(finding?.message).toContain("blank/white video");
-  });
-
-  it("does not error when a full-frame transition flash is initially hidden", async () => {
-    const html = `
-<html><body data-composition-id="c1" data-width="1920" data-height="1080">
-  <div id="tr-flash-1" style="position:fixed;inset:0;background:#fff;opacity:0;pointer-events:none;z-index:990"></div>
-  <section class="clip" data-start="0" data-duration="8"><h1>Scene 1</h1></section>
-  <section class="clip" data-start="8" data-duration="8"><h1>Scene 2</h1></section>
-  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#tr-flash-1", { opacity: 1, duration: 0.08 }, 7.92);
-    tl.to("#tr-flash-1", { opacity: 0, duration: 0.18 }, 8.00);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find(
-      (f) => f.code === "gsap_fullscreen_overlay_starts_visible",
-    );
-    expect(finding).toBeUndefined();
-  });
-
-  it("does not error when GSAP hides a full-frame transition flash at frame zero", async () => {
-    const html = `
-<html><body data-composition-id="c1" data-width="1920" data-height="1080">
-  <div id="tr-flash-1" style="position:fixed;inset:0;background:#fff;pointer-events:none;z-index:990"></div>
-  <section class="clip" data-start="0" data-duration="8"><h1>Scene 1</h1></section>
-  <section class="clip" data-start="8" data-duration="8"><h1>Scene 2</h1></section>
-  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.set("#tr-flash-1", { opacity: 0 }, 0);
-    tl.to("#tr-flash-1", { opacity: 1, duration: 0.08 }, 7.92);
-    tl.to("#tr-flash-1", { opacity: 0, duration: 0.18 }, 8.00);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find(
-      (f) => f.code === "gsap_fullscreen_overlay_starts_visible",
-    );
-    expect(finding).toBeUndefined();
-  });
-
-  it("reports one full-frame transition flash finding when multiple scripts touch it", async () => {
-    const html = `
-<html><body data-composition-id="c1" data-width="1920" data-height="1080">
-  <div id="tr-flash-1" style="position:fixed;inset:0;background:#fff;pointer-events:none;z-index:990"></div>
-  <section class="clip" data-start="0" data-duration="8"><h1>Scene 1</h1></section>
-  <section class="clip" data-start="8" data-duration="8"><h1>Scene 2</h1></section>
-  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#tr-flash-1", { opacity: 1, duration: 0.08 }, 7.92);
-    tl.to("#tr-flash-1", { opacity: 0, duration: 0.18 }, 8.00);
-    window.__timelines["c1"] = tl;
-  </script>
-  <script>
-    const tl2 = gsap.timeline({ paused: true });
-    tl2.to("#tr-flash-1", { opacity: 1, duration: 0.08 }, 9.92);
-    tl2.to("#tr-flash-1", { opacity: 0, duration: 0.18 }, 10.00);
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    expect(
-      result.findings.filter((f) => f.code === "gsap_fullscreen_overlay_starts_visible"),
-    ).toHaveLength(1);
-  });
-
-  it("errors when a full-frame transition flash uses a GSAP from reveal", async () => {
-    const html = `
-<html><body data-composition-id="c1" data-width="1920" data-height="1080">
-  <div id="tr-flash-1" style="position:fixed;inset:0;background:#fff;pointer-events:none;z-index:990"></div>
-  <section class="clip" data-start="0" data-duration="8"><h1>Scene 1</h1></section>
-  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.from("#tr-flash-1", { opacity: 0, duration: 0.18 }, 7.92);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find(
-      (f) => f.code === "gsap_fullscreen_overlay_starts_visible",
-    );
-    expect(finding).toBeDefined();
-    expect(finding?.selector).toBe("#tr-flash-1");
-  });
-
-  it("errors when a grouped GSAP selector targets a visible full-frame flash", async () => {
-    const html = `
-<html><body data-composition-id="c1" data-width="1920" data-height="1080">
-  <div id="tr-flash-1" style="position:fixed;inset:0;background:#fff;pointer-events:none;z-index:990"></div>
-  <div id="unused"></div>
-  <section class="clip" data-start="0" data-duration="8"><h1>Scene 1</h1></section>
-  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#unused, #tr-flash-1", { opacity: 1, duration: 0.08 }, 7.92);
-    tl.to("#unused, #tr-flash-1", { opacity: 0, duration: 0.18 }, 8.00);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find(
-      (f) => f.code === "gsap_fullscreen_overlay_starts_visible",
-    );
-    expect(finding).toBeDefined();
-    expect(finding?.selector).toBe("#tr-flash-1");
-  });
-
-  it("errors when full-frame transition flash styles come from a style block", async () => {
-    const html = `
-<html><body data-composition-id="c1" data-width="1920" data-height="1080">
-  <style>
-    .tr-flash { position: fixed; inset: 0; background: #fff; pointer-events: none; z-index: 990; }
-  </style>
-  <div id="tr-flash-1" class="tr-flash"></div>
-  <section class="clip" data-start="0" data-duration="8"><h1>Scene 1</h1></section>
-  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to(".tr-flash", { opacity: 1, duration: 0.08 }, 7.92);
-    tl.to(".tr-flash", { opacity: 0, duration: 0.18 }, 8.00);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find(
-      (f) => f.code === "gsap_fullscreen_overlay_starts_visible",
-    );
-    expect(finding).toBeDefined();
-    expect(finding?.selector).toBe(".tr-flash");
-  });
-
-  it("does NOT error when GSAP animates opacity on a clip element", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="title" class="clip" data-start="0" data-duration="5" data-track-index="0">
-      <h1>Title</h1>
-    </div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.from("#title", { opacity: 0, y: -50, duration: 0.5 }, 0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does NOT error when GSAP animates transform props on a clip element", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="box" class="clip" data-start="0" data-duration="5" data-track-index="0">
-      <div>Box</div>
-    </div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#box", { scale: 1.2, x: 100, rotation: 45, duration: 0.5 }, 0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does NOT require a local GSAP script for sub-compositions", async () => {
-    const html = `<template id="intro-template">
-  <div data-composition-id="intro" data-width="1920" data-height="1080">
-    <div class="title">Hello</div>
-    <script>
-      window.__timelines = window.__timelines || {};
-      const tl = gsap.timeline({ paused: true });
-      tl.from(".title", { opacity: 0, duration: 1 });
-      window.__timelines["intro"] = tl;
-    </script>
-  </div>
-</template>`;
-
-    const result = await lintHyperframeHtml(html, { isSubComposition: true });
-    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does NOT require a local GSAP script when a template composition is linted in isolation", async () => {
-    const html = `<template id="intro-template">
-  <div data-composition-id="intro" data-width="1920" data-height="1080">
-    <div class="title">Hello</div>
-    <script>
-      window.__timelines = window.__timelines || {};
-      const tl = gsap.timeline({ paused: true });
-      tl.from(".title", { opacity: 0, duration: 1 });
-      window.__timelines["intro"] = tl;
-    </script>
-  </div>
-</template>`;
-
-    const result = await lintHyperframeHtml(html, { filePath: "compositions/intro.html" });
-    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
-    expect(finding).toBeUndefined();
-  });
-
-  it("ERRORS when GSAP animates visibility on a clip element", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="overlay" class="clip" data-start="0" data-duration="5" data-track-index="0">
-      <p>Overlay</p>
-    </div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#overlay", { visibility: "hidden", duration: 0.3 }, 2.0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.selector).toBe("#overlay");
-    expect(finding?.message).toContain("visibility");
-  });
-
-  it("ERRORS when GSAP animates display on a clip element", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="card" class="clip" data-start="0" data-duration="5" data-track-index="0">
-      <p>Card</p>
-    </div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#card", { display: "none", duration: 0.3 }, 3.0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.selector).toBe("#card");
-    expect(finding?.message).toContain("display");
-  });
-
-  it("ERRORS when GSAP tween mixes safe properties with visibility on a clip element", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="overlay" class="clip" data-start="0" data-duration="5" data-track-index="0">
-      <h1>Hello</h1>
-    </div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#overlay", { opacity: 0, visibility: "hidden", duration: 0.3 }, 2.0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_animates_clip_element");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.message).toContain("visibility");
-  });
-
-  it("warns when tl.to animates x on an element with CSS translateX", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="title" style=""></div>
-  </div>
-  <style>
-    #title { position: absolute; top: 240px; left: 50%; transform: translateX(-50%); }
-  </style>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#title", { x: 0, opacity: 1, duration: 0.4 }, 0.5);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.selector).toBe("#title");
-    expect(finding?.fixHint).toMatch(/fromTo/);
-    expect(finding?.fixHint).toMatch(/xPercent/);
-  });
-
-  it("warns when tl.to animates scale on an element with CSS scale transform", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="hero"></div>
-  </div>
-  <style>
-    #hero { transform: scale(0.8); opacity: 0; }
-  </style>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#hero", { opacity: 1, scale: 1, duration: 0.5 }, 1.0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.selector).toBe("#hero");
-  });
-
-  it("does NOT warn when tl.to targets element without CSS transform", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="card"></div>
-  </div>
-  <style>
-    #card { position: absolute; top: 100px; left: 100px; opacity: 0; }
-  </style>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#card", { x: 0, opacity: 1, duration: 0.3 }, 0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const conflict = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
-    expect(conflict).toBeUndefined();
-  });
-
-  it("does NOT warn when tl.fromTo targets element WITH CSS transform (author owns both ends)", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="title"></div>
-  </div>
-  <style>
-    #title { position: absolute; left: 50%; transform: translateX(-50%); }
-  </style>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.fromTo("#title", { xPercent: -50, x: -1000, opacity: 0 }, { xPercent: -50, x: 0, opacity: 1, duration: 0.4 }, 0.5);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const conflict = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
-    expect(conflict).toBeUndefined();
-  });
-
-  it("does NOT warn when tl.from targets element WITH CSS transform (from() owns start values)", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="badge"></div>
-  </div>
-  <style>
-    #badge { position: absolute; left: 50%; transform: translateX(-50%); }
-  </style>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.from("#badge", { xPercent: -50, x: -200, opacity: 0, duration: 0.4 }, 0.5);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const conflict = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
-    expect(conflict).toBeUndefined();
-  });
-
-  it("emits one warning when a combined CSS transform conflicts with multiple GSAP properties", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="hero"></div>
-  </div>
-  <style>
-    #hero { transform: translateX(-50%) scale(0.8); }
-  </style>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#hero", { x: 0, scale: 1, opacity: 1, duration: 0.5 }, 1.0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const conflicts = result.findings.filter((f) => f.code === "gsap_css_transform_conflict");
-    expect(conflicts).toHaveLength(1);
-    expect(conflicts[0]?.message).toMatch(/x\/scale|scale\/x/);
-  });
-
-  // --- Inline style transform detection tests ---
-
-  it("warns when inline style transform: translateX conflicts with GSAP x", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="centered" style="position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%);">Text</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#centered", { x: 0, y: 0, opacity: 1, duration: 0.4 }, 0.5);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
-    expect(finding).toBeDefined();
-    expect(finding?.selector).toBe("#centered");
-  });
-
-  it("warns when inline style transform: scale conflicts with GSAP scale", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="box" style="transform: scale(0.9);">Box</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#box", { scale: 1, duration: 0.5 }, 1.0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
-    expect(finding).toBeDefined();
-    expect(finding?.selector).toBe("#box");
-  });
-
-  it("does not false-positive on inline transform: rotate when GSAP uses rotation", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="spinner" style="transform: rotate(12deg);">Icon</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#spinner", { rotation: 360, duration: 1 }, 0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    // rotation doesn't conflict with rotate() — GSAP handles rotation separately
-    const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
-    expect(finding).toBeUndefined();
-  });
-
-  it("detects conflict via class selector when element has multiple classes", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div class="card hero" style="transform: translateX(-50%);">Card</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to(".hero", { x: 100, duration: 0.4 }, 0.5);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
-    expect(finding).toBeDefined();
-  });
-
-  it("handles both style block and inline style on same selector without crash", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="dual" style="transform: scale(0.5);">Dual</div>
-  </div>
-  <style>
-    #dual { transform: translateY(-50%); }
-  </style>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#dual", { y: 0, scale: 1, duration: 0.5 }, 0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const conflicts = result.findings.filter((f) => f.code === "gsap_css_transform_conflict");
-    expect(conflicts.length).toBeGreaterThanOrEqual(1);
-  });
-
-  it("detects conflict via a SCOPED descendant selector (tl.to)", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div class="lab">Label</div>
-  </div>
-  <style>
-    .lab { transform: translateX(-50%); }
-  </style>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#root .lab", { x: 40, opacity: 1, duration: 0.4 }, 0.5);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
-    expect(finding).toBeDefined();
-    expect(finding?.selector).toBe("#root .lab");
-  });
-
-  it("detects conflict via a standalone gsap.set with a GROUPED scoped selector", async () => {
-    // The exact shape that slipped through: centering seated with a standalone
-    // gsap.set on a grouped, #root-scoped selector, against a CSS class transform.
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div class="lab">A</div><div class="sub">B</div>
-  </div>
-  <style>
-    .lab { transform: translateX(-50%); }
-    .sub { transform: translateX(-50%); }
-  </style>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    gsap.set("#root .lab, #root .sub", { xPercent: -50 });
-    tl.to(".lab", { y: 0, opacity: 1, duration: 0.4 }, 0.5);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find(
-      (f) => f.code === "gsap_css_transform_conflict" && f.selector === "#root .lab, #root .sub",
-    );
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-  });
-
-  it("does NOT false-positive when a scoped selector targets a class WITHOUT a CSS transform", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div class="lab">Label</div>
-  </div>
-  <style>
-    .lab { opacity: 0; }
-  </style>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#root .lab", { x: 40, opacity: 1, duration: 0.4 }, 0.5);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const conflict = result.findings.find((f) => f.code === "gsap_css_transform_conflict");
-    expect(conflict).toBeUndefined();
-  });
-
-  it("reports error when GSAP is used without a GSAP script tag", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#box", { x: 100, duration: 1 }, 0);
-    window.__timelines["main"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.message).toContain("GSAP");
-  });
-
-  it("does not report missing_gsap_script when GSAP CDN script is present", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></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("#box", { x: 100, duration: 1 }, 0);
-    window.__timelines["main"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does not report missing_gsap_script when GSAP is bundled inline", async () => {
-    // Simulate a large inline GSAP bundle (>5KB) with GreenSock marker
-    const fakeGsapLib = "/* GreenSock GSAP */" + " ".repeat(6000);
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
-  <script>${fakeGsapLib}</script>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#box", { x: 100, duration: 1 }, 0);
-    window.__timelines["main"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does not report missing_gsap_script when producer inlined CDN script", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
-  <script>/* inlined: https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js */
-    !function(t,e){t.gsap=e()}(this,function(){return {}});
-  </script>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#box", { x: 100, duration: 1 }, 0);
-    window.__timelines["main"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
-    expect(finding).toBeUndefined();
-  });
-
-  it("still reports missing_gsap_script for small inline scripts that use but don't bundle GSAP", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#box", { x: 100, duration: 1 }, 0);
-    window.__timelines["main"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "missing_gsap_script");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-  });
-
-  it("errors on repeat: -1 (infinite repeat breaks capture engine)", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></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("#spinner", { rotation: 360, duration: 0.8, repeat: -1, ease: "none" }, 0);
-    window.__timelines["main"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_infinite_repeat");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.message).toContain("repeat: -1");
-  });
-
-  it("does not error on finite repeat values", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></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("#spinner", { rotation: 360, duration: 0.8, repeat: 4, ease: "none" }, 0);
-    window.__timelines["main"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_infinite_repeat");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does not error on repeat: -1 inside JavaScript comments", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></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 });
-    // avoid repeat:-1 anywhere in user code
-    /*
-      This rule should still allow comments mentioning repeat: -1.
-    */
-    tl.to("#spinner", { rotation: 360, duration: 0.8, repeat: 4, ease: "none" }, 0);
-    window.__timelines["main"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_infinite_repeat");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does NOT report overlapping_gsap_tweens when an object-target tween is interleaved (regression)", async () => {
-    // Regression: a non-DOM-targeting tween like `tl.to({ _: 0 }, …)` (used to
-    // anchor timeline duration) was matched by the regex but skipped by the
-    // parser, drifting the index and making the second tween "see" the first
-    // tween's selector — producing a phantom self-overlap warning.
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="a" class="clip" data-start="0" data-duration="5" data-track-index="0"></div>
-    <div id="b" class="clip" data-start="0" data-duration="5" data-track-index="1"></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({ _: 0 }, { _: 1, duration: 5, ease: "none" }, 0);
-    tl.to("#a", { opacity: 1, duration: 0.5 }, 0);
-    tl.to("#b", { opacity: 1, duration: 0.5 }, 1);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "overlapping_gsap_tweens");
-    expect(finding).toBeUndefined();
-  });
-
-  it("detects overlapping_gsap_tweens between variable-target tweens", async () => {
-    // Both tweens target the same element via a querySelector variable and their
-    // windows overlap on `opacity`. The structure-driven window builder must see
-    // through the variable target to flag the conflict.
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="hero" class="hero" data-start="0" data-duration="5" data-track-index="0"></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 });
-    const hero = document.querySelector("#hero");
-    tl.to(hero, { opacity: 1, duration: 1 }, 0);
-    tl.to(hero, { opacity: 0.5, duration: 1 }, 0.5);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "overlapping_gsap_tweens");
-    expect(finding).toBeDefined();
-  });
-
-  it("warns when an opacity exit ends at a clip start boundary without a hard kill", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0" data-duration="6">
-    <div id="scene-a" class="clip" data-start="0" data-duration="3" data-track-index="0">
-      <h1 id="headline">First beat</h1>
-    </div>
-    <div id="scene-b" class="clip" data-start="3" data-duration="3" data-track-index="0">
-      <h1>Second beat</h1>
-    </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("#headline", { opacity: 0, duration: 0.3 }, 2.7);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_exit_missing_hard_kill");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.selector).toBe("#headline");
-    expect(finding?.message).toContain("3.00s");
-  });
-
-  it("does not warn when a boundary exit has a matching hard kill", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0" data-duration="6">
-    <div id="scene-a" class="clip" data-start="0" data-duration="3" data-track-index="0">
-      <h1 id="headline">First beat</h1>
-    </div>
-    <div id="scene-b" class="clip" data-start="3" data-duration="3" data-track-index="0">
-      <h1>Second beat</h1>
-    </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("#headline", { opacity: 0, duration: 0.3 }, 2.7);
-    tl.set("#headline", { opacity: 0, visibility: "hidden" }, 3);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_exit_missing_hard_kill");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does not match sub-composition exits against root clip boundaries", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="root" data-width="1920" data-height="1080" data-start="0" data-duration="6">
-    <div id="root-a" class="clip" data-start="0" data-duration="3" data-track-index="0"></div>
-    <div id="root-b" class="clip" data-start="3" data-duration="3" data-track-index="0"></div>
-  </div>
-  <div data-composition-id="sub" data-width="1920" data-height="1080" data-start="0" data-duration="4">
-    <div id="sub-a" class="clip" data-start="0" data-duration="2" data-track-index="0">
-      <h1 id="sub-title">Sub scene</h1>
-    </div>
-    <div id="sub-b" class="clip" data-start="2" data-duration="2" data-track-index="0"></div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#sub-title", { opacity: 0, duration: 0.3 }, 2.7);
-    window.__timelines["sub"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_exit_missing_hard_kill");
-    expect(finding).toBeUndefined();
-  });
-
-  it("uses the authored hidden property in hard-kill fix hints", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0" data-duration="6">
-    <div id="scene-a" class="clip" data-start="0" data-duration="3" data-track-index="0">
-      <h1 id="headline">First beat</h1>
-    </div>
-    <div id="scene-b" class="clip" data-start="3" data-duration="3" data-track-index="0">
-      <h1>Second beat</h1>
-    </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("#headline", { autoAlpha: 0, duration: 0.3 }, 2.7);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_exit_missing_hard_kill");
-    expect(finding?.fixHint).toContain("{ autoAlpha: 0 }");
-  });
-
-  it("does not false-positive on repeat: -10 (invalid GSAP but not infinite)", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080"></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("#box", { x: 100, duration: 1, repeat: -10 }, 0);
-    window.__timelines["main"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_infinite_repeat");
-    expect(finding).toBeUndefined();
-  });
-
-  it("errors when CSS opacity:0 + gsap.from({opacity:0}) — invisible forever", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="title" style="opacity: 0; font-size: 120px;">Hello</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.from("#title", { opacity: 0, y: 30, duration: 0.5 }, 0.2);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
-    expect(finding).toBeDefined();
-    expect(finding!.severity).toBe("error");
-    expect(finding!.selector).toBe("#title");
-  });
-
-  it("errors when style block has opacity:0 + gsap.from({opacity:0})", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="hero">Hello</div>
-  </div>
-  <style>
-    #hero { font-size: 200px; color: #fff; opacity: 0; }
-  </style>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.from("#hero", { opacity: 0, scale: 3.5, duration: 0.25, ease: "expo.out" }, 0.1);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
-    expect(finding).toBeDefined();
-  });
-
-  it("does NOT error when gsap.from({opacity:0}) and CSS has no opacity:0", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="title" style="font-size: 120px; color: #fff;">Hello</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.from("#title", { opacity: 0, y: 30, duration: 0.5 }, 0.2);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does NOT error when gsap.fromTo({opacity:0}, {opacity:1}) — destination overrides CSS", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="title" style="opacity: 0; font-size: 120px;">Hello</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.fromTo("#title", { opacity: 0, y: 30 }, { opacity: 1, y: 0, duration: 0.5 }, 0.2);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does NOT error when gsap.to() uses opacity:0 (exit animation)", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="title" style="opacity: 0;">Hello</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#title", { opacity: 0, duration: 0.5 }, 4.0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does NOT error when gsap.from({opacity: 0.5}) — non-zero opacity is a valid reveal", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="ghost" style="opacity: 0;">Hello</div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.from("#ghost", { opacity: 0.5, duration: 0.4 }, 0.1);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
-    expect(finding).toBeUndefined();
-  });
-
-  it("warns when gsap.timeline is created but not registered in __timelines", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="root" data-width="1920" data-height="1080">
-    <div id="box">Hello</div>
-  </div>
-  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
-  <script>
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#box", { opacity: 0.5, duration: 2 });
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_timeline_not_registered");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-  });
-
-  it("does NOT warn when timeline is registered in __timelines", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="root" data-width="1920" data-height="1080">
-    <div id="box">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("#box", { opacity: 0.5, duration: 2 });
-    window.__timelines["root"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_timeline_not_registered");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does NOT warn when timeline is registered with dot property syntax", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="root" data-width="1920" data-height="1080">
-    <div id="box">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("#box", { opacity: 0.5, duration: 2 });
-    window.__timelines.root = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_timeline_not_registered");
-    expect(finding).toBeUndefined();
-  });
-
-  it("does NOT warn for sub-compositions (template-based)", async () => {
-    const html = `
-<template>
-  <div data-composition-id="sub" data-width="1920" data-height="1080">
-    <div id="box">Hello</div>
-  </div>
-  <script>
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#box", { opacity: 0.5, duration: 2 });
-  </script>
-</template>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "gsap_timeline_not_registered");
-    expect(finding).toBeUndefined();
-  });
-
-  it("scene_layer_missing_visibility_kill: fires when multi-scene exit lacks hard kill", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="scene1"></div>
-    <div id="scene2"></div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#scene1", { opacity: 0, duration: 0.5 }, 2.0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "scene_layer_missing_visibility_kill");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.elementId).toBe("scene1");
-  });
-
-  it("scene_layer_missing_visibility_kill: DOES fire when kill is only in a comment (stripJsComments guard)", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="scene1"></div>
-    <div id="scene2"></div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    // tl.set("#scene1", { visibility: "hidden" }, 2.5);
-    tl.to("#scene1", { opacity: 0, duration: 0.5 }, 2.0);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "scene_layer_missing_visibility_kill");
-    expect(finding).toBeDefined();
-  });
-
-  it("scene_layer_missing_visibility_kill: does NOT fire when hard kill is present", async () => {
-    const html = `
-<html><body>
-  <div data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="scene1"></div>
-    <div id="scene2"></div>
-  </div>
-  <script>
-    window.__timelines = window.__timelines || {};
-    const tl = gsap.timeline({ paused: true });
-    tl.to("#scene1", { opacity: 0, duration: 0.5 }, 2.0);
-    tl.set("#scene1", { visibility: "hidden" }, 2.5);
-    window.__timelines["c1"] = tl;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "scene_layer_missing_visibility_kill");
-    expect(finding).toBeUndefined();
-  });
-});
diff --git a/packages/core/src/lint/rules/gsap.ts b/packages/core/src/lint/rules/gsap.ts
deleted file mode 100644
index ef792db500..0000000000
--- a/packages/core/src/lint/rules/gsap.ts
+++ /dev/null
@@ -1,1142 +0,0 @@
-interface LintParsedGsap {
-  animations: Array<{
-    targetSelector: string;
-    method: string;
-    position: number | string;
-    properties: Record<string, number | string>;
-    duration?: number;
-    ease?: string;
-    extras?: Record<string, unknown>;
-  }>;
-  timelineVar: string;
-}
-
-// Use the acorn read parser: it resolves computed timelines (helpers, bounded
-// loops) so lint findings like overlapping_gsap_tweens reflect true positions
-// instead of all-collapsed-at-0. It's also browser-safe, so this keeps recast
-// out of the lint graph entirely. Dynamic import preserves the lazy load.
-async function loadParseGsapScript(): Promise<(script: string) => LintParsedGsap> {
-  const mod = await import("@hyperframes/parsers/gsap-parser-acorn");
-  return mod.parseGsapScriptAcorn as unknown as (script: string) => LintParsedGsap;
-}
-import type { LintContext } from "../context";
-import type { HyperframeLintFinding, LintRule } from "../types";
-import type { OpenTag } from "../utils";
-import {
-  readAttr,
-  truncateSnippet,
-  stripJsComments,
-  WINDOW_TIMELINE_ASSIGN_PATTERN,
-} from "../utils";
-
-// ── GSAP-specific types ────────────────────────────────────────────────────
-
-type GsapWindow = {
-  targetSelector: string;
-  position: number;
-  end: number;
-  properties: string[];
-  propertyValues: Record<string, string | number>;
-  overwriteAuto: boolean;
-  method: string;
-  raw: string;
-};
-
-type CompositionRange = {
-  id: string;
-  start: number;
-  end: number;
-};
-
-const SCENE_BOUNDARY_EPSILON_SECONDS = 0.05;
-
-// ── GSAP parsing utilities ─────────────────────────────────────────────────
-
-function countClassUsage(tags: OpenTag[]): Map<string, number> {
-  const counts = new Map<string, number>();
-  for (const tag of tags) {
-    const classAttr = readAttr(tag.raw, "class");
-    if (!classAttr) continue;
-    for (const className of classAttr.split(/\s+/).filter(Boolean)) {
-      counts.set(className, (counts.get(className) || 0) + 1);
-    }
-  }
-  return counts;
-}
-
-function readRegisteredTimelineCompositionId(script: string): string | null {
-  const match = script.match(WINDOW_TIMELINE_ASSIGN_PATTERN);
-  return match?.[1] || match?.[2] || null;
-}
-
-/** Strip a `__raw:` prefix the parser adds to unresolvable values. */
-function unwrapRaw(value: unknown): string | number | undefined {
-  if (typeof value === "number") return value;
-  if (typeof value !== "string") return undefined;
-  const code = value.startsWith("__raw:") ? value.slice(6) : value;
-  return code.replace(/^\s*["']|["']\s*$/g, "");
-}
-
-function extrasNumber(value: unknown): number {
-  const unwrapped = unwrapRaw(value);
-  const numeric = typeof unwrapped === "number" ? unwrapped : Number(unwrapped);
-  return Number.isFinite(numeric) ? numeric : 0;
-}
-
-/** A readable single-line snippet of a tween for finding messages. */
-function synthesizeWindowRaw(
-  timelineVar: string,
-  anim: LintParsedGsap["animations"][number],
-): string {
-  const entries = Object.entries(anim.properties).map(([k, v]) => {
-    if (typeof v === "string" && v.startsWith("__raw:")) return `${k}: ${v.slice(6)}`;
-    return `${k}: ${typeof v === "string" ? JSON.stringify(v) : v}`;
-  });
-  if (anim.duration !== undefined) entries.push(`duration: ${anim.duration}`);
-  if (anim.ease) entries.push(`ease: ${JSON.stringify(anim.ease)}`);
-  const pos = typeof anim.position === "number" ? anim.position : JSON.stringify(anim.position);
-  return `${timelineVar}.${anim.method}("${anim.targetSelector}", { ${entries.join(", ")} }, ${pos})`;
-}
-
-const gsapWindowsCache = new Map<string, GsapWindow[]>();
-
-async function cachedExtractGsapWindows(scriptContent: string): Promise<GsapWindow[]> {
-  const cached = gsapWindowsCache.get(scriptContent);
-  if (cached) return cached;
-  const windows = await extractGsapWindows(scriptContent);
-  gsapWindowsCache.set(scriptContent, windows);
-  return windows;
-}
-
-// fallow-ignore-next-line complexity
-async function extractGsapWindows(script: string): Promise<GsapWindow[]> {
-  if (!/gsap\.timeline/.test(script)) return [];
-  const parseGsapScript = await loadParseGsapScript();
-  const parsed = parseGsapScript(script);
-  if (parsed.animations.length === 0) return [];
-
-  const windows: GsapWindow[] = [];
-  for (const animation of parsed.animations) {
-    // Skip animations with string positions (e.g. "+=1", "<") — their absolute
-    // timing depends on runtime evaluation and can't be statically linted.
-    if (typeof animation.position !== "number") continue;
-    const repeat = extrasNumber(animation.extras?.repeat);
-    const cycleCount = repeat > 0 ? repeat + 1 : 1;
-    const effectiveDuration =
-      animation.method === "set" ? 0 : (animation.duration ?? 0) * cycleCount;
-    windows.push({
-      targetSelector: animation.targetSelector,
-      position: animation.position,
-      end: animation.position + effectiveDuration,
-      properties: Object.keys(animation.properties),
-      propertyValues: animation.properties,
-      overwriteAuto: unwrapRaw(animation.extras?.overwrite) === "auto",
-      method: animation.method,
-      raw: synthesizeWindowRaw(parsed.timelineVar, animation),
-    });
-  }
-  return windows;
-}
-
-function numberValue(value: string | number | undefined): number | null {
-  if (typeof value === "number") return value;
-  if (typeof value === "string" && value.trim()) {
-    const numeric = Number(value);
-    return Number.isFinite(numeric) ? numeric : null;
-  }
-  return null;
-}
-
-function stringValue(value: string | number | undefined): string | null {
-  if (typeof value === "string") return value;
-  if (typeof value === "number") return String(value);
-  return null;
-}
-
-function zeroValue(value: string | number | undefined): boolean {
-  if (typeof value === "number") return value === 0;
-  if (typeof value !== "string") return false;
-  return Number(value.trim()) === 0;
-}
-
-function isHiddenGsapState(values: Record<string, string | number>): boolean {
-  const visibility = stringValue(values.visibility)?.toLowerCase();
-  const display = stringValue(values.display)?.toLowerCase();
-  return (
-    zeroValue(values.opacity) ||
-    zeroValue(values.autoAlpha) ||
-    visibility === "hidden" ||
-    display === "none"
-  );
-}
-
-function oneValue(
-  values: Record<string, string | number>,
-  keys: string[],
-): string | number | undefined {
-  for (const key of keys) {
-    const value = values[key];
-    if (value !== undefined) return value;
-  }
-  return undefined;
-}
-
-function isVisibleGsapState(values: Record<string, string | number>): boolean {
-  const opacity = oneValue(values, ["opacity", "autoAlpha"]);
-  if (typeof opacity === "number") return opacity > 0;
-  if (typeof opacity === "string" && opacity.trim()) {
-    const numeric = Number(opacity);
-    if (Number.isFinite(numeric)) return numeric > 0;
-  }
-
-  const visibility = stringValue(values.visibility)?.toLowerCase();
-  if (visibility === "visible" || visibility === "inherit") return true;
-
-  const display = stringValue(values.display)?.toLowerCase();
-  if (display && display !== "none") return true;
-
-  return false;
-}
-
-function makesOverlayVisible(win: GsapWindow): boolean {
-  if (win.method === "from" && isHiddenGsapState(win.propertyValues)) return true;
-  return isVisibleGsapState(win.propertyValues);
-}
-
-function isSceneBoundaryExit(win: GsapWindow): boolean {
-  if (win.end <= win.position) return false;
-  if (win.method !== "to" && win.method !== "fromTo") return false;
-  return isHiddenGsapState(win.propertyValues);
-}
-
-function isHardKillSet(win: GsapWindow, selector: string, boundary: number): boolean {
-  return (
-    win.method === "set" &&
-    win.targetSelector === selector &&
-    Math.abs(win.position - boundary) <= SCENE_BOUNDARY_EPSILON_SECONDS &&
-    isHiddenGsapState(win.propertyValues)
-  );
-}
-
-function hiddenStateLiteral(values: Record<string, string | number>): string {
-  if (zeroValue(values.autoAlpha)) return "{ autoAlpha: 0 }";
-  if (zeroValue(values.opacity)) return "{ opacity: 0 }";
-  if (stringValue(values.visibility)?.toLowerCase() === "hidden") return '{ visibility: "hidden" }';
-  if (stringValue(values.display)?.toLowerCase() === "none") return '{ display: "none" }';
-  return "{ opacity: 0 }";
-}
-
-function findTagEnd(source: string, tag: OpenTag): number {
-  const escapedTagName = tag.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const pattern = new RegExp(`<\\/?${escapedTagName}\\b[^>]*>`, "gi");
-  pattern.lastIndex = tag.index;
-
-  let depth = 0;
-  let match: RegExpExecArray | null;
-  while ((match = pattern.exec(source)) !== null) {
-    const raw = match[0];
-    const isClosing = /^<\s*\//.test(raw);
-    const isSelfClosing = /\/\s*>$/.test(raw);
-    if (!isClosing && !isSelfClosing) depth += 1;
-    if (isClosing) depth -= 1;
-    if (depth === 0) return pattern.lastIndex;
-  }
-
-  return source.length;
-}
-
-function collectCompositionRanges(source: string, tags: OpenTag[]): CompositionRange[] {
-  return tags
-    .map((tag) => {
-      const id = readAttr(tag.raw, "data-composition-id");
-      if (!id) return null;
-      return {
-        id,
-        start: tag.index,
-        end: findTagEnd(source, tag),
-      };
-    })
-    .filter((range) => range !== null);
-}
-
-function findContainingCompositionId(tag: OpenTag, ranges: CompositionRange[]): string | null {
-  let match: CompositionRange | null = null;
-  for (const range of ranges) {
-    if (tag.index < range.start || tag.index >= range.end) continue;
-    if (!match || range.start >= match.start) match = range;
-  }
-  return match?.id || null;
-}
-
-function collectClipStartBoundariesByComposition(
-  source: string,
-  tags: OpenTag[],
-): Map<string, number[]> {
-  const ranges = collectCompositionRanges(source, tags);
-  const boundaries = new Map<string, Set<number>>();
-
-  for (const tag of tags) {
-    const classAttr = readAttr(tag.raw, "class") || "";
-    const classes = classAttr.split(/\s+/).filter(Boolean);
-    if (!classes.includes("clip")) continue;
-    const compositionId = findContainingCompositionId(tag, ranges);
-    if (!compositionId) continue;
-    const start = numberValue(readAttr(tag.raw, "data-start") ?? undefined);
-    if (start == null || start <= 0) continue;
-    const compositionBoundaries = boundaries.get(compositionId) ?? new Set<number>();
-    compositionBoundaries.add(start);
-    boundaries.set(compositionId, compositionBoundaries);
-  }
-
-  return new Map(
-    [...boundaries.entries()].map(([compositionId, values]) => [
-      compositionId,
-      [...values].sort((a, b) => a - b),
-    ]),
-  );
-}
-
-function findMatchingSceneBoundary(time: number, boundaries: number[]): number | null {
-  for (const boundary of boundaries) {
-    if (Math.abs(time - boundary) <= SCENE_BOUNDARY_EPSILON_SECONDS) return boundary;
-  }
-  return null;
-}
-
-function isSuspiciousGlobalSelector(selector: string): boolean {
-  if (!selector) return false;
-  if (selector.includes("[data-composition-id=")) return false;
-  if (selector.startsWith("#")) return false;
-  return selector.startsWith(".") || /^[a-z]/i.test(selector);
-}
-
-function getSingleClassSelector(selector: string): string | null {
-  const match = selector.trim().match(/^\.(?<name>[A-Za-z0-9_-]+)$/);
-  return match?.groups?.name || null;
-}
-
-function readStyleProperty(style: string, property: string): string | null {
-  const escapedProperty = property.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const match = style.match(new RegExp(`(?:^|;)\\s*${escapedProperty}\\s*:\\s*([^;]+)`, "i"));
-  return match?.[1]?.trim() || null;
-}
-
-function cssZero(value: string | null): boolean {
-  if (!value) return false;
-  return /^0(?:\.0+)?(?:px|%|vw|vh|rem|em)?$/i.test(value.trim());
-}
-
-function styleHasHiddenInitialState(style: string): boolean {
-  const opacity = readStyleProperty(style, "opacity");
-  if (opacity && Number(opacity) === 0) return true;
-  if (readStyleProperty(style, "visibility")?.toLowerCase() === "hidden") return true;
-  if (readStyleProperty(style, "display")?.toLowerCase() === "none") return true;
-  return false;
-}
-
-function styleHasOpaqueBackground(style: string): boolean {
-  const background =
-    readStyleProperty(style, "background") || readStyleProperty(style, "background-color");
-  if (!background) return false;
-  const normalized = background.toLowerCase().replace(/\s+/g, "");
-  if (normalized === "transparent" || normalized === "none") return false;
-  if (/rgba?\([^)]*,0(?:\.0+)?\)$/.test(normalized)) return false;
-  if (/hsla?\([^)]*,0(?:\.0+)?\)$/.test(normalized)) return false;
-  return true;
-}
-
-function styleLooksFullFrameOverlay(style: string): boolean {
-  const position = readStyleProperty(style, "position")?.toLowerCase();
-  if (position !== "fixed" && position !== "absolute") return false;
-  const coversFrame =
-    cssZero(readStyleProperty(style, "inset")) ||
-    (cssZero(readStyleProperty(style, "top")) &&
-      cssZero(readStyleProperty(style, "right")) &&
-      cssZero(readStyleProperty(style, "bottom")) &&
-      cssZero(readStyleProperty(style, "left")));
-  return coversFrame && styleHasOpaqueBackground(style);
-}
-
-function collectSimpleStyleRules(styles: LintContext["styles"]): Map<string, string> {
-  const rules = new Map<string, string>();
-  for (const style of styles) {
-    for (const [, selectorList, body] of style.content.matchAll(/([^{}]+)\{([^}]+)\}/g)) {
-      if (!selectorList || !body) continue;
-      for (const selector of selectorList.split(",")) {
-        const token = selector.trim();
-        if (!/^[#.][A-Za-z0-9_-]+$/.test(token)) continue;
-        rules.set(token, `${rules.get(token) || ""};${body}`);
-      }
-    }
-  }
-  return rules;
-}
-
-function tagSimpleSelectors(tag: OpenTag): string[] {
-  const selectors: string[] = [];
-  const id = readAttr(tag.raw, "id");
-  if (id) selectors.push(`#${id}`);
-  const classes = readAttr(tag.raw, "class")?.split(/\s+/).filter(Boolean) ?? [];
-  for (const className of classes) selectors.push(`.${className}`);
-  return selectors;
-}
-
-function combinedTagStyle(tag: OpenTag, styleRules: Map<string, string>): string {
-  const styles = [readAttr(tag.raw, "style") || ""];
-  for (const selector of tagSimpleSelectors(tag)) {
-    const ruleStyle = styleRules.get(selector);
-    if (ruleStyle) styles.push(ruleStyle);
-  }
-  return styles.filter(Boolean).join(";");
-}
-
-// fallow-ignore-next-line complexity
-function cssTransformToGsapProps(cssTransform: string): string | null {
-  const parts: string[] = [];
-
-  // translate(-50%, -50%) or translate(X, Y)
-  const translateMatch = cssTransform.match(
-    /translate\(\s*(-?[\d.]+)(%|px)?\s*,\s*(-?[\d.]+)(%|px)?\s*\)/,
-  );
-  if (translateMatch) {
-    const [, xVal, xUnit, yVal, yUnit] = translateMatch;
-    if (xUnit === "%") parts.push(`xPercent: ${xVal}`);
-    else parts.push(`x: ${xVal}`);
-    if (yUnit === "%") parts.push(`yPercent: ${yVal}`);
-    else parts.push(`y: ${yVal}`);
-  }
-
-  // translateX(-50%) or translateX(px)
-  const txMatch = cssTransform.match(/translateX\(\s*(-?[\d.]+)(%|px)?\s*\)/);
-  if (txMatch) {
-    const [, val, unit] = txMatch;
-    parts.push(unit === "%" ? `xPercent: ${val}` : `x: ${val}`);
-  }
-
-  // translateY(-50%) or translateY(px)
-  const tyMatch = cssTransform.match(/translateY\(\s*(-?[\d.]+)(%|px)?\s*\)/);
-  if (tyMatch) {
-    const [, val, unit] = tyMatch;
-    parts.push(unit === "%" ? `yPercent: ${val}` : `y: ${val}`);
-  }
-
-  // scale(N)
-  const scaleMatch = cssTransform.match(/scale\(\s*([\d.]+)\s*\)/);
-  if (scaleMatch) {
-    parts.push(`scale: ${scaleMatch[1]}`);
-  }
-
-  return parts.length > 0 ? parts.join(", ") : null;
-}
-
-// ── CSS-transform ↔ GSAP-transform conflict matching ─────────────────────────
-
-// Transform components that COMBINE with a CSS translate/scale on the same
-// element. GSAP bakes the element's existing CSS transform in when it seeks, so
-// these stack rather than override in the capture path (e.g. CSS translateX(-50%)
-// + xPercent:-50 renders as -100% — off-centre). `rotation` is excluded: it maps
-// to CSS rotate(), which this rule treats separately (no false positive on spin).
-const CONFLICTING_TRANSLATE_PROPS = ["x", "y", "xPercent", "yPercent"];
-const CONFLICTING_SCALE_PROPS = ["scale", "scaleX", "scaleY"];
-
-type GsapTransformCall = {
-  method: string;
-  selector: string;
-  properties: string[];
-  raw: string;
-};
-
-// Decompose a (possibly grouped / descendant / compound) GSAP target selector
-// into the simple `#id` / `.class` tokens of the elements it actually targets —
-// the RIGHTMOST compound of each comma group is the targeted element. This lets a
-// CSS rule keyed by a simple selector (`.m04-label`) match a scoped GSAP selector
-// (`"#root .m04-label, #root .m04-sub"`), which the prior exact-string lookup
-// missed — so every scoped/grouped selector slipped past the rule entirely.
-function targetedSelectorTokens(selector: string): Set<string> {
-  const tokens = new Set<string>();
-  for (const group of selector.split(",")) {
-    const compounds = group
-      .trim()
-      .split(/[\s>+~]+/)
-      .filter(Boolean);
-    const last = compounds[compounds.length - 1];
-    if (!last) continue;
-    const simple = last.match(/[#.][A-Za-z0-9_-]+/g);
-    if (simple) for (const token of simple) tokens.add(token);
-  }
-  return tokens;
-}
-
-// Find a CSS transform conflicting with a GSAP target selector: exact-string
-// match first (fast path + back-compat with the original behaviour), then a
-// token match so scoped/grouped/descendant selectors resolve to their class/id.
-function matchCssTransform(gsapSelector: string, cssMap: Map<string, string>): string | undefined {
-  if (cssMap.size === 0) return undefined;
-  const direct = cssMap.get(gsapSelector);
-  if (direct) return direct;
-  const tokens = targetedSelectorTokens(gsapSelector);
-  for (const [cssSelector, value] of cssMap) {
-    if (tokens.has(cssSelector)) return value;
-  }
-  return undefined;
-}
-
-// Scan for STANDALONE `gsap.set/to/from/fromTo("selector", { ...props })` calls.
-// The acorn timeline parser only captures calls rooted on the timeline var
-// (`tl.to`, `tl.set`, …); a top-level `gsap.set("#root .label", { xPercent: -50 })`
-// — a common way to seat shared base transforms before the timeline runs — is
-// invisible to it, so the conflict rule never saw it. Variable selectors
-// (`gsap.set(kicker, …)`) can't be resolved statically and are skipped.
-function extractStandaloneGsapTransformCalls(script: string): GsapTransformCall[] {
-  const calls: GsapTransformCall[] = [];
-  const pattern = /gsap\.(set|to|from|fromTo)\s*\(\s*(["'])([^"']+)\2\s*,\s*\{([^{}]*)\}/g;
-  let match: RegExpExecArray | null;
-  while ((match = pattern.exec(script)) !== null) {
-    const method = match[1] ?? "set";
-    const selector = match[3] ?? "";
-    const propsBody = match[4] ?? "";
-    const properties = [...propsBody.matchAll(/([A-Za-z_$][\w$]*)\s*:/g)].map((m) => m[1] ?? "");
-    calls.push({ method, selector, properties, raw: truncateSnippet(match[0]) ?? match[0] });
-  }
-  return calls;
-}
-
-// ── GSAP rules ─────────────────────────────────────────────────────────────
-
-// fallow-ignore-next-line complexity
-export const gsapRules: LintRule<LintContext>[] = [
-  // overlapping_gsap_tweens + gsap_animates_clip_element + unscoped_gsap_selector
-  // fallow-ignore-next-line complexity
-  async ({ source, tags, scripts, styles, rootCompositionId }) => {
-    const findings: HyperframeLintFinding[] = [];
-
-    // Build clip element selector map
-    type ClipInfo = { tag: string; id: string; classes: string };
-    const clipIds = new Map<string, ClipInfo>();
-    const clipClasses = new Map<string, ClipInfo>();
-    for (const tag of tags) {
-      const classAttr = readAttr(tag.raw, "class") || "";
-      const classes = classAttr.split(/\s+/).filter(Boolean);
-      if (!classes.includes("clip")) continue;
-      const id = readAttr(tag.raw, "id");
-      const info: ClipInfo = {
-        tag: tag.name,
-        id: id || "",
-        classes: classAttr,
-      };
-      if (id) clipIds.set(`#${id}`, info);
-      for (const cls of classes) {
-        if (cls !== "clip") clipClasses.set(`.${cls}`, info);
-      }
-    }
-
-    const classUsage = countClassUsage(tags);
-    const clipStartBoundariesByComposition = collectClipStartBoundariesByComposition(source, tags);
-    const styleRules = collectSimpleStyleRules(styles);
-    const reportedVisibleOverlayKeys = new Set<string>();
-
-    for (const script of scripts) {
-      const localTimelineCompId = readRegisteredTimelineCompositionId(script.content);
-      const gsapWindows = await cachedExtractGsapWindows(script.content);
-      const clipStartBoundaries =
-        clipStartBoundariesByComposition.get(localTimelineCompId || rootCompositionId || "") ?? [];
-
-      // overlapping_gsap_tweens
-      for (let i = 0; i < gsapWindows.length; i++) {
-        const left = gsapWindows[i];
-        if (!left) continue;
-        if (left.end <= left.position) continue;
-        for (let j = i + 1; j < gsapWindows.length; j++) {
-          const right = gsapWindows[j];
-          if (!right) continue;
-          if (right.end <= right.position) continue;
-          if (left.targetSelector !== right.targetSelector) continue;
-          const overlapStart = Math.max(left.position, right.position);
-          const overlapEnd = Math.min(left.end, right.end);
-          if (overlapEnd <= overlapStart) continue;
-          if (left.overwriteAuto || right.overwriteAuto) continue;
-          const sharedProperties = left.properties.filter((prop) =>
-            right.properties.includes(prop),
-          );
-          if (sharedProperties.length === 0) continue;
-          findings.push({
-            code: "overlapping_gsap_tweens",
-            severity: "warning",
-            message: `GSAP tweens overlap on "${left.targetSelector}" for ${sharedProperties.join(", ")} between ${overlapStart.toFixed(2)}s and ${overlapEnd.toFixed(2)}s.`,
-            selector: left.targetSelector,
-            fixHint: 'Shorten the earlier tween, move the later tween, or add `overwrite: "auto"`.',
-            snippet: truncateSnippet(`${left.raw}\n${right.raw}`),
-          });
-        }
-      }
-
-      // gsap_exit_missing_hard_kill
-      if (clipStartBoundaries.length > 0) {
-        for (const win of gsapWindows) {
-          if (!isSceneBoundaryExit(win)) continue;
-          const boundary = findMatchingSceneBoundary(win.end, clipStartBoundaries);
-          if (boundary == null) continue;
-          const hasHardKill = gsapWindows.some((candidate) =>
-            isHardKillSet(candidate, win.targetSelector, boundary),
-          );
-          if (hasHardKill) continue;
-
-          findings.push({
-            code: "gsap_exit_missing_hard_kill",
-            severity: "error",
-            message:
-              `GSAP exit on "${win.targetSelector}" ends at the ${boundary.toFixed(2)}s clip start boundary ` +
-              "without a matching tl.set hard kill. Non-linear seeking can land after the fade and leave stale visibility state.",
-            selector: win.targetSelector,
-            fixHint:
-              `Add \`tl.set("${win.targetSelector}", ${hiddenStateLiteral(win.propertyValues)}, ${boundary.toFixed(2)})\` ` +
-              "after the exit tween.",
-            snippet: truncateSnippet(win.raw),
-          });
-        }
-      }
-
-      // gsap_fullscreen_overlay_starts_visible
-      for (const tag of tags) {
-        const selectors = tagSimpleSelectors(tag);
-        if (selectors.length === 0) continue;
-        const overlayKey = readAttr(tag.raw, "id") || String(tag.index);
-        if (reportedVisibleOverlayKeys.has(overlayKey)) continue;
-        const authoredStyle = combinedTagStyle(tag, styleRules);
-        if (!authoredStyle || !styleLooksFullFrameOverlay(authoredStyle)) continue;
-        if (styleHasHiddenInitialState(authoredStyle)) continue;
-
-        const visibilityWindows = gsapWindows
-          .filter((win) => {
-            const tokens = targetedSelectorTokens(win.targetSelector);
-            if (!selectors.some((selector) => tokens.has(selector))) return false;
-            return win.properties.some((prop) =>
-              ["opacity", "autoAlpha", "visibility", "display"].includes(prop),
-            );
-          })
-          .sort((a, b) => a.position - b.position);
-        const startsHiddenAtZero = visibilityWindows.some(
-          (win) =>
-            win.position <= SCENE_BOUNDARY_EPSILON_SECONDS && isHiddenGsapState(win.propertyValues),
-        );
-        if (startsHiddenAtZero) continue;
-        const firstVisible = visibilityWindows.find((win) => makesOverlayVisible(win));
-        if (!firstVisible) continue;
-        const selector =
-          selectors.find((candidate) =>
-            targetedSelectorTokens(firstVisible.targetSelector).has(candidate),
-          ) ||
-          selectors[0] ||
-          tag.name;
-        const laterHidden = visibilityWindows.some(
-          (win) => win.position >= firstVisible.position && isHiddenGsapState(win.propertyValues),
-        );
-        if (firstVisible.method !== "from" && !laterHidden) continue;
-
-        reportedVisibleOverlayKeys.add(overlayKey);
-        findings.push({
-          code: "gsap_fullscreen_overlay_starts_visible",
-          severity: "error",
-          message:
-            `Full-frame overlay "${selector}" starts visible before its first GSAP opacity tween at ` +
-            `${firstVisible.position.toFixed(2)}s. It will cover earlier render frames, often as a blank/white video.`,
-          selector,
-          elementId: readAttr(tag.raw, "id") || undefined,
-          fixHint:
-            `Add \`opacity: 0\` to "${selector}" in CSS/inline styles, or add ` +
-            `\`tl.set("${selector}", { opacity: 0 }, 0)\` before the reveal tween.`,
-          snippet: truncateSnippet(firstVisible.raw),
-        });
-      }
-
-      // gsap_animates_clip_element — only error when GSAP animates visibility/display
-      for (const win of gsapWindows) {
-        const sel = win.targetSelector;
-        const clipInfo = clipIds.get(sel) || clipClasses.get(sel);
-        if (!clipInfo) continue;
-        const conflictingProps = win.properties.filter(
-          (p) => p === "visibility" || p === "display",
-        );
-        if (conflictingProps.length === 0) continue;
-        const elDesc = `<${clipInfo.tag}${clipInfo.id ? ` id="${clipInfo.id}"` : ""} class="${clipInfo.classes}">`;
-        findings.push({
-          code: "gsap_animates_clip_element",
-          severity: "error",
-          message: `GSAP animation sets ${conflictingProps.join(", ")} on a clip element. Selector "${sel}" resolves to element ${elDesc}. The framework manages clip visibility via ${conflictingProps.join("/")} — do not animate these properties on clip elements.`,
-          selector: sel,
-          elementId: clipInfo.id || undefined,
-          fixHint:
-            "Remove the visibility/display tween, or move the content into a child <div> and target that instead.",
-          snippet: truncateSnippet(win.raw),
-        });
-      }
-
-      // unscoped_gsap_selector
-      if (!localTimelineCompId || localTimelineCompId === rootCompositionId) continue;
-      for (const win of gsapWindows) {
-        if (!isSuspiciousGlobalSelector(win.targetSelector)) continue;
-        const className = getSingleClassSelector(win.targetSelector);
-        if (className && (classUsage.get(className) || 0) < 2) continue;
-        findings.push({
-          code: "unscoped_gsap_selector",
-          severity: "error",
-          message: `Timeline "${localTimelineCompId}" uses unscoped selector "${win.targetSelector}" that will target elements in ALL compositions when bundled, causing data loss (opacity, transforms, etc.).`,
-          selector: win.targetSelector,
-          fixHint: `Scope the selector: \`[data-composition-id="${localTimelineCompId}"] ${win.targetSelector}\` or use a unique id.`,
-          snippet: truncateSnippet(win.raw),
-        });
-      }
-    }
-    return findings;
-  },
-
-  // gsap_css_transform_conflict
-  // fallow-ignore-next-line complexity
-  async ({ styles, scripts, tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const cssTranslateSelectors = new Map<string, string>();
-    const cssScaleSelectors = new Map<string, string>();
-
-    // Check <style> blocks for transform rules
-    for (const style of styles) {
-      for (const [, selector, body] of style.content.matchAll(
-        /([#.][a-zA-Z0-9_-]+)\s*\{([^}]+)\}/g,
-      )) {
-        const tMatch = body?.match(/transform\s*:\s*([^;]+)/);
-        if (!tMatch || !tMatch[1]) continue;
-        const transformVal = tMatch[1].trim();
-        if (/translate/i.test(transformVal))
-          cssTranslateSelectors.set((selector ?? "").trim(), transformVal);
-        if (/scale/i.test(transformVal))
-          cssScaleSelectors.set((selector ?? "").trim(), transformVal);
-      }
-    }
-
-    // Also check inline style="..." attributes on tags
-    for (const tag of tags) {
-      const inlineStyle = readAttr(tag.raw, "style");
-      if (!inlineStyle) continue;
-      const tMatch = inlineStyle.match(/transform\s*:\s*([^;]+)/);
-      if (!tMatch || !tMatch[1]) continue;
-      const transformVal = tMatch[1].trim();
-      // Derive selectors from the tag's id and all classes
-      const id = readAttr(tag.raw, "id");
-      const classes = readAttr(tag.raw, "class")?.split(/\s+/).filter(Boolean) ?? [];
-      const selectors: string[] = [];
-      if (id) selectors.push(`#${id}`);
-      for (const cls of classes) selectors.push(`.${cls}`);
-      if (selectors.length === 0) continue;
-      for (const sel of selectors) {
-        if (/translate/i.test(transformVal) && !cssTranslateSelectors.has(sel))
-          cssTranslateSelectors.set(sel, transformVal);
-        if (/scale/i.test(transformVal) && !cssScaleSelectors.has(sel))
-          cssScaleSelectors.set(sel, transformVal);
-      }
-    }
-
-    if (cssTranslateSelectors.size === 0 && cssScaleSelectors.size === 0) return findings;
-
-    for (const script of scripts) {
-      if (!/gsap\.timeline/.test(script.content)) continue;
-      const windows = await cachedExtractGsapWindows(script.content);
-
-      // Two sources of transform-setting calls: timeline-rooted tweens (from the
-      // acorn parser) and standalone gsap.* calls (regex — the parser ignores
-      // these). Normalize both into one shape and run the same conflict check.
-      const calls: GsapTransformCall[] = [
-        ...windows.map((win) => ({
-          method: win.method,
-          selector: win.targetSelector,
-          properties: win.properties,
-          raw: win.raw,
-        })),
-        ...extractStandaloneGsapTransformCalls(stripJsComments(script.content)),
-      ];
-
-      type Conflict = { cssTransform: string; props: Set<string>; raw: string };
-      const conflicts = new Map<string, Conflict>();
-
-      for (const call of calls) {
-        // from() and fromTo() both supply explicit start values so GSAP owns
-        // the full transform from t=0, making the CSS conflict moot
-        if (call.method === "fromTo" || call.method === "from") continue;
-        const sel = call.selector;
-        const translateProps = call.properties.filter((p) =>
-          CONFLICTING_TRANSLATE_PROPS.includes(p),
-        );
-        const scaleProps = call.properties.filter((p) => CONFLICTING_SCALE_PROPS.includes(p));
-        const cssFromTranslate =
-          translateProps.length > 0 ? matchCssTransform(sel, cssTranslateSelectors) : undefined;
-        const cssFromScale =
-          scaleProps.length > 0 ? matchCssTransform(sel, cssScaleSelectors) : undefined;
-        if (!cssFromTranslate && !cssFromScale) continue;
-        const existing = conflicts.get(sel) ?? {
-          cssTransform: [cssFromTranslate, cssFromScale].filter(Boolean).join(" "),
-          props: new Set<string>(),
-          raw: call.raw,
-        };
-        for (const p of [...translateProps, ...scaleProps]) existing.props.add(p);
-        conflicts.set(sel, existing);
-      }
-
-      for (const [sel, { cssTransform, props, raw }] of conflicts) {
-        const propList = [...props].join("/");
-        const gsapEquivalent = cssTransformToGsapProps(cssTransform);
-        const fixHint = gsapEquivalent
-          ? `Remove \`transform: ${cssTransform}\` from CSS and replace with GSAP properties: ${gsapEquivalent}. ` +
-            `Example: tl.fromTo('${sel}', { ${gsapEquivalent} }, { ${gsapEquivalent}, ...yourAnimation }). ` +
-            `tl.fromTo is exempt from this rule.`
-          : `Remove the transform from CSS and use tl.fromTo('${sel}', ` +
-            `{ xPercent: -50, x: -1000 }, { xPercent: -50, x: 0 }) so GSAP owns ` +
-            `the full transform state. tl.fromTo is exempt from this rule.`;
-        findings.push({
-          code: "gsap_css_transform_conflict",
-          severity: "error",
-          message:
-            `"${sel}" has CSS \`transform: ${cssTransform}\` and a GSAP tween animates ` +
-            `${propList}. GSAP will overwrite the full CSS transform, discarding any ` +
-            `translateX(-50%) centering or CSS scale value.`,
-          selector: sel,
-          fixHint,
-          snippet: truncateSnippet(raw),
-        });
-      }
-    }
-    return findings;
-  },
-
-  // missing_gsap_script
-  ({ scripts, rawSource, options }) => {
-    const allScriptTexts = scripts.filter((s) => !/\bsrc\s*=/.test(s.attrs)).map((s) => s.content);
-    const allScriptSrcs = scripts
-      .map((s) => readAttr(`<script ${s.attrs}>`, "src") || "")
-      .filter(Boolean);
-    const canInheritGsapFromHost =
-      options.isSubComposition || rawSource.trimStart().toLowerCase().startsWith("<template");
-
-    const usesGsap = allScriptTexts.some((t) =>
-      /gsap\.(to|from|fromTo|timeline|set|registerPlugin)\b/.test(t),
-    );
-    const hasGsapScript = allScriptSrcs.some((src) => /gsap/i.test(src));
-    // Detect GSAP bundled inline (no src attribute). Match:
-    // - Producer's CDN-inlining comment: /* inlined: ...gsap... */
-    // - GSAP library internals: _gsScope, GreenSock, gsap.config
-    // - Large inline scripts (>5KB) that reference gsap (likely bundled library)
-    const hasInlineGsap = allScriptTexts.some(
-      (t) =>
-        /\/\*\s*inlined:.*gsap/i.test(t) ||
-        /\b_gsScope\b/.test(t) ||
-        /\bGreenSock\b/.test(t) ||
-        /\bgsap\.(config|defaults|version)\b/.test(t) ||
-        (t.length > 5000 && /\bgsap\b/i.test(t)),
-    );
-
-    if (!usesGsap || hasGsapScript || hasInlineGsap || canInheritGsapFromHost) return [];
-    return [
-      {
-        code: "missing_gsap_script",
-        severity: "error",
-        message: "Composition uses GSAP but no GSAP script is loaded. The animation will not run.",
-        fixHint:
-          'Add <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script> before your animation script.',
-      },
-    ];
-  },
-
-  // audio_reactive_single_tween_per_group
-  // fallow-ignore-next-line complexity
-  ({ scripts, styles }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const isCaptionFile = styles.some((s) => /\.caption[-_]?(?:group|word)/i.test(s.content));
-    if (!isCaptionFile) return findings;
-
-    for (const script of scripts) {
-      const content = script.content;
-      // Detect audio data loading
-      const hasAudioData = /AUDIO|audio[-_]?data|bands\[/.test(content);
-      if (!hasAudioData) continue;
-
-      // Detect caption group loop
-      const hasCaptionLoop = /forEach/.test(content) && /caption|group|cg-/.test(content);
-      if (!hasCaptionLoop) continue;
-
-      // Check if audio-reactive tweens are created at intervals (loop inside the group loop)
-      // vs a single tween per group (no inner time-sampling loop)
-      const hasInnerSamplingLoop =
-        /for\s*\(\s*var\s+\w+\s*=\s*group\.start/.test(content) ||
-        /for\s*\(\s*var\s+at\s*=/.test(content) ||
-        /while\s*\(\s*\w+\s*<\s*group\.end/.test(content);
-
-      if (!hasInnerSamplingLoop) {
-        // Check if there's at least a peak-based single tween (the minimal pattern)
-        const hasPeakTween =
-          /peak(?:Bass|Treble|Energy)/.test(content) && /group\.start/.test(content);
-        if (hasPeakTween) {
-          findings.push({
-            code: "audio_reactive_single_tween_per_group",
-            severity: "warning",
-            message:
-              "Audio-reactive captions use a single tween per group based on peak values. " +
-              "This sets one static value at group.start — not perceptible as audio reactivity.",
-            fixHint:
-              "Sample audio data at 100-200ms intervals throughout each group's lifetime " +
-              "(for loop from group.start to group.end) and create a tween at each sample " +
-              "point for visible pulsing.",
-          });
-        }
-      }
-    }
-    return findings;
-  },
-
-  // gsap_infinite_repeat
-  ({ scripts }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const script of scripts) {
-      const content = stripJsComments(script.content);
-      // Match repeat: -1 in GSAP tweens or timeline configs
-      const pattern = /repeat\s*:\s*-1(?!\d)/g;
-      let match: RegExpExecArray | null;
-      while ((match = pattern.exec(content)) !== null) {
-        const contextStart = Math.max(0, match.index - 60);
-        const contextEnd = Math.min(content.length, match.index + match[0].length + 60);
-        const snippet = content.slice(contextStart, contextEnd).trim();
-        findings.push({
-          code: "gsap_infinite_repeat",
-          severity: "error",
-          message:
-            "GSAP tween uses `repeat: -1` (infinite). Infinite repeats break the deterministic " +
-            "capture engine which seeks to exact frame times. Use a finite repeat count calculated " +
-            "from the composition duration: `repeat: Math.floor(duration / cycleDuration) - 1`.",
-          fixHint:
-            "Replace `repeat: -1` with a finite count, e.g. `repeat: Math.floor(totalDuration / singleCycleDuration) - 1`. " +
-            "Use Math.floor (not Math.ceil) to ensure the animation fits within the total duration.",
-          snippet: truncateSnippet(snippet),
-        });
-      }
-    }
-    return findings;
-  },
-
-  // gsap_repeat_ceil_overshoot
-  ({ scripts }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const script of scripts) {
-      const content = script.content;
-      // Match patterns like: repeat: Math.ceil(duration / X) - 1
-      // or repeat: Math.ceil(totalDuration / cycleDuration) - 1
-      const pattern = /repeat\s*:\s*Math\.ceil\s*\([^)]+\)\s*-\s*1/g;
-      let match: RegExpExecArray | null;
-      while ((match = pattern.exec(content)) !== null) {
-        const contextStart = Math.max(0, match.index - 40);
-        const contextEnd = Math.min(content.length, match.index + match[0].length + 40);
-        const snippet = content.slice(contextStart, contextEnd).trim();
-        findings.push({
-          code: "gsap_repeat_ceil_overshoot",
-          severity: "warning",
-          message:
-            "GSAP repeat calculation uses `Math.ceil` which can overshoot the composition duration. " +
-            "For example, Math.ceil(10.5 / 2) - 1 = 5 repeats → 6 cycles × 2s = 12s, exceeding 10.5s.",
-          fixHint:
-            "Use `Math.floor` instead of `Math.ceil` to ensure the animation fits within the duration: " +
-            "`repeat: Math.floor(totalDuration / cycleDuration) - 1`. " +
-            "Math.floor(10.5 / 2) - 1 = 4 repeats → 5 cycles × 2s = 10s ✓",
-          snippet: truncateSnippet(snippet),
-        });
-      }
-    }
-    return findings;
-  },
-
-  // scene_layer_missing_visibility_kill
-  ({ scripts, tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-
-    // Detect multi-scene compositions: multiple elements with "scene" in their id
-    const sceneElements = tags.filter((t) => {
-      const id = readAttr(t.raw, "id") || "";
-      return /^scene\d+$/i.test(id);
-    });
-    if (sceneElements.length < 2) return findings;
-
-    for (const script of scripts) {
-      const content = stripJsComments(script.content);
-      // For each scene, check if there's a visibility:hidden set after exit tweens
-      for (const tag of sceneElements) {
-        const id = readAttr(tag.raw, "id") || "";
-        // Check if this scene has exit tweens (opacity: 0)
-        const exitPattern = new RegExp(`["']#${id}["'][^)]*opacity\\s*:\\s*0`);
-        const hasExit = exitPattern.test(content);
-        if (!hasExit) continue;
-
-        // Check if there's a hard visibility kill
-        const killPattern = new RegExp(`["']#${id}["'][^)]*visibility\\s*:\\s*["']hidden["']`);
-        const hasKill = killPattern.test(content);
-        if (!hasKill) {
-          findings.push({
-            code: "scene_layer_missing_visibility_kill",
-            severity: "error",
-            elementId: id,
-            message:
-              `Scene layer "#${id}" exits via opacity tween but has no visibility: hidden hard kill. ` +
-              "When scrubbing or when tweens conflict, the scene may remain partially visible and overlap the next scene.",
-            fixHint: `Add \`tl.set("#${id}", { visibility: "hidden" }, <exit-end-time>)\` after the scene's exit tweens.`,
-          });
-        }
-      }
-    }
-    return findings;
-  },
-
-  // gsap_timeline_not_registered
-  ({ scripts, rawSource, options }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const canInheritFromHost =
-      options.isSubComposition || rawSource.trimStart().toLowerCase().startsWith("<template");
-
-    for (const script of scripts) {
-      const content = script.content;
-      if (!/gsap\.timeline/.test(content)) continue;
-      const hasRegistration = WINDOW_TIMELINE_ASSIGN_PATTERN.test(content);
-      if (hasRegistration || canInheritFromHost) continue;
-      findings.push({
-        code: "gsap_timeline_not_registered",
-        severity: "error",
-        message:
-          "GSAP timeline is created but never registered in window.__timelines. " +
-          "The runtime discovers timelines from this registry — without registration, " +
-          "animations will not play during preview or render.",
-        fixHint:
-          "Add `window.__timelines = window.__timelines || {};` and " +
-          '`window.__timelines["root"] = tl;` after creating the timeline (use the ' +
-          "composition's data-composition-id as the key).",
-      });
-    }
-    return findings;
-  },
-
-  // gsap_timeline_registered_before_async_build — registering window.__timelines[id]
-  // BEFORE the timeline is built inside document.fonts.ready (or any async callback)
-  // leaves an EMPTY timeline registered. The runtime's sub-composition readiness gate
-  // treats "key present" as "ready" and nests the child ONCE, while still empty — so the
-  // animation never renders when this composition is mounted as a sub-composition.
-  // Register only AFTER the build completes (the documented async-setup contract).
-  ({ scripts }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const script of scripts) {
-      const content = stripJsComments(script.content);
-      const regIdx = content.search(/window\s*\.\s*__timelines\s*\[/);
-      if (regIdx < 0) continue;
-      const fontsReadyIdx = content.search(/document\s*\.\s*fonts\s*\.\s*ready/);
-      if (fontsReadyIdx < 0) continue;
-      // Registering after the async boundary is the correct pattern — skip it.
-      if (regIdx >= fontsReadyIdx) continue;
-      // Confirm the build is actually deferred past the boundary (a tween/build call
-      // appears after document.fonts.ready), i.e. the registered timeline starts empty.
-      const tail = content.slice(fontsReadyIdx);
-      if (!/\.(?:to|from|fromTo)\s*\(|buildEffect\s*\(/.test(tail)) continue;
-      findings.push({
-        code: "gsap_timeline_registered_before_async_build",
-        severity: "error",
-        message:
-          "window.__timelines is assigned BEFORE the timeline is built inside " +
-          "document.fonts.ready. An empty timeline registered early gets nested empty " +
-          "when this composition is used as a sub-composition (the readiness gate treats " +
-          '"key present" as "ready" and never re-nests), so the animation renders blank.',
-        fixHint:
-          "Move the `window.__timelines[id] = tl;` assignment to the END of the " +
-          "document.fonts.ready callback, after the tweens are added. Optionally call " +
-          "window.__hfForceTimelineRebind() right after, to re-nest the populated timeline.",
-      });
-    }
-    return findings;
-  },
-
-  // gsap_from_opacity_noop — CSS opacity:0 + gsap.from({opacity:0}) = invisible forever
-  // fallow-ignore-next-line complexity
-  async ({ styles, scripts, tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const cssOpacityZeroSelectors = new Set<string>();
-
-    for (const style of styles) {
-      for (const [, selector, body] of style.content.matchAll(
-        /([#.][a-zA-Z0-9_-]+)\s*\{([^}]+)\}/g,
-      )) {
-        if (body && /opacity\s*:\s*0\s*[;}]/.test(body)) {
-          cssOpacityZeroSelectors.add((selector ?? "").trim());
-        }
-      }
-    }
-
-    for (const tag of tags) {
-      const inlineStyle = readAttr(tag.raw, "style");
-      if (!inlineStyle || !/opacity\s*:\s*0/.test(inlineStyle)) continue;
-      const id = readAttr(tag.raw, "id");
-      const classes = readAttr(tag.raw, "class")?.split(/\s+/).filter(Boolean) ?? [];
-      if (id) cssOpacityZeroSelectors.add(`#${id}`);
-      for (const cls of classes) cssOpacityZeroSelectors.add(`.${cls}`);
-    }
-
-    if (cssOpacityZeroSelectors.size === 0) return findings;
-
-    for (const script of scripts) {
-      if (!/gsap\.timeline/.test(script.content)) continue;
-      const windows = await cachedExtractGsapWindows(script.content);
-
-      for (const win of windows) {
-        if (win.method !== "from") continue;
-        if (!win.properties.includes("opacity")) continue;
-        // Only a noop when the tween animates FROM 0 (same as the CSS value)
-        if (win.propertyValues["opacity"] !== 0) continue;
-        const sel = win.targetSelector;
-        const cssKey = sel.startsWith("#") || sel.startsWith(".") ? sel : `#${sel}`;
-        if (!cssOpacityZeroSelectors.has(cssKey)) continue;
-
-        findings.push({
-          code: "gsap_from_opacity_noop",
-          severity: "error",
-          message:
-            `"${sel}" has CSS \`opacity: 0\` and a gsap.${win.method}() that also sets opacity to 0. ` +
-            `gsap.from() animates FROM the specified value TO the current CSS value — ` +
-            `since CSS is already 0, the element animates from 0→0 and never becomes visible.`,
-          selector: sel,
-          fixHint:
-            `Remove \`opacity: 0\` from the CSS/inline style on "${sel}". ` +
-            `Let gsap.from({opacity: 0}) handle the initial hidden state — ` +
-            `it will animate FROM 0 TO the CSS value (1 by default).`,
-          snippet: truncateSnippet(win.raw),
-        });
-      }
-    }
-    return findings;
-  },
-
-  // gsap_group_selector_keyframes
-  ({ scripts }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const script of scripts) {
-      const content = stripJsComments(script.content);
-      const pattern = /\.(?:to|from|fromTo)\(\s*["']([^"']+,\s*[^"']+)["']\s*,\s*\{[^}]*keyframes/g;
-      let match: RegExpExecArray | null;
-      while ((match = pattern.exec(content)) !== null) {
-        const selector = match[1]!;
-        const count = selector.split(",").length;
-        const contextStart = Math.max(0, match.index - 20);
-        const contextEnd = Math.min(content.length, match.index + match[0].length + 40);
-        findings.push({
-          code: "gsap_group_selector_keyframes",
-          severity: "warning",
-          message:
-            `GSAP tween targets ${count} elements with shared keyframes ("${truncateSnippet(selector, 60)}"). ` +
-            `Editing one element's keyframes in Studio will affect all ${count} elements. ` +
-            `Split into individual tweens for per-element keyframe control.`,
-          fixHint:
-            `Replace the group selector with individual tl.to() calls per element, ` +
-            `each with their own keyframes object.`,
-          snippet: truncateSnippet(content.slice(contextStart, contextEnd)),
-        });
-      }
-    }
-    return findings;
-  },
-];
diff --git a/packages/core/src/lint/rules/media.test.ts b/packages/core/src/lint/rules/media.test.ts
deleted file mode 100644
index 5a38bf02c5..0000000000
--- a/packages/core/src/lint/rules/media.test.ts
+++ /dev/null
@@ -1,251 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { lintHyperframeHtml } from "../hyperframeLinter.js";
-
-describe("media rules", () => {
-  it("reports error for duplicate media ids", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <video id="v1" src="a.mp4" data-start="0" data-duration="5"></video>
-    <video id="v1" src="b.mp4" data-start="0" data-duration="3"></video>
-  </div>
-  <script>window.__timelines = {};</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "duplicate_media_id");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.elementId).toBe("v1");
-  });
-
-  it("reports error for audio with data-start but no id", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <audio data-start="0" data-duration="10" src="narration.wav"></audio>
-  </div>
-  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "media_missing_id");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.message).toContain("SILENT");
-  });
-
-  it("reports error for video with data-start but no id", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <video data-start="0" data-duration="10" src="clip.mp4" muted playsinline></video>
-  </div>
-  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "media_missing_id");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.message).toContain("FROZEN");
-  });
-
-  it("does not flag media elements that have id", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <audio id="a1" data-start="0" data-duration="10" src="narration.wav"></audio>
-    <video id="v1" data-start="0" data-duration="10" src="clip.mp4" muted playsinline></video>
-  </div>
-  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "media_missing_id");
-    expect(finding).toBeUndefined();
-  });
-
-  it("reports warning for media with preload=none", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <video id="v1" data-start="0" data-duration="10" src="clip.mp4" muted playsinline preload="none"></video>
-  </div>
-  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "media_preload_none");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("warning");
-  });
-
-  it("reports error for media with id but no src", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <audio id="a1" data-start="0" data-duration="10"></audio>
-  </div>
-  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "media_missing_src");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-  });
-
-  it("reports error for media with src but no data-start", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <video id="demo-video" src="clip.mp4" muted playsinline></video>
-  </div>
-  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "media_missing_data_start");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.elementId).toBe("demo-video");
-  });
-
-  it("allows audible video clips to omit muted when data-has-audio is true", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <video id="demo-video" data-start="0" data-duration="5" data-has-audio="true" src="clip.mp4" playsinline></video>
-  </div>
-  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    expect(result.findings.find((f) => f.code === "video_missing_muted")).toBeUndefined();
-    expect(
-      result.findings.find((f) => f.code === "video_muted_with_declared_audio"),
-    ).toBeUndefined();
-  });
-
-  it("reports error for videos that declare audio while muted", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <video id="demo-video" data-start="0" data-duration="5" data-has-audio="true" src="clip.mp4" muted playsinline></video>
-  </div>
-  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "video_muted_with_declared_audio");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.elementId).toBe("demo-video");
-  });
-
-  it("does NOT flag <video> as nested in a void element with data-start (regression)", async () => {
-    // Regression: void elements like <img> have no closing tag, so the previous
-    // implementation kept them on the parent stack indefinitely and flagged any
-    // later <video> with data-start as "nested" inside them.
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <img id="hdr-img" src="hdr.png" data-start="0" data-duration="5" data-track-index="0" />
-    <video id="hdr-vid" src="clip.mp4" data-start="5" data-duration="5" data-track-index="1" muted playsinline></video>
-  </div>
-  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "video_nested_in_timed_element");
-    expect(finding).toBeUndefined();
-  });
-
-  it("reports imperative play() control on managed media ids", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <video id="demo-video" data-start="0" data-duration="5" src="clip.mp4" muted playsinline></video>
-  </div>
-  <script>
-    const video = document.getElementById("demo-video");
-    video.play();
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "imperative_media_control");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.elementId).toBe("demo-video");
-  });
-
-  it("reports imperative currentTime writes on query-selected managed media", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <video id="demo-video" data-start="0" data-duration="5" src="clip.mp4" muted playsinline></video>
-  </div>
-  <script>
-    const demo = document.querySelector("#demo-video");
-    demo.currentTime = 1.5;
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "imperative_media_control");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-  });
-
-  it("reports imperative muted/play control on class-selected media without ids", async () => {
-    const html = `
-<template id="scene-template">
-  <div data-composition-id="scene" data-width="1920" data-height="1080">
-    <video class="demo-video" src="clip.mp4" muted playsinline></video>
-    <script>
-      const vid = document.querySelector('[data-composition-id="scene"] .demo-video');
-      if (vid) { vid.muted = true; vid.play(); }
-    </script>
-  </div>
-</template>`;
-    const result = await lintHyperframeHtml(html, { filePath: "compositions/scene.html" });
-    const imperativeFindings = result.findings.filter((f) => f.code === "imperative_media_control");
-    expect(imperativeFindings.length).toBe(2);
-    expect(imperativeFindings.some((f) => f.snippet === "vid.muted =")).toBe(true);
-    expect(imperativeFindings.some((f) => f.snippet === "vid.play(")).toBe(true);
-  });
-
-  it("does not flag play() on non-media elements", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <div id="panel"></div>
-  </div>
-  <script>
-    const panel = document.getElementById("panel");
-    panel.play?.();
-  </script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "imperative_media_control");
-    expect(finding).toBeUndefined();
-  });
-
-  it("flags <video> inside a sub-composition (media must be a host-root child)", async () => {
-    const html = `<template id="scene-template">
-  <div id="root" data-composition-id="scene" data-width="1920" data-height="1080">
-    <video id="v1" src="clip.mp4" data-start="0" data-duration="5" muted playsinline></video>
-    <script>window.__timelines = window.__timelines || {}; window.__timelines["scene"] = gsap.timeline({ paused: true });</script>
-  </div>
-</template>`;
-    const result = await lintHyperframeHtml(html, { isSubComposition: true });
-    const finding = result.findings.find((f) => f.code === "media_in_subcomposition");
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("error");
-    expect(finding?.elementId).toBe("v1");
-    expect(finding?.message).toContain("sub-composition");
-  });
-
-  it("does not flag media in a host-root (non-sub) composition", async () => {
-    const html = `
-<html><body>
-  <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">
-    <video id="v1" src="clip.mp4" data-start="0" data-duration="5" muted playsinline></video>
-  </div>
-  <script>window.__timelines = window.__timelines || {}; window.__timelines["c1"] = gsap.timeline({ paused: true });</script>
-</body></html>`;
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((f) => f.code === "media_in_subcomposition");
-    expect(finding).toBeUndefined();
-  });
-});
diff --git a/packages/core/src/lint/rules/media.ts b/packages/core/src/lint/rules/media.ts
deleted file mode 100644
index 03d5f53bfa..0000000000
--- a/packages/core/src/lint/rules/media.ts
+++ /dev/null
@@ -1,526 +0,0 @@
-import type { LintContext, HyperframeLintFinding } from "../context";
-import { readAttr, truncateSnippet, isMediaTag } from "../utils";
-
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function hasAttrName(tagSource: string, attr: string): boolean {
-  const escaped = escapeRegExp(attr);
-  const attrs = tagSource.replace(/^<\s*[a-z][\w:-]*/i, "");
-  return new RegExp(`(?:^|\\s)${escaped}(?:\\s*=|\\s|/?>)`, "i").test(attrs);
-}
-
-function classNamesFromAttr(classAttr: string | null): string[] {
-  if (!classAttr) return [];
-  return classAttr.split(/\s+/).filter(Boolean);
-}
-
-type MediaSelectorIndex = {
-  ids: Set<string>;
-  classes: Set<string>;
-  hasVideo: boolean;
-  hasAudio: boolean;
-};
-
-function selectorTargetsManagedMedia(selector: string, mediaIndex: MediaSelectorIndex): boolean {
-  const normalized = selector.trim();
-  if (!normalized) return false;
-  if (mediaIndex.hasVideo && /\bvideo\b/i.test(normalized)) return true;
-  if (mediaIndex.hasAudio && /\baudio\b/i.test(normalized)) return true;
-  for (const mediaId of mediaIndex.ids) {
-    const escapedId = escapeRegExp(mediaId);
-    if (
-      new RegExp(`#${escapedId}(?![\\w-])`).test(normalized) ||
-      normalized.includes(`[id="${mediaId}"]`) ||
-      normalized.includes(`[id='${mediaId}']`)
-    ) {
-      return true;
-    }
-  }
-  for (const className of mediaIndex.classes) {
-    if (new RegExp(`\\.${escapeRegExp(className)}(?![\\w-])`).test(normalized)) {
-      return true;
-    }
-  }
-  return false;
-}
-
-function findImperativeMediaControlFindings(ctx: LintContext): HyperframeLintFinding[] {
-  const findings: HyperframeLintFinding[] = [];
-  const mediaTags = ctx.tags.filter((tag) => tag.name === "video" || tag.name === "audio");
-  const mediaIndex: MediaSelectorIndex = {
-    ids: new Set(
-      mediaTags.map((tag) => readAttr(tag.raw, "id")).filter((id): id is string => Boolean(id)),
-    ),
-    classes: new Set(mediaTags.flatMap((tag) => classNamesFromAttr(readAttr(tag.raw, "class")))),
-    hasVideo: mediaTags.some((tag) => tag.name === "video"),
-    hasAudio: mediaTags.some((tag) => tag.name === "audio"),
-  };
-
-  if (mediaTags.length === 0 || ctx.scripts.length === 0) return findings;
-
-  for (const script of ctx.scripts) {
-    const mediaVars = new Map<string, string | undefined>();
-    const assignmentPatterns = [
-      {
-        pattern:
-          /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)/g,
-        variableIndex: 1,
-        targetIndex: 2,
-      },
-      {
-        pattern:
-          /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:document|window\.document)\.querySelector\(\s*(["'])([\s\S]*?)\2\s*\)/g,
-        variableIndex: 1,
-        targetIndex: 3,
-      },
-    ];
-
-    for (const { pattern, variableIndex, targetIndex } of assignmentPatterns) {
-      let match: RegExpExecArray | null;
-      while ((match = pattern.exec(script.content)) !== null) {
-        const variableName = match[variableIndex];
-        const target = match[targetIndex];
-        if (!variableName || !target) continue;
-        if (mediaIndex.ids.has(target) || selectorTargetsManagedMedia(target, mediaIndex)) {
-          mediaVars.set(variableName, mediaIndex.ids.has(target) ? target : undefined);
-        }
-      }
-    }
-
-    const directIdPatterns = [
-      {
-        pattern:
-          /\b(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)\.play\s*\(/g,
-        kind: "play()",
-        targetIndex: 1,
-      },
-      {
-        pattern:
-          /\b(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)\.pause\s*\(/g,
-        kind: "pause()",
-        targetIndex: 1,
-      },
-      {
-        pattern:
-          /\b(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)\.currentTime\s*=/g,
-        kind: "currentTime",
-        targetIndex: 1,
-      },
-      {
-        pattern:
-          /\b(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)\.muted\s*=/g,
-        kind: "muted assignment",
-        targetIndex: 1,
-      },
-      {
-        pattern:
-          /\b(?:document|window\.document)\.querySelector\(\s*(["'])([\s\S]*?)\1\s*\)\.play\s*\(/g,
-        kind: "play()",
-        targetIndex: 2,
-      },
-      {
-        pattern:
-          /\b(?:document|window\.document)\.querySelector\(\s*(["'])([\s\S]*?)\1\s*\)\.pause\s*\(/g,
-        kind: "pause()",
-        targetIndex: 2,
-      },
-      {
-        pattern:
-          /\b(?:document|window\.document)\.querySelector\(\s*(["'])([\s\S]*?)\1\s*\)\.currentTime\s*=/g,
-        kind: "currentTime",
-        targetIndex: 2,
-      },
-      {
-        pattern:
-          /\b(?:document|window\.document)\.querySelector\(\s*(["'])([\s\S]*?)\1\s*\)\.muted\s*=/g,
-        kind: "muted assignment",
-        targetIndex: 2,
-      },
-    ];
-
-    for (const { pattern, kind, targetIndex } of directIdPatterns) {
-      let match: RegExpExecArray | null;
-      while ((match = pattern.exec(script.content)) !== null) {
-        const target = match[targetIndex];
-        if (!target) continue;
-        const elementId = mediaIndex.ids.has(target)
-          ? target
-          : selectorTargetsManagedMedia(target, mediaIndex)
-            ? undefined
-            : null;
-        if (elementId === null) continue;
-        findings.push({
-          code: "imperative_media_control",
-          severity: "error",
-          message: `Inline <script> imperatively controls managed media via ${kind}. HyperFrames must own media play/pause/seek to keep preview, timeline, and renders deterministic.`,
-          elementId: elementId || undefined,
-          fixHint:
-            "Remove imperative media play/pause/currentTime/muted control. Express timing with data-start/data-duration and media offsets like data-media-start or data-playback-start instead.",
-          snippet: truncateSnippet(match[0]),
-        });
-      }
-    }
-
-    for (const [variableName, elementId] of mediaVars) {
-      const escapedVar = escapeRegExp(variableName);
-      const variablePatterns = [
-        { pattern: new RegExp(`\\b${escapedVar}\\.play\\s*\\(`, "g"), kind: "play()" },
-        { pattern: new RegExp(`\\b${escapedVar}\\.pause\\s*\\(`, "g"), kind: "pause()" },
-        { pattern: new RegExp(`\\b${escapedVar}\\.currentTime\\s*=`, "g"), kind: "currentTime" },
-        {
-          pattern: new RegExp(`\\b${escapedVar}\\.muted\\s*=`, "g"),
-          kind: "muted assignment",
-        },
-      ];
-      for (const { pattern, kind } of variablePatterns) {
-        let match: RegExpExecArray | null;
-        while ((match = pattern.exec(script.content)) !== null) {
-          findings.push({
-            code: "imperative_media_control",
-            severity: "error",
-            message: `Inline <script> imperatively controls managed media via ${kind}. HyperFrames must own media play/pause/seek to keep preview, timeline, and renders deterministic.`,
-            elementId,
-            fixHint:
-              "Remove imperative media play/pause/currentTime/muted control. Express timing with data-start/data-duration and media offsets like data-media-start or data-playback-start instead.",
-            snippet: truncateSnippet(match[0]),
-          });
-        }
-      }
-    }
-  }
-
-  return findings;
-}
-
-export const mediaRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
-  // duplicate_media_id + duplicate_media_discovery_risk
-  ({ tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const mediaById = new Map<string, typeof tags>();
-    const mediaFingerprintCounts = new Map<string, number>();
-
-    for (const tag of tags) {
-      if (!isMediaTag(tag.name)) continue;
-      const elementId = readAttr(tag.raw, "id");
-      if (elementId) {
-        const existing = mediaById.get(elementId) || [];
-        existing.push(tag);
-        mediaById.set(elementId, existing);
-      }
-      const fingerprint = [
-        tag.name,
-        readAttr(tag.raw, "src") || "",
-        readAttr(tag.raw, "data-start") || "",
-        readAttr(tag.raw, "data-duration") || "",
-      ].join("|");
-      mediaFingerprintCounts.set(fingerprint, (mediaFingerprintCounts.get(fingerprint) || 0) + 1);
-    }
-
-    for (const [elementId, mediaTags] of mediaById) {
-      if (mediaTags.length < 2) continue;
-      findings.push({
-        code: "duplicate_media_id",
-        severity: "error",
-        message: `Media id "${elementId}" is defined multiple times.`,
-        elementId,
-        fixHint:
-          "Give each media element a unique id so preview and producer discover the same media graph.",
-        snippet: truncateSnippet(mediaTags[0]?.raw || ""),
-      });
-    }
-
-    for (const [fingerprint, count] of mediaFingerprintCounts) {
-      if (count < 2) continue;
-      const [tagName, src, dataStart, dataDuration] = fingerprint.split("|");
-      findings.push({
-        code: "duplicate_media_discovery_risk",
-        severity: "warning",
-        message: `Detected ${count} matching ${tagName} entries with the same source/start/duration.`,
-        fixHint: "Avoid duplicated media nodes that can be discovered twice during compilation.",
-        snippet: truncateSnippet(
-          `${tagName} src=${src} data-start=${dataStart} data-duration=${dataDuration}`,
-        ),
-      });
-    }
-    return findings;
-  },
-
-  // video_missing_muted
-  ({ tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const tag of tags) {
-      if (tag.name !== "video") continue;
-      const hasMuted = hasAttrName(tag.raw, "muted");
-      const hasDeclaredAudio = readAttr(tag.raw, "data-has-audio") === "true";
-      if (!hasMuted && !hasDeclaredAudio && readAttr(tag.raw, "data-start")) {
-        const elementId = readAttr(tag.raw, "id") || undefined;
-        findings.push({
-          code: "video_missing_muted",
-          severity: "error",
-          message: `<video${elementId ? ` id="${elementId}"` : ""}> has data-start but is not muted. Mark audible videos with data-has-audio="true"; otherwise keep video muted and use a separate <audio> element for sound.`,
-          elementId,
-          fixHint:
-            'Add the `muted` attribute for silent video, or add data-has-audio="true" when the video track should contribute audio.',
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-      if (hasMuted && hasDeclaredAudio) {
-        const elementId = readAttr(tag.raw, "id") || undefined;
-        findings.push({
-          code: "video_muted_with_declared_audio",
-          severity: "error",
-          message: `<video${elementId ? ` id="${elementId}"` : ""}> declares data-has-audio="true" but also has muted. Studio preview will silence the video audio.`,
-          elementId,
-          fixHint:
-            'Remove the `muted` attribute if this video should be audible, or remove data-has-audio="true" and use data-volume="0" for silent visual video.',
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-    }
-    return findings;
-  },
-
-  // video_nested_in_timed_element
-  ({ source, tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-    // HTML5 void elements cannot contain children, so they can never be a
-    // parent of a nested <video>. Skipping them avoids false positives where
-    // the linter looks for `</img>` and never finds it.
-    const voidElements = new Set([
-      "area",
-      "base",
-      "br",
-      "col",
-      "embed",
-      "hr",
-      "img",
-      "input",
-      "link",
-      "meta",
-      "source",
-      "track",
-      "wbr",
-    ]);
-    const timedTagPositions: Array<{ name: string; start: number; id?: string }> = [];
-    for (const tag of tags) {
-      if (tag.name === "video" || tag.name === "audio") continue;
-      if (voidElements.has(tag.name)) continue;
-      // Skip the composition root — it uses data-start as a playback anchor, not as a clip timer
-      if (readAttr(tag.raw, "data-composition-id")) continue;
-      if (readAttr(tag.raw, "data-start")) {
-        timedTagPositions.push({
-          name: tag.name,
-          start: tag.index,
-          id: readAttr(tag.raw, "id") || undefined,
-        });
-      }
-    }
-    for (const tag of tags) {
-      if (tag.name !== "video") continue;
-      if (!readAttr(tag.raw, "data-start")) continue;
-      for (const parent of timedTagPositions) {
-        if (parent.start < tag.index) {
-          const parentClosePattern = new RegExp(`</${parent.name}>`, "gi");
-          const between = source.substring(parent.start, tag.index);
-          if (!parentClosePattern.test(between)) {
-            findings.push({
-              code: "video_nested_in_timed_element",
-              severity: "error",
-              message: `<video> with data-start is nested inside <${parent.name}${parent.id ? ` id="${parent.id}"` : ""}> which also has data-start. The framework cannot manage playback of nested media — video will be FROZEN in renders.`,
-              elementId: readAttr(tag.raw, "id") || undefined,
-              fixHint:
-                "Move the <video> to be a direct child of the stage, or remove data-start from the wrapper div (use it as a non-timed visual container).",
-              snippet: truncateSnippet(tag.raw),
-            });
-            break;
-          }
-        }
-      }
-    }
-    return findings;
-  },
-
-  // media_in_subcomposition — <video>/<audio> only render as a DIRECT child of the host
-  // root (index.html). Inside a sub-composition <template> the runtime never seeks/decodes
-  // them, so they render BLANK/black in preview and renders — and the other lint/validate
-  // passes otherwise miss it (only a per-frame snapshot reveals the blank panel).
-  ({ tags, options }) => {
-    const findings: HyperframeLintFinding[] = [];
-    if (!options.isSubComposition) return findings;
-    for (const tag of tags) {
-      if (tag.name !== "video" && tag.name !== "audio") continue;
-      const elementId = readAttr(tag.raw, "id") || undefined;
-      findings.push({
-        code: "media_in_subcomposition",
-        severity: "error",
-        message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> is inside a sub-composition. The runtime only drives media that is a DIRECT child of the host root (index.html); media inside a sub-comp <template> is never seeked/decoded and renders BLANK/black in preview and renders.`,
-        elementId,
-        fixHint:
-          "Move the media OUT of the sub-composition: place the <video>/<audio> as a direct child of #root in index.html, positioned over the scene, and drive any per-scene motion on the MAIN timeline at global time (a sub-comp timeline cannot reach host elements). See composition-patterns.md archetype B.",
-        snippet: truncateSnippet(tag.raw),
-      });
-    }
-    return findings;
-  },
-
-  // self_closing_media_tag
-  ({ source }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const selfClosingMediaRe = /<(audio|video)\b[^>]*\/>/gi;
-    let scMatch: RegExpExecArray | null;
-    while ((scMatch = selfClosingMediaRe.exec(source)) !== null) {
-      const tagName = scMatch[1] || "audio";
-      const elementId = readAttr(scMatch[0], "id") || undefined;
-      findings.push({
-        code: "self_closing_media_tag",
-        severity: "error",
-        message: `Self-closing <${tagName}/> is invalid HTML. The browser will leave the tag open, swallowing all subsequent elements as invisible fallback content. This makes compositions INVISIBLE.`,
-        elementId,
-        fixHint: `Change <${tagName} .../> to <${tagName} ...></${tagName}> — media elements MUST have explicit closing tags.`,
-        snippet: truncateSnippet(scMatch[0]),
-      });
-    }
-    return findings;
-  },
-
-  // placeholder_media_url
-  ({ tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const PLACEHOLDER_DOMAINS =
-      /\b(placehold\.co|placeholder\.com|placekitten\.com|picsum\.photos|example\.com|via\.placeholder\.com|dummyimage\.com)\b/i;
-    for (const tag of tags) {
-      if (!isMediaTag(tag.name)) continue;
-      const src = readAttr(tag.raw, "src");
-      if (!src) continue;
-      if (PLACEHOLDER_DOMAINS.test(src)) {
-        const elementId = readAttr(tag.raw, "id") || undefined;
-        findings.push({
-          code: "placeholder_media_url",
-          severity: "error",
-          message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses a placeholder URL that will 404 at render time: ${src.slice(0, 80)}`,
-          elementId,
-          fixHint: "Replace with a real media URL. Placeholder domains will 404 at render time.",
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-    }
-    return findings;
-  },
-
-  // base64_media_prohibited
-  ({ source }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const base64MediaRe =
-      /src\s*=\s*["'](data:(?:audio|video)\/[^;]+;base64,([A-Za-z0-9+/=]{20,}))["']/gi;
-    let b64Match: RegExpExecArray | null;
-    while ((b64Match = base64MediaRe.exec(source)) !== null) {
-      const sample = (b64Match[2] || "").slice(0, 200);
-      const uniqueChars = new Set(sample.replace(/[A-Za-z0-9+/=]/g, (c) => c)).size;
-      const dataSize = Math.round(((b64Match[2] || "").length * 3) / 4);
-      const isSuspicious = uniqueChars < 15 || (dataSize > 1000 && dataSize < 50000);
-      findings.push({
-        code: "base64_media_prohibited",
-        severity: "error",
-        message: `Inline base64 audio/video detected (${(dataSize / 1024).toFixed(0)} KB)${isSuspicious ? " — likely fabricated data" : ""}. Base64 media is prohibited — it bloats file size and breaks rendering.`,
-        fixHint:
-          "Use a relative path (assets/music.mp3) or HTTPS URL for the audio/video src. Never embed media as base64.",
-        snippet: truncateSnippet((b64Match[1] ?? "").slice(0, 80) + "..."),
-      });
-    }
-    return findings;
-  },
-
-  // media_missing_data_start + media_missing_id + media_missing_src + media_preload_none
-  ({ tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-    for (const tag of tags) {
-      if (tag.name !== "video" && tag.name !== "audio") continue;
-      const hasDataStart = readAttr(tag.raw, "data-start");
-      const hasId = readAttr(tag.raw, "id");
-      const hasSrc = readAttr(tag.raw, "src");
-      if (hasSrc && !hasDataStart) {
-        findings.push({
-          code: "media_missing_data_start",
-          severity: "error",
-          message: `<${tag.name}${hasId ? ` id="${hasId}"` : ""}> has src but no data-start. HyperFrames cannot own playback for untimed media, so preview and render behavior can diverge.`,
-          elementId: hasId || undefined,
-          fixHint: `Add data-start="0" (or the intended start time) and data-duration if the clip should stop before the source ends.`,
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-      if (hasDataStart && !hasId) {
-        findings.push({
-          code: "media_missing_id",
-          severity: "error",
-          message: `<${tag.name}> has data-start but no id attribute. The renderer requires id to discover media elements — this ${tag.name === "audio" ? "audio will be SILENT" : "video will be FROZEN"} in renders.`,
-          fixHint: `Add a unique id attribute: <${tag.name} id="my-${tag.name}" ...>`,
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-      if (hasDataStart && hasId && !hasSrc) {
-        findings.push({
-          code: "media_missing_src",
-          severity: "error",
-          message: `<${tag.name} id="${hasId}"> has data-start but no src attribute. The renderer cannot load this media.`,
-          elementId: hasId,
-          fixHint: `Add a src attribute to the <${tag.name}> element directly. If using <source> children, the renderer still requires src on the parent element.`,
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-      if (readAttr(tag.raw, "preload") === "none") {
-        findings.push({
-          code: "media_preload_none",
-          severity: "warning",
-          message: `<${tag.name}${hasId ? ` id="${hasId}"` : ""}> has preload="none" which prevents the renderer from loading this media. The compiler strips it for renders, but preview may also have issues.`,
-          elementId: hasId || undefined,
-          fixHint: `Remove preload="none" or change to preload="auto". The framework manages media loading.`,
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-    }
-    return findings;
-  },
-
-  // video_audio_double_source — catches audible <video> paired with a separate
-  // <audio> pointing to the same file, which causes double playback at runtime
-  ({ tags }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const videoSources = new Map<string, { id?: string; raw: string }>();
-    const audioSources = new Map<string, { id?: string; raw: string }>();
-
-    for (const tag of tags) {
-      if (!readAttr(tag.raw, "data-start")) continue;
-      const src = readAttr(tag.raw, "src");
-      if (!src) continue;
-      const elementId = readAttr(tag.raw, "id") || undefined;
-      if (tag.name === "video") {
-        const isMuted = hasAttrName(tag.raw, "muted");
-        if (!isMuted) {
-          videoSources.set(src, { id: elementId, raw: tag.raw });
-        }
-      } else if (tag.name === "audio") {
-        audioSources.set(src, { id: elementId, raw: tag.raw });
-      }
-    }
-
-    for (const [src, audioInfo] of audioSources) {
-      const videoInfo = videoSources.get(src);
-      if (!videoInfo) continue;
-      findings.push({
-        code: "video_audio_double_source",
-        severity: "error",
-        message: `<audio${audioInfo.id ? ` id="${audioInfo.id}"` : ""}> and <video${videoInfo.id ? ` id="${videoInfo.id}"` : ""}> both point to the same source. The unmuted video already provides audio — the duplicate <audio> will cause double playback and echo.`,
-        elementId: audioInfo.id,
-        fixHint:
-          "Either mute the video (add `muted` attribute) and keep the separate <audio>, or remove the <audio> element and let the video provide its own audio track.",
-        snippet: truncateSnippet(audioInfo.raw),
-      });
-    }
-    return findings;
-  },
-
-  // imperative_media_control
-  findImperativeMediaControlFindings,
-];
diff --git a/packages/core/src/lint/rules/slideshow.test.ts b/packages/core/src/lint/rules/slideshow.test.ts
deleted file mode 100644
index 8b7ed69464..0000000000
--- a/packages/core/src/lint/rules/slideshow.test.ts
+++ /dev/null
@@ -1,73 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { lintHyperframeHtml } from "../hyperframeLinter.js";
-
-async function findSlideshow(html: string) {
-  const result = await lintHyperframeHtml(html, { isSubComposition: true });
-  return result.findings.filter((f) => f.code.startsWith("slideshow_"));
-}
-
-describe("slideshow lint rule", () => {
-  it("passes a composition with no slideshow island", async () => {
-    const html = `<div data-composition-id="c" data-width="1920" data-height="1080">
-      <div id="a" class="clip" data-start="0" data-duration="5"></div>
-    </div>`;
-    expect(await findSlideshow(html)).toEqual([]);
-  });
-
-  it("passes a valid island where sceneId resolves to a data-composition-id scene", async () => {
-    const html = `<div data-composition-id="c" data-width="1920" data-height="1080">
-      <div data-composition-id="a" data-start="0" data-duration="5"></div>
-      <script type="application/hyperframes-slideshow+json">{"slides":[{"sceneId":"a"}]}</script>
-    </div>`;
-    expect(await findSlideshow(html)).toEqual([]);
-  });
-
-  it("flags a sceneId that matches only a .clip[id] (not a data-composition-id)", async () => {
-    const html = `<div data-composition-id="c" data-width="1920" data-height="1080">
-      <div id="a" class="clip" data-start="0" data-duration="5"></div>
-      <script type="application/hyperframes-slideshow+json">{"slides":[{"sceneId":"a"}]}</script>
-    </div>`;
-    const findings = await findSlideshow(html);
-    expect(findings.length).toBeGreaterThan(0);
-    expect(findings[0]?.message).toContain("a");
-  });
-
-  it("flags an unresolved sceneId", async () => {
-    const html = `<div data-composition-id="c" data-width="1920" data-height="1080">
-      <div id="a" class="clip" data-start="0" data-duration="5"></div>
-      <script type="application/hyperframes-slideshow+json">{"slides":[{"sceneId":"ghost"}]}</script>
-    </div>`;
-    const findings = await findSlideshow(html);
-    expect(findings.length).toBeGreaterThan(0);
-    expect(findings[0]!.message).toContain("ghost");
-  });
-
-  it("flags invalid JSON in the island", async () => {
-    const html = `<div data-composition-id="c" data-width="1920" data-height="1080">
-      <script type="application/hyperframes-slideshow+json">NOT_JSON</script>
-    </div>`;
-    const findings = await findSlideshow(html);
-    expect(findings.length).toBeGreaterThan(0);
-    expect(findings[0]!.code).toBe("slideshow_invalid");
-  });
-
-  it("passes when sceneId resolves to a data-composition-id element (no .clip[id])", async () => {
-    const html = `<div data-composition-id="c" data-width="1920" data-height="1080">
-      <div data-composition-id="scene-a" data-start="0" data-duration="5"></div>
-      <script type="application/hyperframes-slideshow+json">{"slides":[{"sceneId":"scene-a"}]}</script>
-    </div>`;
-    expect(await findSlideshow(html)).toEqual([]);
-  });
-
-  it("flags a hotspot targeting an unknown sequence", async () => {
-    const html = `<div data-composition-id="c" data-width="1920" data-height="1080">
-      <div data-composition-id="a" data-start="0" data-duration="5"></div>
-      <script type="application/hyperframes-slideshow+json">${JSON.stringify({
-        slides: [{ sceneId: "a", hotspots: [{ id: "h1", label: "Go", target: "no-such-seq" }] }],
-      })}</script>
-    </div>`;
-    const findings = await findSlideshow(html);
-    expect(findings.length).toBeGreaterThan(0);
-    expect(findings[0]!.message).toContain("no-such-seq");
-  });
-});
diff --git a/packages/core/src/lint/rules/slideshow.ts b/packages/core/src/lint/rules/slideshow.ts
deleted file mode 100644
index 80b5d8f449..0000000000
--- a/packages/core/src/lint/rules/slideshow.ts
+++ /dev/null
@@ -1,82 +0,0 @@
-import type { LintContext, HyperframeLintFinding } from "../context";
-import type { LintRule } from "../types";
-import { readAttr } from "../utils";
-import { parseSlideshowManifest, resolveSlideshow } from "../../slideshow/parseSlideshow";
-import { isSceneLikeCompositionId } from "../../slideshow/sceneId";
-
-type Scene = { id: string; start: number; duration: number };
-
-function parseTiming(raw: string): { start: number; duration: number } | null {
-  const startStr = readAttr(raw, "data-start");
-  if (startStr === null) return null;
-  const start = Number(startStr);
-  if (!Number.isFinite(start)) return null;
-
-  const durationStr = readAttr(raw, "data-duration");
-  if (durationStr !== null) {
-    const duration = Number(durationStr);
-    if (Number.isFinite(duration)) return { start, duration };
-  }
-  const endStr = readAttr(raw, "data-end") ?? readAttr(raw, "data-hf-authored-end");
-  if (endStr !== null) {
-    const end = Number(endStr);
-    if (Number.isFinite(end) && end > start) return { start, duration: end - start };
-  }
-  return null;
-}
-
-function collectCompositionIdScenes(ctx: LintContext, seen: Set<string>, out: Scene[]): void {
-  for (const tag of ctx.tags) {
-    const compositionId = readAttr(tag.raw, "data-composition-id");
-    if (!compositionId || !isSceneLikeCompositionId(compositionId) || seen.has(compositionId))
-      continue;
-    const timing = parseTiming(tag.raw);
-    if (!timing || timing.duration <= 0) continue;
-    seen.add(compositionId);
-    out.push({ id: compositionId, ...timing });
-  }
-}
-
-function extractScenesFromClips(ctx: LintContext): Scene[] {
-  const seen = new Set<string>();
-  const scenes: Scene[] = [];
-  collectCompositionIdScenes(ctx, seen, scenes);
-  return scenes;
-}
-
-export const slideshowRules: LintRule<LintContext>[] = [
-  (ctx) => {
-    const findings: HyperframeLintFinding[] = [];
-
-    let manifest;
-    try {
-      manifest = parseSlideshowManifest(ctx.source);
-    } catch (e) {
-      findings.push({
-        code: "slideshow_invalid",
-        severity: "error",
-        message: `Slideshow island contains invalid JSON or structure: ${e instanceof Error ? e.message : String(e)}`,
-        fixHint:
-          'Ensure the <script type="application/hyperframes-slideshow+json"> block contains valid JSON matching the SlideshowManifest schema.',
-      });
-      return findings;
-    }
-
-    if (!manifest) return findings;
-
-    const scenes = extractScenesFromClips(ctx);
-    const { errors } = resolveSlideshow(manifest, scenes);
-
-    for (const error of errors) {
-      findings.push({
-        code: "slideshow_unresolved_ref",
-        severity: "error",
-        message: `Slideshow manifest error: ${error}`,
-        fixHint:
-          "Ensure every sceneId in the slideshow island matches the data-composition-id of a scene element in the composition, or provide explicit startTime/endTime.",
-      });
-    }
-
-    return findings;
-  },
-];
diff --git a/packages/core/src/lint/rules/textures.test.ts b/packages/core/src/lint/rules/textures.test.ts
deleted file mode 100644
index c9505fa10a..0000000000
--- a/packages/core/src/lint/rules/textures.test.ts
+++ /dev/null
@@ -1,145 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { lintHyperframeHtml } from "../hyperframeLinter.js";
-
-function baseHtml(body: string, style = ""): string {
-  return `<html><body>
-  <div data-composition-id="main" data-width="1920" data-height="1080">
-    ${body}
-  </div>
-  <style>${style}</style>
-  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
-</body></html>`;
-}
-
-const textureCss = `
-.hf-texture-text {
-  color: #fff;
-  -webkit-mask-size: var(--mask-size, cover);
-  mask-size: var(--mask-size, cover);
-}
-.hf-texture-lava {
-  -webkit-mask-image: url("masks/lava.png");
-  mask-image: url("masks/lava.png");
-}
-`;
-
-describe("texture rules", () => {
-  it("does not warn for a valid texture mask text usage", async () => {
-    const html = baseHtml(
-      '<div class="shadow"><div class="hf-texture-text hf-texture-lava">TEXT</div></div>',
-      `${textureCss}.shadow { filter: drop-shadow(1px 2px 1px rgba(0,0,0,.48)); }`,
-    );
-
-    const result = await lintHyperframeHtml(html);
-
-    expect(result.findings.filter((finding) => finding.code.startsWith("texture_"))).toEqual([]);
-  });
-
-  it("warns when a material class is used without hf-texture-text", async () => {
-    const html = baseHtml('<div class="hf-texture-lava">TEXT</div>', textureCss);
-
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((item) => item.code === "texture_class_missing_base");
-
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("warning");
-    expect(finding?.fixHint).toContain("hf-texture-text");
-  });
-
-  it("warns when hf-texture-text has no material class or custom mask image", async () => {
-    const html = baseHtml('<div class="hf-texture-text">TEXT</div>', textureCss);
-
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((item) => item.code === "texture_text_missing_mask");
-
-    expect(finding).toBeDefined();
-    expect(finding?.severity).toBe("warning");
-  });
-
-  it("allows hf-texture-text with an inline custom mask image", async () => {
-    const html = baseHtml(
-      '<div class="hf-texture-text" style="-webkit-mask-image:url(custom.png); mask-image:url(custom.png)">TEXT</div>',
-      textureCss,
-    );
-
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((item) => item.code === "texture_text_missing_mask");
-
-    expect(finding).toBeUndefined();
-  });
-
-  it("warns when a texture material class is not defined by local CSS", async () => {
-    const html = baseHtml('<div class="hf-texture-text hf-texture-marbel">TEXT</div>', textureCss);
-
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((item) => item.code === "texture_class_unknown");
-
-    expect(finding).toBeDefined();
-    expect(finding?.message).toContain("hf-texture-marbel");
-  });
-
-  it("warns when drop-shadow is applied inline to the textured text element", async () => {
-    const html = baseHtml(
-      '<div class="hf-texture-text hf-texture-lava" style="filter: drop-shadow(1px 2px 1px black)">TEXT</div>',
-      textureCss,
-    );
-
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((item) => item.code === "texture_drop_shadow_on_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.fixHint).toContain("wrapper");
-  });
-
-  it("warns when drop-shadow is applied by CSS directly to hf-texture-text", async () => {
-    const html = baseHtml(
-      '<div class="hf-texture-text hf-texture-lava">TEXT</div>',
-      `${textureCss}.hf-texture-text { filter: drop-shadow(1px 2px 1px black); }`,
-    );
-
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((item) => item.code === "texture_drop_shadow_on_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.selector).toBe(".hf-texture-text");
-  });
-
-  it("warns when drop-shadow targets a material class before the mask rule is declared", async () => {
-    const html = baseHtml(
-      '<div class="hf-texture-text hf-texture-lava">TEXT</div>',
-      `.hf-texture-lava { filter: drop-shadow(1px 2px 1px black); }
-       ${textureCss}`,
-    );
-
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((item) => item.code === "texture_drop_shadow_on_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.selector).toBe(".hf-texture-lava");
-  });
-
-  it("warns when drop-shadow targets another class on the textured text element", async () => {
-    const html = baseHtml(
-      '<div class="hf-texture-text hf-texture-lava headline">TEXT</div>',
-      `${textureCss}.headline { filter: drop-shadow(1px 2px 1px black); }`,
-    );
-
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((item) => item.code === "texture_drop_shadow_on_text");
-
-    expect(finding).toBeDefined();
-    expect(finding?.selector).toBe(".headline");
-  });
-
-  it("does not warn when another-class drop-shadow selector needs an unmatched ancestor", async () => {
-    const html = baseHtml(
-      '<div class="hf-texture-text hf-texture-lava headline">TEXT</div>',
-      `${textureCss}.card .headline { filter: drop-shadow(1px 2px 1px black); }`,
-    );
-
-    const result = await lintHyperframeHtml(html);
-    const finding = result.findings.find((item) => item.code === "texture_drop_shadow_on_text");
-
-    expect(finding).toBeUndefined();
-  });
-});
diff --git a/packages/core/src/lint/rules/textures.ts b/packages/core/src/lint/rules/textures.ts
deleted file mode 100644
index 1ab1d7f92d..0000000000
--- a/packages/core/src/lint/rules/textures.ts
+++ /dev/null
@@ -1,226 +0,0 @@
-import postcss from "postcss";
-import type { LintContext, HyperframeLintFinding, OpenTag } from "../context";
-import { readAttr, truncateSnippet } from "../utils";
-
-const TEXTURE_BASE_CLASS = "hf-texture-text";
-const TEXTURE_CLASS_PREFIX = "hf-texture-";
-
-type DropShadowRule = {
-  selector: string;
-  directlyTargetsTexture: boolean;
-};
-
-function classNames(tag: OpenTag): string[] {
-  return (readAttr(tag.raw, "class") ?? "").split(/\s+/).filter(Boolean);
-}
-
-function isTextureMaterialClass(className: string): boolean {
-  return className.startsWith(TEXTURE_CLASS_PREFIX) && className !== TEXTURE_BASE_CLASS;
-}
-
-function hasInlineMaskImage(tag: OpenTag): boolean {
-  const style = readAttr(tag.raw, "style") ?? "";
-  return /\b(?:-webkit-)?mask-image\s*:/i.test(style);
-}
-
-function hasInlineDropShadow(tag: OpenTag): boolean {
-  const style = readAttr(tag.raw, "style") ?? "";
-  return /\bfilter\s*:\s*[^;]*\bdrop-shadow\s*\(/i.test(style);
-}
-
-function classNamesInSelector(selector: string): string[] {
-  const classes = new Set<string>();
-  const pattern = /\.([A-Za-z_][\w-]*)/g;
-  let match: RegExpExecArray | null;
-  while ((match = pattern.exec(selector)) !== null) {
-    const className = match[1];
-    if (!className) continue;
-    classes.add(className);
-  }
-  return [...classes];
-}
-
-function textureClassesInSelector(selector: string): string[] {
-  return classNamesInSelector(selector).filter(isTextureMaterialClass);
-}
-
-function simpleSelectorMatchesTag(selector: string, tag: OpenTag, tagClasses: string[]): boolean {
-  const trimmed = selector.trim();
-  const simpleSelectorPattern = /^(?:[A-Za-z][\w-]*)?(?:\.[A-Za-z_][\w-]*)+$/;
-  if (!simpleSelectorPattern.test(trimmed)) return false;
-
-  const typeMatch = /^([A-Za-z][\w-]*)/.exec(trimmed);
-  if (typeMatch && typeMatch[1]!.toLowerCase() !== tag.name) return false;
-
-  const selectorClasses = classNamesInSelector(trimmed);
-  return (
-    selectorClasses.length > 0 &&
-    selectorClasses.every((className) => tagClasses.includes(className))
-  );
-}
-
-function collectTextureCss(styles: LintContext["styles"]): {
-  definedTextureClasses: Set<string>;
-  dropShadowRules: DropShadowRule[];
-} {
-  const definedTextureClasses = new Set<string>();
-  const dropShadowRules: DropShadowRule[] = [];
-  const roots: postcss.Root[] = [];
-
-  for (const style of styles) {
-    let root: postcss.Root;
-    try {
-      root = postcss.parse(style.content);
-    } catch {
-      continue;
-    }
-    roots.push(root);
-
-    // fallow-ignore-next-line complexity
-    root.walkRules((rule) => {
-      const selectors = rule.selectors ?? [];
-      let hasMaskImage = false;
-
-      for (const node of rule.nodes ?? []) {
-        if (node.type !== "decl") continue;
-        const prop = node.prop.toLowerCase();
-        if (prop === "mask-image" || prop === "-webkit-mask-image") hasMaskImage = true;
-      }
-
-      if (hasMaskImage) {
-        for (const selector of selectors) {
-          for (const className of textureClassesInSelector(selector)) {
-            definedTextureClasses.add(className);
-          }
-        }
-      }
-    });
-  }
-
-  for (const root of roots) {
-    // fallow-ignore-next-line complexity
-    root.walkRules((rule) => {
-      const selectors = rule.selectors ?? [];
-      let hasDropShadow = false;
-
-      for (const node of rule.nodes ?? []) {
-        if (node.type !== "decl") continue;
-        if (node.prop.toLowerCase() === "filter" && /\bdrop-shadow\s*\(/i.test(node.value)) {
-          hasDropShadow = true;
-        }
-      }
-
-      if (hasDropShadow) {
-        for (const selector of selectors) {
-          const targetsBaseClass = /\.hf-texture-text\b/.test(selector);
-          const targetsDefinedTextureClass = textureClassesInSelector(selector).some((className) =>
-            definedTextureClasses.has(className),
-          );
-          dropShadowRules.push({
-            selector,
-            directlyTargetsTexture: targetsBaseClass || targetsDefinedTextureClass,
-          });
-        }
-      }
-    });
-  }
-
-  return { definedTextureClasses, dropShadowRules };
-}
-
-// fallow-ignore-next-line complexity
-export const textureRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
-  ({ tags, styles }) => {
-    const findings: HyperframeLintFinding[] = [];
-    const { definedTextureClasses, dropShadowRules } = collectTextureCss(styles);
-
-    for (const { selector, directlyTargetsTexture } of dropShadowRules) {
-      if (!directlyTargetsTexture) continue;
-      findings.push({
-        code: "texture_drop_shadow_on_text",
-        severity: "warning",
-        message: "Drop shadow is applied directly to textured text.",
-        selector,
-        fixHint:
-          "Wrap the textured text and apply `filter: drop-shadow(...)` to the wrapper, not the `hf-texture-text` element.",
-      });
-    }
-
-    for (const tag of tags) {
-      if (tag.name === "style" || tag.name === "script") continue;
-
-      const classes = classNames(tag);
-      if (classes.length === 0) continue;
-
-      const hasBaseClass = classes.includes(TEXTURE_BASE_CLASS);
-      const textureClasses = classes.filter(isTextureMaterialClass);
-
-      if (textureClasses.length > 0 && !hasBaseClass) {
-        findings.push({
-          code: "texture_class_missing_base",
-          severity: "warning",
-          message: `Texture material class \`${textureClasses[0]}\` is used without \`${TEXTURE_BASE_CLASS}\`.`,
-          elementId: readAttr(tag.raw, "id") || undefined,
-          fixHint: `Add \`${TEXTURE_BASE_CLASS}\` alongside the material class, for example \`class="${TEXTURE_BASE_CLASS} ${textureClasses[0]}"\`.`,
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-
-      if (hasBaseClass && textureClasses.length === 0 && !hasInlineMaskImage(tag)) {
-        findings.push({
-          code: "texture_text_missing_mask",
-          severity: "warning",
-          message: `\`${TEXTURE_BASE_CLASS}\` is used without a texture material class or custom mask image.`,
-          elementId: readAttr(tag.raw, "id") || undefined,
-          fixHint:
-            "Add a material class such as `hf-texture-lava`, or set `mask-image` and `-webkit-mask-image` on the element.",
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-
-      for (const textureClass of textureClasses) {
-        if (definedTextureClasses.has(textureClass)) continue;
-        findings.push({
-          code: "texture_class_unknown",
-          severity: "error",
-          message: `Texture material class \`${textureClass}\` is not defined by local CSS.`,
-          elementId: readAttr(tag.raw, "id") || undefined,
-          fixHint:
-            "Paste the Texture Mask Text component `<style>...</style>` block into the composition, or fix the texture class typo.",
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-
-      if (hasBaseClass) {
-        for (const rule of dropShadowRules) {
-          if (rule.directlyTargetsTexture) continue;
-          if (!simpleSelectorMatchesTag(rule.selector, tag, classes)) continue;
-          findings.push({
-            code: "texture_drop_shadow_on_text",
-            severity: "warning",
-            message: "Drop shadow is applied directly to textured text.",
-            selector: rule.selector,
-            elementId: readAttr(tag.raw, "id") || undefined,
-            fixHint:
-              "Wrap the textured text and apply `filter: drop-shadow(...)` to the wrapper, not the `hf-texture-text` element.",
-            snippet: truncateSnippet(tag.raw),
-          });
-        }
-      }
-
-      if (hasBaseClass && hasInlineDropShadow(tag)) {
-        findings.push({
-          code: "texture_drop_shadow_on_text",
-          severity: "warning",
-          message: "Drop shadow is applied directly to textured text.",
-          elementId: readAttr(tag.raw, "id") || undefined,
-          fixHint:
-            "Wrap the textured text and apply `filter: drop-shadow(...)` to the wrapper, not the `hf-texture-text` element.",
-          snippet: truncateSnippet(tag.raw),
-        });
-      }
-    }
-
-    return findings;
-  },
-];
diff --git a/packages/core/src/lint/types.ts b/packages/core/src/lint/types.ts
deleted file mode 100644
index 8911566f93..0000000000
--- a/packages/core/src/lint/types.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-export type HyperframeLintSeverity = "error" | "warning" | "info";
-
-export type HyperframeLintFinding = {
-  code: string;
-  severity: HyperframeLintSeverity;
-  message: string;
-  file?: string;
-  selector?: string;
-  elementId?: string;
-  fixHint?: string;
-  snippet?: string;
-};
-
-export type HyperframeLintResult = {
-  ok: boolean;
-  errorCount: number;
-  warningCount: number;
-  infoCount: number;
-  findings: HyperframeLintFinding[];
-};
-
-export type HyperframeLinterOptions = {
-  filePath?: string;
-  isSubComposition?: boolean;
-  externalStyles?: Array<{ href: string; content: string }>;
-  /**
-   * Set to `true` when linting compositions destined for distributed / Lambda
-   * rendering, where system-font capture (`allowSystemFontCapture`) is
-   * disabled.  When `true`, the `system_font_will_alias` rule is elevated from
-   * `"info"` to `"warning"` because the alias substitution will NOT happen at
-   * render time — the font will silently fall back to whatever the OS provides.
-   */
-  distributed?: boolean;
-};
-
-// A rule is a function: receives parsed context, returns zero or more findings.
-// Rules may be async (e.g. when lazy-loading heavy dependencies like recast).
-export type LintRule<TContext> = (
-  ctx: TContext,
-) => HyperframeLintFinding[] | Promise<HyperframeLintFinding[]>;
diff --git a/packages/core/src/lint/utils.ts b/packages/core/src/lint/utils.ts
deleted file mode 100644
index 21c24ce6e5..0000000000
--- a/packages/core/src/lint/utils.ts
+++ /dev/null
@@ -1,300 +0,0 @@
-// Shared types, regex constants, and utility functions used across lint rule modules.
-// Nothing in this file should emit findings — it only parses and extracts.
-
-export type OpenTag = {
-  raw: string;
-  name: string;
-  attrs: string;
-  index: number;
-};
-
-export type ExtractedBlock = {
-  attrs: string;
-  content: string;
-  raw: string;
-  index: number;
-};
-
-const TAG_PATTERN = /<([a-z][\w:-]*)(\s[^<>]*?)?>/gi;
-export const STYLE_BLOCK_PATTERN = /<style\b([^>]*)>([\s\S]*?)<\/style>/gi;
-export const SCRIPT_BLOCK_PATTERN = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
-const COMPOSITION_ID_IN_CSS_PATTERN = /\[data-composition-id=["']([^"']+)["']\]/g;
-export const TIMELINE_REGISTRY_INIT_PATTERN =
-  /window\.__timelines\s*=\s*window\.__timelines\s*\|\|\s*\{\}|window\.__timelines\s*=\s*\{\}|window\.__timelines\s*\?\?=\s*\{\}/i;
-export const TIMELINE_REGISTRY_ASSIGN_PATTERN =
-  /window\.__timelines(?:\[[^\]]+\]|\.[A-Za-z_$][\w$]*)\s*=/i;
-export const WINDOW_TIMELINE_ASSIGN_PATTERN =
-  /window\.__timelines(?:\[\s*["']([^"']+)["']\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*=\s*([A-Za-z_$][\w$]*)/i;
-export const INVALID_SCRIPT_CLOSE_PATTERN = /<script[^>]*>[\s\S]*?<\s*\/\s*script(?!>)/i;
-
-const TIMELINE_REGISTRY_KEY_PATTERN =
-  /window\.__timelines(?:\[\s*["']([^"']+)["']\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*=/g;
-
-export function extractOpenTags(source: string): OpenTag[] {
-  const tags: OpenTag[] = [];
-  let match: RegExpExecArray | null;
-  const pattern = new RegExp(TAG_PATTERN.source, TAG_PATTERN.flags);
-  while ((match = pattern.exec(source)) !== null) {
-    const raw = match[0];
-    if (raw.startsWith("</") || raw.startsWith("<!")) continue;
-    tags.push({
-      raw,
-      name: (match[1] || "").toLowerCase(),
-      attrs: match[2] || "",
-      index: match.index,
-    });
-  }
-  return tags;
-}
-
-export function extractBlocks(source: string, pattern: RegExp): ExtractedBlock[] {
-  const blocks: ExtractedBlock[] = [];
-  let match: RegExpExecArray | null;
-  const p = new RegExp(pattern.source, pattern.flags);
-  while ((match = p.exec(source)) !== null) {
-    blocks.push({
-      attrs: match[1] || "",
-      content: match[2] || "",
-      raw: match[0],
-      index: match.index,
-    });
-  }
-  return blocks;
-}
-
-/**
- * Find the `<html>` open tag in the source. Distinct from `findRootTag`,
- * which returns the first element inside `<body>` — the latter is "the
- * composition's visible root", whereas `<html>` is where document-level
- * metadata like `data-composition-variables` lives.
- */
-export function findHtmlTag(source: string): OpenTag | null {
-  const match = /<html\b([^<>]*)>/i.exec(source);
-  if (!match) return null;
-  return {
-    raw: match[0],
-    name: "html",
-    attrs: match[1] ?? "",
-    index: match.index,
-  };
-}
-
-export function findRootTag(source: string): OpenTag | null {
-  const bodyOpenMatch = /<body\b([^>]*)>/i.exec(source);
-  const bodyCloseMatch = /<\/body>/i.exec(source);
-  if (
-    bodyOpenMatch &&
-    (readAttr(bodyOpenMatch[0], "data-composition-id") ||
-      readAttr(bodyOpenMatch[0], "data-width") ||
-      readAttr(bodyOpenMatch[0], "data-height"))
-  ) {
-    return {
-      raw: bodyOpenMatch[0],
-      name: "body",
-      attrs: bodyOpenMatch[1] ?? "",
-      index: bodyOpenMatch.index,
-    };
-  }
-  const bodyStart = bodyOpenMatch ? bodyOpenMatch.index + bodyOpenMatch[0].length : 0;
-  const bodyEnd =
-    bodyOpenMatch && bodyCloseMatch && bodyCloseMatch.index > bodyStart
-      ? bodyCloseMatch.index
-      : source.length;
-  const bodyContent = bodyOpenMatch ? source.slice(bodyStart, bodyEnd) : source;
-  const bodyTags = extractOpenTags(bodyContent);
-  for (const tag of bodyTags) {
-    if (["script", "style", "meta", "link", "title"].includes(tag.name)) continue;
-    return { ...tag, index: tag.index + bodyStart };
-  }
-  return null;
-}
-
-export function readAttr(tagSource: string, attr: string): string | null {
-  if (!tagSource) return null;
-  const escaped = attr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const match = tagSource.match(new RegExp(`\\b${escaped}\\s*=\\s*["']([^"']+)["']`, "i"));
-  return match?.[1] || null;
-}
-
-/**
- * Read an attribute that may legitimately contain the opposite quote
- * character. `readAttr` truncates `data-variable-values='{"title":"Hello"}'`
- * at the first internal `"` because its `[^"']+` class excludes both quote
- * types. This variant alternates: a double-quoted value never contains an
- * unescaped `"`, and a single-quoted value never contains an unescaped `'`,
- * so each branch can use a quote-specific class.
- *
- * Use for attributes whose values are JSON or otherwise carry the opposite
- * quote character. Existing single-token attributes (`id`, `class`, etc.)
- * stick with `readAttr` for consistency with the rest of the lint code.
- */
-export function readJsonAttr(tagSource: string, attr: string): string | null {
-  if (!tagSource) return null;
-  const escaped = attr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const match = tagSource.match(new RegExp(`\\b${escaped}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, "i"));
-  if (!match) return null;
-  return match[1] ?? match[2] ?? null;
-}
-
-export function collectCompositionIds(tags: OpenTag[]): Set<string> {
-  const ids = new Set<string>();
-  for (const tag of tags) {
-    const compId = readAttr(tag.raw, "data-composition-id");
-    if (compId) ids.add(compId);
-  }
-  return ids;
-}
-
-export function extractCompositionIdsFromCss(css: string): string[] {
-  const ids = new Set<string>();
-  let match: RegExpExecArray | null;
-  const pattern = new RegExp(
-    COMPOSITION_ID_IN_CSS_PATTERN.source,
-    COMPOSITION_ID_IN_CSS_PATTERN.flags,
-  );
-  while ((match = pattern.exec(css)) !== null) {
-    if (match[1]) ids.add(match[1]);
-  }
-  return [...ids];
-}
-
-export function extractTimelineRegistryKeys(source: string): string[] {
-  const keys = new Set<string>();
-  let match: RegExpExecArray | null;
-  const pattern = new RegExp(
-    TIMELINE_REGISTRY_KEY_PATTERN.source,
-    TIMELINE_REGISTRY_KEY_PATTERN.flags,
-  );
-  while ((match = pattern.exec(source)) !== null) {
-    const key = match[1] ?? match[2];
-    if (key) keys.add(key);
-  }
-  return [...keys];
-}
-
-export function getInlineScriptSyntaxError(source: string): string | null {
-  if (!source.trim()) return null;
-  try {
-    // eslint-disable-next-line no-new-func
-    new Function(source);
-    return null;
-  } catch (error) {
-    if (error instanceof Error) return error.message;
-    return String(error);
-  }
-}
-
-// fallow-ignore-next-line complexity
-export function stripJsComments(source: string): string {
-  let out = "";
-  let i = 0;
-  let quote: "'" | '"' | "`" | null = null;
-  let escaped = false;
-
-  while (i < source.length) {
-    const ch = source[i] ?? "";
-    const next = source[i + 1] ?? "";
-
-    if (quote) {
-      out += ch;
-      if (escaped) {
-        escaped = false;
-      } else if (ch === "\\") {
-        escaped = true;
-      } else if (ch === quote) {
-        quote = null;
-      }
-      i += 1;
-      continue;
-    }
-
-    if (ch === "'" || ch === '"' || ch === "`") {
-      quote = ch;
-      out += ch;
-      i += 1;
-      continue;
-    }
-
-    if (ch === "/" && next === "/") {
-      out += "  ";
-      i += 2;
-      while (i < source.length && source[i] !== "\n" && source[i] !== "\r") {
-        out += " ";
-        i += 1;
-      }
-      continue;
-    }
-
-    if (ch === "/" && next === "*") {
-      out += "  ";
-      i += 2;
-      while (i < source.length) {
-        const blockCh = source[i] ?? "";
-        const blockNext = source[i + 1] ?? "";
-        if (blockCh === "*" && blockNext === "/") {
-          out += "  ";
-          i += 2;
-          break;
-        }
-        out += blockCh === "\n" || blockCh === "\r" ? blockCh : " ";
-        i += 1;
-      }
-      continue;
-    }
-
-    out += ch;
-    i += 1;
-  }
-
-  return out;
-}
-
-// One linear pass that drops every `<!-- … -->` region. Uses indexOf, not a
-// `/<!--[\s\S]*?-->/` regex: that pattern backtracks O(n²) on inputs with many
-// unterminated "<!--" (CodeQL js/polynomial-redos). An unterminated "<!--" with
-// no closing "-->" is kept verbatim, matching the prior regex's no-match behavior.
-function stripHtmlCommentsOnce(source: string): string {
-  let out = "";
-  let i = 0;
-  for (;;) {
-    const start = source.indexOf("<!--", i);
-    if (start < 0) return out + source.slice(i);
-    const end = source.indexOf("-->", start + 4);
-    if (end < 0) return out + source.slice(i);
-    out += source.slice(i, start);
-    i = end + 3;
-  }
-}
-
-// Strip HTML comments to a fixpoint. A single pass is not enough: deleting one
-// comment can splice adjacent markers into a fresh, complete <!-- … --> (e.g.
-// "<<!-- -->!-- … -->" → "<!-- … -->"), which would otherwise survive and let a
-// commented-out <template>/tag hijack the linter's tag scan.
-export function stripHtmlComments(source: string): string {
-  let out = source;
-  for (let prev = ""; prev !== out; ) {
-    prev = out;
-    out = stripHtmlCommentsOnce(out);
-  }
-  return out;
-}
-
-export function extractScriptTextsAndSrcs(scripts: ExtractedBlock[]): {
-  texts: string[];
-  srcs: string[];
-} {
-  const texts = scripts.filter((s) => !/\bsrc\s*=/.test(s.attrs)).map((s) => s.content);
-  const srcs = scripts.map((s) => readAttr(`<script ${s.attrs}>`, "src") || "").filter(Boolean);
-  return { texts, srcs };
-}
-
-export function isMediaTag(tagName: string): boolean {
-  return tagName === "video" || tagName === "audio" || tagName === "img";
-}
-
-export function truncateSnippet(value: string, maxLength = 220): string | undefined {
-  const normalized = value.replace(/\s+/g, " ").trim();
-  if (!normalized) return undefined;
-  if (normalized.length <= maxLength) return normalized;
-  return `${normalized.slice(0, maxLength - 3)}...`;
-}