@hyperframes/lint 0.8.145 → 0.8.147

package/dist/index.js

@@ -599,7 +599,10 @@ function truncateSnippet(value, maxLength = 220) {
   return `${normalized2.slice(0, maxLength - 3)}...`;
 }
 function mediaSrcTagRe(tagAlternation) {
-  return new RegExp(`<(${tagAlternation})\\b[^>]*\\ssrc\\s*=\\s*["']([^"']+)["'][^>]*>`, "gi");
+  return new RegExp(`<(${tagAlternation})\\b[^>]*\\ssrc\\s*=\\s*("[^"]*"|'[^']*')[^>]*>`, "gi");
+}
+function mediaSrcOf(match) {
+  return readDecodedAttr(match[0], "src") ?? "";
 }
 
 // src/sourceLocations.ts
@@ -1080,7 +1083,7 @@ function describeRootDimensionsDrift(source, dataWidth, dataHeight) {
   const declared = `Root composition declares data-width="${dataWidth}" data-height="${dataHeight}"`;
   if (!bodyCssMismatch) {
     return {
-      message: `${declared}, but ${viewportMismatch}. The viewport meta has no effect on capture \u2014 the renderer sizes the viewport from the root's own data-width/data-height \u2014 so this is stale metadata, not a clipping risk.`,
+      message: `${declared}, but ${viewportMismatch}. The viewport meta has no effect on capture (the renderer sizes the viewport from the root's own data-width/data-height), so this is stale metadata, not a clipping risk.`,
       fixHint: "update the meta viewport to match, or scaffold with `hyperframes init --resolution portrait`"
     };
   }
@@ -1352,7 +1355,7 @@ var coreRules = [
       findings.push({
         code: "unclosed_tag_swallowed_element",
         severity: "error",
-        message: `<${tag.name}> is missing its closing \`>\` before the next \`<\` \u2014 the following element is swallowed as bogus attribute text and never becomes a real node.`,
+        message: `<${tag.name}> is missing its closing \`>\` before the next \`<\`, so the following element is swallowed as bogus attribute text and never becomes a real node.`,
         fixHint: "Close the previous tag's `>` before opening the next element.",
         snippet: truncateSnippet(tag.raw)
       });
@@ -2067,7 +2070,7 @@ var mediaRules = [
           severity: "error",
           message: `<video${elementId ? ` id="${elementId}"` : ""}> has data-start but declares neither muted nor data-has-audio. If the file has sound, add data-has-audio="true" (the sound stays on this clip). If it is silent, add muted.`,
           elementId,
-          fixHint: 'Add data-has-audio="true" when the file has sound (recommended \u2014 keeps picture and sound on one clip), or add `muted` for silent footage.',
+          fixHint: 'Add data-has-audio="true" when the file has sound (recommended: it keeps picture and sound on one clip), or add `muted` for silent footage.',
           snippet: truncateSnippet(tag.raw)
         });
       }
@@ -2152,7 +2155,7 @@ var mediaRules = [
         severity: "error",
         message: `Self-closing <${tagName}/> is invalid HTML. The browser will leave the tag open, swallowing all subsequent elements as invisible fallback content. This makes compositions INVISIBLE.`,
         elementId,
-        fixHint: `Change <${tagName} .../> to <${tagName} ...></${tagName}> \u2014 media elements MUST have explicit closing tags.`,
+        fixHint: `Change <${tagName} .../> to <${tagName} ...></${tagName}>. Media elements MUST have explicit closing tags.`,
         snippet: truncateSnippet(scMatch[0])
       });
     }
