Skip to content

Commit f45788b

Browse files
authored
feat(inspector): query timelines and inspect the live preview (#5508)
* feat(inspector): query timelines and inspect the live preview * fix(inspector): align live timeline contracts Keep realm-safe target detection through the restack and align floating-point interval boundaries. Update the live group fixture and make the private runtime entry build itself before use. * fix(inspector): declare generated build inputs
1 parent 73bbd37 commit f45788b

29 files changed

Lines changed: 2183 additions & 175 deletions

‎.fallowrc.jsonc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -761,6 +761,8 @@
761761
// boundary, while htmlBundler keeps parallel module/classic-script paths.
762762
"packages/inspector/tests/browser.ts",
763763
"packages/inspector/tests/film.ts",
764+
"packages/inspector/tests/timeline.ts",
765+
"packages/inspector/tests/timelineCompositions.ts",
764766
"packages/core/src/compiler/htmlBundler.ts",
765767
],
766768
},
@@ -1030,6 +1032,12 @@
10301032
"packages/inspector/src/server.ts",
10311033
"packages/core/src/runtime/inspection.ts",
10321034
"packages/inspector/tests/film.ts",
1035+
"packages/inspector/src/mapInspection.ts",
1036+
"packages/inspector/src/live.ts",
1037+
"packages/inspector/src/elementMap.js",
1038+
"packages/inspector/src/sourceDependencies.ts",
1039+
"packages/core/src/runtime/timelineInspection.ts",
1040+
"packages/cli/src/commands/timeline.ts",
10331041
],
10341042
},
10351043
}

‎.github/workflows/ci.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -380,6 +380,11 @@ jobs:
380380
node-version: 22
381381
- uses: ./.github/actions/prepare-ffmpeg-bin
382382
- run: bash scripts/ci/install-workspace-dependencies.sh
383+
- name: Build generated inspector inputs
384+
run: |
385+
bun run --filter '@hyperframes/{parsers,lint}' build
386+
bun run build:hyperframes-runtime
387+
bun run --filter @hyperframes/inspector build
383388
- name: Run fallow audit
384389
id: audit
385390
# `bun install` above made `bunx fallow` resolve from node_modules, so

‎bun.lock‎

