@hyperframes/lint 0.8.73 → 0.8.74

package/dist/index.js

@@ -2254,6 +2254,7 @@ import {
   readAuthoredDurationSeconds,
   resolveMediaDuration
 } from "@hyperframes/parsers/media-duration";
+var INSPECTION_VIEWPORT_CAP = 4096;
 var MAX_COMPOSITION_LINES = 300;
 var MAX_TIMED_ELEMENTS_PER_TRACK = 3;
 var TRACK_DENSITY_EXEMPT_TAGS = /* @__PURE__ */ new Set(["audio", "script", "style", "video"]);
@@ -2376,6 +2377,81 @@ function rootClassStyledSelectors(styles, rootClasses) {
   }
   return offenders;
 }
+var ZOOM_DECLARATION = /(?<![\w-])zoom\s*:\s*([^;}]+)/gi;
+function isIdentityZoom(rawValue) {
+  const value = rawValue.trim().replace(/!\s*important\s*$/i, "").trim().toLowerCase();
+  return value === "" || value === "normal" || value === "unset" || value === "initial" || value === "revert" || value === "1" || value === "1.0" || value === "100%";
+}
+function firstRescalingZoom(css) {
+  ZOOM_DECLARATION.lastIndex = 0;
+  let match;
+  while ((match = ZOOM_DECLARATION.exec(css)) !== null) {
+    const value = (match[1] ?? "").trim();
+    if (!isIdentityZoom(value)) return value.replace(/!\s*important\s*$/i, "").trim();
+  }
+  return null;
+}
+function targetsCanvasRoot(selector, rootId, rootClasses) {
+  const leftmost = selector.trim().split(/[\s>+~]+/)[0] ?? "";
+  const bare = leftmost.toLowerCase();
+  if (bare === "html" || bare === "body" || bare === ":root" || bare === "*") return true;
+  if (rootId && leftmostCompoundId(selector) === rootId) return true;
+  return leftmostCompoundClasses(selector).some((cls) => rootClasses.includes(cls));
+}
+function inlineCanvasZoomHits(rootTag, tags) {
+  const hits = [];
+  const htmlTag = findHtmlTag(tags);
+  const bodyTag = tags.find((tag) => tag.name.toLowerCase() === "body");
+  for (const [label, tag] of [
+    ["the root element's inline style", rootTag],
+    ["<html>'s inline style", htmlTag],
+    ["<body>'s inline style", bodyTag]
+  ]) {
+    if (!tag) continue;
+    const inline = readAttr(tag.raw, "style");
+    const value = inline ? firstRescalingZoom(inline) : null;
+    if (value) hits.push({ where: label, value, snippet: truncateSnippet(tag.raw) });
+  }
+  return hits;
+}
+function firstCanvasSelector(header, rootId, rootClasses) {
+  for (const selector of header.split(",")) {
+    const trimmed = selector.trim();
+    if (trimmed && targetsCanvasRoot(trimmed, rootId, rootClasses)) return trimmed;
+  }
+  return null;
+}
+function canvasZoomInRule(header, body, rootId, rootClasses) {
+  const trimmedHeader = header.trim();
+  if (!trimmedHeader || trimmedHeader.startsWith("@")) return null;
+  const value = firstRescalingZoom(body);
+  if (!value) return null;
+  const selector = firstCanvasSelector(trimmedHeader, rootId, rootClasses);
+  if (!selector) return null;
+  return {
+    where: `\`${selector}\``,
+    value,
+    snippet: truncateSnippet(`${selector} { zoom: ${value} }`)
+  };
+}
+function stylesheetCanvasZoomHits(styles, rootId, rootClasses) {
+  const hits = [];
+  for (const style of styles) {
+    const ruleWithBody = /([^{}]+)\{([^{}]*)\}/g;
+    let match;
+    while ((match = ruleWithBody.exec(stripCssComments(style.content))) !== null) {
+      const hit = canvasZoomInRule(match[1] ?? "", match[2] ?? "", rootId, rootClasses);
+      if (hit) hits.push(hit);
+    }
+  }
+  return hits;
+}
+function canvasZoomHits(rootTag, tags, styles, rootId, rootClasses) {
+  return [
+    ...inlineCanvasZoomHits(rootTag, tags),
+    ...stylesheetCanvasZoomHits(styles, rootId, rootClasses)
+  ];
+}
 function collectDeclaredVariableIds(htmlTagRaw) {
   const declared = /* @__PURE__ */ new Set();
   const raw = readJsonAttr(htmlTagRaw, "data-composition-variables");
@@ -2414,6 +2490,29 @@ function isInsideInertTemplate(tag, tags) {
     (candidate) => candidate.name === "template" && candidate.closeIndex != null && tag.index > candidate.index && tag.index < candidate.closeIndex
   );
 }
