@hyperframes/lint 0.7.58 → 0.7.59

package/dist/index.js

@@ -57,7 +57,7 @@ function findHtmlTag(tags) {
 function findRootTag(source, parsedTags) {
   const tags = parsedTags ?? parseHtmlStructure(source).tags;
   const bodyTag = tags.find((tag) => tag.name === "body");
-  if (bodyTag && (readAttr(bodyTag.raw, "data-composition-id") || readAttr(bodyTag.raw, "data-width") || readAttr(bodyTag.raw, "data-height"))) {
+  if (bodyTag && (readDecodedAttr(bodyTag.raw, "data-composition-id") || readAttr(bodyTag.raw, "data-width") || readAttr(bodyTag.raw, "data-height"))) {
     return bodyTag;
   }
   const bodyStart = bodyTag ? bodyTag.index + bodyTag.raw.length : 0;
@@ -67,7 +67,7 @@ function findRootTag(source, parsedTags) {
   for (const tag of bodyTags) {
     if (tag.index < skipBefore) continue;
     if (["script", "style", "meta", "link", "title"].includes(tag.name)) continue;
-    if (tag.name === "svg" && !readAttr(tag.raw, "data-composition-id") && !readAttr(tag.raw, "data-width") && !readAttr(tag.raw, "data-height")) {
+    if (tag.name === "svg" && !readDecodedAttr(tag.raw, "data-composition-id") && !readAttr(tag.raw, "data-width") && !readAttr(tag.raw, "data-height")) {
       skipBefore = tag.endIndex ?? Infinity;
       continue;
     }
@@ -81,6 +81,20 @@ function readAttr(tagSource, attr) {
   const match = tagSource.match(new RegExp(`(?<![\\w-])${escaped}\\s*=\\s*["']([^"']+)["']`, "i"));
   return match?.[1] || null;
 }
+function readDecodedAttr(tagSource, attr) {
+  if (!tagSource) return null;
+  let value = null;
+  const parser = new Parser(
+    {
+      onattribute(name, decodedValue) {
+        if (value === null && name.toLowerCase() === attr.toLowerCase()) value = decodedValue;
+      }
+    },
+    { decodeEntities: true, lowerCaseAttributeNames: false, lowerCaseTags: true }
+  );
+  parser.end(tagSource);
+  return value;
+}
 function readJsonAttr(tagSource, attr) {
   if (!tagSource) return null;
   const escaped = attr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -93,7 +107,7 @@ function readJsonAttr(tagSource, attr) {
 function collectCompositionIds(tags) {
   const ids = /* @__PURE__ */ new Set();
   for (const tag of tags) {
-    const compId = readAttr(tag.raw, "data-composition-id");
+    const compId = readDecodedAttr(tag.raw, "data-composition-id");
     if (compId) ids.add(compId);
   }
   return ids;
@@ -270,7 +284,7 @@ function buildLintContext(html, options = {}) {
   const scripts = structure.scripts;
   const compositionIds = collectCompositionIds(tags);
   const rootTag = findRootTag(source, tags);
-  const rootCompositionId = readAttr(rootTag?.raw || "", "data-composition-id");
+  const rootCompositionId = readDecodedAttr(rootTag?.raw || "", "data-composition-id");
   return {
     source,
     rawSource,
@@ -306,7 +320,7 @@ function isStudioTimelineElement(tag) {
 function describeStudioElement(tag) {
   const parts = [`<${tag.name}`];
   const className = readAttr(tag.raw, "class");
-  const compositionId = readAttr(tag.raw, "data-composition-id");
+  const compositionId = readDecodedAttr(tag.raw, "data-composition-id");
   const dataStart = readAttr(tag.raw, "data-start");
   const dataTrack = readAttr(tag.raw, "data-track-index") ?? readAttr(tag.raw, "data-track");
   if (className) {
@@ -428,7 +442,7 @@ var coreRules = [
   // root_missing_composition_id + root_missing_dimensions
   ({ rootTag }) => {
     const findings = [];
-    if (!rootTag || !readAttr(rootTag.raw, "data-composition-id")) {
+    if (!rootTag || !readDecodedAttr(rootTag.raw, "data-composition-id")) {
       findings.push({
         code: "root_missing_composition_id",
         severity: "error",
@@ -504,15 +518,10 @@ var coreRules = [
     return findings;
   },
   // timeline_id_mismatch
-  ({ source }) => {
+  ({ source, compositionIds }) => {
     const findings = [];
-    const htmlCompIds = /* @__PURE__ */ new Set();
+    const htmlCompIds = new Set(compositionIds);
     const timelineRegKeys = /* @__PURE__ */ new Set();
-    const compIdRe = /data-composition-id\s*=\s*["']([^"']+)["']/gi;
-    let m;
-    while ((m = compIdRe.exec(source)) !== null) {
-      if (m[1]) htmlCompIds.add(m[1]);
-    }
     for (const key of extractTimelineRegistryKeys(source)) {
       timelineRegKeys.add(key);
     }
@@ -567,7 +576,7 @@ var coreRules = [
     for (const tag of tags) {
       const src = readAttr(tag.raw, "data-composition-src");
       if (!src) continue;
-      if (readAttr(tag.raw, "data-composition-id")) continue;
+      if (readDecodedAttr(tag.raw, "data-composition-id")) continue;
       findings.push({
         code: "host_missing_composition_id",
         severity: "error",
@@ -642,7 +651,7 @@ var coreRules = [
         code: "studio_missing_editable_id",
         severity: "warning",
         message: `${descriptor} has no id, so Studio cannot use a stable edit target for its timeline and canvas controls.`,
-        selector: readAttr(tag.raw, "data-composition-id") ? `[data-composition-id="${readAttr(tag.raw, "data-composition-id")}"]` : void 0,
+        selector: readDecodedAttr(tag.raw, "data-composition-id") ? `[data-composition-id="${readDecodedAttr(tag.raw, "data-composition-id")}"]` : void 0,
         fixHint: 'Add a stable, human-readable id such as id="hero-title" or id="scene-1-card" to every timeline-visible element you want agents or Studio to edit.',
         snippet: truncateSnippet(tag.raw)
       });
@@ -1001,7 +1010,7 @@ var mediaRules = [
     for (const tag of tags) {
       if (tag.name === "video" || tag.name === "audio") continue;
       if (voidElements.has(tag.name)) continue;
-      if (readAttr(tag.raw, "data-composition-id")) continue;
+      if (readDecodedAttr(tag.raw, "data-composition-id")) continue;
       if (readAttr(tag.raw, "data-start")) {
         timedTagPositions.push({
           name: tag.name,
@@ -1247,6 +1256,10 @@ async function loadParseGsapScript() {
 }
 var SCENE_BOUNDARY_EPSILON_SECONDS = 0.05;
 var UNRESOLVED_TARGET = "__unresolved__";
+function targetHasNoStableIdentity(selector, identity) {
+  if (identity) return false;
+  return selector === UNRESOLVED_TARGET || selector === "dwell/hold" || selector.startsWith("proxy \u2192 ");
+}
 function countClassUsage(tags) {
   const counts = /* @__PURE__ */ new Map();
   for (const tag of tags) {
@@ -1304,6 +1317,7 @@ async function extractGsapWindows(script) {
     const effectiveDuration = animation.method === "set" ? 0 : (animation.duration ?? 0) * cycleCount;
     windows.push({
       targetSelector: animation.targetSelector,
+      targetIdentity: animation.targetIdentity,
       position: animation.position,
       end: animation.position + effectiveDuration,
       properties: Object.keys(animation.properties),
@@ -1395,7 +1409,7 @@ function findTagEnd(source, tag) {
 }
 function collectCompositionRanges(source, tags) {
   return tags.map((tag) => {
-    const id = readAttr(tag.raw, "data-composition-id");
+    const id = readDecodedAttr(tag.raw, "data-composition-id");
     if (!id) return null;
     return {
       id,
@@ -1628,12 +1642,14 @@ var gsapRules = [
         const left = gsapWindows[i];
         if (!left) continue;
         if (left.end <= left.position) continue;
-        if (left.targetSelector === UNRESOLVED_TARGET) continue;
+        if (targetHasNoStableIdentity(left.targetSelector, left.targetIdentity)) continue;
         for (let j = i + 1; j < gsapWindows.length; j++) {
           const right = gsapWindows[j];
           if (!right) continue;
           if (right.end <= right.position) continue;
-          if (left.targetSelector !== right.targetSelector) continue;
+          const leftIdentity = left.targetIdentity ?? left.targetSelector;
+          const rightIdentity = right.targetIdentity ?? right.targetSelector;
+          if (leftIdentity !== rightIdentity) continue;
           const overlapStart = Math.max(left.position, right.position);
           const overlapEnd = Math.min(left.end, right.end);
           if (overlapEnd <= overlapStart) continue;
@@ -2404,6 +2420,7 @@ import { COMPOSITION_VARIABLE_TYPES } from "@hyperframes/parsers/composition";
 var MAX_COMPOSITION_LINES = 300;
 var MAX_TIMED_ELEMENTS_PER_TRACK = 3;
 var TRACK_DENSITY_EXEMPT_TAGS = /* @__PURE__ */ new Set(["audio", "script", "style", "video"]);
+var CAPTION_CUE_TOKEN = /^(?:caption(?:[-_](?:group|word|line|block|cue|text))?|subtitle(?:[-_](?:group|line|cue|text))?|cg-.+)$/i;
 var OVERLAP_EPSILON_SECONDS = 1e-6;
 function countPhysicalLines(source) {
   if (source.length === 0) return 0;
@@ -2414,6 +2431,11 @@ function countPhysicalLines(source) {
 function countStructuralLines(source) {
   return countPhysicalLines(source.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "<style></style>"));
 }
+function isCaptionCue(tag) {
+  const classTokens = (readAttr(tag.raw, "class") || "").split(/\s+/).filter(Boolean);
+  const id = readAttr(tag.raw, "id");
+  return classTokens.some((token) => CAPTION_CUE_TOKEN.test(token)) || Boolean(id && CAPTION_CUE_TOKEN.test(id));
+}
 function isRegistrySourceFile(filePath) {
   if (!filePath) return false;
   const normalized = filePath.replace(/\\/g, "/");
@@ -2424,7 +2446,7 @@ function isRegistryInstalledFile(rawSource) {
 }
 function isCompositionRootOrMount(rawTag) {
   return Boolean(
-    readAttr(rawTag, "data-composition-id") || readAttr(rawTag, "data-composition-src")
+    readDecodedAttr(rawTag, "data-composition-id") || readAttr(rawTag, "data-composition-src")
   );
 }
 function extractCssUrlReferences(css) {
@@ -2500,7 +2522,36 @@ function declaredIdsForBindingCheck(tags) {
   if (declared.size === 0 && !findHtmlTag(tags)) return null;
   return declared;
 }
+function isInsideInertTemplate(tag, tags) {
+  return tags.some(
+    (candidate) => candidate.name === "template" && candidate.closeIndex != null && tag.index > candidate.index && tag.index < candidate.closeIndex
+  );
+}
 var compositionRules = [
+  // duplicate_composition_id catches meta-tag/root collisions that create duplicate composition entries.
+  ({ tags }) => {
+    const tagsByCompositionId = /* @__PURE__ */ new Map();
+    for (const tag of tags) {
+      if (isInsideInertTemplate(tag, tags)) continue;
+      const compositionId = readDecodedAttr(tag.raw, "data-composition-id");
+      if (!compositionId || compositionId.trim().length === 0) continue;
+      const matchingTags = tagsByCompositionId.get(compositionId) ?? [];
+      matchingTags.push(tag.raw);
+      tagsByCompositionId.set(compositionId, matchingTags);
+    }
+    const findings = [];
+    for (const [compositionId, matchingTags] of tagsByCompositionId) {
+      if (matchingTags.length < 2) continue;
+      findings.push({
+        code: "duplicate_composition_id",
+        severity: "error",
+        message: `Composition id "${compositionId}" is used by ${matchingTags.length} elements. Each data-composition-id value must be unique within a composition file.`,
+        fixHint: "Keep data-composition-id on exactly one element, the composition root. Remove it from metadata or duplicate hosts, especially a <meta> tag carrying the same data-composition-id as the root <div>, which causes a silent duplicate-id collision.",
+        snippet: truncateSnippet(matchingTags[0] ?? "")
+      });
+    }
+    return findings;
+  },
   // invalid_parent_traversal_in_asset_path — catches `../` traversal in src,
   // href, inline-style url(), and <style> url() asset references on
   // compositions. Sub-compositions live under compositions/ but are served
@@ -2575,6 +2626,7 @@ var compositionRules = [
     const trackCounts = /* @__PURE__ */ new Map();
     for (const tag of tags) {
       if (TRACK_DENSITY_EXEMPT_TAGS.has(tag.name)) continue;
+      if (isCaptionCue(tag)) continue;
       if (isCompositionRootOrMount(tag.raw)) continue;
       if (!readAttr(tag.raw, "data-start")) continue;
       const track = readAttr(tag.raw, "data-track-index");
@@ -2601,7 +2653,7 @@ var compositionRules = [
     for (const tag of tags) {
       if (tag.name === "audio" || tag.name === "script" || tag.name === "style") continue;
       if (!readAttr(tag.raw, "data-start")) continue;
-      if (readAttr(tag.raw, "data-composition-id")) continue;
+      if (readDecodedAttr(tag.raw, "data-composition-id")) continue;
       if (readAttr(tag.raw, "data-composition-src")) continue;
       const classAttr = readAttr(tag.raw, "class") || "";
       const styleAttr = readAttr(tag.raw, "style") || "";
@@ -2701,7 +2753,7 @@ var compositionRules = [
     const skipTags = /* @__PURE__ */ new Set(["audio", "video", "script", "style", "template"]);
     for (const tag of tags) {
       if (skipTags.has(tag.name)) continue;
-      if (readAttr(tag.raw, "data-composition-id")) continue;
+      if (readDecodedAttr(tag.raw, "data-composition-id")) continue;
       if (readAttr(tag.raw, "data-composition-src")) continue;
       const hasStart = readAttr(tag.raw, "data-start") !== null;
       const hasDuration = readAttr(tag.raw, "data-duration") !== null;
@@ -2767,7 +2819,7 @@ var compositionRules = [
     const findings = [];
     if (options.isSubComposition) return findings;
     if (!rootTag) return findings;
-    const compId = readAttr(rootTag.raw, "data-composition-id");
+    const compId = readDecodedAttr(rootTag.raw, "data-composition-id");
     if (!compId) return findings;
     const hasStart = readAttr(rootTag.raw, "data-start") !== null;
     if (!hasStart) {
@@ -3125,7 +3177,7 @@ var compositionRules = [
   ({ rootTag, scripts, styles, tags, options }) => {
     if (options.isSubComposition) return [];
     if (!rootTag) return [];
-    if (readAttr(rootTag.raw, "data-composition-id") === null) return [];
+    if (readDecodedAttr(rootTag.raw, "data-composition-id") === null) return [];
     if (readAttr(rootTag.raw, "data-duration") !== null) return [];
     const allScriptTexts = scripts.map((s) => stripJsComments(s.content));
     const hasGsapTimeline = allScriptTexts.some((t) => /gsap\.timeline\s*\(/.test(t));
@@ -3606,7 +3658,7 @@ function parseTiming(raw) {
 }
 function collectCompositionIdScenes(ctx, seen, out) {
   for (const tag of ctx.tags) {
-    const compositionId = readAttr(tag.raw, "data-composition-id");
+    const compositionId = readDecodedAttr(tag.raw, "data-composition-id");
     if (!compositionId || !isSceneLikeCompositionId(compositionId) || seen.has(compositionId))
       continue;
     const timing = parseTiming(tag.raw);
@@ -3906,8 +3958,10 @@ async function lintProject(projectDir, entryFile) {
       const out = [];
       for (const entry of readdirSync(dir, { withFileTypes: true })) {
         const relPath = rel ? `${rel}/${entry.name}` : entry.name;
-        if (entry.isDirectory()) out.push(...collectHtmlFiles(join(dir, entry.name), relPath));
-        else if (entry.isFile() && entry.name.endsWith(".html") && !entry.name.startsWith("._")) {
+        if (entry.isDirectory()) {
+          if (!rel && entry.name === "components") continue;
+          out.push(...collectHtmlFiles(join(dir, entry.name), relPath));
+        } else if (entry.isFile() && entry.name.endsWith(".html") && !entry.name.startsWith("._")) {
           out.push(relPath);
         }
       }