Skip to content

Commit 072f53c

Browse files
authored
feat(inspector): element map, live inspection engine and Node runtime (#5509)
* feat(inspector): element map, live inspection engine and Node runtime * fix(inspector): reject preview reload races Return the live document generation from the same page invocation as each query and reject mismatches. Rearm browser cleanup for failures before a page operation starts, and cover reloads across all three live operations.
1 parent f45788b commit 072f53c

28 files changed

Lines changed: 1190 additions & 603 deletions

‎.fallowrc.jsonc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
// Inspector is a private Bun service with CLI-driven browser contract
1313
// scripts; its runtime module is bundled by file path into the page.
1414
"packages/inspector/src/{service,server,mcp}.ts",
15+
"packages/inspector/src/liveRuntime.ts",
1516
"packages/inspector/tests/*.ts",
1617
"packages/core/src/runtime/inspection.ts",
1718
"packages/producer/src/regression-harness.ts",
@@ -117,6 +118,12 @@
117118
"packages/cli/bin/**",
118119
],
119120
"ignoreExports": [
121+
// Browser helper public API, paired with elementMap.d.ts and consumed by
122+
// external harnesses rather than another workspace package.
123+
{
124+
"file": "packages/inspector/src/elementMap.js",
125+
"exports": ["createElementMap"],
126+
},
120127
// Public player-state types are consumed by package users outside this
121128
// workspace. Keep the barrel stable even when no in-repo import needs it.
122129
{
@@ -1038,6 +1045,12 @@
10381045
"packages/inspector/src/sourceDependencies.ts",
10391046
"packages/core/src/runtime/timelineInspection.ts",
10401047
"packages/cli/src/commands/timeline.ts",
1048+
// Protocol validators and deterministic report formatters enumerate wire
1049+
// variants explicitly; splitting those branches would scatter one contract.
1050+
"packages/inspector/src/requests.ts",
1051+
"packages/inspector/src/timelineReport.ts",
1052+
"packages/inspector/src/pageQueries.ts",
1053+
"packages/core/src/runtime/timelineValues.ts",
10411054
],
10421055
},
10431056
}

