hyperframes 0.7.78 → 0.7.79

package/dist/cli.js

@@ -50,7 +50,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.7.78" : "0.0.0-dev";
+    VERSION = true ? "0.7.79" : "0.0.0-dev";
   }
 });
 
@@ -62373,6 +62373,30 @@ var init_feedbackRating = __esm({
   }
 });
 
+// src/utils/errorMessage.ts
+function normalizeErrorMessage(error) {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  if (typeof error === "object" && error !== null) {
+    const msg = error.message;
+    if (typeof msg === "string") return msg;
+    try {
+      return JSON.stringify(error);
+    } catch {
+      try {
+        return `{${Object.keys(error).join(", ")}}`;
+      } catch {
+      }
+    }
+  }
+  return String(error ?? "unknown error");
+}
+var init_errorMessage = __esm({
+  "src/utils/errorMessage.ts"() {
+    "use strict";
+  }
+});
+
 // src/telemetry/config.ts
 import { existsSync as existsSync2, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
 import { join as join3 } from "path";
@@ -62425,7 +62449,11 @@ function readConfig() {
     cachedConfig = config;
     return { ...config };
   } catch {
-    const config = { ...DEFAULT_CONFIG, anonymousId: randomUUID() };
+    const config = {
+      ...DEFAULT_CONFIG,
+      telemetryEnabled: false,
+      anonymousId: randomUUID()
+    };
     writeConfig(config);
     return config;
   }
@@ -62435,15 +62463,18 @@ function readConfigFresh() {
   return readConfig();
 }
 function writeConfig(config) {
+  return writeConfigWithResult(config).ok;
+}
+function writeConfigWithResult(config) {
   try {
     mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
     const tmpFile = `${CONFIG_FILE}.${process.pid}.tmp`;
     writeFileSync(tmpFile, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
     renameSync(tmpFile, CONFIG_FILE);
     cachedConfig = { ...config };
-    return true;
-  } catch {
-    return false;
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: normalizeErrorMessage(error) };
   }
 }
 function incrementCommandCount() {
@@ -62456,6 +62487,7 @@ var CONFIG_DIR, CONFIG_FILE, MAX_RECENT_RENDERS, DEFAULT_CONFIG, cachedConfig, C
 var init_config = __esm({
   "src/telemetry/config.ts"() {
     "use strict";
+    init_errorMessage();
     CONFIG_DIR = join3(homedir(), ".hyperframes");
     CONFIG_FILE = join3(CONFIG_DIR, "config.json");
     MAX_RECENT_RENDERS = 5;
@@ -62594,21 +62626,6 @@ var init_diagnostics2 = __esm({
   }
 });
 
-// src/utils/env.ts
-function isDevMode() {
-  try {
-    const url = new URL(import.meta.url);
-    return url.pathname.endsWith(".ts");
-  } catch {
-    return false;
-  }
-}
-var init_env = __esm({
-  "src/utils/env.ts"() {
-    "use strict";
-  }
-});
-
 // ../engine/src/services/systemMemory.ts
 import { readFileSync as readFileSync2 } from "fs";
 import { totalmem } from "os";
@@ -88795,18 +88812,59 @@ var init_transport = __esm({
   }
 });
 
-// src/telemetry/client.ts
-function shouldTrack() {
-  if (telemetryEnabled !== null) return telemetryEnabled;
-  if (process.env["HYPERFRAMES_NO_TELEMETRY"] === "1" || process.env["DO_NOT_TRACK"] === "1") {
-    telemetryEnabled = false;
+// src/utils/env.ts
+function isDevMode() {
+  try {
+    const url = new URL(import.meta.url);
+    return url.pathname.endsWith(".ts");
+  } catch {
     return false;
   }
+}
+var init_env = __esm({
+  "src/utils/env.ts"() {
+    "use strict";
+  }
+});
+
+// src/telemetry/policy.ts
+function isEnvOptOutValue(value) {
+  return value !== void 0 && ENV_OPT_OUT_VALUES.has(value.trim().toLowerCase());
+}
+function telemetryRuntimeOverride() {
+  if (isEnvOptOutValue(process.env["HYPERFRAMES_NO_TELEMETRY"])) {
+    return "HYPERFRAMES_NO_TELEMETRY";
+  }
+  if (isEnvOptOutValue(process.env["DO_NOT_TRACK"])) {
+    return "DO_NOT_TRACK";
+  }
   if (isDevMode()) {
-    telemetryEnabled = false;
-    return false;
+    return "dev_mode";
   }
   if (!POSTHOG_API_KEY.startsWith("phc_")) {
+    return "telemetry_disabled_build";
+  }
+  return null;
+}
+function effectiveTelemetryStatus(configEnabled) {
+  const override = telemetryRuntimeOverride();
+  if (override !== null) return { enabled: false, source: override };
+  return { enabled: configEnabled, source: "config" };
+}
+var ENV_OPT_OUT_VALUES;
+var init_policy = __esm({
+  "src/telemetry/policy.ts"() {
+    "use strict";
+    init_env();
+    init_transport();
+    ENV_OPT_OUT_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+  }
+});
+
+// src/telemetry/client.ts
+function shouldTrack() {
+  if (telemetryEnabled !== null) return telemetryEnabled;
+  if (telemetryRuntimeOverride() !== null) {
     telemetryEnabled = false;
     return false;
   }
@@ -88870,9 +88928,9 @@ var init_client = __esm({
     init_version();
     init_colors();
     init_diagnostics2();
-    init_env();
     init_system();
     init_transport();
+    init_policy();
     init_transport();
     telemetryEnabled = null;
   }
@@ -93480,9 +93538,10 @@ async function checkForUpdate(force) {
       return fallbackResult(config.latestVersion);
     }
     const latest = data2.version;
-    config.lastUpdateCheck = (/* @__PURE__ */ new Date()).toISOString();
-    config.latestVersion = latest;
-    writeConfig(config);
+    const freshConfig = readConfigFresh();
+    freshConfig.lastUpdateCheck = (/* @__PURE__ */ new Date()).toISOString();
+    freshConfig.latestVersion = latest;
+    writeConfig(freshConfig);
     return { current: VERSION, latest, updateAvailable: isNewerSemver(latest, VERSION) };
   } catch {
     return fallbackResult(config.latestVersion);
@@ -94875,30 +94934,6 @@ var init_storyboard = __esm({
   }
 });
 
-// src/utils/errorMessage.ts
-function normalizeErrorMessage(error) {
-  if (error instanceof Error) return error.message;
-  if (typeof error === "string") return error;
-  if (typeof error === "object" && error !== null) {
-    const msg = error.message;
-    if (typeof msg === "string") return msg;
-    try {
-      return JSON.stringify(error);
-    } catch {
-      try {
-        return `{${Object.keys(error).join(", ")}}`;
-      } catch {
-      }
-    }
-  }
-  return String(error ?? "unknown error");
-}
-var init_errorMessage = __esm({
-  "src/utils/errorMessage.ts"() {
-    "use strict";
-  }
-});
-
 // src/utils/openBrowser.ts
 import { spawn as spawn7 } from "child_process";
 function parseRemoteDebuggingPort(value) {
@@ -139816,12 +139851,17 @@ function geometryIssueAnchor(candidate, time) {
     rect: candidate.rect
   };
 }
+function captionCenterInZone(rect, zone, canvas) {
+  const cx = rect.left + rect.width / 2;
+  const cy = rect.top + rect.height / 2;
+  const inside = cx >= zone.x0 * canvas.width && cx <= zone.x1 * canvas.width && cy >= zone.y0 * canvas.height && cy <= zone.y1 * canvas.height;
+  return { inside, cy };
+}
 function captionFinding(candidate, options, canvas, time) {
   const zone = options.captionZone;
   if (!zone || candidate.kind !== "text" || !candidateIsSized(candidate, canvas)) return null;
-  const cx = candidate.rect.left + candidate.rect.width / 2;
-  const cy = candidate.rect.top + candidate.rect.height / 2;
-  const inside = cx >= zone.x0 * canvas.width && cx <= zone.x1 * canvas.width && cy >= zone.y0 * canvas.height && cy <= zone.y1 * canvas.height;
+  if ("data-layout-allow-caption-zone" in candidate.dataAttributes) return null;
+  const { inside, cy } = captionCenterInZone(candidate.rect, zone, canvas);
   if (!inside) return null;
   const text2 = candidate.text.slice(0, 48);
   const pctFromBottom = Math.round((canvas.height - cy) / canvas.height * 100);
@@ -139833,7 +139873,7 @@ function captionFinding(candidate, options, canvas, time) {
       severity: zone.severity === "error" ? "error" : "warning",
       text: text2,
       message: `<${candidate.tag}> "${text2}" is centred in the reserved caption band (~${pctFromBottom}% up from the bottom).`,
-      fixHint: "Keep main content outside the configured caption band."
+      fixHint: "Keep main content outside the configured caption band, or mark intentional lower-third copy with data-layout-allow-caption-zone."
     }
   };
 }
@@ -147313,42 +147353,67 @@ __export(telemetry_exports, {
   default: () => telemetry_default,
   examples: () => examples27
 });
-function runEnable() {
-  const config = readConfig();
-  config.telemetryEnabled = true;
-  writeConfig(config);
-  console.log(`
-  ${c.success("\u2713")}  Telemetry ${c.success("enabled")}
-`);
+function describeOverride(source) {
+  switch (source) {
+    case "HYPERFRAMES_NO_TELEMETRY":
+    case "DO_NOT_TRACK":
+      return `${source} is set`;
+    case "dev_mode":
+      return "this is a development build";
+    case "telemetry_disabled_build":
+      return "this build has no telemetry key";
+  }
 }
-function runDisable() {
-  const config = readConfig();
-  config.telemetryEnabled = false;
-  writeConfig(config);
+function setTelemetryEnabled(enabled) {
+  const config = readConfigFresh();
+  config.telemetryEnabled = enabled;
+  const result = writeConfigWithResult(config);
+  if (!result.ok) {
+    console.error(
+      `
+  ${c.error("\u2717")}  Could not persist telemetry preference to ${c.accent(CONFIG_PATH)}
+  ${c.dim("Reason:")} ${result.error}
+`
+    );
+    failCommand();
+  }
+  const effective = effectiveTelemetryStatus(enabled);
+  const preference = enabled ? c.success("enabled") : c.bold("disabled");
+  const noun = enabled && !effective.enabled ? "Telemetry preference" : "Telemetry";
   console.log(`
-  ${c.success("\u2713")}  Telemetry ${c.bold("disabled")}
-`);
+  ${c.success("\u2713")}  ${noun} ${preference}`);
+  if (effective.source !== "config") {
+    console.log(
+      `  ${c.dim("Note:")} Telemetry remains disabled because ${describeOverride(effective.source)}.`
+    );
+  }
+  console.log();
 }
 function runStatus() {
-  const config = readConfig();
-  const status = config.telemetryEnabled ? c.success("enabled") : c.dim("disabled");
+  const config = readConfigFresh();
+  const effective = effectiveTelemetryStatus(config.telemetryEnabled);
+  const status = effective.enabled ? c.success("enabled") : c.dim("disabled");
   console.log();
   console.log(`  ${c.dim("Status:")}     ${status}`);
+  console.log(`  ${c.dim("Source:")}     ${effective.source}`);
   console.log(`  ${c.dim("Config:")}     ${c.accent(CONFIG_PATH)}`);
-  console.log(`  ${c.dim("Commands:")}   ${c.bold(String(config.commandCount))}`);
+  console.log(`  ${c.dim("Tracked commands:")} ${c.bold(String(config.commandCount))}`);
   console.log();
   console.log(`  ${c.dim("Disable:")}    ${c.accent("hyperframes telemetry disable")}`);
-  console.log(`  ${c.dim("Env var:")}    ${c.accent("HYPERFRAMES_NO_TELEMETRY=1")}`);
+  console.log(
+    `  ${c.dim("Env var:")}    ${c.accent("HYPERFRAMES_NO_TELEMETRY=1")} ${c.dim("or")} ${c.accent("DO_NOT_TRACK=1")}`
+  );
   console.log();
 }
 var examples27, telemetry_default;
 var init_telemetry = __esm({
   "src/commands/telemetry.ts"() {
     "use strict";
-    init_commandResult();
     init_dist();
-    init_colors();
     init_config();
+    init_policy();
+    init_colors();
+    init_commandResult();
     examples27 = [
       ["Check current telemetry status", "hyperframes telemetry status"],
       ["Disable telemetry", "hyperframes telemetry disable"],
@@ -147387,15 +147452,15 @@ ${c.bold("WHAT WE DON'T COLLECT:")}
   ${c.dim("\u2022")} IP addresses (discarded by our analytics provider)
   ${c.dim("\u2022")} Any personally identifiable information
 
-${c.dim("You can also set")} ${c.accent("HYPERFRAMES_NO_TELEMETRY=1")} ${c.dim("to disable.")}
+${c.dim("You can also set")} ${c.accent("HYPERFRAMES_NO_TELEMETRY=1")} ${c.dim("or")} ${c.accent("DO_NOT_TRACK=1")} ${c.dim("to disable.")}
 `);
           return;
         }
         switch (subcommand) {
           case "enable":
-            return runEnable();
+            return setTelemetryEnabled(true);
           case "disable":
-            return runDisable();
+            return setTelemetryEnabled(false);
           case "status":
             return runStatus();
           default:
@@ -200970,7 +201035,7 @@ if (!isHelp && command !== "telemetry" && command !== "events" && command !== "u
     if (mod.shouldTrack()) mod.incrementCommandCount();
   });
 }
-if (!isHelp && !hasJsonFlag && command !== "upgrade" && command !== "events" && command !== "skills") {
+if (!isHelp && !hasJsonFlag && command !== "upgrade" && command !== "events" && command !== "telemetry" && command !== "skills") {
   Promise.resolve().then(() => (init_autoUpdate(), autoUpdate_exports)).then((mod) => mod.reportCompletedUpdate()).catch(() => {
   });
   Promise.resolve().then(() => (init_updateCheck(), updateCheck_exports)).then(async (mod) => {

package/dist/commands/layout-audit.browser.js

@@ -105,6 +105,10 @@
     return !!element.closest("[data-layout-allow-overflow]");
   }
 
+  function hasAllowCaptionZoneFlag(element) {
+    return !!element.closest("[data-layout-allow-caption-zone]");
+  }
+
   function hasTextClipOptOut(element) {
     return hasAllowOverflowFlag(element) || element.hasAttribute("data-layout-bleed");
   }
@@ -1396,7 +1400,7 @@
       }
       if (!isVisibleElement(element, 0.05, false)) continue;
       const elementRect = toRect(element.getBoundingClientRect());
-      if (includeText && hasOwnTextCandidate(element, true)) {
+      if (includeText && hasOwnTextCandidate(element, true) && !hasAllowCaptionZoneFlag(element)) {
         const rect = textRectFor(element, true);
         if (rect) {
           candidates.push(

package/dist/hyperframes-player.global.js

@@ -1,4 +1,4 @@
-"use strict";var HyperframesPlayer=(()=>{var J=Object.defineProperty;var Ge=Object.getOwnPropertyDescriptor;var qe=Object.getOwnPropertyNames;var Ye=Object.prototype.hasOwnProperty;var Xe=(i,e)=>{for(var t in e)J(i,t,{get:e[t],enumerable:!0})},Ze=(i,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of qe(e))!Ye.call(i,n)&&n!==t&&J(i,n,{get:()=>e[n],enumerable:!(r=Ge(e,n))||r.enumerable});return i};var Qe=i=>Ze(J({},"__esModule",{value:!0}),i);var Lt={};Xe(Lt,{HyperframesPlayer:()=>Q,SPEED_PRESETS:()=>te,formatSpeed:()=>N,formatTime:()=>$});function ye(i){return i.hasRuntime||i.runtimeInjected?!1:!!(i.hasNestedCompositions||i.hasTimelines&&i.attempts>=5)}function I(i){return typeof i=="object"&&i!==null}function Ee(i){return I(i)&&typeof i.getDuration=="function"}function Se(i){return I(i)&&typeof i.duration=="function"&&typeof i.time=="function"&&typeof i.seek=="function"&&typeof i.play=="function"&&typeof i.pause=="function"}var Je="https://cdn.jsdelivr.net/npm/@hyperframes/core@0.7.78/dist/hyperframe.runtime.iife.js";function D(i){if(i===null)return null;let e=Number.parseInt(i,10);return Number.isFinite(e)&&e>0?e:null}function Ke(i){let e=i?.querySelector("[data-composition-id][data-width][data-height]")??i?.querySelector("[data-width][data-height]");if(!e)return null;let t=D(e.getAttribute("data-width")),r=D(e.getAttribute("data-height"));return t!==null&&r!==null?{width:t,height:r}:null}var j=class{constructor(e,t){this._iframe=e;this._callbacks=t}_iframe;_callbacks;_interval=null;_runtimeInjected=!1;get runtimeInjected(){return this._runtimeInjected}start(){this.stop(),this._runtimeInjected=!1;let e=0;this._interval=setInterval(()=>{e++;try{let t=this._iframe.contentWindow;if(!t)return;let r=!!(t.__hf||t.__player),n=!!(t.__timelines&&Object.keys(t.__timelines).length>0),o=!!this._iframe.contentDocument?.querySelector("[data-composition-src]");if(ye({hasRuntime:r,hasTimelines:n,hasNestedCompositions:o,runtimeInjected:this._runtimeInjected,attempts:e})){this._injectRuntime();return}if(this._runtimeInjected&&!r)return;let s=this._resolvePlaybackDurationAdapter(t);if(s&&s.getDuration()>0){this.stop();let l=Ke(this._iframe.contentDocument);this._callbacks.onReady({duration:s.getDuration(),adapter:s,compositionSize:l});return}}catch{}e>=40&&(this.stop(),this._callbacks.onError("Composition timeline not found after 8s"))},200)}stop(){this._interval!==null&&(clearInterval(this._interval),this._interval=null)}resolveDirectTimelineAdapter(){try{let e=this._iframe.contentWindow;return e?this._resolveDirectTimelineAdapterFromWindow(e):null}catch{return null}}resolveDirectTimelineAdapterFromWindow(e){return this._resolveDirectTimelineAdapterFromWindow(e)}hasRuntimeBridge(e){return Reflect.get(e,"__hf")!==void 0||I(Reflect.get(e,"__player"))}_injectRuntime(){this._runtimeInjected=!0;try{let e=this._iframe.contentDocument;if(!e)return;let t=e.createElement("script");t.src=Je,(e.head||e.documentElement).appendChild(t),this._callbacks.onRuntimeInjected?.()}catch{}}_resolveDirectTimelineAdapterFromWindow(e){if(this.hasRuntimeBridge(e))return null;let t=Reflect.get(e,"__timelines");if(!I(t))return null;let r=Object.keys(t);if(r.length===0)return null;let n=this._iframe.contentDocument?.querySelector("[data-composition-id]")?.getAttribute("data-composition-id"),o=n&&n in t?n:r[r.length-1],s=t[o];return Se(s)?s:null}_resolvePlaybackDurationAdapter(e){let t=Reflect.get(e,"__player");if(Ee(t))return{kind:"runtime",getDuration:()=>t.getDuration()};let r=this._resolveDirectTimelineAdapterFromWindow(e);return r?{kind:"direct-timeline",timeline:r,getDuration:()=>r.duration()}:null}};var Te=`
+"use strict";var HyperframesPlayer=(()=>{var J=Object.defineProperty;var Ge=Object.getOwnPropertyDescriptor;var qe=Object.getOwnPropertyNames;var Ye=Object.prototype.hasOwnProperty;var Xe=(i,e)=>{for(var t in e)J(i,t,{get:e[t],enumerable:!0})},Ze=(i,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of qe(e))!Ye.call(i,n)&&n!==t&&J(i,n,{get:()=>e[n],enumerable:!(r=Ge(e,n))||r.enumerable});return i};var Qe=i=>Ze(J({},"__esModule",{value:!0}),i);var Lt={};Xe(Lt,{HyperframesPlayer:()=>Q,SPEED_PRESETS:()=>te,formatSpeed:()=>N,formatTime:()=>$});function ye(i){return i.hasRuntime||i.runtimeInjected?!1:!!(i.hasNestedCompositions||i.hasTimelines&&i.attempts>=5)}function I(i){return typeof i=="object"&&i!==null}function Ee(i){return I(i)&&typeof i.getDuration=="function"}function Se(i){return I(i)&&typeof i.duration=="function"&&typeof i.time=="function"&&typeof i.seek=="function"&&typeof i.play=="function"&&typeof i.pause=="function"}var Je="https://cdn.jsdelivr.net/npm/@hyperframes/core@0.7.79/dist/hyperframe.runtime.iife.js";function D(i){if(i===null)return null;let e=Number.parseInt(i,10);return Number.isFinite(e)&&e>0?e:null}function Ke(i){let e=i?.querySelector("[data-composition-id][data-width][data-height]")??i?.querySelector("[data-width][data-height]");if(!e)return null;let t=D(e.getAttribute("data-width")),r=D(e.getAttribute("data-height"));return t!==null&&r!==null?{width:t,height:r}:null}var j=class{constructor(e,t){this._iframe=e;this._callbacks=t}_iframe;_callbacks;_interval=null;_runtimeInjected=!1;get runtimeInjected(){return this._runtimeInjected}start(){this.stop(),this._runtimeInjected=!1;let e=0;this._interval=setInterval(()=>{e++;try{let t=this._iframe.contentWindow;if(!t)return;let r=!!(t.__hf||t.__player),n=!!(t.__timelines&&Object.keys(t.__timelines).length>0),o=!!this._iframe.contentDocument?.querySelector("[data-composition-src]");if(ye({hasRuntime:r,hasTimelines:n,hasNestedCompositions:o,runtimeInjected:this._runtimeInjected,attempts:e})){this._injectRuntime();return}if(this._runtimeInjected&&!r)return;let s=this._resolvePlaybackDurationAdapter(t);if(s&&s.getDuration()>0){this.stop();let l=Ke(this._iframe.contentDocument);this._callbacks.onReady({duration:s.getDuration(),adapter:s,compositionSize:l});return}}catch{}e>=40&&(this.stop(),this._callbacks.onError("Composition timeline not found after 8s"))},200)}stop(){this._interval!==null&&(clearInterval(this._interval),this._interval=null)}resolveDirectTimelineAdapter(){try{let e=this._iframe.contentWindow;return e?this._resolveDirectTimelineAdapterFromWindow(e):null}catch{return null}}resolveDirectTimelineAdapterFromWindow(e){return this._resolveDirectTimelineAdapterFromWindow(e)}hasRuntimeBridge(e){return Reflect.get(e,"__hf")!==void 0||I(Reflect.get(e,"__player"))}_injectRuntime(){this._runtimeInjected=!0;try{let e=this._iframe.contentDocument;if(!e)return;let t=e.createElement("script");t.src=Je,(e.head||e.documentElement).appendChild(t),this._callbacks.onRuntimeInjected?.()}catch{}}_resolveDirectTimelineAdapterFromWindow(e){if(this.hasRuntimeBridge(e))return null;let t=Reflect.get(e,"__timelines");if(!I(t))return null;let r=Object.keys(t);if(r.length===0)return null;let n=this._iframe.contentDocument?.querySelector("[data-composition-id]")?.getAttribute("data-composition-id"),o=n&&n in t?n:r[r.length-1],s=t[o];return Se(s)?s:null}_resolvePlaybackDurationAdapter(e){let t=Reflect.get(e,"__player");if(Ee(t))return{kind:"runtime",getDuration:()=>t.getDuration()};let r=this._resolveDirectTimelineAdapterFromWindow(e);return r?{kind:"direct-timeline",timeline:r,getDuration:()=>r.duration()}:null}};var Te=`
   :host {
     display: block;
     position: relative;

package/dist/skills/hyperframes-cli/references/lint-validate-inspect.md

@@ -9,7 +9,7 @@ When the composition is animation-driven, run the checks before you reach for `p
 - Run `lint` after the first HTML pass for early feedback. It is an iteration aid, not a separate final gate.
 - Run `check --snapshots` at the first full pass: the overview frames and per-finding crops show you what the auditor saw.
 - Look at the PNGs before tuning automated warnings: your eye catches what the auditor misses, and the auditor catches what your eye misses.
-- Treat layout errors as defects unless a snapshot proves the layering is intentional, in which case mark it with `data-layout-allow-overflow` / `data-layout-allow-overlap` / `data-layout-allow-occlusion`.
+- Treat layout errors as defects unless a snapshot proves the layering is intentional, in which case mark it with `data-layout-allow-overflow` / `data-layout-allow-overlap` / `data-layout-allow-occlusion` / `data-layout-allow-caption-zone` (caption band only).
 - State motion intent in a `*.motion.json` sidecar so `check` verifies it automatically (entrances firing under seek, stagger order, in-frame, liveness). This is the closest automated proxy for "watch the MP4" and catches render-vs-preview bugs the eye misses (see **Motion verification** below).
 
 ## lint
@@ -57,6 +57,7 @@ Every finding carries a selector, the element's `data-*` identity, the compositi
 - `data-layout-allow-overflow` — overflow is intentional (entrance/exit travel).
 - `data-layout-allow-overlap` — deliberate text layering (e.g. a demo cursor label over a heading).
 - `data-layout-allow-occlusion` — an element is meant to cover text.
+- `data-layout-allow-caption-zone` — intentional lower-third / caption-band copy under `--caption-zone`. Applies to the marked element and every descendant (`closest`); silences only `caption_zone_collision` (not overflow/overlap/occlusion). Prefer the narrowest wrapper that owns the intentional band copy.
 - `data-layout-ignore` — decorative element that should never be audited.
 
 **Opt-in pipeline gates** (used by orchestrators; off by default):
@@ -66,7 +67,7 @@ npx hyperframes check --caption-zone "x0=0;y0=.82;x1=1;y1=1;severity=error;seek=
 npx hyperframes check --frame-check     # media (img/svg/video/canvas) out-of-frame detection
 ```
 
-`--caption-zone` takes fractional band geometry (`x0/y0/x1/y1` required, 0-1 fractions of the composition's own canvas, portrait included) with optional `severity` and comma-separated `seek` fractions; it flags content whose center sits inside the band. `--frame-check` reports media elements breaching the canvas beyond `max(120px, 6% of the min canvas dimension)`.
+`--caption-zone` takes fractional band geometry (`x0/y0/x1/y1` required, 0-1 fractions of the composition's own canvas, portrait included) with optional `severity` and comma-separated `seek` fractions; it flags content whose center sits inside the band. Waive intentional lower-third copy with `data-layout-allow-caption-zone` on the element or its nearest wrapper (see Escape hatches). `--frame-check` reports media elements breaching the canvas beyond `max(120px, 6% of the min canvas dimension)`.
 
 **Fixing contrast errors** — thresholds are 4.5:1 for normal text, 3:1 for large text (24px+, or 19px+ bold). The finding's `suggestedColor` already picks the nearest compliant color in the right direction (brighten on dark backgrounds, darken on light); apply it or adjust within the palette family, then re-run `check`.
 

package/dist/studio/assets/{hyperframes-player-uiAAPKvw.js → hyperframes-player-mFah2TZE.js}

@@ -1,4 +1,4 @@
-var ce=Object.defineProperty;var pe=(r,t,e)=>t in r?ce(r,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):r[t]=e;var c=(r,t,e)=>pe(r,typeof t!="symbol"?t+"":t,e);import{r as ne,i as me,a as fe}from"./index-BSZrK0bx.js";function _e(r){return r.hasRuntime||r.runtimeInjected?!1:!!(r.hasNestedCompositions||r.hasTimelines&&r.attempts>=5)}function F(r){return typeof r=="object"&&r!==null}function ge(r){return F(r)&&typeof r.getDuration=="function"}function ye(r){return F(r)&&typeof r.duration=="function"&&typeof r.time=="function"&&typeof r.seek=="function"&&typeof r.play=="function"&&typeof r.pause=="function"}function ve(r){if(!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(r))throw new Error(`Invalid HyperFrames runtime version: ${r}`);return`https://cdn.jsdelivr.net/npm/@hyperframes/core@${r}/dist/hyperframe.runtime.iife.js`}const be=typeof __HYPERFRAMES_RUNTIME_CDN_URL__=="string"?__HYPERFRAMES_RUNTIME_CDN_URL__:ve("0.0.0-dev");function H(r){if(r===null)return null;const t=Number.parseInt(r,10);return Number.isFinite(t)&&t>0?t:null}function we(r){const t=(r==null?void 0:r.querySelector("[data-composition-id][data-width][data-height]"))??(r==null?void 0:r.querySelector("[data-width][data-height]"));if(!t)return null;const e=H(t.getAttribute("data-width")),i=H(t.getAttribute("data-height"));return e!==null&&i!==null?{width:e,height:i}:null}class Ae{constructor(t,e){c(this,"_interval",null);c(this,"_runtimeInjected",!1);this._iframe=t,this._callbacks=e}get runtimeInjected(){return this._runtimeInjected}start(){this.stop(),this._runtimeInjected=!1;let t=0;this._interval=setInterval(()=>{var e;t++;try{const i=this._iframe.contentWindow;if(!i)return;const s=!!(i.__hf||i.__player),o=!!(i.__timelines&&Object.keys(i.__timelines).length>0),d=!!((e=this._iframe.contentDocument)!=null&&e.querySelector("[data-composition-src]"));if(_e({hasRuntime:s,hasTimelines:o,hasNestedCompositions:d,runtimeInjected:this._runtimeInjected,attempts:t})){this._injectRuntime();return}if(this._runtimeInjected&&!s)return;const a=this._resolvePlaybackDurationAdapter(i);if(a&&a.getDuration()>0){this.stop();const h=we(this._iframe.contentDocument);this._callbacks.onReady({duration:a.getDuration(),adapter:a,compositionSize:h});return}}catch{}t>=40&&(this.stop(),this._callbacks.onError("Composition timeline not found after 8s"))},200)}stop(){this._interval!==null&&(clearInterval(this._interval),this._interval=null)}resolveDirectTimelineAdapter(){try{const t=this._iframe.contentWindow;return t?this._resolveDirectTimelineAdapterFromWindow(t):null}catch{return null}}resolveDirectTimelineAdapterFromWindow(t){return this._resolveDirectTimelineAdapterFromWindow(t)}hasRuntimeBridge(t){return Reflect.get(t,"__hf")!==void 0||F(Reflect.get(t,"__player"))}_injectRuntime(){var t,e;this._runtimeInjected=!0;try{const i=this._iframe.contentDocument;if(!i)return;const s=i.createElement("script");s.src=be,(i.head||i.documentElement).appendChild(s),(e=(t=this._callbacks).onRuntimeInjected)==null||e.call(t)}catch{}}_resolveDirectTimelineAdapterFromWindow(t){var a,h;if(this.hasRuntimeBridge(t))return null;const e=Reflect.get(t,"__timelines");if(!F(e))return null;const i=Object.keys(e);if(i.length===0)return null;const s=(h=(a=this._iframe.contentDocument)==null?void 0:a.querySelector("[data-composition-id]"))==null?void 0:h.getAttribute("data-composition-id"),o=s&&s in e?s:i[i.length-1],d=e[o];return ye(d)?d:null}_resolvePlaybackDurationAdapter(t){const e=Reflect.get(t,"__player");if(ge(e))return{kind:"runtime",getDuration:()=>e.getDuration()};const i=this._resolveDirectTimelineAdapterFromWindow(t);return i?{kind:"direct-timeline",timeline:i,getDuration:()=>i.duration()}:null}}const Ee=`
+var ce=Object.defineProperty;var pe=(r,t,e)=>t in r?ce(r,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):r[t]=e;var c=(r,t,e)=>pe(r,typeof t!="symbol"?t+"":t,e);import{r as ne,i as me,a as fe}from"./index-DlZMDyYs.js";function _e(r){return r.hasRuntime||r.runtimeInjected?!1:!!(r.hasNestedCompositions||r.hasTimelines&&r.attempts>=5)}function F(r){return typeof r=="object"&&r!==null}function ge(r){return F(r)&&typeof r.getDuration=="function"}function ye(r){return F(r)&&typeof r.duration=="function"&&typeof r.time=="function"&&typeof r.seek=="function"&&typeof r.play=="function"&&typeof r.pause=="function"}function ve(r){if(!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(r))throw new Error(`Invalid HyperFrames runtime version: ${r}`);return`https://cdn.jsdelivr.net/npm/@hyperframes/core@${r}/dist/hyperframe.runtime.iife.js`}const be=typeof __HYPERFRAMES_RUNTIME_CDN_URL__=="string"?__HYPERFRAMES_RUNTIME_CDN_URL__:ve("0.0.0-dev");function H(r){if(r===null)return null;const t=Number.parseInt(r,10);return Number.isFinite(t)&&t>0?t:null}function we(r){const t=(r==null?void 0:r.querySelector("[data-composition-id][data-width][data-height]"))??(r==null?void 0:r.querySelector("[data-width][data-height]"));if(!t)return null;const e=H(t.getAttribute("data-width")),i=H(t.getAttribute("data-height"));return e!==null&&i!==null?{width:e,height:i}:null}class Ae{constructor(t,e){c(this,"_interval",null);c(this,"_runtimeInjected",!1);this._iframe=t,this._callbacks=e}get runtimeInjected(){return this._runtimeInjected}start(){this.stop(),this._runtimeInjected=!1;let t=0;this._interval=setInterval(()=>{var e;t++;try{const i=this._iframe.contentWindow;if(!i)return;const s=!!(i.__hf||i.__player),o=!!(i.__timelines&&Object.keys(i.__timelines).length>0),d=!!((e=this._iframe.contentDocument)!=null&&e.querySelector("[data-composition-src]"));if(_e({hasRuntime:s,hasTimelines:o,hasNestedCompositions:d,runtimeInjected:this._runtimeInjected,attempts:t})){this._injectRuntime();return}if(this._runtimeInjected&&!s)return;const a=this._resolvePlaybackDurationAdapter(i);if(a&&a.getDuration()>0){this.stop();const h=we(this._iframe.contentDocument);this._callbacks.onReady({duration:a.getDuration(),adapter:a,compositionSize:h});return}}catch{}t>=40&&(this.stop(),this._callbacks.onError("Composition timeline not found after 8s"))},200)}stop(){this._interval!==null&&(clearInterval(this._interval),this._interval=null)}resolveDirectTimelineAdapter(){try{const t=this._iframe.contentWindow;return t?this._resolveDirectTimelineAdapterFromWindow(t):null}catch{return null}}resolveDirectTimelineAdapterFromWindow(t){return this._resolveDirectTimelineAdapterFromWindow(t)}hasRuntimeBridge(t){return Reflect.get(t,"__hf")!==void 0||F(Reflect.get(t,"__player"))}_injectRuntime(){var t,e;this._runtimeInjected=!0;try{const i=this._iframe.contentDocument;if(!i)return;const s=i.createElement("script");s.src=be,(i.head||i.documentElement).appendChild(s),(e=(t=this._callbacks).onRuntimeInjected)==null||e.call(t)}catch{}}_resolveDirectTimelineAdapterFromWindow(t){var a,h;if(this.hasRuntimeBridge(t))return null;const e=Reflect.get(t,"__timelines");if(!F(e))return null;const i=Object.keys(e);if(i.length===0)return null;const s=(h=(a=this._iframe.contentDocument)==null?void 0:a.querySelector("[data-composition-id]"))==null?void 0:h.getAttribute("data-composition-id"),o=s&&s in e?s:i[i.length-1],d=e[o];return ye(d)?d:null}_resolvePlaybackDurationAdapter(t){const e=Reflect.get(t,"__player");if(ge(e))return{kind:"runtime",getDuration:()=>e.getDuration()};const i=this._resolveDirectTimelineAdapterFromWindow(t);return i?{kind:"direct-timeline",timeline:i,getDuration:()=>i.duration()}:null}}const Ee=`
   :host {
     display: block;
     position: relative;

package/dist/studio/assets/{index-CDSTMtUs.js → index-Bqj3h_1a.js}

@@ -1,4 +1,4 @@
-import{n as Qi}from"./index-BSZrK0bx.js";/*!
+import{n as Qi}from"./index-DlZMDyYs.js";/*!
  * Copyright (c) 2026-present, Vanilagy and contributors
  *
  * This Source Code Form is subject to the terms of the Mozilla Public