Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(inspector): a component report names a snippet's file and lines only in its id (#6016)
Xuanru Li1d422a2fa5b4
diff --git a/packages/inspector/README.md b/packages/inspector/README.mdindex d11af9a216..a1e24b0a42 100644--- a/packages/inspector/README.md+++ b/packages/inspector/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.diff --git a/packages/inspector/src/mapInspection.ts b/packages/inspector/src/mapInspection.tsindex 07101e69b3..b57cb7128f 100644--- a/packages/inspector/src/mapInspection.ts+++ b/packages/inspector/src/mapInspection.ts@@ -1,11 +1,5 @@import { Sources, markupSnippet, mergeSnippets } from "./sources";import type { InspectRequest, RuntimeResponse, Snippet } from "./types";-const 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.",-];const KEPT_FIRST_UNDER_BUDGET = ["animation creation","animation caller",@@ -21,6 +15,14 @@ const rank = (kind: string) => {const priority = (snippet: Snippet) => Math.min(...snippet.kind.map(rank));const byPosition = (a: Snippet, b: Snippet) =>a.file.localeCompare(b.file) || a.startLine - b.startLine;+const CO_TARGETS_SHOWN = 3;++function shown(snippet: Snippet, targetCount: number) {+ const { id, kind, code, uniqueInFile, targets } = snippet;+ return targetCount === 1+ ? { id, kind, code, uniqueInFile }+ : { id, kind, targets, code, uniqueInFile };+}export function mapInspection(raw: RuntimeResponse,@@ -39,6 +41,7 @@ export function mapInspection(const { sources, map, catalog, generation, sourceVersion, reused, start, visualState } = context;const maxBytes = request.maxBytes ?? 12000;const collected: Snippet[] = [];+ 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) {@@ -67,20 +70,24 @@ export function mapInspection(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,};@@ -100,11 +107,10 @@ export function mapInspection(sourceVersion: sourceVersion,reused,results,- snippets: [] as Snippet[],+ snippets: [] as ReturnType<typeof shown>[],omitted: [] as { id: string; bytes: number }[],omittedCount: 0,nextOffset: null as number | null,- coverage,recordLimitReached: raw.recordLimitReached,hooked: raw.hooked,debugAvailable: true,@@ -125,8 +131,10 @@ export function mapInspection(}};trimCandidates(maxBytes / 2, 5);+ const targetCount = request.targets.length;+ const kept: Snippet[] = [];for (let i = offset; i < selected.length; i++) {- response.snippets.push(selected[i]);+ response.snippets.push(shown(selected[i], targetCount));if (size() > maxBytes - 700) {response.snippets.pop();response.omittedCount = selected.length - i;@@ -137,8 +145,10 @@ export function mapInspection(response.nextOffset = nothingFit ? (i + 1 < selected.length ? i + 1 : null) : i;break;}+ kept.push(selected[i]);}- if (!request.snippets) response.snippets.sort(byPosition);+ 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");diff --git a/packages/inspector/tests/browser.ts b/packages/inspector/tests/browser.tsindex b596697df1..f7a0196bb1 100644--- a/packages/inspector/tests/browser.ts+++ b/packages/inspector/tests/browser.ts@@ -1,4 +1,5 @@-import { mkdtempSync, mkdirSync, copyFileSync, writeFileSync, readFileSync, rmSync } from "node:fs";+import { snippetSource } from "./snippetSource";+import { mkdtempSync, mkdirSync, copyFileSync, writeFileSync, rmSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";import assert from "node:assert/strict";@@ -39,18 +40,10 @@ try {assert(cold.snippets.some((s) => s.code.includes("function move") || s.code.includes("tl.to(element")),);- assert(cold.snippets.some((s) => s.targets.length === 2 && s.code.includes("tl.to(element")));+ assert(cold.snippets.some((s) => s.targets?.length === 2 && s.code.includes("tl.to(element")));checks.push("multi-target source deduplication");- for (const snippet of cold.snippets) {- const text = readFileSync(join(project, snippet.file), "utf8");- assert.equal(- snippet.code,- text- .split(/(?<=\n)/)- .slice(snippet.startLine - 1, snippet.endLine)- .join(""),- );- }+ for (const snippet of cold.snippets)+ assert.equal(snippet.code, snippetSource(project, snippet.id));checks.push("literal snippets equal original bytes");const single = await inspector.inspect({ targets: [{ selector: "#title" }] });const ambiguity = await inspector.inspect({@@ -65,7 +58,9 @@ try {["found", "missing", "found"],);assert.equal(ambiguity.results[0].candidates.length, 2);- assert(ambiguity.snippets.some((s) => s.targets.includes(0) && s.code.includes("tl.to(element")));+ assert(+ ambiguity.snippets.some((s) => s.targets?.includes(0) && s.code.includes("tl.to(element")),+ );const overlapping = await inspector.inspect({ targets: [{ selector: "#scene-a, #title" }] });assert.equal(overlapping.results[0].animations, single.results[0].animations);checks.push("class groups, overlapping scopes, partial success and optional within");diff --git a/packages/inspector/tests/film.ts b/packages/inspector/tests/film.tsindex 56ade76fd6..98d2633c32 100644--- a/packages/inspector/tests/film.ts+++ b/packages/inspector/tests/film.ts@@ -1,3 +1,4 @@+import { snippetSource } from "./snippetSource";import { Inspector } from "../src/service";import { cpSync, mkdtempSync, readFileSync, writeFileSync, rmSync } from "node:fs";import { join } from "node:path";@@ -57,16 +58,8 @@ try {notes.afterState = await state();assert.equal(inspector.stats.browserStarts, 1);assert.equal(inspector.stats.pageLoads, 2);- for (const snippet of after.snippets) {- const text = readFileSync(join(project, snippet.file), "utf8");- assert.equal(- snippet.code,- text- .split(/(?<=\n)/)- .slice(snippet.startLine - 1, snippet.endLine)- .join(""),- );- }+ for (const snippet of after.snippets)+ assert.equal(snippet.code, snippetSource(project, snippet.id));const afterState = notes.afterState as typeof before;assert.deepEqual(afterState.timelines, before.timelines);const parity = [];diff --git a/packages/inspector/tests/live.ts b/packages/inspector/tests/live.tsindex 72c3c8c5ca..c622905d29 100644--- a/packages/inspector/tests/live.ts+++ b/packages/inspector/tests/live.ts@@ -1,3 +1,4 @@+import { snippetSource } from "./snippetSource";import assert from "node:assert/strict";import { mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";import { tmpdir } from "node:os";@@ -89,17 +90,10 @@ try {assert.equal(result.results[0]!.unmappedAnimations, 0);assert(result.snippets.some(- (s) => s.code.includes("function move") && s.targets.includes(0) && s.targets.includes(1),+ (s) => s.code.includes("function move") && s.targets?.includes(0) && s.targets.includes(1),),);- for (const s of result.snippets)- assert.equal(- s.code,- readFileSync(join(dir, s.file), "utf8")- .split(/(?<=\n)/)- .slice(s.startLine - 1, s.endLine)- .join(""),- );+ for (const s of result.snippets) assert.equal(s.code, snippetSource(dir, s.id));const timeline = await live.timeline(runner, { at: 2, component: { selector: "#title" } });assert.equal(timeline.status, "found");assert(timeline.text.includes("index.html:"), "timeline maps its animations to source lines");diff --git a/packages/inspector/tests/mapInspection.test.ts b/packages/inspector/tests/mapInspection.test.tsindex a9e4e12069..1526fb40c8 100644--- a/packages/inspector/tests/mapInspection.test.ts+++ b/packages/inspector/tests/mapInspection.test.ts@@ -184,7 +184,7 @@ describe("components report priority", () => {it("returns the snippets it keeps in file order", () => {const { report } = withAnimation({ targets: [{ selector: ".w-dot" }], maxBytes: 256000 });- const lines = report.snippets.map((s) => s.startLine);+ const lines = report.snippets.map((s) => Number(/:(\d+)-/.exec(s.id)![1]));expect(lines).toEqual([...lines].sort((a, b) => a - b));expect(report.snippets.at(-1)?.kind).toEqual(["animation creation"]);expect(report.omittedCount).toBe(0);@@ -206,3 +206,81 @@ describe("components report priority", () => {expect(fetched.omittedCount).toBe(0);});});++describe("components report shape", () => {+ const call = `tl.to(".w-dot", { x: 100, duration: 1 }, 2);`;++ function report(targets: number, coTargets: number) {+ const dir = mkdtempSync(join(tmpdir(), "inspect-shape-"));+ const html = `<html><body>\n<script>\nconst tl = gsap.timeline();\n${call}\n</script>\n</body></html>`;+ writeFileSync(join(dir, "index.html"), html);+ const sources = new Sources(dir);+ const start = html.indexOf(call);+ const creation = sources.slice(+ "index.html",+ start,+ start + call.length,+ "animation creation",+ 0,+ )!;+ const moved = Array.from({ length: coTargets + 1 }, (_, n) => element(n));+ const result = (n: number) => ({+ target: { selector: `.w-dot.t${n}` },+ status: "found" as const,+ candidates: [element(n)],+ animations: [{ stack: "s", attachmentStacks: [], targets: moved } as never],+ elements: [element(n)],+ css: [],+ truncated: false,+ });+ try {+ return mapInspection(+ {+ results: Array.from({ length: targets }, (_, n) => result(n)),+ recorded: 1,+ recordLimitReached: false,+ hooked: true,+ },+ { targets: Array.from({ length: targets }, (_, n) => ({ selector: `.w-dot.t${n}` })) },+ {+ sources,+ map: () => [{ ...creation, targets: Array.from({ length: targets }, (_, n) => n) }],+ catalog: new Map<string, Snippet>(),+ generation: "g",+ sourceVersion: "v",+ reused: false,+ start: performance.now(),+ },+ );+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ }++ it("names a snippet's file and lines once, in its id, and carries no fixed disclaimers", () => {+ const shown = report(1, 0);+ expect(shown).not.toHaveProperty("coverage");+ expect(shown.snippets).toEqual([+ { id: "index.html:4-4", kind: ["animation creation"], code: `${call}\n`, uniqueInFile: true },+ ]);+ });++ it("says which target each snippet serves when the query names more than one", () => {+ expect(report(2, 0).snippets[0]).toMatchObject({ id: "index.html:4-4", targets: [0, 1] });+ });++ it("keeps an unqueried co-target visible when four queried elements share its tween", () => {+ for (const result of report(4, 4).results) {+ expect(result.coTargets[0]?.ref).toBe(element(4).ref);+ expect(result.coTargets).toHaveLength(3);+ expect(result.coTargetsOmitted).toBe(1);+ }+ });++ it("lists three elements the same animation also moves and counts the rest", () => {+ const [result] = report(1, 7).results;+ expect(result!.coTargets).toHaveLength(3);+ expect(result!.coTargetsOmitted).toBe(4);+ expect(report(1, 2).results[0]).not.toHaveProperty("coTargetsOmitted");+ });+});diff --git a/packages/inspector/tests/snippetSource.ts b/packages/inspector/tests/snippetSource.tsnew file mode 100644index 0000000000..a7d589bd29--- /dev/null+++ b/packages/inspector/tests/snippetSource.ts@@ -0,0 +1,11 @@+import { readFileSync } from "node:fs";+import { join } from "node:path";++/** The file lines a snippet id, `<file>:<start>-<end>`, names, as they are on disk now. */+export function snippetSource(project: string, id: string): string {+ const [, file, startLine, endLine] = /^(.+):(\d+)-(\d+)$/.exec(id)!;+ return readFileSync(join(project, file!), "utf8")+ .split(/(?<=\n)/)+ .slice(Number(startLine) - 1, Number(endLine))+ .join("");+}