feat(lint): add prefer_container_units rule, drop runtime injection

Adds a lint rule that suggests cqw/cqh over px for positioning and
sizing on elements inside compositions. Severity: info (suggestion).
Calculates the exact container-unit equivalent based on composition
dimensions. Drops the runtime container-type injection per feedback —
authors opt in explicitly via CSS.

8 new tests covering suggestions, unit selection, value calculation,
small-value exemption, and tag filtering.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: miguel-heygen

packages/core/src/lint/hyperframeLinter.ts

@@ -7,6 +7,7 @@ import { gsapRules } from "./rules/gsap";
 import { captionRules } from "./rules/captions";
 import { compositionRules } from "./rules/composition";
 import { adapterRules } from "./rules/adapters";
+import { responsiveUnitRules } from "./rules/responsiveUnits";
 
 const ALL_RULES = [
   ...coreRules,
@@ -15,6 +16,7 @@ const ALL_RULES = [
   ...captionRules,
   ...compositionRules,
   ...adapterRules,
+  ...responsiveUnitRules,
 ];
 
 export function lintHyperframeHtml(

packages/core/src/lint/rules/responsiveUnits.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from "vitest";
+import { lintHyperframeHtml } from "../hyperframeLinter";
+
+function findByCode(html: string, code: string) {
+  return lintHyperframeHtml(html).findings.filter((f) => f.code === code);
+}
+
+describe("prefer_container_units", () => {
+  it("flags px positioning on elements inside a composition", () => {
+    const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+      <h1 style="position:absolute; left:96px; top:108px; font-size:64px;">Title</h1>
+    </div>`;
+    const findings = findByCode(html, "prefer_container_units");
+    expect(findings.length).toBeGreaterThanOrEqual(3);
+    expect(findings.some((f) => f.message.includes("left"))).toBe(true);
+    expect(findings.some((f) => f.message.includes("top"))).toBe(true);
+    expect(findings.some((f) => f.message.includes("font-size"))).toBe(true);
+  });
+
+  it("suggests cqw for horizontal properties", () => {
+    const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+      <div style="left:192px;">content</div>
+    </div>`;
+    const findings = findByCode(html, "prefer_container_units");
+    expect(findings[0].message).toContain("cqw");
+  });
+
+  it("suggests cqh for vertical properties", () => {
+    const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+      <div style="top:108px;">content</div>
+    </div>`;
+    const findings = findByCode(html, "prefer_container_units");
+    expect(findings[0].message).toContain("cqh");
+  });
+
+  it("calculates correct container unit values", () => {
+    const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+      <div style="left:96px;">content</div>
+    </div>`;
+    const findings = findByCode(html, "prefer_container_units");
+    expect(findings[0].message).toContain("5cqw");
+  });
+
+  it("ignores small px values (borders, shadows)", () => {
+    const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+      <div style="border-radius:2px; width:4px;">content</div>
+    </div>`;
+    const findings = findByCode(html, "prefer_container_units");
+    expect(findings).toHaveLength(0);
+  });
+
+  it("ignores composition root elements", () => {
+    const html = `<div data-composition-id="test" data-width="1920" data-height="1080" style="width:1920px; height:1080px;">
+      <p>content</p>
+    </div>`;
+    const findings = findByCode(html, "prefer_container_units");
+    expect(findings).toHaveLength(0);
+  });
+
+  it("ignores script, style, and audio tags", () => {
+    const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+      <script style="width:500px;"></script>
+      <style>body { width: 1920px; }</style>
+      <audio style="width:100px;" data-start="0" src="vo.mp3"></audio>
+    </div>`;
+    const findings = findByCode(html, "prefer_container_units");
+    expect(findings).toHaveLength(0);
+  });
+
+  it("severity is info (suggestion, not error)", () => {
+    const html = `<div data-composition-id="test" data-width="1920" data-height="1080">
+      <div style="left:200px;">content</div>
+    </div>`;
+    const findings = findByCode(html, "prefer_container_units");
+    expect(findings[0].severity).toBe("info");
+  });
+});

packages/core/src/lint/rules/responsiveUnits.ts

@@ -0,0 +1,71 @@
+import type { LintContext, HyperframeLintFinding, OpenTag } from "../context";
+import { readAttr, truncateSnippet } from "../utils";
+
+const POSITION_PROPS =
+  /\b(left|right|top|bottom|width|height|font-size|padding|margin|gap|border-radius)\s*:\s*(\d+(?:\.\d+)?)px/gi;
+
+function isCompositionRoot(tag: OpenTag): boolean {
+  return Boolean(readAttr(tag.raw, "data-composition-id"));
+}
+
+function suggestUnit(prop: string): string {
+  const p = prop.toLowerCase();
+  if (p === "top" || p === "bottom" || p === "height") return "cqh";
+  return "cqw";
+}
+
+function pxToContainerUnit(
+  px: number,
+  prop: string,
+  compWidth: number,
+  compHeight: number,
+): string {
+  const unit = suggestUnit(prop);
+  const base = unit === "cqh" ? compHeight : compWidth;
+  if (base <= 0) return `${px}px`;
+  const value = (px / base) * 100;
+  const rounded = Math.round(value * 100) / 100;
+  return `${rounded}${unit}`;
+}
+
+export const responsiveUnitRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
+  (ctx) => {
+    const findings: HyperframeLintFinding[] = [];
+    if (!ctx.rootTag) return findings;
+
+    const widthAttr = readAttr(ctx.rootTag.raw, "data-width");
+    const heightAttr = readAttr(ctx.rootTag.raw, "data-height");
+    const compWidth = parseInt(widthAttr || "1920", 10);
+    const compHeight = parseInt(heightAttr || "1080", 10);
+
+    for (const tag of ctx.tags) {
+      if (isCompositionRoot(tag)) continue;
+      if (tag.name === "script" || tag.name === "style" || tag.name === "audio") continue;
+
+      const style = readAttr(tag.raw, "style") || "";
+      if (!style) continue;
+
+      let match: RegExpExecArray | null;
+      POSITION_PROPS.lastIndex = 0;
+      while ((match = POSITION_PROPS.exec(style)) !== null) {
+        const prop = match[1] ?? "";
+        const px = parseFloat(match[2] ?? "0");
+        if (px <= 4) continue;
+
+        const elementId = readAttr(tag.raw, "id") || undefined;
+        const suggested = pxToContainerUnit(px, prop, compWidth, compHeight);
+
+        findings.push({
+          code: "prefer_container_units",
+          severity: "info",
+          message: `${prop}: ${px}px could be ${suggested} for aspect-ratio independence.`,
+          elementId,
+          fixHint: `Use container-relative units (cqw/cqh) instead of px for layout properties. Add container-type:size to the composition root, then replace ${prop}: ${px}px with ${prop}: ${suggested}.`,
+          snippet: truncateSnippet(tag.raw),
+        });
+      }
+    }
+
+    return findings;
+  },
+];

packages/core/src/runtime/init.ts

@@ -230,7 +230,6 @@ export function initSandboxRuntimeModular(): void {
     if (forcedHeight) rootEl.style.height = forcedHeight;
     if (forcedWidth) rootEl.style.setProperty("--comp-width", forcedWidth);
     if (forcedHeight) rootEl.style.setProperty("--comp-height", forcedHeight);
-    rootEl.style.containerType = "size";
   };
 
   const sanitizeCompositionDurationAttributes = () => {