Lines changed: 9 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/cli/src/commands/timeline.ts‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,29 @@ export default defineCommand({
9191
meta: { name: "timeline", description: "Print and edit the project's tracks and clips" },
9292
args: {
9393
dir: { type: "positional", description: "Project directory", required: false },
94+
component: {
95+
type: "string",
96+
description:
97+
"Unique component selector, or JSON target {selector|hfId|ref}; runtime inspection",
98+
},
99+
at: { type: "string", description: "Global second; requires the inspector service" },
100+
range: {
101+
type: "string",
102+
description: "Global start,end (half-open); requires the inspector service",
103+
},
104+
boundary: {
105+
type: "string",
106+
description: "Global boundary second; requires the inspector service",
107+
},
108+
generation: {
109+
type: "string",
110+
description: "Inspector generation for a continued runtime query",
111+
},
112+
offset: {
113+
type: "string",
114+
description: "Group offset for a continued runtime query",
115+
},
116+
94117
json: { type: "boolean", description: "Output as JSON", default: false },
95118
},
96119
subCommands,
@@ -106,6 +129,42 @@ export default defineCommand({
106129
if (isTimelineSubcommand(args._[0], rawArgs)) return;
107130
resolveExtraPositionals({ args: cmd.args }, "timeline", args);
108131
const project = resolveProject(args.dir);
132+
if ([args.component, args.at, args.range, args.boundary].some((v) => v !== undefined)) {
133+
const url = process.env.HF_INSPECT_URL;
134+
if (!url || !/^http:\/\/(127\.0\.0\.1|localhost):\d+$/.test(url))
135+
throw new Error(
136+
"Runtime timeline queries require HF_INSPECT_URL from the existing inspector service.",
137+
);
138+
const info = await fetch(`${url}/info`, { signal: AbortSignal.timeout(5000) }).then((r) =>
139+
r.json(),
140+
);
141+
const { realpathSync } = await import("node:fs");
142+
const { dirname } = await import("node:path");
143+
if (realpathSync(info.project) !== realpathSync(dirname(project.indexPath)))
144+
throw new Error("Inspector service belongs to another project");
145+
const component = args.component?.trim().startsWith("{")
146+
? JSON.parse(args.component)
147+
: args.component
148+
? { selector: args.component }
149+
: undefined;
150+
const response = await fetch(`${url}/timeline`, {
151+
method: "POST",
152+
headers: { "Content-Type": "application/json" },
153+
body: JSON.stringify({
154+
component,
155+
at: args.at === undefined ? undefined : Number(args.at),
156+
range: args.range?.split(",").map(Number),
157+
boundary: args.boundary === undefined ? undefined : Number(args.boundary),
158+
generation: args.generation,
159+
offset: args.offset === undefined ? undefined : Number(args.offset),
160+
}),
161+
signal: AbortSignal.timeout(60000),
162+
});
163+
const result = await response.json();
164+
if (!response.ok) throw new Error(result.error ?? "Timeline query failed");
165+
console.log(args.json ? JSON.stringify(result) : result.text);
166+
return;
167+
}
109168
ensureDOMParser();
110169
const timeline = await describeProject(project.indexPath);
111170
console.log(

‎packages/core/src/compiler/htmlBundler.ts‎

Lines changed: 11 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -831,20 +831,18 @@ function stripJsCommentsParserSafe(
831831
): string {
832832
if (!source) return source;
833833
try {
834-
const result = transformSync(source, { loader: "js", minify: false, legalComments: "none" });
834+
const result = transformSync(source, {
835+
loader: "js",
836+
minify: false,
837+
legalComments: "none",
838+
...(provenance
839+
? { sourcemap: "external" as const, sourcefile: "hf-authored-bundle.js" }
840+
: {}),
841+
});
835842
if (provenance) {
836-
const mapped = transformSync(source, {
837-
loader: "js",
838-
minify: false,
839-
legalComments: "none",
840-
sourcemap: "external",
841-
sourcefile: "hf-authored-bundle.js",
842-
});
843-
if (mapped.code.trim() === result.code.trim()) {
844-
const sourceURL = `hf-inspect-${createHash("sha256").update(source).digest("hex")}.js`;
845-
provenance({ input: source, output: result.code.trim(), sourceMap: mapped.map, sourceURL });
846-
return `${result.code.trim()}\n//# sourceURL=${sourceURL}`;
847-
}
843+
const sourceURL = `hf-inspect-${createHash("sha256").update(source).digest("hex")}.js`;
844+
provenance({ input: source, output: result.code.trim(), sourceMap: result.map, sourceURL });
845+
return `${result.code.trim()}\n//# sourceURL=${sourceURL}`;
848846
}
849847
return result.code.trim();
850848
} catch {

‎packages/core/src/runtime/inspection.ts‎

Lines changed: 70 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
import {
2+
inspectTimelineRuntime,
3+
type TimelineRequest,
4+
type TimedAnimation,
5+
type TimelineRuntimeResult,
6+
} from "./timelineInspection";
17
import type {
28
ElementRef,
39
RuntimeAnimation,
@@ -23,7 +29,12 @@ interface Gsap {
2329
}
2430
interface InspectorWindow extends Omit<Window, "__timelines" | "gsap"> {
2531
gsap?: Gsap;
26-
__hfInspection?: { query: (q: RuntimeQuery) => RuntimeResponse; dispose: () => void };
32+
__hfInspection?: {
33+
query: (q: RuntimeQuery) => RuntimeResponse;
34+
timeline: (q: TimelineRequest) => TimelineRuntimeResult;
35+
dispose: () => void;
36+
};
37+
__timelines?: Record<string, TimedAnimation>;
2738
}
2839
const animation = (value: unknown): value is Animation =>
2940
!!value &&
@@ -191,16 +202,34 @@ export function installInspection(win: InspectorWindow, generation: string, limi
191202
} catch {
192203
return { ...base, status: "invalid-selector" };
193204
}
194-
if (elements.length !== 1)
205+
if (elements.length === 0)
195206
return {
196207
...base,
197-
status: elements.length ? "ambiguous" : "missing",
208+
status: "missing",
198209
candidates: elements.slice(0, 20).map(describe),
199210
truncated: elements.length > 20,
200211
};
201-
const targetElement = elements[0]!;
202-
const descendants = q.descendants ? [...targetElement.querySelectorAll("*")] : [];
203-
const scope = [targetElement, ...descendants.slice(0, 1000)];
212+
const selected = new Set<Element>();
213+
let truncated = false;
214+
const add = (el: Element) => {
215+
if (selected.has(el)) return;
216+
if (selected.size >= 1001) {
217+
truncated = true;
218+
return;
219+
}
220+
selected.add(el);
221+
};
222+
for (const element of elements) {
223+
add(element);
224+
if (q.descendants) {
225+
for (const child of element.querySelectorAll("*")) {
226+
add(child);
227+
if (truncated) break;
228+
}
229+
}
230+
if (truncated) break;
231+
}
232+
const scope = [...selected];
204233
const animations = (gsap?.getTweensOf?.(scope) ?? []).map((tw): RuntimeAnimation => {
205234
const attachmentStacks: string[] = [];
206235
const visited = new Set<Animation>();
@@ -236,15 +265,48 @@ export function installInspection(win: InspectorWindow, generation: string, limi
236265
return {
237266
...base,
238267
status: "found",
239-
candidates: [describe(targetElement)],
268+
candidates: elements.slice(0, 1001).map(describe),
240269
elements: scope.map(describe),
241270
animations,
242271
css,
243-
truncated: descendants.length > 1000,
272+
truncated,
244273
};
245274
});
246275
return { results, recorded: count, recordLimitReached: count >= limit, hooked: !!gsap };
247276
},
277+
timeline(q: TimelineRequest): TimelineRuntimeResult {
278+
let scope: Element = document.documentElement;
279+
if (q.component) {
280+
const found = api.query({ targets: [q.component], descendants: false, cssRules: [] })
281+
.results[0];
282+
if (!found) return { status: "missing", candidates: [], events: [], warnings: [] };
283+
if (found.status !== "found")
284+
return { status: found.status, candidates: found.candidates, events: [], warnings: [] };
285+
const [only, ...others] = found.candidates;
286+
if (!only || others.length > 0)
287+
return { status: "ambiguous", candidates: found.candidates, events: [], warnings: [] };
288+
const el = refs.get(only.ref)?.deref();
289+
if (!el) return { status: "stale-ref", candidates: [], events: [], warnings: [] };
290+
scope = el;
291+
}
292+
const registered = Object.values(win.__timelines ?? {});
293+
const roots = registered.filter(
294+
(root) =>
295+
!registered.some(
296+
(other) =>
297+
other !== root && (other.getChildren?.(true, false, true) ?? []).includes(root),
298+
),
299+
);
300+
return inspectTimelineRuntime(
301+
q,
302+
roots,
303+
scope,
304+
describe,
305+
(a) => records.get(a) ?? null,
306+
reserved,
307+
win.__timelines ?? {},
308+
);
309+
},
248310
dispose() {
249311
disposed = true;
250312
for (const restore of restorers.reverse()) restore();

0 commit comments

Comments
 (0)