@@ -2195,7 +2198,7 @@ var mediaRules = [
       findings.push({
         code: "base64_media_prohibited",
         severity: "error",
-        message: `Inline base64 audio/video detected (${(dataSize / 1024).toFixed(0)} KB)${isSuspicious ? " \u2014 likely fabricated data" : ""}. Base64 media is prohibited \u2014 it bloats file size and breaks rendering.`,
+        message: `Inline base64 audio/video detected (${(dataSize / 1024).toFixed(0)} KB)${isSuspicious ? ", likely fabricated data" : ""}. Base64 media is prohibited: it bloats file size and breaks rendering.`,
         fixHint: "Use a relative path (assets/music.mp3) or HTTPS URL for the audio/video src. Never embed media as base64.",
         snippet: truncateSnippet((b64Match[1] ?? "").slice(0, 80) + "...")
       });
@@ -2224,7 +2227,7 @@ var mediaRules = [
         findings.push({
           code: "media_missing_id",
           severity: "error",
-          message: `<${tag.name}> has data-start but no id attribute. The renderer requires id to discover media elements \u2014 this ${tag.name === "audio" ? "audio will be SILENT" : "video will be FROZEN"} in renders.`,
+          message: `<${tag.name}> has data-start but no id attribute. The renderer requires id to discover media elements, so this ${tag.name === "audio" ? "audio will be SILENT" : "video will be FROZEN"} in renders.`,
           fixHint: `Add a unique id attribute: <${tag.name} id="my-${tag.name}" ...>`,
           snippet: truncateSnippet(tag.raw)
         });
@@ -2281,7 +2284,7 @@ var mediaRules = [
       findings.push({
         code: "media_crossorigin_breaks_preview",
         severity: "error",
-        message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has crossorigin, which forces a CORS-checked fetch. If the media host omits Access-Control-Allow-Origin, the load silently fails in Studio preview (media shows BLANK/black) while server-side renders still work \u2014 hiding the bug.`,
+        message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has crossorigin, which forces a CORS-checked fetch. If the media host omits Access-Control-Allow-Origin, the load silently fails in Studio preview (media shows BLANK/black) while server-side renders still work, which hides the bug.`,
         elementId,
         fixHint: "Remove the crossorigin attribute unless you read the media back via canvas/WebGL/WebAudio AND the host is known to send CORS headers. Plain displayed media never needs it.",
         snippet: truncateSnippet(tag.raw)
@@ -2315,7 +2318,7 @@ var mediaRules = [
       findings.push({
         code: "video_audio_double_source",
         severity: "error",
-        message: `<audio${audioInfo.id ? ` id="${audioInfo.id}"` : ""}> and <video${videoInfo.id ? ` id="${videoInfo.id}"` : ""}> both point to the same source at the same time. The unmuted video already provides audio \u2014 the duplicate <audio> will cause double playback and echo.`,
+        message: `<audio${audioInfo.id ? ` id="${audioInfo.id}"` : ""}> and <video${videoInfo.id ? ` id="${videoInfo.id}"` : ""}> both point to the same source at the same time. The unmuted video already provides audio, so the duplicate <audio> will cause double playback and echo.`,
         elementId: audioInfo.id,
         fixHint: "Remove the <audio> element and let the video carry its own sound (recommended), or mute the video (add `muted`) and keep the separate <audio> when picture and sound must be cut independently.",
         snippet: truncateSnippet(audioInfo.raw)
@@ -2351,7 +2354,7 @@ function findVolumeTweenOverridesGainFindings(ctx) {
     findings.push({
       code: "audio_volume_tween_overrides_gain",
       severity: "warning",
-      message: `#${id} has data-volume="${volume}" (${db}) and a GSAP tween on \`volume\`. Tween values are absolute \u2014 they REPLACE this gain rather than scale it \u2014 so wherever the tween names a value the clip plays at that value, not at ${db}.`,
+      message: `#${id} has data-volume="${volume}" (${db}) and a GSAP tween on \`volume\`. Tween values are absolute: they REPLACE this gain rather than scale it, so wherever the tween names a value the clip plays at that value, not at ${db}.`,
       elementId: id,
       fixHint: "Write the tween's targets in the same absolute gain (e.g. `volume: 1.95`, not `volume: 1`), or reset data-volume to 1 and let the tween carry the level on its own.",
       snippet: truncateSnippet(tag.raw)
@@ -2370,7 +2373,7 @@ function findVolumeDoubleAutomationFindings(ctx) {
     findings.push({
       code: "audio_volume_double_automation",
       severity: "warning",
-      message: `#${id} has both a volume automation lane and a GSAP tween on \`volume\`. The lane wins \u2014 the tween is ignored in preview and in the render.`,
+      message: `#${id} has both a volume automation lane and a GSAP tween on \`volume\`. The lane wins, and the tween is ignored in preview and in the render.`,
       elementId: id,
       fixHint: "Keep one of them: delete the volume lane to go back to tweening, or drop the tween and shape the level in the automation lane.",
       snippet: truncateSnippet(tag.raw)
@@ -2418,7 +2421,7 @@ function findCarveUngroupedSourcesFindings(ctx) {
       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.",
+      fixHint: "Group the voice clips and carve against the group. A hand-rolled clip list silently rots when a clip is added.",
       snippet: truncateSnippet(tag.raw)
     });
   }
@@ -2467,7 +2470,7 @@ function findAudioGroupTimingAttrFindings(ctx) {
     findings.push({
       code: "audio_group_timing_attrs",
       severity: "warning",
-      message: `${elementId ? `#${elementId}` : "This audio group"} carries ${present.map((attr) => `\`${attr}\``).join(", ")}, which a bus has no use for \u2014 its members carry the timing and its automation clock is composition time.`,
+      message: `${elementId ? `#${elementId}` : "This audio group"} carries ${present.map((attr) => `\`${attr}\``).join(", ")}, which a bus has no use for: its members carry the timing and its automation clock is composition time.`,
       elementId,
       fixHint: `Remove ${present.map((attr) => `\`${attr}\``).join(", ")} from the group element.`,
       snippet: truncateSnippet(tag.raw)
@@ -2484,7 +2487,7 @@ function findAudioGroupCarveAttrFindings(ctx) {
     findings.push({
       code: "audio_group_carve_attr",
       severity: "warning",
-      message: `${elementId ? `#${elementId}` : "This audio group"} carries \`data-fx-carve\`, which belongs on the clip being carved \u2014 a bus has no audio of its own to level-match against, and a carve here stacks with any its members already have.`,
+      message: `${elementId ? `#${elementId}` : "This audio group"} carries \`data-fx-carve\`, which belongs on the clip being carved. A bus has no audio of its own to level-match against, and a carve here stacks with any its members already have.`,
       elementId,
       fixHint: "Remove `data-fx-carve` and the `fromCarve` nodes it wrote into this bus's `data-fx-chain`, and carve the bed clip instead.",
       snippet: truncateSnippet(tag.raw)
@@ -3162,7 +3165,7 @@ var compositionRules = [
       findings.push({
         code: "root_composition_missing_html_wrapper",
         severity: "error",
-        message: "Composition starts with a bare element instead of a proper HTML document. An index.html that contains data-composition-id but no <!DOCTYPE html>, <html>, or <body> is a fragment \u2014 browsers quirks-mode it, the preview server cannot load it, and the bundler will fail to inject runtime scripts.",
+        message: "Composition starts with a bare element instead of a proper HTML document. An index.html that contains data-composition-id but no <!DOCTYPE html>, <html>, or <body> is a fragment: browsers quirks-mode it, the preview server cannot load it, and the bundler will fail to inject runtime scripts.",
         fixHint: 'Wrap the composition in <!DOCTYPE html><html><head><meta charset="UTF-8"></head><body>...</body></html>.',
         snippet: rootTag ? truncateSnippet(rootTag.raw) : void 0
       });
@@ -3317,7 +3320,7 @@ var compositionRules = [
         findings.push({
           code: "unknown_variable_binding",
           severity: "warning",
-          message: `<${tag.name}> binds ${attr}="${id}" but no variable "${id}" is declared in data-composition-variables \u2014 the binding will silently keep the authored fallback.`,
+          message: `<${tag.name}> binds ${attr}="${id}" but no variable "${id}" is declared in data-composition-variables, so the binding will silently keep the authored fallback.`,
           fixHint: `Declare the variable on the composition root (<html>, or the [data-composition-id] root element for a template/fragment comp): data-composition-variables='[{"id":"${id}","type":"${attr === "data-var-src" ? "image" : "string"}","label":"${id}","default":"..."}]', or fix the binding id.`,
           elementId: readAttr(tag.raw, "id") || void 0,
           snippet: truncateSnippet(tag.raw)
@@ -3358,8 +3361,8 @@ var compositionRules = [
       {
         code: "html_dir_attribute_breaks_render",
         severity: "error",
-        message: `<html dir="${dir}"> renders correctly in preview/snapshot but produces a fully blank/black video from render \u2014 a confirmed, silent failure.`,
-        fixHint: `Remove dir="${dir}" from <html>. Keep lang, and scope ${scopedDirection} to individual text-containing elements instead \u2014 text still shapes correctly via the browser's own bidi algorithm.`,
+        message: `<html dir="${dir}"> renders correctly in preview/snapshot but produces a fully blank/black video from render. This is a confirmed, silent failure.`,
+        fixHint: `Remove dir="${dir}" from <html>. Keep lang, and scope ${scopedDirection} to individual text-containing elements instead. Text still shapes correctly via the browser's own bidi algorithm.`,
         snippet: truncateSnippet(htmlTag.raw)
       }
     ];
@@ -3397,7 +3400,7 @@ var compositionRules = [
       findings.push({
         code: "subcomposition_blanks_before_host",
         severity: "warning",
-        message: `<${t.tag.name}${elementId ? ` id="${elementId}"` : ""}> sub-composition ends at ${round3(t.end)}s but the composition runs to ${round3(rootDuration)}s \u2014 its slot will be blank for ~${gap}s.`,
+        message: `<${t.tag.name}${elementId ? ` id="${elementId}"` : ""}> sub-composition ends at ${round3(t.end)}s but the composition runs to ${round3(rootDuration)}s, so its slot will be blank for ~${gap}s.`,
         elementId,
         fixHint: `data-duration is the slot's visible window. Set this sub-composition's data-duration to ${round3(rootDuration - t.start)} to fill the host window, or add another clip to cover the remaining ~${gap}s.`,
         snippet: truncateSnippet(t.tag.raw)
@@ -3436,7 +3439,7 @@ var compositionRules = [
         severity: "error",
         message: `Root element has class="${rootClasses.join(" ")}" and is styled by ${offenders.length} rule(s) keyed off that class (e.g. ${example}). At render, every sub-composition rule is scoped to [data-composition-id="${rootCompositionId}"] <selector>, so a selector whose leftmost part is the ROOT's own class becomes a descendant selector that cannot match the scoped element itself. Since #1886 the producer preserves the authored root as an inner wrapper, so this no longer renders the scene unstyled, but #root is the shape the scoper special-cases and the registry blocks model. Use it so preview, render, and Studio agree.`,
         selector: example,
-        fixHint: `Give the root id="root" and style it with \`#root { ... }\` plus plain descendant selectors (\`.kicker\`, \`#hero\`) \u2014 the runtime already scopes each sub-composition by data-composition-id, so a class namespace on the root is redundant.`,
+        fixHint: `Give the root id="root" and style it with \`#root { ... }\` plus plain descendant selectors (\`.kicker\`, \`#hero\`). The runtime already scopes each sub-composition by data-composition-id, so a class namespace on the root is redundant.`,
         snippet: truncateSnippet(rootTag.raw)
       }
     ];
@@ -3519,7 +3522,7 @@ ${allInlineStyles}`.replace(/\/\*[\s\S]*?\*\//g, "");
         {
           code: "root_composition_missing_duration_source",
           severity: "error",
-          message: `Root composition uses Three.js with no data-duration. The runtime cannot discover a Three.js scene's duration automatically (no AnimationClip/AnimationMixer inspection) \u2014 render will fail with "Composition has zero duration".`,
+          message: `Root composition uses Three.js with no data-duration. The runtime cannot discover a Three.js scene's duration automatically (no AnimationClip/AnimationMixer inspection), so render will fail with "Composition has zero duration".`,
           fixHint: 'Add data-duration="<seconds>" to the root element.',
           snippet: truncateSnippet(rootTag.raw)
         }
@@ -3582,8 +3585,8 @@ ${allInlineStyles}`.replace(/\/\*[\s\S]*?\*\//g, "");
       {
         code: "composition_heavy_overlay_count_high",
         severity: "warning",
-        message: `This composition has ${heavyCount} elements carrying "heavy overlay" CSS (filter:blur, radial-gradient, or clip-path). Field signal: a composition with ~40 such elements \u2014 including opacity:0 / visibility:hidden ones \u2014 captures solid-black for the first ~half of the render, recovering near the end. Reproduces identically via drawElement, forced screenshot capture, and snapshot, so the capture layer itself is the offender (not encoder/mux). Independent of duration. Presence alone matters; only display:none elements are excluded here.`,
-        fixHint: `${splitTarget} and concat the pieces (FFmpeg or the runtime's slideshow) so each capture only sees a small subset of heavy overlays at once. Even hidden overlays (opacity:0 / visibility:hidden) contribute \u2014 either remove truly unused ones from the source or scope them into their own per-transition sub-composition. If an overlay is genuinely inert for the whole clip, use display:none so it never enters the render tree. Field ref ts=1784040753 (#hyperframes-cli-feedback).`
+        message: `This composition has ${heavyCount} elements carrying "heavy overlay" CSS (filter:blur, radial-gradient, or clip-path). Field signal: a composition with ~40 such elements (including opacity:0 / visibility:hidden ones) captures solid-black for the first ~half of the render, recovering near the end. Reproduces identically via drawElement, forced screenshot capture, and snapshot, so the capture layer itself is the offender (not encoder/mux). Independent of duration. Presence alone matters; only display:none elements are excluded here.`,
+        fixHint: `${splitTarget} and concat the pieces (FFmpeg or the runtime's slideshow) so each capture only sees a small subset of heavy overlays at once. Even hidden overlays (opacity:0 / visibility:hidden) contribute: either remove truly unused ones from the source or scope them into their own per-transition sub-composition. If an overlay is genuinely inert for the whole clip, use display:none so it never enters the render tree. Field ref ts=1784040753 (#hyperframes-cli-feedback).`
       }
     ];
   },
@@ -3626,8 +3629,8 @@ ${allInlineStyles}`.replace(/\/\*[\s\S]*?\*\//g, "");
       {
         code: "root_zoom_rescales_a_fixed_canvas",
         severity: "error",
-        message: `\`zoom: ${hit.value}\` on ${hit.where} rescales the painted composition inside a frame that does not rescale with it. The capture frame is sized from the root's data-width/data-height in LAYOUT pixels, and \`zoom\` changes only what is painted inside it, so ` + (enlarging ? `content past the frame's edge renders zero pixels \u2014 it is inside the declared composition and absent from the output, with nothing else reporting it.` : `the composition paints into part of the frame and the remainder of every output frame is dead space.`),
-        fixHint: `Author the composition at its real size \u2014 set data-width/data-height (and the root's width/height) to the dimensions you want \u2014 and drop the canvas-level \`zoom\`. To scale the OUTPUT without changing layout, pass \`--output-resolution\` to render, which supersamples. \`zoom\` on descendants is fine and is not flagged: it is honoured exactly as specified.`,
+        message: `\`zoom: ${hit.value}\` on ${hit.where} rescales the painted composition inside a frame that does not rescale with it. The capture frame is sized from the root's data-width/data-height in LAYOUT pixels, and \`zoom\` changes only what is painted inside it, so ` + (enlarging ? `content past the frame's edge renders zero pixels. It is inside the declared composition and absent from the output, with nothing else reporting it.` : `the composition paints into part of the frame and the remainder of every output frame is dead space.`),
+        fixHint: `Author the composition at its real size: set data-width/data-height (and the root's width/height) to the dimensions you want, and drop the canvas-level \`zoom\`. To scale the OUTPUT without changing layout, pass \`--output-resolution\` to render, which supersamples. \`zoom\` on descendants is fine and is not flagged: it is honoured exactly as specified.`,
         snippet: hit.snippet
       }
     ];
@@ -3671,8 +3674,8 @@ ${allInlineStyles}`.replace(/\/\*[\s\S]*?\*\//g, "");
       {
         code: "composition_exceeds_inspection_viewport_cap",
         severity: "warning",
-        message: `${over.join(" and ")} exceeds the ${INSPECTION_VIEWPORT_CAP}px viewport cap that check, validate, snapshot, compare and layout clamp to. render is unaffected and produces the full size, so the video is correct \u2014 but every inspection command captures a ${INSPECTION_VIEWPORT_CAP}px-wide frame, and anything beyond that is missing from what they report. Measured at 0.8.71: a 5000x400 composition renders 5000x400 with all content, while snapshot returns 4096x400 with the element at left:4500 absent.`,
-        fixHint: `Keep the authored size if the output needs it, and verify the region past ${INSPECTION_VIEWPORT_CAP}px from a render rather than from check/snapshot/compare \u2014 a clean inspection result does not cover it. If the large canvas is only there to gain resolution, author at the layout size and pass \`--output-resolution\` to render instead, which supersamples without changing layout.`,
+        message: `${over.join(" and ")} exceeds the ${INSPECTION_VIEWPORT_CAP}px viewport cap that check, validate, snapshot, compare and layout clamp to. render is unaffected and produces the full size, so the video is correct, but every inspection command captures a ${INSPECTION_VIEWPORT_CAP}px-wide frame, and anything beyond that is missing from what they report. Measured at 0.8.71: a 5000x400 composition renders 5000x400 with all content, while snapshot returns 4096x400 with the element at left:4500 absent.`,
+        fixHint: `Keep the authored size if the output needs it, and verify the region past ${INSPECTION_VIEWPORT_CAP}px from a render rather than from check/snapshot/compare. A clean inspection result does not cover it. If the large canvas is only there to gain resolution, author at the layout size and pass \`--output-resolution\` to render instead, which supersamples without changing layout.`,
         snippet: truncateSnippet(rootTag.raw)
       }
     ];
@@ -4551,7 +4554,7 @@ ${right.raw}`)
         findings.push({
           code: "gsap_animates_clip_element",
           severity: "error",
-          message: `GSAP animation sets ${conflictingProps.join(", ")} on a clip element. Selector "${sel}" resolves to element ${elDesc}. The framework manages clip visibility, and autoAlpha writes visibility as well as opacity \u2014 do not animate these properties on clip elements.`,
+          message: `GSAP animation sets ${conflictingProps.join(", ")} on a clip element. Selector "${sel}" resolves to element ${elDesc}. The framework manages clip visibility, and autoAlpha writes visibility as well as opacity. Do not animate these properties on clip elements.`,
           selector: sel,
           elementId: clipInfo.id || void 0,
           fixHint: "Remove the visibility/display/autoAlpha tween, or move the content into a child <div> and target that instead.",
@@ -4745,7 +4748,7 @@ ${right.raw}`)
           findings.push({
             code: "audio_reactive_single_tween_per_group",
             severity: "warning",
-            message: "Audio-reactive captions use a single tween per group based on peak values. This sets one static value at group.start \u2014 not perceptible as audio reactivity.",
+            message: "Audio-reactive captions use a single tween per group based on peak values. This sets one static value at group.start, which is not perceptible as audio reactivity.",
             fixHint: "Sample audio data at 100-200ms intervals throughout each group's lifetime (for loop from group.start to group.end) and create a tween at each sample point for visible pulsing."
           });
         }
@@ -4830,7 +4833,7 @@ ${right.raw}`)
         ...locate(script, gsapCallOffset(script, "timeline")),
         code: "gsap_timeline_not_registered",
         severity: "error",
-        message: "GSAP timeline is created but never registered in window.__timelines. The runtime discovers timelines from this registry \u2014 without registration, animations will not play during preview or render.",
+        message: "GSAP timeline is created but never registered in window.__timelines. The runtime discovers timelines from this registry. Without registration, animations will not play during preview or render.",
         fixHint: 'Add `window.__timelines = window.__timelines || {};` and `window.__timelines["root"] = tl;` after creating the timeline (use the composition\'s data-composition-id as the key).'
       });
     }
@@ -4898,9 +4901,9 @@ ${right.raw}`)
         findings.push({
           code: "gsap_from_opacity_noop",
           severity: "error",
-          message: `"${sel}" has CSS \`opacity: 0\` and a gsap.${win.method}() that also sets opacity to 0. gsap.from() animates FROM the specified value TO the current CSS value \u2014 since CSS is already 0, the element animates from 0\u21920 and never becomes visible.`,
+          message: `"${sel}" has CSS \`opacity: 0\` and a gsap.${win.method}() that also sets opacity to 0. gsap.from() animates FROM the specified value TO the current CSS value. Since CSS is already 0, the element animates from 0\u21920 and never becomes visible.`,
           selector: sel,
-          fixHint: `Remove \`opacity: 0\` from the CSS/inline style on "${sel}". Let gsap.from({opacity: 0}) handle the initial hidden state \u2014 it will animate FROM 0 TO the CSS value (1 by default).`,
+          fixHint: `Remove \`opacity: 0\` from the CSS/inline style on "${sel}". Let gsap.from({opacity: 0}) handle the initial hidden state. It will animate FROM 0 TO the CSS value (1 by default).`,
           snippet: truncateSnippet(win.raw)
         });
       }
@@ -4979,12 +4982,12 @@ ${right.raw}`)
         if (layoutProps.length > 0 && allTargetsHtmlInCanvas(call.selector)) layoutProps = [];
         if (layoutProps.length === 0 && reflowProps.length === 0 && !usesRoundProps) continue;
         const flagged = [...layoutProps, ...reflowProps, ...usesRoundProps ? ["roundProps"] : []];
-        const message = `GSAP tween on "${call.selector}" uses motion that snaps to integer device pixels: ${flagged.join(", ")}. Layout and text-reflow properties snap during browser layout; roundProps rounds the tween value. Slow motion or an ease-out tail then stutters under the seek-by-frame capture engine \u2014 animate transforms (x/y/scale/opacity) instead.`;
+        const message = `GSAP tween on "${call.selector}" uses motion that snaps to integer device pixels: ${flagged.join(", ")}. Layout and text-reflow properties snap during browser layout; roundProps rounds the tween value. Slow motion or an ease-out tail then stutters under the seek-by-frame capture engine. Animate transforms (x/y/scale/opacity) instead.`;
         const fixes = [];
         if (layoutProps.length > 0) {
           const tokens = [...new Set(layoutProps.flatMap((p) => LAYOUT_FIX[p] ?? []))];
           fixes.push(
-            `replace ${layoutProps.join("/")} with the transform equivalent (${tokens.join(", ")}) \u2014 e.g. tl.fromTo("${call.selector}", { x: -1300 }, { x: 0, ...yourAnimation })`
+            `replace ${layoutProps.join("/")} with the transform equivalent (${tokens.join(", ")}), e.g. tl.fromTo("${call.selector}", { x: -1300 }, { x: 0, ...yourAnimation })`
           );
         }
         if (reflowProps.length > 0) {
@@ -4996,7 +4999,7 @@ ${right.raw}`)
           }
           if (spacing.length > 0) {
             parts.push(
-              `for ${spacing.join("/")}, split the text into per-character elements and animate each glyph's x (the spread) \u2014 uniform scale is NOT equivalent \u2014 or hold the final value statically`
+              `for ${spacing.join("/")}, split the text into per-character elements and animate each glyph's x (the spread), since uniform scale is NOT equivalent, or hold the final value statically`
             );
           }
           fixes.push(
@@ -5060,7 +5063,7 @@ ${right.raw}`)
           findings.push({
             code: "gsap_relative_value_second_writer",
             severity: "error",
-            message: `Relative value(s) ${values} on "${win.targetSelector}" start while another writer for the same propert${sharedProps.length > 1 ? "ies" : "y"} is active between ${formatTime(win.position)} and ${formatTime(overlapEnd)}. Relative tweens capture their base at tween init: the sequential path inits mid-flight of the other writer, a cold render worker landing later inits with its end state \u2014 the same frame renders at two different positions (snap at chunk boundaries).`,
+            message: `Relative value(s) ${values} on "${win.targetSelector}" start while another writer for the same propert${sharedProps.length > 1 ? "ies" : "y"} is active between ${formatTime(win.position)} and ${formatTime(overlapEnd)}. Relative tweens capture their base at tween init: the sequential path inits mid-flight of the other writer, a cold render worker landing later inits with its end state, so the same frame renders at two different positions (snap at chunk boundaries).`,
             selector: win.targetSelector,
             fixHint: `Use absolute values for ${sharedProps.join(", ")}, or a fromTo() with explicit endpoints, so every seek path resolves the same state. Single-writer relative values are safe; the conflict is the second writer.`,
             snippet: truncateSnippet(`${win.raw}
@@ -5129,13 +5132,13 @@ ${other.raw}`)
           const readsInvariant = TRANSFORM_INVARIANT_READ.test(fn.body);
           const badMember = firstParamMemberAccessHazard(fn);
           if (!readsSensitive && !readsInvariant && !badMember) continue;
-          const reason = readsSensitive ? "reads transform-sensitive geometry, so its result depends on the worker's own seek order" : badMember ? `accesses .${badMember} on its first parameter \u2014 GSAP function values receive (index, target, targets), so the first parameter is a NUMBER and this throws at tween init` : "measures layout at tween init, which is deterministic across cold render workers only while the measured layout never animates";
+          const reason = readsSensitive ? "reads transform-sensitive geometry, so its result depends on the worker's own seek order" : badMember ? `accesses .${badMember} on its first parameter. GSAP function values receive (index, target, targets), so the first parameter is a NUMBER and this throws at tween init` : "measures layout at tween init, which is deterministic across cold render workers only while the measured layout never animates";
           findings.push({
             code: "gsap_function_value_hazard",
             severity: readsSensitive || badMember ? "error" : "warning",
             message: `Function-valued tween var for ${prop} on "${anim.targetSelector}" ${reason}. Each render worker initializes tweens independently.`,
             selector: anim.targetSelector,
-            fixHint: badMember ? "Use the SECOND parameter for the element: (index, target) => ... \u2014 or index arithmetic like (i) => i * 20." : "Compute the value once at build time (before the timeline is registered) and pass a constant, or derive it from fixed composition coordinates.",
+            fixHint: badMember ? "Use the SECOND parameter for the element: (index, target) => ..., or index arithmetic like (i) => i * 20." : "Compute the value once at build time (before the timeline is registered) and pass a constant, or derive it from fixed composition coordinates.",
             snippet: truncateSnippet(raw)
           });
         }
@@ -5171,9 +5174,9 @@ ${other.raw}`)
         findings.push({
           code: "gsap_callback_dom_measurement",
           severity: "warning",
-          message: "Timeline callback reaches DOM measurement (getBoundingClientRect/getTotalLength/getComputedStyle/...). The renderer seeks with suppressEvents=false, so callbacks re-fire on every seek \u2014 and a cold render worker runs them against whatever DOM state its own non-linear seek order produced. Measured geometry is seek-order-dependent, and values measured at build time (before the callback ran) are stale or zero.",
+          message: "Timeline callback reaches DOM measurement (getBoundingClientRect/getTotalLength/getComputedStyle/...). The renderer seeks with suppressEvents=false, so callbacks re-fire on every seek, and a cold render worker runs them against whatever DOM state its own non-linear seek order produced. Measured geometry is seek-order-dependent, and values measured at build time (before the callback ran) are stale or zero.",
           selector: truncateSnippet(site, 120),
-          fixHint: "Do all measurement and DOM setup synchronously at build time, before registering the timeline \u2014 or derive geometry from fixed composition coordinates instead of measuring.",
+          fixHint: "Do all measurement and DOM setup synchronously at build time, before registering the timeline, or derive geometry from fixed composition coordinates instead of measuring.",
           snippet: truncateSnippet(snippet)
         });
       };
@@ -5246,8 +5249,8 @@ ${other.raw}`)
         findings.push({
           code: "gsap_timeline_return_used_as_tween",
           severity: "error",
-          message: `\`${match[0].includes(".push") ? "push" : boundName}\` captures the return of \`.${method}()\` on timeline \`${timelineVars[0]}\`, but a timeline's \`.to()\`/\`.from()\`/\`.set()\` returns THE TIMELINE ITSELF, not the tween it created. Every captured value is the same master timeline, so a tween-scoped call on it \u2014 \`.kill()\` above all \u2014 hits the whole composition: it interrupts the timeline and detaches it from its parent, which freezes a parent-driven seek while an explicit \`tl.progress()\` keeps working. Only \`gsap.to()\` returns a tween.`,
-          fixHint: "To build a group of keyframes you can later discard, put them in a nested timeline: `const nested = gsap.timeline(); nested.to(...); tl.add(nested, 0);` \u2014 then `nested.kill()` replaces exactly those keyframes and cannot reach `tl`. Children keep their absolute times when the nest is added at 0. To hold a single real tween, create it with `gsap.to(...)` and place it with `tl.add(tween, at)`.",
+          message: `\`${match[0].includes(".push") ? "push" : boundName}\` captures the return of \`.${method}()\` on timeline \`${timelineVars[0]}\`, but a timeline's \`.to()\`/\`.from()\`/\`.set()\` returns THE TIMELINE ITSELF, not the tween it created. Every captured value is the same master timeline, so a tween-scoped call on it (\`.kill()\` above all) hits the whole composition: it interrupts the timeline and detaches it from its parent, which freezes a parent-driven seek while an explicit \`tl.progress()\` keeps working. Only \`gsap.to()\` returns a tween.`,
+          fixHint: "To build a group of keyframes you can later discard, put them in a nested timeline: `const nested = gsap.timeline(); nested.to(...); tl.add(nested, 0);`. Then `nested.kill()` replaces exactly those keyframes and cannot reach `tl`. Children keep their absolute times when the nest is added at 0. To hold a single real tween, create it with `gsap.to(...)` and place it with `tl.add(tween, at)`.",
           snippet: truncateSnippet(source.slice(contextStart, match.index + match[0].length + 60))
         });
       }
@@ -5342,7 +5345,7 @@ ${other.raw}`)
           findings.push({
             code: "svg_drawon_css_dasharray_conflict",
             severity: "error",
-            message: `GSAP writes strokeDasharray on "${targetLabel}", but its CSS ("${conflictToken}") declares a multi-component stroke-dasharray. GSAP merges dash lists per component, so the CSS gap survives (e.g. "641.4px, 10px") \u2014 the draw-on hide only hides one gap's worth and the line stays visible the whole scene.`,
+            message: `GSAP writes strokeDasharray on "${targetLabel}", but its CSS ("${conflictToken}") declares a multi-component stroke-dasharray. GSAP merges dash lists per component, so the CSS gap survives (e.g. "641.4px, 10px"). The draw-on hide only hides one gap's worth and the line stays visible the whole scene.`,
             selector: quotedSelector ?? void 0,
             fixHint: `Remove the CSS stroke-dasharray from "${conflictToken}" (decorative dashes belong on a separate element), or set the full two-component value in GSAP: strokeDasharray: "\${len} \${len}".`,
             snippet: truncateSnippet(match[0] + firstVars.slice(1))
@@ -5464,7 +5467,7 @@ ${other.raw}`)
         findings.push({
           code: "svg_measure_before_path_d",
           severity: sameVarAssignmentExists ? "warning" : "error",
-          message: sameVarAssignmentExists ? `getTotalLength() is called on "${tokenLabel}", whose \`d\` is only assigned inside a function body \u2014 if the measure runs before that function (e.g. the function is a timeline callback), the length is 0 and the dash animation is dead.` : `getTotalLength() is called on "${tokenLabel}", but the path has no static \`d\` attribute and no d assignment exists anywhere \u2014 getTotalLength() returns 0 in Chrome, silently killing dash animations.`,
+          message: sameVarAssignmentExists ? `getTotalLength() is called on "${tokenLabel}", whose \`d\` is only assigned inside a function body. If the measure runs before that function (e.g. the function is a timeline callback), the length is 0 and the dash animation is dead.` : `getTotalLength() is called on "${tokenLabel}", but the path has no static \`d\` attribute and no d assignment exists anywhere, so getTotalLength() returns 0 in Chrome, silently killing dash animations.`,
           selector: tokenLabel,
           fixHint: "Assign the path's `d` synchronously at build time (top level, before measuring), or author a static d attribute in the HTML.",
           snippet: truncateSnippet(match[0] + ")")
@@ -6012,7 +6015,7 @@ var fontRules = [
       {
         code: "system_font_will_alias",
         severity: "warning",
-        message: `Font ${aliased.length === 1 ? "family" : "families"} will be substituted at render time: ${aliased.join(", ")}. In distributed/Lambda rendering system-font capture is disabled \u2014 these fonts will fall back to OS defaults. Embed explicit @font-face declarations instead.`
+        message: `Font ${aliased.length === 1 ? "family" : "families"} will be substituted at render time: ${aliased.join(", ")}. In distributed/Lambda rendering system-font capture is disabled, so these fonts will fall back to OS defaults. Embed explicit @font-face declarations instead.`
       }
     ];
   },
@@ -6032,7 +6035,7 @@ var fontRules = [
       code: "font_family_without_font_face",
       severity: "error",
       message: `Font ${undeclared.length === 1 ? "family" : "families"} used without @font-face declaration: ${undeclared.join(", ")}. These are not in the auto-resolved font list, so the renderer cannot supply them automatically. Text will fall back to a generic font, producing incorrect typography in the video.`,
-      fixHint: "Add @font-face { font-family: '...'; src: url('capture/assets/fonts/...woff2'); } for each font family, pointing to the captured .woff2 files. For an OS-bundled system font (e.g. Hiragino Sans, Microsoft YaHei) that has no downloadable file, use src: local('Exact Font Name') instead \u2014 the declaration alone satisfies this check without needing a font file."
+      fixHint: "Add @font-face { font-family: '...'; src: url('capture/assets/fonts/...woff2'); } for each font family, pointing to the captured .woff2 files. For an OS-bundled system font (e.g. Hiragino Sans, Microsoft YaHei) that has no downloadable file, use src: local('Exact Font Name') instead. The declaration alone satisfies this check without needing a font file."
     });
     return findings;
   }
