@hyperframes/inspector 0.8.180 → 0.8.183

package/README.md

@@ -42,7 +42,7 @@ The package ships the capability, not agent tools: a harness defines its own too
 
 ## Output
 
-The default JSON is capped at 12,000 UTF-8 bytes, including metadata. `snippets` contain file, start/end line, kinds, associated input target indices, **unmodified full source lines**, and whether that exact block occurs only once in the file. No pretty-printing or ellipses are inserted into code. Adjacent/overlapping blocks merge across targets.
+The default JSON is capped at 12,000 UTF-8 bytes, including metadata. Each snippet's `id` names its file and its start and end lines (`file:start-end`); a snippet also carries its kinds, **unmodified full source lines**, and whether that exact block occurs only once in the file. When a query names more than one target, `targets` gives the input target indices it serves. No pretty-printing or ellipses are inserted into code. Adjacent/overlapping blocks merge across targets.
 
 ```json
 {
@@ -51,9 +51,6 @@ The default JSON is capped at 12,000 UTF-8 bytes, including metadata. `snippets`
   "snippets": [
     {
       "id": "scene.html:20-24",
-      "file": "scene.html",
-      "startLine": 20,
-      "endLine": 24,
       "kind": ["animation creation"],
       "targets": [0, 1],
       "code": "the exact original source lines, including whitespace",
@@ -65,7 +62,7 @@ The default JSON is capped at 12,000 UTF-8 bytes, including metadata. `snippets`
 
 This illustration omits metadata. Actual files in the implementation report show the full output.
 
-Shared helpers appear once with all **queried** targets using them. `coTargets` names observed additional DOM targets of the same tween; it does not claim to enumerate all separate calls to a helper. Creation statements and authored caller statements are mapped; small named helper functions are returned whole. Variable assignments are not a stack/data-flow history. A missing source origin increments `unmappedAnimations`, rather than guessing an editable location.
+Shared helpers appear once with all **queried** targets using them. `coTargets` names up to three observed additional DOM targets of the same tween, prioritizing elements outside the query, and `coTargetsOmitted` counts the rest; it does not claim to enumerate all separate calls to a helper. Creation statements and authored caller statements are mapped; small named helper functions are returned whole. Variable assignments are not a stack/data-flow history. A missing source origin increments `unmappedAnimations`, rather than guessing an editable location.
 
 HTML snippets are uniquely identified authored opening tags (their full source lines); dynamically generated markup may have no authored tag match. CSS is an authored-selector candidate scan, not proof of active cascade, media-query state, or inherited styles. In particular, a class reused in different scoped scene styles can have multiple candidate source rules.
 

package/dist/inspection.js

@@ -1394,7 +1394,7 @@
     return timeAtSourceTime(playbackRate, Math.max(0, sourceDuration - mediaStart));
   }
 
-  // ../core/src/mediaTiming.ts
+  // ../parsers/src/mediaTiming.ts
   var MEDIA_START_BASIS_ATTR = "data-hf-media-start-basis";
   function readMediaStartBasis(value) {
     return value?.trim().toLowerCase() === "global" ? "global" : "local";

package/dist/live.js

@@ -2,7 +2,7 @@ import { createRequire } from "node:module"; const require = createRequire(impor
 
 // src/live.ts
 import { randomUUID } from "node:crypto";
-import { readFileSync as readFileSync2, realpathSync } from "node:fs";
+import { readFileSync as readFileSync2, realpathSync as realpathSync2 } from "node:fs";
 
 // src/authoredState.ts
 var PLAIN_CLASS = /^[a-zA-Z_-][\w-]*$/;
@@ -459,10 +459,11 @@ function formatElementMap(snapshot, { file = "index.html" } = {}) {
 }
 
 // src/sources.ts
-import { closeSync, fstatSync, openSync, readFileSync, readdirSync } from "node:fs";
-import { extname, join, relative } from "node:path";
+import { closeSync, fstatSync, openSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { extname, join, posix, relative, resolve } from "node:path";
 import { createHash as createHash2 } from "node:crypto";
 import { parse as parse2 } from "acorn";
+import { Parser } from "htmlparser2";
 import postcss from "postcss";
 import { TraceMap, originalPositionFor } from "@jridgewell/trace-mapping";
 
@@ -556,6 +557,14 @@ function occurrences(text, needle) {
   }
   return hits;
 }
+function realPath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+var SHOWN_WHOLE = 2e3;
 var excluded = /* @__PURE__ */ new Set([...PREVIEW_IGNORED_DIRS, ".agents", ".claude", "evidence", "snapshots"]);
 function sourceFiles(project) {
   const files = [];
@@ -649,7 +658,24 @@ function rawTextElements(text, tag) {
   }
   return elements;
 }
+function nesting(text) {
+  const parents = /* @__PURE__ */ new Map();
+  const open = [];
+  const parser = new Parser({
+    onopentag() {
+      parents.set(parser.startIndex, open.at(-1));
+      open.push(parser.startIndex);
+    },
+    onclosetag() {
+      open.pop();
+    }
+  });
+  parser.write(text);
+  parser.end();
+  return parents;
+}
 function htmlTagsOf(file, text) {
+  const parents = nesting(text);
   return [...text.matchAll(/<([a-z][\w-]*)\b[^>]*>/gi)].map((m) => {
     const attr = (name) => {
       const quoted = new RegExp(`\\s${name}\\s*=\\s*["']([^"']*)["']`, "i").exec(m[0]);
@@ -663,7 +689,11 @@ function htmlTagsOf(file, text) {
       tag: m[1].toLowerCase(),
       id: attr("id"),
       hfId: attr("data-hf-id"),
-      classes: (attr("class") ?? "").split(/\s+/).filter(Boolean)
+      classes: (attr("class") ?? "").split(/\s+/).filter(Boolean),
+      compositionId: attr("data-composition-id"),
+      compositionSrc: attr("data-composition-src"),
+      inMarkup: parents.has(m.index),
+      parent: parents.get(m.index)
     };
   });
 }
@@ -680,11 +710,14 @@ function authoredHtml(project) {
   return html;
 }
 var Sources = class {
-  constructor(project) {
+  constructor(project, served) {
     this.project = project;
+    const root = realPath(project);
+    const bundled = served && new Set([...served].map((path) => relative(root, realPath(path))));
     for (const path of sourceFiles(project)) {
       const file = relative(project, path);
       if (/(?:^|\/)(?:vendor|lib)\//.test(file)) continue;
+      if (bundled && !bundled.has(file)) continue;
       const fd = openSync(path, "r");
       let text;
       try {
@@ -767,12 +800,69 @@ var Sources = class {
     };
   }
   markup(element, target) {
+    const tag = this.markupTag(element);
+    return tag ? this.slice(tag.file, tag.start, tag.end, "html opening tag", target) : null;
+  }
+  markupTag(element) {
     const sameTag = this.htmlTags.filter((tag) => tag.tag === element.tag);
     const byHfId = element.hfId ? sameTag.filter((tag) => tag.hfId === element.hfId) : [];
     const tags = byHfId.length ? byHfId : sameTag.filter(
       (tag) => element.id ? tag.id === element.id : element.classes.length > 0 && element.classes.every((c) => tag.classes.includes(c))
     );
-    return tags.length === 1 ? this.slice(tags[0].file, tags[0].start, tags[0].end, "html opening tag", target) : null;
+    return tags.length === 1 ? tags[0] : null;
+  }
+  nestingIndex;
+  get nested() {
+    if (this.nestingIndex) return this.nestingIndex;
+    const tagAt = new Map(this.htmlTags.map((t) => [`${t.file}:${t.start}`, t]));
+    const hostsOf = /* @__PURE__ */ new Map();
+    for (const host of this.htmlTags.filter((t) => t.inMarkup && t.compositionSrc)) {
+      const file = this.mountedFile(host);
+      if (file) hostsOf.set(file, [...hostsOf.get(file) ?? [], host]);
+    }
+    return this.nestingIndex = { tagAt, hostsOf };
+  }
+  fileByPath;
+  mountedFile(host) {
+    const files = this.fileByPath ??= new Map(
+      [...this.files.keys()].map((file) => [file.replace(/\\/g, "/"), file])
+    );
+    const src = (host.compositionSrc ?? "").split(/[?#]/)[0].replace(/\\/g, "/");
+    const path = [
+      posix.normalize(src.replace(/^\.?\//, "")),
+      posix.join(posix.dirname(host.file.replace(/\\/g, "/")), src)
+    ].find((file) => files.has(file));
+    return path === void 0 ? void 0 : files.get(path);
+  }
+  compositions(tag, target) {
+    const { tagAt, hostsOf } = this.nested;
+    const shown2 = /* @__PURE__ */ new Set([tag]);
+    const result = [];
+    const show = (t, kind) => {
+      if (shown2.has(t)) return false;
+      shown2.add(t);
+      const snippet = this.slice(t.file, t.start, t.end, kind, target);
+      if (snippet) result.push(snippet);
+      return true;
+    };
+    const mounted = tag.compositionSrc && this.mountedFile(tag);
+    const root = mounted && this.htmlTags.find(
+      (t) => t.file === mounted && t.inMarkup && t.compositionId && (!tag.compositionId || t.compositionId === tag.compositionId)
+    );
+    if (root) show(root, "composition root");
+    const parentOf = (t) => t.parent === void 0 ? void 0 : tagAt.get(`${t.file}:${t.parent}`);
+    const climb = [{ tag, candidate: false }];
+    for (let from = climb.shift(); from; from = climb.shift()) {
+      for (let at2 = parentOf(from.tag); at2; at2 = parentOf(at2))
+        if (at2.compositionId)
+          show(at2, from.candidate ? "composition root candidate" : "composition root");
+      const hosts = hostsOf.get(from.tag.file) ?? [];
+      const candidate = from.candidate || hosts.length > 1;
+      for (const host of hosts)
+        if (show(host, candidate ? "composition host candidate" : "composition host"))
+          climb.push({ tag: host, candidate });
+    }
+    return result;
   }
   mapper(html, provenance) {
     const htmlLines = starts(html);
@@ -822,17 +912,20 @@ var Sources = class {
         const enclosing = hit.chunk.statements.filter((s) => hit.local >= s.start && hit.local < s.end).sort((a, b) => a.end - a.start - (b.end - b.start))[0];
         if (!enclosing) continue;
         const helper = hit.chunk.statements.filter(
-          (s) => s.type === "FunctionDeclaration" && hit.local >= s.start && hit.local < s.end && s.end - s.start <= 2e3
+          (s) => s.type === "FunctionDeclaration" && hit.local >= s.start && hit.local < s.end && s.end - s.start <= SHOWN_WHOLE
         ).sort((a, b) => a.end - a.start - (b.end - b.start))[0];
-        const range = helper ?? enclosing;
+        const caller = result.length > 0;
+        const callLine = caller && !helper && enclosing.end - enclosing.start > SHOWN_WHOLE;
+        const range = callLine ? { start: hit.local, end: hit.local + 1 } : helper ?? enclosing;
         const snippet = this.slice(
           hit.chunk.file,
           hit.chunk.offset + range.start,
           hit.chunk.offset + range.end,
-          result.length ? "animation caller" : "animation creation",
+          caller ? "animation caller" : "animation creation",
           target
         );
         if (snippet) result.push(snippet);
+        if (callLine) continue;
         for (const dependency of hit.chunk.dependencies(range)) {
           const definition = this.slice(
             hit.chunk.file,
@@ -849,9 +942,6 @@ var Sources = class {
     };
   }
 };
-function markupSnippet(sources, element, target) {
-  return sources.markup(element, target);
-}
 function mergeSnippets(snippets, sources) {
   const sorted = snippets.sort((a, b) => a.file.localeCompare(b.file) || a.startLine - b.startLine);
   const output = [];
@@ -874,16 +964,31 @@ function mergeSnippets(snippets, sources) {
 }
 
 // src/mapInspection.ts
-var coverage = [
-  "GSAP associations observed since page initialization; callback-created animations may require an explicit time query.",
-  "Animation source dependencies include lexically resolved declarations in the same script; later mutations, imports, and cross-script bindings are not traced.",
-  "CSS selector matches are candidates, not a full cascade or dependency graph. HTML is the authored opening tag when uniquely located.",
-  "Direct constructors, other animation systems, iframe contents, removed animations and unexecuted paths may be absent; missing origins are reported."
+var KEPT_FIRST_UNDER_BUDGET = [
+  "animation creation",
+  "animation caller",
+  "timeline attachment",
+  "html opening tag",
+  "animation source dependency",
+  "matched CSS candidate"
 ];
+var rank = (kind) => {
+  const at2 = KEPT_FIRST_UNDER_BUDGET.indexOf(kind);
+  return at2 === -1 ? KEPT_FIRST_UNDER_BUDGET.length : at2;
+};
+var priority = (snippet) => Math.min(...snippet.kind.map(rank));
+var byPosition = (a, b) => a.file.localeCompare(b.file) || a.startLine - b.startLine;
+var CO_TARGETS_SHOWN = 3;
+function shown(snippet, targetCount) {
+  const { id, kind, code, uniqueInFile, targets } = snippet;
+  return targetCount === 1 ? { id, kind, code, uniqueInFile } : { id, kind, targets, code, uniqueInFile };
+}
 function mapInspection(raw, request, context) {
   const { sources, map, catalog, generation, sourceVersion, reused, start, visualState } = context;
   const maxBytes = request.maxBytes ?? 12e3;
   const collected = [];
+  const compositions = [];
+  const queriedRefs = new Set(raw.results.flatMap((result) => result.elements.map((el) => el.ref)));
   const results = raw.results.map((result, index) => {
     let unmappedAnimations = 0;
     for (const animation of result.animations) {
@@ -896,8 +1001,11 @@ function mapInspection(raw, request, context) {
         );
     }
     for (const el of result.elements) {
-      const snippet = markupSnippet(sources, el, index);
+      const tag = sources.markupTag(el);
+      if (!tag) continue;
+      const snippet = sources.slice(tag.file, tag.start, tag.end, "html opening tag", index);
       if (snippet) collected.push(snippet);
+      compositions.push(...sources.compositions(tag, index));
     }
     for (const id of result.css) {
       const rule = sources.cssRules.find((rule2) => rule2.id === id);
@@ -912,30 +1020,35 @@ function mapInspection(raw, request, context) {
         if (snippet) collected.push(snippet);
       }
     }
+    const coTargets = [
+      ...new Map(
+        result.animations.flatMap((animation) => animation.targets).filter((element) => !result.elements.some((own) => own.ref === element.ref)).map((element) => [element.ref, element])
+      ).values()
+    ].sort((a, b) => Number(queriedRefs.has(a.ref)) - Number(queriedRefs.has(b.ref)));
     return {
       target: index,
       status: result.status,
       candidates: result.candidates,
       candidatesOmitted: 0,
       animations: result.animations.length,
-      coTargets: [
-        ...new Map(
-          result.animations.flatMap((animation) => animation.targets).filter((element) => !result.elements.some((own) => own.ref === element.ref)).map((element) => [element.ref, element])
-        ).values()
-      ].slice(0, 10),
+      coTargets: coTargets.slice(0, CO_TARGETS_SHOWN),
+      ...coTargets.length > CO_TARGETS_SHOWN && {
+        coTargetsOmitted: coTargets.length - CO_TARGETS_SHOWN
+      },
       unmappedAnimations,
       scopeTruncated: result.truncated
     };
   });
-  const merged = mergeSnippets(collected, sources);
+  const merged = withCompositionsLast(mergeSnippets(collected, sources), compositions, sources);
   for (const snippet of merged) catalog.set(snippet.id, snippet);
-  let selected = merged;
+  let selected = [...merged].sort((a, b) => priority(a) - priority(b));
   if (request.snippets)
     selected = request.snippets.map((id) => {
       const snippet = catalog.get(id);
       if (!snippet) throw new Error(`unknown_snippet: ${id}`);
       return snippet;
     });
+  const candidateContext = {};
   const response = {
     generation,
     visualState,
@@ -946,7 +1059,7 @@ function mapInspection(raw, request, context) {
     omitted: [],
     omittedCount: 0,
     nextOffset: null,
-    coverage,
+    ...candidateContext,
     recordLimitReached: raw.recordLimitReached,
     hooked: raw.hooked,
     debugAvailable: true,
@@ -967,23 +1080,46 @@ function mapInspection(raw, request, context) {
     }
   };
   trimCandidates(maxBytes / 2, 5);
+  const targetCount = request.targets.length;
+  const kept = [];
   for (let i = offset; i < selected.length; i++) {
-    response.snippets.push(selected[i]);
+    response.snippets.push(shown(selected[i], targetCount));
+    const priorCoverage = response.coverage;
+    if (response.coverage === void 0 && selected[i].kind.some(
+      (kind) => kind.startsWith("composition ") && kind.endsWith(" candidate")
+    ))
+      response.coverage = [
+        "Composition candidates are alternative source mounts and their enclosing roots, not a verified runtime instance chain; all alternatives remain available within the snippet budget and pagination."
+      ];
     if (size() > maxBytes - 700) {
       response.snippets.pop();
+      response.coverage = priorCoverage;
       response.omittedCount = selected.length - i;
       response.omitted = selected.slice(i, i + 8).map((item) => ({ id: item.id, bytes: Buffer.byteLength(item.code) }));
       const nothingFit = response.snippets.length === 0;
       response.nextOffset = nothingFit ? i + 1 < selected.length ? i + 1 : null : i;
       break;
     }
+    kept.push(selected[i]);
   }
+  if (!request.snippets)
+    response.snippets = kept.sort(byPosition).map((snippet) => shown(snippet, targetCount));
   trimCandidates(maxBytes, 0);
   if (Buffer.byteLength(JSON.stringify(response)) > maxBytes)
     throw new Error("metadata_exceeds_budget: use fewer targets or increase maxBytes");
   if (request.debug) return { ...response, debug: raw };
   return response;
 }
+function withCompositionsLast(merged, compositions, sources) {
+  const covered = (s) => merged.some((m) => m.file === s.file && m.startLine <= s.startLine && m.endLine >= s.endLine);
+  return [
+    ...merged,
+    ...mergeSnippets(
+      compositions.filter((s) => !covered(s)),
+      sources
+    )
+  ];
+}
 
 // src/pageQueries.ts
 function queryPage(query) {
@@ -1118,8 +1254,8 @@ var located = (sources) => onePerSourceLine(sources).map((s) => `${s.file}:${s.s
 function describeValue(value) {
   if (value.kind === "unknown") return "?";
   if (value.kind === "expression" && value.value === "custom function") return "custom function";
-  const shown = typeof value.value === "number" ? Number(value.value.toFixed(4)) : value.value;
-  return `${shown}${value.kind === "literal" ? "" : ` (${value.kind})`}`;
+  const shown2 = typeof value.value === "number" ? Number(value.value.toFixed(4)) : value.value;
+  return `${shown2}${value.kind === "literal" ? "" : ` (${value.kind})`}`;
 }
 function describeValues(values) {
   return `    authored: ${values.properties.map((p) => `${p.property}: ${describeValue(p.from)} \u2192 ${describeValue(p.to)}`).join("; ")}; ease: ${describeValue(values.ease)}`;
@@ -1334,8 +1470,8 @@ function assertGeneration(requested, current) {
 
 // src/live.ts
 var runtime = () => readFileSync2(new URL(`./inspection.${"js"}`, import.meta.url), "utf8");
-function prepareLiveInspection(projectDir, html, provenance, sourceVersion) {
-  const project = realpathSync(projectDir);
+function prepareLiveInspection(projectDir, html, provenance, sourceVersion, reads) {
+  const project = realpathSync2(projectDir);
   if (fingerprint2(project) !== sourceVersion) throw new Error("source_changed_during_load");
   if (!/<head\b[^>]*>/i.test(html)) throw new Error("preview_head_missing");
   const generation = randomUUID();
@@ -1353,7 +1489,7 @@ ${runtime()}`.replace(/<\/script/gi, "<\\/script");
     pageGeneration: generation,
     sourceContext() {
       if (!context) {
-        const sources = new Sources(project);
+        const sources = new Sources(project, reads);
         context = { sources, map: sources.mapper(document2, [...provenance]) };
       }
       return context;