@hyperframes/lint 0.8.6 → 0.8.8

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;
@@ -251,6 +287,9 @@ function truncateSnippet(value, maxLength = 220) {
   if (normalized.length <= maxLength) return normalized;
   return `${normalized.slice(0, maxLength - 3)}...`;
 }
+function mediaSrcTagRe(tagAlternation) {
+  return new RegExp(`<(${tagAlternation})\\b[^>]*\\ssrc\\s*=\\s*["']([^"']+)["'][^>]*>`, "gi");
+}
 
 // src/context.ts
 function buildLintContext(html, options = {}) {
@@ -453,6 +492,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")) {
@@ -492,6 +532,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 [];
@@ -670,7 +711,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."
       },
@@ -691,15 +735,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",
@@ -1258,7 +1307,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));
@@ -1298,6 +1349,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() {
@@ -2100,9 +2185,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",
@@ -3051,7 +3136,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."
+            )
           });
         }
       }
@@ -3179,7 +3269,7 @@ var captionRules = [
 ];
 
 // src/rules/composition.ts
-import { COMPOSITION_VARIABLE_TYPES } from "@hyperframes/parsers/composition";
+import { COMPOSITION_VARIABLE_TYPES, isSafeMediaUrl } from "@hyperframes/parsers/composition";
 import { COMPOSITION_ATTRIBUTES, readClipTiming } from "@hyperframes/parsers/composition-contract";
 var MAX_COMPOSITION_LINES = 300;
 var MAX_TIMED_ELEMENTS_PER_TRACK = 3;
@@ -3206,7 +3296,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) });
 }
@@ -3348,6 +3437,7 @@ var compositionRules = [
     const tagsByCompositionId = /* @__PURE__ */ new Map();
     for (const tag of tags) {
       if (isInsideInertTemplate(tag, tags)) continue;
+      if (readAttr(tag.raw, "data-composition-src")) continue;
       const compositionId = readDecodedAttr(tag.raw, "data-composition-id");
       if (!compositionId || compositionId.trim().length === 0) continue;
       const matchingTags = tagsByCompositionId.get(compositionId) ?? [];
@@ -3571,64 +3661,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 = [];
@@ -3808,6 +3840,11 @@ var compositionRules = [
     }
     const findings = [];
     const knownTypes = new Set(COMPOSITION_VARIABLE_TYPES);
+    const varSrcIds = /* @__PURE__ */ new Set();
+    for (const tag of tags) {
+      const bound = readAttr(tag.raw, "data-var-src");
+      if (bound) varSrcIds.add(bound);
+    }
     for (let i = 0; i < parsed.length; i += 1) {
       const entry = parsed[i];
       if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
@@ -3832,6 +3869,17 @@ var compositionRules = [
           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)
         });
+        continue;
+      }
+      const id = String(e.id);
+      if ((e.type === "image" || varSrcIds.has(id)) && typeof e.default === "string" && e.default.length > 0 && !isSafeMediaUrl(e.default)) {
+        findings.push({
+          code: "unloadable_media_variable_default",
+          severity: "error",
+          message: `Variable "${id}" defaults to a URL the runtime will refuse to load, so any element bound to it renders its authored fallback src instead and the render still exits 0.`,
+          fixHint: `Media URLs must be relative, http(s), blob:, or a data:image/* URI. Copy the file into the project and reference it relatively (e.g. "assets/bg.png") rather than by absolute path.`,
+          snippet: truncateSnippet(htmlTag.raw)
+        });
       }
     }
     return findings;
@@ -4743,13 +4791,13 @@ async function probeIsHevc(ffprobePath, filePath) {
 }
 function collectLocalVideoCandidates(projectDir, htmlSources) {
   const candidates = /* @__PURE__ */ new Map();
-  const videoSrcRe = /<video\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi;
+  const videoSrcRe = mediaSrcTagRe("video");
   for (const { html, compSrcPath } of htmlSources) {
     const scannable = maskNonScannableRanges(html);
     const re = new RegExp(videoSrcRe.source, videoSrcRe.flags);
     let match;
     while ((match = re.exec(scannable)) !== null) {
-      const rawSrc = match[1] ?? "";
+      const rawSrc = match[2] ?? "";
       if (isUnresolvedAssetPlaceholder(rawSrc)) continue;
       const src = cleanAssetUrl(rawSrc);
       if (!src) continue;
@@ -4936,6 +4984,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))
@@ -4958,6 +5007,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;
@@ -4982,12 +5061,12 @@ function lintProjectAudioFiles(projectDir, htmlSources) {
 }
 function lintAudioSrcNotFound(projectDir, htmlSources) {
   const findings = [];
-  const audioSrcRe = /<audio\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi;
+  const audioSrcRe = mediaSrcTagRe("audio");
   const missingSrcs = [];
   for (const { html, compSrcPath } of htmlSources) {
     let match;
     while ((match = audioSrcRe.exec(html)) !== null) {
-      const src = match[1];
+      const src = match[2];
       if (/^(https?:|data:|blob:)/i.test(src)) continue;
       if (isUnresolvedAssetPlaceholder2(src)) continue;
       const rootRelative = compSrcPath ? rewriteAssetPath2(compSrcPath, src, (path) => existsSync2(join2(projectDir, path))) : src;
@@ -5009,7 +5088,7 @@ function lintAudioSrcNotFound(projectDir, htmlSources) {
 }
 function lintMissingLocalAsset(projectDir, htmlSources) {
   const findings = [];
-  const localAssetSrcRe = /<(video|img|source)\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi;
+  const localAssetSrcRe = mediaSrcTagRe("video|img|source");
   const missingByTag = /* @__PURE__ */ new Map();
   for (const { html, compSrcPath } of htmlSources) {
     const scannable = maskNonScannableRanges2(html);