+var NEGATIVE_Z_INDEX = /(?<![\w-])z-index\s*:\s*-(?!0(?:\s*[;}]|\s*$))([\d.]+)/g;
+function cssOwnerSelector(content, matchIndex) {
+  const blockStart = content.lastIndexOf("{", matchIndex);
+  if (blockStart === -1) return void 0;
+  const previousBlockEnd = content.lastIndexOf("}", blockStart);
+  const lines = content.slice(previousBlockEnd + 1, blockStart).trim().split("\n");
+  return lines[lines.length - 1]?.trim() || void 0;
+}
+function elementSelector(tag) {
+  const elementId = readAttr(tag.raw, "id");
+  return elementId ? `#${elementId}` : void 0;
+}
+function negativeZIndexFinding(match, selector) {
+  const level = match[1] ?? "";
+  return {
+    code: "negative_z_index",
+    severity: "warning",
+    ...selector ? { selector } : {},
+    message: `\`z-index: -${level}\` paints the element behind its nearest stacking context's own content. With no stacking-context ancestor that context is the composition root itself, so an opaque background there hides it entirely: in the DOM, laid out, and absent from the picture. A transparent root leaves it visible. Siblings at \`z-index: 0\` or above are unaffected.`,
+    fixHint: "Give the element's parent a stacking context - `isolation: isolate` is the cheapest, and `transform`, `filter`, `opacity` below 1, `contain: paint` and `will-change` all work too. The negative-z child then paints above that parent's background and renders normally. Or express paint order through DOM order - an earlier sibling paints behind a later one - and raise the elements that should sit in front rather than lowering this one.",
+    snippet: truncateSnippet(match[0])
+  };
+}
 var compositionRules = [
   // duplicate_composition_id catches meta-tag/root collisions that create duplicate composition entries.
   ({ tags }) => {
@@ -2704,6 +2803,59 @@ var compositionRules = [
       }
     ];
   },
+  // negative_z_index
+  // An element at a negative z-index is silently absent from both `snapshot`
+  // and `render`, while siblings differing only in the sign of z-index render
+  // exactly (heygen-com/hyperframes#4366). lint, validate and render all exit 0
+  // and report nothing, so the first suspicion falls on the author's own CSS.
+  // NOT A RENDERER DEFECT -- ORDINARY CSS PAINTING ORDER, measured at 0.8.72.
+  // The element is PAINTED; it is simply painted beneath something opaque. Remove
+  // every opaque background above it and the same `z-index: -1` band renders at
+  // full coverage, identically to the same band with `z-index` deleted. A negative-z
+  // descendant paints at step 2 of its nearest stacking context -- above that
+  // context root's own background, but below the context's positioned in-flow
+  // content -- so a `position: relative` composition root with an opaque background
+  // paints over it. That is the shape #4366 reports; nothing is dropped and the
+  // renderer has no say in it.
+  //
+  // Kept as a warning because authors hit it and nothing explains why: the element
+  // is in the DOM, laid out, and invisible. The message therefore names the CAUSE
+  // and the remedy rather than implying the tool failed.
+  //
+  // THE CONDITION IS LOAD-BEARING AND THE MESSAGE STATES IT. The element is only
+  // dropped when its nearest ancestor stacking context is the composition root,
+  // which is the shape #4366 reports. Give any ancestor a stacking context and it
+  // renders correctly: measured at 0.8.72 on ONE frame carrying the same
+  // `z-index: -1` band under six triggers -- isolation:isolate, transform,
+  // opacity below 1, filter, contain:paint, will-change -- all six PRESENT at full
+  // coverage, against the no-stacking-context control ABSENT at zero coverage.
+  // That is ordinary CSS painting order: a negative-z child paints above its
+  // stacking context root's own background, so only the root case is hidden.
+  //
+  // This rule matches CSS TEXT and does not resolve the cascade, so it cannot know
+  // whether an ancestor forms a stacking context and fires on both shapes. That is
+  // why the message is CONDITIONAL rather than an assertion of absence: an
+  // unconditional "silently dropped" is false for every isolated case, and a lint
+  // message that overclaims is how authors learn to disregard the rule.
+  ({ tags, styles }) => {
+    const findings = [];
+    for (const style of styles) {
+      const content = stripCssComments(style.content);
+      NEGATIVE_Z_INDEX.lastIndex = 0;
+      let match;
+      while ((match = NEGATIVE_Z_INDEX.exec(content)) !== null) {
+        findings.push(negativeZIndexFinding(match, cssOwnerSelector(content, match.index)));
+      }
+    }
+    for (const tag of tags) {
+      const inline = readAttr(tag.raw, "style");
+      if (!inline) continue;
+      NEGATIVE_Z_INDEX.lastIndex = 0;
+      const match = NEGATIVE_Z_INDEX.exec(inline);
+      if (match) findings.push(negativeZIndexFinding(match, elementSelector(tag)));
+    }
+    return findings;
+  },
   // requestanimationframe_in_composition
   ({ scripts, rawSource, options }) => {
     if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
@@ -3123,6 +3275,96 @@ ${allInlineStyles}`.replace(/\/\*[\s\S]*?\*\//g, "");
         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).`
       }
     ];
