@hyperframes/lint 0.7.70 → 0.7.72

package/dist/browser.js

@@ -861,6 +861,7 @@ var coreRules = [
 ];
 
 // src/rules/media.ts
+import { validateColorGradingContract } from "@hyperframes/parsers/color-grading-contract";
 function escapeRegExp2(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -1063,6 +1064,56 @@ var mediaRules = [
     }
     return findings;
   },
+  // color_grading_* — grading is a structured media-only contract. Unknown
+  // keys are ignored by the runtime, so catch them before an agent can report
+  // controls that never actually rendered.
+  ({ tags }) => {
+    const findings = [];
+    for (const tag of tags) {
+      const raw = readDecodedAttr(tag.raw, "data-color-grading");
+      if (raw === null) continue;
+      const elementId = readAttr(tag.raw, "id") || void 0;
+      const report = (code, message, fixHint) => {
+        findings.push({
+          code,
+          severity: "error",
+          message,
+          elementId,
+          fixHint,
+          snippet: truncateSnippet(tag.raw)
+        });
+      };
+      if (tag.name !== "video" && tag.name !== "img") {
+        report(
+          "color_grading_non_media",
+          `data-color-grading on <${tag.name}> has no effect. The shader runtime only grades real <video> and <img> elements.`,
+          "Move the grading attribute to the real <video> or <img> media element. Do not attach it to a wrapper or CSS background."
+        );
+        continue;
+      }
+      const trimmed = raw.trim();
+      if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(trimmed);
+      } catch {
+        report(
+          "color_grading_invalid_json",
+          "data-color-grading contains malformed JSON and will not render.",
+          'Use valid JSON, for example {"preset":"skin-soft","intensity":0.6,"adjust":{"highlights":-0.08}}.'
+        );
+        continue;
+      }
+      for (const issue of validateColorGradingContract(parsed)) {
+        report(
+          "color_grading_invalid_structure",
+          `data-color-grading ${issue.path} ${issue.message}.`,
+          issue.hint ?? "Use the documented media-treatment contract and correct or remove the invalid value."
+        );
+      }
+    }
+    return findings;
+  },
   // video_missing_muted
   ({ tags }) => {
     const findings = [];
@@ -1149,27 +1200,6 @@ var mediaRules = [
     }
     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 = [];
-    if (!options.isSubComposition) return findings;
-    for (const tag of tags) {
-      if (tag.name !== "video" && tag.name !== "audio") continue;
-      const elementId = readAttr(tag.raw, "id") || void 0;
-      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 = [];
@@ -2426,8 +2456,12 @@ ${right.raw}`)
     return findings;
   },
   // gsap_infinite_repeat
-  ({ scripts }) => {
+  ({ scripts, rootTag }) => {
     const findings = [];
+    const declaredDuration = Number.parseFloat(
+      rootTag ? readAttr(rootTag.raw, "data-duration") ?? "" : ""
+    );
+    const hasFiniteCompositionWindow = Number.isFinite(declaredDuration) && declaredDuration > 0;
     const pattern = /repeat\s*:\s*-1(?!\d)/g;
     for (const { snippet } of scanScriptsForRegexMatches(scripts, pattern, {
       stripComments: true,
@@ -2436,9 +2470,9 @@ ${right.raw}`)
     })) {
       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.max(0, Math.floor(duration / cycleDuration) - 1)`.",
-        fixHint: "Replace `repeat: -1` with a finite count, e.g. `repeat: Math.max(0, Math.floor(totalDuration / singleCycleDuration) - 1)`. Use Math.floor (not Math.ceil) so the animation fits, and clamp at zero so a short composition cannot evaluate to -1.",
+        severity: hasFiniteCompositionWindow ? "warning" : "error",
+        message: hasFiniteCompositionWindow ? `GSAP tween uses \`repeat: -1\` (infinite), but the composition declares a finite ${declaredDuration}s window. HyperFrames clips deterministic seeking and export to that explicit duration.` : "GSAP tween uses `repeat: -1` (infinite) without a finite composition `data-duration`. The timeline can report an unbounded duration and make render planning fail.",
+        fixHint: hasFiniteCompositionWindow ? "Keep the explicit finite composition `data-duration`. Use a finite repeat count only when the loop itself must end before the composition does." : "Add a finite composition `data-duration`, or replace `repeat: -1` with `repeat: Math.max(0, Math.floor(totalDuration / singleCycleDuration) - 1)`.",
         snippet: truncateSnippet(snippet)
       });
     }