@hyperframes/lint 0.8.5 → 0.8.7

package/dist/index.d.ts

@@ -8,6 +8,8 @@ type HyperframeLintFinding = {
     elementId?: string;
     fixHint?: string;
     snippet?: string;
+    /** Optional standalone entry that command-specific guidance can act on. */
+    suggestedComposition?: string;
 };
 /**
  * Where a single lint pass spent its time. Attributed per rule-source module

package/dist/index.js

@@ -7,7 +7,7 @@ var TIMELINE_REGISTRY_ASSIGN_PATTERN = /window\.__timelines(?:\[[^\]]+\]|\.[A-Za
 var WINDOW_TIMELINE_ASSIGN_PATTERN = /window\.__timelines(?:\[\s*(?:["']([^"']+)["']|[A-Za-z_$][\w$.]*)\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*=\s*([A-Za-z_$][\w$]*)/i;
 var INVALID_SCRIPT_CLOSE_PATTERN = /<script[^>]*>[\s\S]*?<\s*\/\s*script(?!>)/i;
 var TIMELINE_REGISTRY_KEY_PATTERN = /window\.__timelines(?:\[\s*["']([^"']+)["']\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*=/g;
-var TIMELINE_REGISTRY_OBJECT_BODY_PATTERN = /window\.__timelines\s*=\s*\{([\s\S]*?)\}/i;
+var TIMELINE_REGISTRY_OBJECT_OPEN_PATTERN = /window\.__timelines\s*=\s*\{/i;
 var TIMELINE_REGISTRY_OBJECT_ENTRY_PATTERN = /(?:["']([^"']+)["']|([A-Za-z_$][\w$]*))\s*:\s*[A-Za-z_$][\w$]*/g;
 function parseHtmlStructure(source) {
   const tags = [];
@@ -135,18 +135,48 @@ function extractTimelineRegistryKeys(source) {
     const key = match[1] ?? match[2];
     if (key) keys.add(key);
   }
-  const objectBody = TIMELINE_REGISTRY_OBJECT_BODY_PATTERN.exec(source)?.[1];
-  if (objectBody) {
-    const entryPattern = new RegExp(
-      TIMELINE_REGISTRY_OBJECT_ENTRY_PATTERN.source,
-      TIMELINE_REGISTRY_OBJECT_ENTRY_PATTERN.flags
-    );
-    while ((match = entryPattern.exec(objectBody)) !== null) {
-      const key = match[1] ?? match[2];
-      if (key) keys.add(key);
+  for (const entry of readTimelineRegistryTopLevelKeys(source)) keys.add(entry);
+  return [...keys];
+}
+function findMatchingBrace(source, bodyStart) {
+  let depth = 1;
+  for (let i = bodyStart; i < source.length; i += 1) {
+    if (source[i] === "{") depth += 1;
+    else if (source[i] === "}" && (depth -= 1) === 0) return i;
+  }
+  return source.length;
+}
+function blankNestedBraceGroups(body) {
+  let out = "";
+  let depth = 0;
+  for (const ch of body) {
+    if (ch === "{") depth += 1;
+    else if (ch === "}") depth = Math.max(0, depth - 1);
+    else if (depth === 0) {
+      out += ch;
+      continue;
     }
+    out += " ";
   }
-  return [...keys];
+  return out;
+}
+function readTimelineRegistryTopLevelKeys(source) {
+  const open = TIMELINE_REGISTRY_OBJECT_OPEN_PATTERN.exec(source);
+  if (!open) return [];
+  const bodyStart = open.index + open[0].length;
+  const body = source.slice(bodyStart, findMatchingBrace(source, bodyStart));
+  const flattened = blankNestedBraceGroups(body);
+  const keys = [];
+  const entryPattern = new RegExp(
+    TIMELINE_REGISTRY_OBJECT_ENTRY_PATTERN.source,
+    TIMELINE_REGISTRY_OBJECT_ENTRY_PATTERN.flags
+  );
+  let entry;
+  while ((entry = entryPattern.exec(flattened)) !== null) {
+    const key = entry[1] ?? entry[2];
+    if (key) keys.push(key);
+  }
+  return keys;
 }
 function getInlineScriptSyntaxError(source) {
   if (!source.trim()) return null;
@@ -158,6 +188,12 @@ function getInlineScriptSyntaxError(source) {
     return String(error);
   }
 }
+function stripStringLiterals(source) {
+  return source.replace(
+    /(['"])(?:\\.|(?!\1)[^\\\n])*\1?/g,
+    (literal) => literal[0] + " ".repeat(Math.max(0, literal.length - 1))
+  );
+}
 function stripJsComments(source) {
   let out = "";
   let i = 0;
@@ -392,54 +428,8 @@ function describeStudioElement(tag) {
   parts.push(">");
   return parts.join("");
 }
-var HEAD_BLOCKS_TO_IGNORE_PATTERN = /<(?:style|script|template|title|noscript)\b[^>]*>[\s\S]*?<\/(?:style|script|template|title|noscript)(?:\s[^>]*)?>/gi;
-var HTML_TAG_PATTERN = /<[^>]+>/g;
-var HEAD_CONTENT_PATTERN = /<head\b[^>]*>([\s\S]*?)(?:<\/head>|<body\b|$)/gi;
-var AFTER_HEAD_BEFORE_BODY_PATTERN = /<\/head(?:\s[^>]*)?>([\s\S]*?)(?=<body\b|$)/gi;
-var STRAY_HEAD_CLOSE_PATTERN = /<\/(?:style|script)(?:\s[^>]*)?>/i;
-var MARKDOWN_CODE_FENCE_PATTERN = /```[^\r\n`]*(?:\r?\n|$)[\s\S]*?```/i;
-var ORPHAN_CSS_AT_RULE_PATTERN = /(?:^|\s)@(?:container|font-face|keyframes|layer|media|page|property|scope|supports)[^{<]*\{[\s\S]*?:[\s\S]*?\}/i;
-var ORPHAN_CSS_RULE_PATTERN = /(?:^|\s)(?:\/\*[\s\S]*?\*\/\s*)?(?:@[a-z-]+[^{}<]*|[.#][\w-]+[^{}<]*|[a-z][\w-]*(?:\s+[.#:[\w-][^{}<]*)?)\s*\{[^{}]*:[^{}]*\}/i;
 var VISIBLE_MARKUP_COMMENT_PATTERN = /\/\*[\s\S]*?\*\//g;
 var VISIBLE_MARKUP_COMMENT_PROTECTED_BLOCK_PATTERN = /<(style|script|template|title|noscript|pre|code|textarea|text)\b[^>]*>[\s\S]*?<\/\1(?:\s[^>]*)?>/gi;
-function findCodeFenceLeak(headWithoutValidBlocks) {
-  return MARKDOWN_CODE_FENCE_PATTERN.exec(headWithoutValidBlocks)?.[0] ?? null;
-}
-function findOrphanCssLeak(headContent) {
-  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) {
-  return STRAY_HEAD_CLOSE_PATTERN.exec(headWithoutValidBlocks)?.[0] ?? null;
-}
-function findLeakedTextInHeadContent(headContent) {
-  const withoutValidBlocks = headContent.replace(HEAD_BLOCKS_TO_IGNORE_PATTERN, " ");
-  return findCodeFenceLeak(withoutValidBlocks) ?? findOrphanCssLeak(headContent) ?? findStrayCloseLeak(withoutValidBlocks);
-}
-function findLeakedTextInHead(rawSource) {
-  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) {
-  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, rootTag) {
-  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));
-}
 function findProtectedVisibleMarkupRanges(source) {
   const ranges = [];
   for (const match of source.matchAll(VISIBLE_MARKUP_COMMENT_PROTECTED_BLOCK_PATTERN)) {
@@ -499,6 +489,7 @@ var coreRules = [
     return findings;
   },
   // root_missing_composition_id + root_missing_dimensions
+  // fallow-ignore-next-line complexity
   ({ rootTag }) => {
     const findings = [];
     if (!rootTag || !readDecodedAttr(rootTag.raw, "data-composition-id")) {
@@ -523,20 +514,6 @@ var coreRules = [
     }
     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)
-      }
-    ];
-  },
   // visible_markup_comment
   ({ source }) => {
     const snippet = findVisibleMarkupCommentLeak(source);
@@ -552,6 +529,7 @@ var coreRules = [
     ];
   },
   // missing_timeline_registry + timeline_registry_missing_init
+  // fallow-ignore-next-line complexity
   ({ source, rawSource, rootTag, options }) => {
     if (options.isSubComposition || rawSource.trimStart().toLowerCase().startsWith("<template")) {
       return [];
@@ -730,7 +708,10 @@ var coreRules = [
         hint: "Remove time-dependent code. Use GSAP timeline position instead of wall-clock time."
       },
       {
-        pattern: /new\s+Date\s*\(/,
+        // Zero-arg only. `new Date(<fixed timestamp>)` is fully deterministic and is how
+        // a composition labels a fixed date on an axis or card; the hint ("remove
+        // time-dependent code") cannot be applied to it without deleting the label.
+        pattern: /new\s+Date\s*\(\s*\)/,
         label: "new Date()",
         hint: "Remove time-dependent code. Use GSAP timeline position instead of wall-clock time."
       },
@@ -751,15 +732,20 @@ var coreRules = [
       },
       {
         // GSAP string form: "random(...)" / "+=random(...)" — re-rolls at tween init.
+        // `scansStrings` because here the string IS the executed value: GSAP parses it.
+        // Every other pattern above matches executable code, so a match inside a string
+        // literal is inert text and must not be reported.
         pattern: /["'`](?:[+-]=)?random\(\s*[-\d[]/,
+        scansStrings: true,
         label: '"random(...)" tween value',
         hint: "GSAP random string values re-roll at tween init and each render worker initializes independently. Use fixed values or precompute with a seeded PRNG."
       }
     ];
     for (const script of scripts) {
-      const stripped = stripJsComments(script.content);
-      for (const { pattern, label, hint } of patterns) {
-        if (pattern.test(stripped)) {
+      const withoutComments = stripJsComments(script.content);
+      const executable = stripStringLiterals(withoutComments);
+      for (const { pattern, label, hint, scansStrings } of patterns) {
+        if (pattern.test(scansStrings ? withoutComments : executable)) {
           findings.push({
             code: "non_deterministic_code",
             severity: "error",
@@ -1318,7 +1304,9 @@ var mediaRules = [
   // audio_volume_double_automation
   findVolumeDoubleAutomationFindings,
   // audio_volume_tween_overrides_gain
-  findVolumeTweenOverridesGainFindings
+  findVolumeTweenOverridesGainFindings,
+  // audio_carve_ungrouped_sources
+  findCarveUngroupedSourcesFindings
 ];
 function findVolumeTweenOverridesGainFindings(ctx) {
   const boosted = ctx.tags.filter((tag) => isMediaTag(tag.name)).map((tag) => ({ tag, volume: Number(readAttr(tag.raw, "data-volume") ?? "1") })).filter((entry) => Number.isFinite(entry.volume) && entry.volume !== 1).filter((entry) => !readDecodedAttr(entry.tag.raw, "data-automation")).map((entry) => ({ ...entry, id: readAttr(entry.tag.raw, "id") })).filter((entry) => Boolean(entry.id));
@@ -1358,6 +1346,40 @@ function findVolumeDoubleAutomationFindings(ctx) {
   }
   return findings;
 }
+function findCarveUngroupedSourcesFindings(ctx) {
+  const groupIds = new Set(
+    ctx.tags.filter((tag) => tag.name === "hf-audio-group").map((tag) => readAttr(tag.raw, "id"))
+  );
+  const findings = [];
+  for (const tag of ctx.tags) {
+    const raw = readDecodedAttr(tag.raw, "data-fx-carve");
+    if (raw === null) continue;
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith("{")) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    const sources = parsed.sources;
+    if (!Array.isArray(sources)) continue;
+    const clipIds = sources.filter(
+      (id) => typeof id === "string" && !groupIds.has(id)
+    );
+    if (clipIds.length < 2) continue;
+    const elementId = readAttr(tag.raw, "id") || void 0;
+    findings.push({
+      code: "audio_carve_ungrouped_sources",
+      severity: "warning",
+      message: `${elementId ? `#${elementId}'s` : "This"} carve names ${clipIds.length} voice clips directly (${clipIds.join(", ")}) instead of a group.`,
+      elementId,
+      fixHint: "Group the voice clips and carve against the group \u2014 a hand-rolled clip list silently rots when a clip is added.",
+      snippet: truncateSnippet(tag.raw)
+    });
+  }
+  return findings;
+}
 
 // src/rules/gsap.ts
 async function loadParseGsapScript() {
@@ -2160,9 +2182,9 @@ ${right.raw}`)
           (candidate) => targetedSelectorTokens(firstVisible.targetSelector).has(candidate)
         ) || selectors[0] || tag.name;
         const laterHidden = visibilityWindows.some(
-          (win) => win.position >= firstVisible.position && isHiddenGsapState(win.propertyValues)
+          (win) => win !== firstVisible && win.method !== "from" && win.position >= firstVisible.position && isHiddenGsapState(win.propertyValues)
         );
-        if (firstVisible.method !== "from" && !laterHidden) continue;
+        if (!laterHidden) continue;
         reportedVisibleOverlayKeys.add(overlayKey);
         findings.push({
           code: "gsap_fullscreen_overlay_starts_visible",
@@ -3111,7 +3133,12 @@ var captionRules = [
             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."
+            fixHint: (
+              // Deliberately does NOT say `overflow: hidden`: caption words are scaled
+              // above 1.0x, and clipping them is exactly what caption_overflow_clips_scaled_words
+              // errors on. Recommending it here made this warning's own fix produce an error.
+              "Add max-width: 1600px (landscape) or max-width: 900px (portrait). Keep overflow visible so scaled emphasis words are not clipped."
+            )
           });
         }
       }
@@ -3266,7 +3293,6 @@ var HEAVY_OVERLAY_EXEMPT_TAGS = /* @__PURE__ */ new Set([
 ]);
 var HEAVY_OVERLAY_CSS_PATTERN = /(?:filter\s*:[^;}]*\bblur\s*\()|(?:clip-path\s*:(?!\s*(?:none|inherit|initial|unset)\b)\s*[^;}]+)|(?:radial-gradient\s*\()/i;
 var INLINE_STYLE_DISPLAY_NONE_PATTERN = /(?:^|;)\s*display\s*:\s*none\b/i;
-var OVERLAP_EPSILON_SECONDS = 1e-6;
 function readTagTiming(rawTag) {
   return readClipTiming({ getAttribute: (name) => readAttr(rawTag, name) });
 }
@@ -3631,64 +3657,6 @@ var compositionRules = [
     }
     return findings;
   },
-  // overlapping_clips_same_track
-  // fallow-ignore-next-line complexity
-  ({ tags }) => {
-    const findings = [];
-    const trackMap = /* @__PURE__ */ new Map();
-    for (const tag of tags) {
-      const trackStr = readAttr(tag.raw, COMPOSITION_ATTRIBUTES.trackIndex);
-      if (!trackStr) continue;
-      const timing = readTagTiming(tag.raw);
-      const { start, duration } = timing;
-      const track = trackStr;
-      if (start == null || duration == null) continue;
-      const clips = trackMap.get(track) || [];
-      clips.push({
-        start,
-        end: start + duration,
-        elementId: readAttr(tag.raw, "id") || void 0,
-        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 > OVERLAP_EPSILON_SECONDS) {
-          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 = [];
-    if (options.isSubComposition) return findings;
-    if (!rootTag) return findings;
-    const compId = readDecodedAttr(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 = [];
@@ -4996,6 +4964,7 @@ async function lintProject(projectDir, entryFile) {
     ...lintMissingLocalAsset(projectDir, allHtmlSources),
     ...lintTextureMaskAssetNotFound(projectDir, allHtmlSources),
     ...!entryFile ? lintMultipleRootCompositions(projectDir) : [],
+    ...!entryFile ? lintBlankRootWithStandaloneComposition(rootHtml, allHtmlSources) : [],
     ...lintDuplicateAudioTracks(allHtmlSources),
     ...lintMissingOrEmptySubComposition(projectDir, rootHtml),
     ...await lintHevcPreviewCodec(collectLocalVideoCandidates(projectDir, allHtmlSources))
@@ -5018,6 +4987,36 @@ async function lintProject(projectDir, entryFile) {
   }
   return { results, totalErrors, totalWarnings, totalInfos };
 }
+function lintBlankRootWithStandaloneComposition(rootHtml, htmlSources) {
+  const { document: rootDocument } = parseHTML(rootHtml);
+  const root = rootDocument.querySelector("body [data-composition-id]");
+  if (!root || root.querySelector("*:not(script):not(style):not(link):not(meta):not(template)")) {
+    return [];
+  }
+  const standaloneCandidates = [];
+  for (const source of htmlSources) {
+    if (!source.compSrcPath) continue;
+    const { document } = parseHTML(source.html);
+    const composition = document.querySelector("body [data-composition-id]");
+    if (!composition) continue;
+    const authoredTimedContent = Array.from(
+      composition.querySelectorAll(
+        ".clip, [data-start], [data-end], video, audio, img, svg, canvas"
+      )
+    ).some((element) => !element.hasAttribute("data-composition-src"));
+    if (authoredTimedContent) standaloneCandidates.push(source.compSrcPath);
+  }
+  if (standaloneCandidates.length === 0) return [];
+  return [
+    {
+      code: "blank_root_with_standalone_composition",
+      severity: "error",
+      message: `The default index.html composition has no renderable content, but ${standaloneCandidates.join(", ")} contains a standalone timed composition. Default check, snapshot, preview, render, and publish commands open index.html, so they will capture or publish only its background.`,
+      fixHint: `Move the authored composition into index.html, or mount it from index.html with data-composition-src and the sub-composition <template> contract. If the separate file is intentional, render it explicitly with --composition ${standaloneCandidates[0]}.`,
+      suggestedComposition: standaloneCandidates[0]
+    }
+  ];
+}
 function lintProjectAudioFiles(projectDir, htmlSources) {
   const findings = [];
   let audioFiles;