@hyperframes/lint 0.8.49 → 0.8.51

package/dist/browser.d.ts

@@ -45,6 +45,8 @@ type HyperframeLinterOptions = {
      * render time — the font will silently fall back to whatever the OS provides.
      */
     distributed?: boolean;
+    /** Who is running the lint: Studio raises the structure rules to errors, the CLI keeps them warnings. */
+    host?: "studio" | "cli";
 };
 
 declare function lintHyperframeHtml(html: string, options?: HyperframeLinterOptions): Promise<HyperframeLintResult>;

package/dist/browser.js

@@ -1538,6 +1538,7 @@ function findRuntimeMediaSrcMutationFindings(ctx) {
 }
 var mediaRules = [
   findNestedMediaStartBasisFindings,
+  findSpeedRampOnNonMediaFindings,
   // duplicate_media_id + duplicate_media_discovery_risk
   ({ tags }) => {
     const findings = [];
@@ -1959,6 +1960,18 @@ function findVolumeDoubleAutomationFindings(ctx) {
   }
   return findings;
 }
+function findSpeedRampOnNonMediaFindings(ctx) {
+  return ctx.tags.filter((tag) => tag.name !== "video" && tag.name !== "audio").filter(
+    (tag) => /"target"\s*:\s*"rate"/.test(readDecodedAttr(tag.raw, "data-automation") ?? "")
+  ).map((tag) => ({
+    code: "speed_ramp_on_non_media",
+    severity: "warning",
+    message: `<${tag.name}> has a speed-ramp lane, but only <video> and <audio> clips can be retimed. The lane does nothing here.`,
+    elementId: readAttr(tag.raw, "id") || void 0,
+    fixHint: "Move the rate lane onto the <video> or <audio> clip, or retime an animation with a GSAP timeline instead.",
+    snippet: truncateSnippet(tag.raw)
+  }));
+}
 function findCarveUngroupedSourcesFindings(ctx) {
   const groupIds = new Set(
     ctx.tags.filter((tag) => tag.name === "hf-audio-group").map((tag) => readAttr(tag.raw, "id"))
@@ -2065,6 +2078,11 @@ function findAudioGroupCarveAttrFindings(ctx) {
 // src/rules/composition.ts
 import { COMPOSITION_VARIABLE_TYPES, isSafeMediaUrl } from "@hyperframes/parsers/composition";
 import { COMPOSITION_ATTRIBUTES, readClipTiming } from "@hyperframes/parsers/composition-contract";
+import { resolveCompositionDuration } from "@hyperframes/parsers/composition-duration";
+import {
+  readAuthoredDurationSeconds,
+  resolveMediaDuration
+} from "@hyperframes/parsers/media-duration";
 var MAX_COMPOSITION_LINES = 300;
 var MAX_TIMED_ELEMENTS_PER_TRACK = 3;
 var TRACK_DENSITY_EXEMPT_TAGS = /* @__PURE__ */ new Set(["audio", "script", "style", "video"]);
@@ -2840,6 +2858,18 @@ ${allInlineStyles}`.replace(/\/\*[\s\S]*?\*\//g, "");
     const hasInfiniteCssAnimation = /\banimation(?:-iteration-count)?\s*:[^;{}]*(?<![\w-])infinite(?![\w-])/.test(combinedCss);
     const hasAnyNonGsapSignal = usesLottie || usesThree || usesWaapi || hasCssAnimationName;
     if (!hasAnyNonGsapSignal) {
+      const derived = deriveDurationFromClips(tags, rootTag);
+      if (derived.source === "derived") {
+        return [
+          {
+            code: "root_composition_duration_derived",
+            severity: "warning",
+            message: `Root composition has no data-duration and no GSAP timeline, so its length is taken from its clips: at least ${derived.seconds}s` + (derived.pendingClips > 0 ? `, and ${derived.pendingClips} clip(s) whose length is only known at runtime` : "") + ".",
+            fixHint: 'Add data-duration="<seconds>" to the root element to set the length yourself.',
+            snippet: truncateSnippet(rootTag.raw)
+          }
+        ];
+      }
       return [
         {
           code: "root_composition_missing_duration_source",
@@ -2924,6 +2954,35 @@ ${allInlineStyles}`.replace(/\/\*[\s\S]*?\*\//g, "");
     ];
   }
 ];
+var CLIP_MEDIA_TAGS = /* @__PURE__ */ new Set(["img", "video", "audio"]);
+function deriveDurationFromClips(tags, rootTag) {
+  const clipEnds = [];
+  for (const tag of tags) {
+    if (tag === rootTag) continue;
+    const startRaw = readAttr(tag.raw, "data-start");
+    if (startRaw === null) continue;
+    const start = Number(startRaw);
+    if (!Number.isFinite(start)) {
+      clipEnds.push(null);
+      continue;
+    }
+    const getAttr = (name) => readAttr(tag.raw, name);
+    const authored = readAuthoredDurationSeconds(getAttr, start);
+    if (CLIP_MEDIA_TAGS.has(tag.name)) {
+      const { seconds } = resolveMediaDuration({
+        tag: tag.name,
+        authoredDurationSeconds: authored,
+        sourceDurationSeconds: null,
+        mediaStartSeconds: 0,
+        playbackRate: 1
+      });
+      clipEnds.push(seconds === null ? null : start + seconds);
+    } else if (authored !== null && authored > 0) {
+      clipEnds.push(start + authored);
+    }
+  }
+  return resolveCompositionDuration({ authoredDurationSeconds: null, clipEndsSeconds: clipEnds });
+}
 
 // src/rules/gsap.ts
 async function loadParseGsapScript() {
@@ -5319,6 +5378,155 @@ var slideshowRules = [
   }
 ];
 
+// src/rules/structure.ts
+import {
+  isSubCompositionHost,
+  topLevelElements,
+  trackKindOf
+} from "@hyperframes/parsers/top-level-elements";
+var INLINE_TEXT_TAGS = /* @__PURE__ */ new Set([
+  "br",
+  "wbr",
+  "b",
+  "i",
+  "u",
+  "s",
+  "em",
+  "strong",
+  "small",
+  "sub",
+  "sup",
+  "mark",
+  "span",
+  "a",
+  "code",
+  "abbr"
+]);
+var OPAQUE_TAGS = /* @__PURE__ */ new Set([
+  "svg",
+  "canvas",
+  "picture",
+  "video",
+  "audio",
+  "select",
+  "textarea",
+  "iframe",
+  "object"
+]);
+var NON_LAYOUT_TAGS = /* @__PURE__ */ new Set(["style", "script", "template", "noscript"]);
+var MEDIA_TAGS = /* @__PURE__ */ new Set(["video", "audio", "img"]);
+var NODE_ATTRS = [
+  "id",
+  "class",
+  "data-start",
+  "data-duration",
+  "data-end",
+  "data-track",
+  "data-track-index",
+  "data-track-kind",
+  "data-composition-id",
+  "data-composition-src"
+];
+function toNode(open) {
+  const attrs = {};
+  for (const name of NODE_ATTRS) attrs[name] = readDecodedAttr(open.raw, name) ?? void 0;
+  return { tag: open.name, attrs, children: [], open };
+}
+function enclosing(stack, root, index) {
+  let top = stack.at(-1);
+  while (top && stack.length > 1 && index >= top.end) {
+    stack.pop();
+    top = stack.at(-1);
+  }
+  return top?.node ?? root;
+}
+function buildTree(ctx) {
+  const { rootTag } = ctx;
+  const rootEnd = rootTag?.closeIndex;
+  if (!rootTag || rootEnd == null) return null;
+  const root = toNode(rootTag);
+  const stack = [{ node: root, end: rootEnd }];
+  for (const tag of ctx.tags.filter((t) => t.index > rootTag.index && t.index < rootEnd)) {
+    const node = toNode(tag);
+    enclosing(stack, root, tag.index).children.push(node);
+    if (tag.closeIndex != null) stack.push({ node, end: tag.closeIndex });
+  }
+  return root;
+}
+function hasNestedStructure(node) {
+  if (OPAQUE_TAGS.has(node.tag)) return null;
+  for (const child of node.children) {
+    if (NON_LAYOUT_TAGS.has(child.tag)) continue;
+    if (!INLINE_TEXT_TAGS.has(child.tag)) return child;
+    const deeper = hasNestedStructure(child);
+    if (deeper) return deeper;
+  }
+  return null;
+}
+var describe = (node) => `<${node.tag}${node.attrs.id ? ` id="${node.attrs.id}"` : ""}>`;
+function nestedStructureFindings(rows, severity) {
+  return rows.flatMap((row) => {
+    const nested = isSubCompositionHost(row) ? null : hasNestedStructure(row);
+    if (!nested) return [];
+    return [
+      {
+        code: "nested_structure_needs_subcomposition",
+        severity,
+        message: `${describe(row)} is a timeline element that contains nested ${describe(nested)}. The timeline shows one row per top-level element, and the root composition is built only from sub-compositions.`,
+        elementId: row.attrs.id,
+        fixHint: `Move ${describe(row)} and its contents into a sub-composition file and mount it with data-composition-src.`
+      }
+    ];
+  });
+}
+function missingDurationFindings(rows, severity) {
+  return rows.filter(
+    (row) => !MEDIA_TAGS.has(row.tag) && row.attrs["data-duration"] === void 0 && row.attrs["data-end"] === void 0 && !isSubCompositionHost(row)
+  ).map((row) => ({
+    code: "timeline_element_missing_timing",
+    severity,
+    message: `${describe(row)} is a timeline element without data-duration, so the timeline cannot draw where it ends.`,
+    elementId: row.attrs.id,
+    fixHint: `Add data-duration (in seconds) to ${describe(row)}.`
+  }));
+}
+function captionFindings(rows, severity) {
+  const captionRows = rows.filter((row) => trackKindOf(row).kind === "captions");
+  const findings = captionRows.filter((row) => trackKindOf(row).source === "legacy-captions").map((row) => ({
+    code: "caption_track_kind_missing",
+    severity,
+    message: `${describe(row)} looks like captions but is not marked as such, so the timeline cannot group it on the caption track.`,
+    elementId: row.attrs.id,
+    fixHint: `Add data-track-kind="captions" to ${describe(row)}.`
+  }));
+  const lanes = new Set(
+    captionRows.flatMap((row) => row.attrs["data-track-index"] ?? row.attrs["data-track"] ?? [])
+  );
+  if (lanes.size > 1) {
+    findings.push({
+      code: "multiple_caption_tracks",
+      severity,
+      message: `Captions are spread across ${lanes.size} timeline tracks. Keep all captions on one track.`,
+      fixHint: "Give every caption element the same data-track-index."
+    });
+  }
+  return findings;
+}
+var structureRules = [
+  (ctx) => {
+    if (ctx.options.isSubComposition) return [];
+    const root = buildTree(ctx);
+    if (!root) return [];
+    const severity = ctx.options.host === "studio" ? "error" : "warning";
+    const rows = topLevelElements(root);
+    return [
+      ...nestedStructureFindings(rows, severity),
+      ...missingDurationFindings(rows, severity),
+      ...captionFindings(rows, severity)
+    ];
+  }
+];
+
 // src/hyperframeLinter.ts
 var RULE_GROUPS = [
   { group: "core", rules: coreRules },
@@ -5329,7 +5537,8 @@ var RULE_GROUPS = [
   { group: "adapters", rules: adapterRules },
   { group: "textures", rules: textureRules },
   { group: "fonts", rules: fontRules },
-  { group: "slideshow", rules: slideshowRules }
+  { group: "slideshow", rules: slideshowRules },
+  { group: "structure", rules: structureRules }
 ];
 var LINT_RULE_COUNT = RULE_GROUPS.reduce((n, g) => n + g.rules.length, 0);
 var LINT_RULE_GROUP_COUNTS = Object.fromEntries(