@@ -6560,7 +6563,7 @@ function collectLocalVideoCandidates(projectDir, htmlSources) {
     const re = new RegExp(videoSrcRe.source, videoSrcRe.flags);
     let match;
     while ((match = re.exec(scannable)) !== null) {
-      const rawSrc = match[2] ?? "";
+      const rawSrc = mediaSrcOf(match);
       const reference = resolveLocalVideoReference(projectDir, rawSrc, compSrcPath);
       if (!reference || candidates.has(reference.resolved)) continue;
       candidates.set(reference.resolved, reference.src);
@@ -6948,9 +6951,10 @@ function lintAudioSrcNotFound(projectDir, htmlSources) {
   const audioSrcRe = mediaSrcTagRe("audio");
   const missingByFile = /* @__PURE__ */ new Map();
   for (const { html, compSrcPath } of htmlSources) {
+    const scannable = maskNonScannableRanges2(html);
     let match;
-    while ((match = audioSrcRe.exec(html)) !== null) {
-      const src = match[2];
+    while ((match = audioSrcRe.exec(scannable)) !== null) {
+      const src = mediaSrcOf(match);
       if (/^(https?:|data:|blob:)/i.test(src)) continue;
       if (isUnresolvedAssetPlaceholder2(src)) continue;
       const rootRelative = compSrcPath ? rewriteAssetPath2(compSrcPath, src, (path) => existsSync2(join2(projectDir, path))) : src;
@@ -6982,7 +6986,7 @@ function lintMissingLocalAsset(projectDir, htmlSources) {
     let match;
     while ((match = re.exec(scannable)) !== null) {
       const tagName = (match[1] ?? "").toLowerCase();
-      const rawSrc = match[2] ?? "";
+      const rawSrc = mediaSrcOf(match);
       if (isUnresolvedAssetPlaceholder2(rawSrc)) continue;
       const src = cleanAssetUrl2(rawSrc);
       if (!src) continue;
@@ -7008,7 +7012,7 @@ function lintMissingLocalAsset(projectDir, htmlSources) {
       severity: "error",
       file,
       message: `<${tagName}> element references local file(s) not found in the project: ${unique.join(", ")}. The renderer will silently skip these and produce a video with missing visuals.`,
-      fixHint: unique.length === 1 ? `Add "${unique[0]}" to the project directory, or update the src attribute to point to an existing file. Common cause: captured asset filenames are unreliable (heygen-logo.svg often contains Google, nvidia-logo.svg may contain Autodesk, etc.). Open the contact sheets and verify the file actually exists at this path before referencing it.` : "Add the missing files to the project directory, or update the src attributes to point to existing files. Captured asset filenames are unreliable \u2014 verify against capture/contact-sheets/ and capture/extracted/asset-descriptions.md."
+      fixHint: unique.length === 1 ? `Add "${unique[0]}" to the project directory, or update the src attribute to point to an existing file. Common cause: captured asset filenames are unreliable (heygen-logo.svg often contains Google, nvidia-logo.svg may contain Autodesk, etc.). Open the contact sheets and verify the file actually exists at this path before referencing it.` : "Add the missing files to the project directory, or update the src attributes to point to existing files. Captured asset filenames are unreliable. Verify against capture/contact-sheets/ and capture/extracted/asset-descriptions.md."
     });
   }
   return findings;
@@ -7075,11 +7079,6 @@ function lintMultipleRootCompositions(projectDir) {
 }
 function lintDuplicateAudioTracks(htmlSources) {
   const findings = [];
-  function extractAttr(tag, name) {
-    const re = new RegExp(`\\b${name}\\s*=\\s*["']([^"']+)["']`, "i");
-    const m = tag.match(re);
-    return m?.[1] ?? null;
-  }
   const tracks = [];
   const seen = /* @__PURE__ */ new Set();
   for (const { html } of htmlSources) {
@@ -7088,10 +7087,10 @@ function lintDuplicateAudioTracks(htmlSources) {
     while ((match = soundTagRe.exec(html)) !== null) {
       const tag = match[0];
       if (/^<video/i.test(tag) && !isAudibleVideoTag(tag)) continue;
-      const trackStr = extractAttr(tag, "data-track-index");
-      const startStr = extractAttr(tag, "data-start");
-      const durStr = extractAttr(tag, "data-duration");
-      const src = extractAttr(tag, "src") ?? "unknown";
+      const trackStr = readAttr(tag, "data-track-index");
+      const startStr = readAttr(tag, "data-start");
+      const durStr = readAttr(tag, "data-duration");
+      const src = readDecodedAttr(tag, "src") || "unknown";
       if (!trackStr || !startStr) continue;
       const trackIndex = parseInt(trackStr, 10);
       const start = parseFloat(startStr);
@@ -7165,7 +7164,7 @@ function lintMissingOrEmptySubComposition(projectDir, rootHtml) {
       code: "missing_or_empty_sub_composition",
       severity: "error",
       message: `data-composition-src references "${srcPath}", but ${problem}.`,
-      fixHint: folder ? `Point data-composition-src at the HTML file inside the folder, such as "${srcPath}/index.html".` : `Fix this before rendering \u2014 the render pre-flight rejects unusable sub-compositions. Write valid HTML into "${srcPath}" \u2014 it needs a <template> or <body> containing an element with data-composition-id, data-width, and data-height. Preview/studio still tolerates and skips the scene while you author it. If a scene-authoring step is still running, wait for it to finish before referencing the file, or re-run the step that generates it.`
+      fixHint: folder ? `Point data-composition-src at the HTML file inside the folder, such as "${srcPath}/index.html".` : `Fix this before rendering: the render pre-flight rejects unusable sub-compositions. Write valid HTML into "${srcPath}". It needs a <template> or <body> containing an element with data-composition-id, data-width, and data-height. Preview/studio still tolerates and skips the scene while you author it. If a scene-authoring step is still running, wait for it to finish before referencing the file, or re-run the step that generates it.`
     });
   }
   return findings;
@@ -7183,4 +7182,3 @@ export {
   lintProject,
   shouldBlockRender
 };
-//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/lint",
-  "version": "0.8.145",
+  "version": "0.8.147",
   "repository": {
     "type": "git",
     "url": "https://github.com/heygen-com/hyperframes",
@@ -35,7 +35,7 @@
     "linkedom": "^0.18.12",
     "postcss": "^8.5.8",
     "postcss-selector-parser": "^7.1.4",
-    "@hyperframes/parsers": "0.8.145"
+    "@hyperframes/parsers": "0.8.147"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",