+  },
+  // root_zoom_rescales_a_fixed_canvas
+  //
+  // The capture frame is sized from the root's data-width/data-height, which are
+  // LAYOUT pixels. CSS `zoom` on the canvas itself (the root, or html/body above
+  // it) rescales the painted content inside that frame without changing the frame,
+  // so the two disagree and the author gets neither of the two things they might
+  // have meant.
+  //
+  // Measured at 0.8.71 on an 800x400 composition holding two 100x100 boxes at
+  // left:100 and left:600, rendered to a PNG sequence and the boxes located by
+  // colour:
+  //
+  //   root zoom:0.5  canvas stays 800x400; boxes paint at (50,25) and (300,25),
+  //                  each 50x50 -- the composition occupies the top-left quarter
+  //                  and the rest of every frame is dead space.
+  //   root zoom:2    canvas stays 800x400; the left:100 box paints at (200,100)
+  //                  at 200x200, and the left:600 box renders ZERO PIXELS --
+  //                  scaled to x=1200, outside a frame that is still 800 wide.
+  //
+  // The second case is the one worth an error: content that is inside the declared
+  // composition silently does not exist in the output, with nothing else in lint,
+  // check or the render log naming it.
+  //
+  // Deliberately NOT flagged: `zoom` on a descendant. Measured in the same run --
+  // a child at left:100 with zoom:2 paints at (200,100) at 200x200, which is
+  // exactly what CSS `zoom` specifies. It is honoured, not ignored, so a rule that
+  // fired on every `zoom` would be flagging correct authoring.
+  ({ rootTag, tags, styles }) => {
+    if (!rootTag) return [];
+    const rootId = readAttr(rootTag.raw, "id");
+    const rootClasses = (readAttr(rootTag.raw, "class") || "").split(/\s+/).filter(Boolean);
+    const hits = canvasZoomHits(rootTag, tags, styles, rootId, rootClasses);
+    const hit = hits[0];
+    if (!hit) return [];
+    const enlarging = !hit.value.startsWith("-") && parseFloat(hit.value) > (hit.value.includes("%") ? 100 : 1);
+    return [
+      {
+        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.`,
+        snippet: hit.snippet
+      }
+    ];
+  },
+  // composition_exceeds_inspection_viewport_cap
+  //
+  // packages/cli/src/utils/compositionViewport.ts caps a parsed data-width /
+  // data-height at MAX_VIEWPORT_DIMENSION (4096) with a plain Math.min and no
+  // warning. captureCompositionFrame resolves its viewport through that helper,
+  // and check, validate, snapshot, compare and layout all capture through it;
+  // layout and motionShot carry their own independent Math.min(..., 4096).
+  //
+  // `render` does NOT go through it, and that asymmetry is the whole finding.
+  // Measured at 0.8.71 on a 5000x400 composition with 100x100 boxes at left:100
+  // and left:4500:
+  //
+  //   render    -> 5000x400 output, both boxes present.
+  //   snapshot  -> 4096x400 frame, the left:4500 box ABSENT.
+  //
+  // So the video is correct and the tools an author would reach for to check it
+  // silently cannot see the last 904 px. The failure direction is the awkward
+  // one: `check` comes back clean on a region it never rendered, and someone
+  // debugging a missing element through `snapshot` chases a difference that
+  // exists only in the instrument.
+  //
+  // A warning, not an error: the deliverable is fine, and a composition wider
+  // than 4096 can be entirely deliberate.
+  ({ rootTag }) => {
+    if (!rootTag) return [];
+    const over = [];
+    for (const attr of ["data-width", "data-height"]) {
+      const raw = readAttr(rootTag.raw, attr);
+      if (!raw) continue;
+      const value = Number.parseInt(raw, 10);
+      if (Number.isFinite(value) && value > INSPECTION_VIEWPORT_CAP) {
+        over.push(`${attr}=${value}`);
+      }
+    }
+    if (over.length === 0) return [];
+    return [
+      {
+        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.`,
+        snippet: truncateSnippet(rootTag.raw)
+      }
+    ];
   }
 ];
 var CLIP_MEDIA_TAGS = /* @__PURE__ */ new Set(["img", "video", "audio"]);