‎bun.lock‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ export {
3333
type BundledHostCompositionIdentity,
3434
bundleToSingleHtml,
3535
type BundleOptions,
36+
type BundleScriptProvenance,
3637
prepareFlattenedInnerRoot,
3738
FLATTENED_INNER_ROOT_STRIP_ATTRS,
3839
emitRootCompositionVariableStyles,

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

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { animationValues, type AnimationValues } from "./timelineValues";
12
import { createRuntimeStartTimeResolver } from "./startResolver";
23
import { findRootCompositionElement } from "./compositionDimension";
34
import { readElementRateSpec, readMediaStart } from "./playbackRate";
@@ -126,6 +127,7 @@ export interface TimelineEvent extends Interval {
126127
component: ElementRef | null;
127128
targets: ElementRef[];
128129
properties: string[];
130+
values?: AnimationValues;
129131
stack: string | null;
130132
}
131133
export interface TimelineRuntimeResult {
@@ -210,6 +212,7 @@ export function inspectTimelineRuntime(
210212
const properties = Object.keys(piece.vars ?? {}).filter(
211213
(k) => !reserved.has(k) && !k.startsWith("on"),
212214
);
215+
const values = animationValues(piece.vars ?? {}, properties);
213216
const localIntervals = internal
214217
? globalIntervals(
215218
a,
@@ -243,7 +246,8 @@ export function inspectTimelineRuntime(
243246
e.start === interval.start &&
244247
e.end === interval.end &&
245248
e.component?.ref === describe(owner).ref &&
246-
e.properties.join() === properties.join(),
249+
e.properties.join() === properties.join() &&
250+
JSON.stringify(e.values) === JSON.stringify(values),
247251
);
248252
if (existing) {
249253
for (const target of targets.map(describe))
@@ -257,6 +261,7 @@ export function inspectTimelineRuntime(
257261
component: describe(owner),
258262
targets: targets.map(describe),
259263
properties,
264+
values,
260265
stack,
261266
});
262267
}
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
export interface DeclaredValue {
2+
kind: "literal" | "relative" | "expression" | "unknown";
3+
value: number | string | null;
4+
}
5+
export interface AnimationValues {
6+
basis: "authored-tween";
7+
properties: Array<{ property: string; from: DeclaredValue; to: DeclaredValue }>;
8+
ease: DeclaredValue;
9+
}
10+
const unknown = (): DeclaredValue => ({ kind: "unknown", value: null });
11+
function declared(value: unknown): DeclaredValue {
12+
if (typeof value === "number" && Number.isFinite(value)) return { kind: "literal", value };
13+
if (typeof value === "string") {
14+
const kind = /^[+\-*/]=/.test(value)
15+
? "relative"
16+
: value.includes("random(")
17+
? "expression"
18+
: "literal";
19+
return { kind, value };
20+
}
21+
return unknown();
22+
}
23+
/** Authored endpoints, never sampled values or inferred previous-tween state. */
24+
export function animationValues(
25+
vars: Record<string, unknown>,
26+
properties: string[],
27+
): AnimationValues {
28+
const startAt =
29+
vars.startAt && typeof vars.startAt === "object"
30+
? (vars.startAt as Record<string, unknown>)
31+
: {};
32+
return {
33+
basis: "authored-tween",
34+
properties: properties.map((property) => ({
35+
property,
36+
from: declared(vars.runBackwards ? vars[property] : startAt[property]),
37+
to: vars.runBackwards ? unknown() : declared(vars[property]),
38+
})),
39+
ease: declared(vars.ease),
40+
};
41+
}

‎packages/inspector/build-live.mjs‎

Lines changed: 0 additions & 16 deletions
This file was deleted.

‎packages/inspector/build.mjs‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
// Builds the inspector for Node and for the page. Bun runs the TypeScript sources directly (package.json "bun").
2+
import { execFileSync } from "node:child_process";
3+
import { copyFileSync, readFileSync, rmSync } from "node:fs";
4+
import { createRequire } from "node:module";
5+
import { build } from "esbuild";
6+
7+
const at = (path) => new URL(path, import.meta.url).pathname;
8+
const { dependencies } = JSON.parse(readFileSync(at("./package.json"), "utf8"));
9+
// Declared dependencies stay imports; the workspace's own sources (core, parsers) are bundled in.
10+
const external = Object.keys(dependencies).filter((name) => !name.startsWith("@hyperframes/"));
11+
// Bundled CommonJS dependencies call require(); an ES module has none until the banner defines it.
12+
const banner = {
13+
js: 'import { createRequire } from "node:module"; const require = createRequire(import.meta.url);',
14+
};
15+
const node = { bundle: true, platform: "node", format: "esm", target: "node22", external, banner };
16+
17+
await Promise.all([
18+
build({ ...node, entryPoints: [at("./src/live.ts")], outfile: at("./dist/live.js") }),
19+
build({ ...node, entryPoints: [at("./src/service.ts")], outfile: at("./dist/service.js") }),
20+
build({ ...node, entryPoints: [at("./src/server.ts")], outfile: at("./dist/server.js") }),
21+
build({ ...node, entryPoints: [at("./src/mcp.ts")], outfile: at("./dist/mcp.js") }),
22+
build({
23+
entryPoints: [at("./src/liveRuntime.ts")],
24+
outfile: at("./dist/inspection.js"),
25+
bundle: true,
26+
platform: "browser",
27+
format: "iife",
28+
}),
29+
]);
30+
// Declarations keep the packages/ layout under dist/types, so their relative imports still resolve once packed.
31+
rmSync(at("./dist/types"), { recursive: true, force: true });
32+
const tsc = createRequire(import.meta.url).resolve("typescript/bin/tsc");
33+
execFileSync(process.execPath, [tsc, "-p", at("./tsconfig.types.json")], { stdio: "inherit" });
34+
// tsc emits declarations for TypeScript only; the element map's JavaScript ships its own.
35+
copyFileSync(at("./src/elementMap.d.ts"), at("./dist/types/inspector/src/elementMap.d.ts"));

‎packages/inspector/package.json‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,31 @@
11
{
22
"name": "@hyperframes/inspector",
3-
"version": "0.8.127",
3+
"version": "0.8.140",
44
"private": true,
55
"type": "module",
66
"exports": {
7-
".": "./src/service.ts",
8-
"./live": "./dist/live.js"
7+
".": {
8+
"bun": "./src/service.ts",
9+
"types": "./dist/types/inspector/src/service.d.ts",
10+
"default": "./dist/service.js"
11+
},
12+
"./live": {
13+
"types": "./dist/types/inspector/src/live.d.ts",
14+
"default": "./dist/live.js"
15+
}
916
},
1017
"scripts": {
11-
"build": "node build-live.mjs",
18+
"build": "node build.mjs",
1219
"test": "vitest run",
1320
"typecheck": "tsc --noEmit",
1421
"serve": "bun run build && bun src/server.ts",
1522
"mcp": "bun run build && bun src/mcp.ts",
1623
"test:timeline": "bun tests/timeline.ts",
1724
"test:timeline-compositions": "bun tests/timelineCompositions.ts",
18-
"build:live": "node build-live.mjs",
19-
"prepack": "node build-live.mjs",
25+
"prepack": "node build.mjs",
2026
"test:live": "bun run build && bun tests/live.ts",
21-
"test:source-release": "bun tests/sourceRelease.ts"
27+
"test:source-release": "bun tests/sourceRelease.ts",
28+
"serve:node": "node dist/server.js"
2229
},
2330
"dependencies": {
2431
"@hyperframes/core": "workspace:*",

‎packages/inspector/src/elementMap.d.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,11 @@ export interface ElementNode {
1414
media: string | null;
1515
relative: string;
1616
groupSelector: string;
17-
siblingMatches: string[];
17+
siblingMatchCount: number;
1818
children: number[];
1919
}
2020
export interface ElementDom {
21+
generation: string | null;
2122
nodes: ElementNode[];
2223
limitations: { canvas: number; iframes: number; shadowRoots: number };
2324
}

‎packages/inspector/src/elementMap.js‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,20 @@ export function collectElementDom() {
44
const excluded = new Set(["SCRIPT", "STYLE", "LINK", "META"]);
55
const nodes = [];
66
const paths = new Map();
7+
const siblingGroups = new WeakMap();
8+
function siblingCount(element, selector) {
9+
const owner = element.parentElement ?? element;
10+
let counts = siblingGroups.get(owner);
11+
if (!counts) {
12+
counts = new Map();
13+
siblingGroups.set(owner, counts);
14+
}
15+
if (!counts.has(selector)) {
16+
const siblings = element.parentElement ? [...element.parentElement.children] : [element];
17+
counts.set(selector, siblings.filter((sibling) => sibling.matches(selector)).length);
18+
}
19+
return counts.get(selector);
20+
}
721
const quote = (value) => JSON.stringify(value);
822
function path(element) {
923
if (paths.has(element)) return paths.get(element);
@@ -57,11 +71,11 @@ export function collectElementDom() {
5771
relative:
5872
element.id && document.querySelectorAll(`#${CSS.escape(element.id)}`).length === 1
5973
? `#${CSS.escape(element.id)}`
60-
: siblings.filter((sibling) => sibling.matches(simple)).length === 1
74+
: siblingCount(element, simple) === 1
6175
? simple
6276
: `${CSS.escape(tag)}:nth-child(${siblings.indexOf(element) + 1})`,
6377
groupSelector: simple,
64-
siblingMatches: siblings.filter((sibling) => sibling.matches(simple)).map(path),
78+
siblingMatchCount: siblingCount(element, simple),
6579
children: [],
6680
};
6781
nodes.push(node);
@@ -73,6 +87,7 @@ export function collectElementDom() {
7387
}
7488
if (document.body) visit(document.body, null);
7589
return {
90+
generation: window.__hfLiveInspection?.generation ?? null,
7691
nodes,
7792
limitations: {
7893
canvas: nodes.filter((node) => node.tag === "canvas").length,
@@ -135,12 +150,7 @@ export function formatElementMap(snapshot, { file = "index.html" } = {}) {
135150
for (const group of groups) {
136151
const members = group.indices.map((index) => nodes[index]);
137152
const node = members[0];
138-
const exactGroup =
139-
members.length > 1 &&
140-
node.siblingMatches.length === members.length &&
141-
node.siblingMatches.every((selector) =>
142-
members.some((member) => member.selector === selector),
143-
);
153+
const exactGroup = members.length > 1 && node.siblingMatchCount === members.length;
144154
if (members.length > 1 && !exactGroup) {
145155
for (const member of members) emit([member], depth);
146156
} else emit(members, depth);

0 commit comments

Comments
 (0)