Files
hyperframes/packages/core/src/runtime/timelineInspection.ts
T
Xuanru Li 45825faa5d fix(inspector): grep timeline windows, continuation, candidates and timeline text from the Canary dogfood (#5595)
* fix(inspector): report nested hosts' authored window, one location per source line

The runtime strips data-duration/data-end from nested composition hosts after
boot and keeps them as data-hf-authored-*. Timeline inspection built its
resolver without authored attrs, so a host with data-duration="4" reported
its GSAP timeline length (3.72s) instead.

Timeline text and events[].sources listed the same file:line once per mapped
snippet (creation, caller, dependency), so a one-line script printed one
location up to nine times.

* refactor(inspector): carry the dedupe reason in the helper's name

* fix(inspector): end continuation on a page that fits no snippet; fill budget with candidates

* fix(inspector): timeline groups by component, names attr values, eases, film end

* fix(studio-server): stamp hf ids into a file without reformatting it

* fix(inspector): find an element's tag before its served hf id reaches the source

* fix(inspector): live element map shows authored classes and text, not the playhead's

* fix(inspector): collapse script-built text so the element map ignores the playhead

Class names stay in source order, a runtime-stripped id is shown as id="…"
rather than a selector, and a grouped row names which children it covers.

* fix(inspector): keep paging, stamping, and the live map still on the reported edges

A snippet larger than the page ended the walk, so later snippets could not
be reached. Raw text ended at a longer tag name, which could stamp an id
inside a script. An empty or mixed source element showed live text, and an
unknown duration read as a film that ends at 0s.

* fix(inspector): mint ids for an empty hf id and keep an unquoted class

An empty data-hf-id was treated as already assigned, so stamping left it
blank while the older stamper minted one. An unquoted class was read as no
class, so the live map dropped it.

* fix(inspector): narrow markup before reading a child tag

skipMarkup returns a boolean, so the build still sees Markup where a tag
is required. Narrow on the kind first so the inspector typechecks.

* fix: quiet check false positives and name the ancestor of an id-less target

Endpoint contact, disjoint fromTo pairs, and a negative z-index under a
stacking-context parent were warnings with bad advice. Layout and contrast
blamed a dot grid, a circular avatar's panel, and a visibility override.
A faint texture veil is no longer the click target.

* fix(lint): drop a history sentence and six gsap comments

The comments check treats "load-bearing" as history, and gsap.ts added six
comment lines. The names already carry what those lines said.

* fix(parsers): ignore an empty id written inside another attribute

The empty-id scan matched the first data-hf-id="" in the tag, including one
inside a quoted title. It now skips quoted text, so the real attribute is minted.

* fix(lint): keep real covers and a negative z-index under a card

A gradient scale-down treated every fill like a radial dot, so a panel
that starts transparent stopped counting as a cover. A stacking context
on any ancestor cleared a negative z-index, and a faint wrapper made
images inside it unpickable.

* fix: keep an emoji from shifting a stamped id

The quote mask replaced one emoji with one space, so the id landed before
the closing quote. A radial cover that turns opaque after a clear stop
stays fully painted.

* fix(lint): score a letter-only dot as a dot, not a color name

namesAColor saw #fff and rgba as words, so those dot grids counted as a
full cover. Hex and rgb colors are stripped before that word check.
2026-10-14 09:16:20 +00:00

306 lines
11 KiB
TypeScript

import { animationValues, type AnimationValues } from "./timelineValues";
import { createRuntimeStartTimeResolver } from "./startResolver";
import { findRootCompositionElement } from "./compositionDimension";
import { readElementRateSpec, readMediaStart } from "./playbackRate";
import { timeAtSourceTime } from "../speedRamp";
import type { ElementRef, Target } from "./inspectionTypes";
import { isElementNode } from "./domRealm";
export interface TimelineRequest {
component?: Target;
at?: number;
range?: [number, number];
boundary?: number;
generation?: string;
offset?: number;
}
export interface TimedAnimation {
parent?: TimedAnimation;
timeline?: TimedAnimation;
_ease?: (progress: number) => number;
vars?: Record<string, unknown>;
targets?: () => unknown[];
getChildren?: (nested: boolean, tweens: boolean, timelines: boolean) => TimedAnimation[];
startTime(): number;
duration(): number;
totalDuration?(): number;
timeScale?(): number;
repeat?(): number;
repeatDelay?(): number;
yoyo?(): boolean;
paused?(): boolean;
}
export interface Interval {
start: number;
end: number;
}
function classify(interval: Interval, q: TimelineRequest): string | null {
const { start, end } = interval;
const near = (a: number, b: number) => Math.abs(a - b) <= 1e-7;
const before = (a: number, b: number) => a < b && !near(a, b);
const beforeOrAt = (a: number, b: number) => a < b || near(a, b);
if (q.boundary != null) {
const t = q.boundary;
if (near(start, end) && near(start, t)) return "instant";
if (near(start, t)) return "starts";
if (near(end, t)) return "ends";
return start < t && end > t ? "crosses" : null;
}
if (q.at != null)
return near(start, end)
? near(start, q.at)
? "instant"
: null
: beforeOrAt(start, q.at) && before(q.at, end)
? "active"
: null;
if (q.range)
return near(start, end)
? beforeOrAt(q.range[0], start) && before(start, q.range[1])
? "instant"
: null
: before(start, q.range[1]) && before(q.range[0], end)
? "intersects"
: null;
return near(start, end) ? "instant" : "scheduled";
}
// Convert a local interval into occurrences in an animation's total-time clock.
function cycles(a: TimedAnimation, input: Interval[], warnings: Set<string>): Interval[] {
const d = a.duration(),
repeat = a.repeat?.() ?? 0,
gap = a.repeatDelay?.() ?? 0;
if (repeat < 0 || repeat > 1000) {
warnings.add("Infinite or >1000 repeats are not expanded; timing incomplete.");
return [];
}
const result: Interval[] = [];
for (let cycle = 0; cycle <= repeat; cycle++)
for (const interval of input) {
const start = Math.max(0, interval.start),
end = Math.min(d, interval.end);
if (end < start) continue;
const reverse = !!a.yoyo?.() && cycle % 2 === 1;
result.push({
start: cycle * (d + gap) + (reverse ? d - end : start),
end: cycle * (d + gap) + (reverse ? d - start : end),
});
if (result.length >= 10000) {
warnings.add("Occurrence expansion limit reached; timing incomplete.");
return result;
}
}
return result;
}
function globalIntervals(
a: TimedAnimation,
root: TimedAnimation,
warnings: Set<string>,
activity: Interval[] = [{ start: 0, end: a.duration() }],
): Interval[] {
let intervals = cycles(a, activity, warnings);
let node = a;
const seen = new Set<TimedAnimation>();
while (node !== root) {
if (seen.has(node) || !node.parent) {
warnings.add("Animation is not attached to a registered root; global time unknown.");
return [];
}
seen.add(node);
const scale = node.timeScale?.() ?? 1;
if (node.paused?.() || !scale) {
warnings.add("Paused or zero-speed nested animation excluded; activation is unknown.");
return [];
}
const total = node.totalDuration?.() ?? node.duration();
intervals = intervals.map((i) => {
const x = node.startTime() + (scale < 0 ? (total - i.end) / -scale : i.start / scale);
const y = node.startTime() + (scale < 0 ? (total - i.start) / -scale : i.end / scale);
return { start: x, end: y };
});
node = node.parent;
intervals = cycles(node, intervals, warnings);
}
return intervals;
}
export interface TimelineEvent extends Interval {
kind: "animation" | "item";
relation: string;
component: ElementRef | null;
targets: ElementRef[];
properties: string[];
values?: AnimationValues;
stack: string | null;
}
export interface TimelineRuntimeResult {
status: string;
candidates: ElementRef[];
events: TimelineEvent[];
warnings: string[];
}
export function inspectTimelineRuntime(
q: TimelineRequest,
roots: TimedAnimation[],
scope: Element,
describe: (el: Element) => ElementRef,
origin: (a: TimedAnimation) => string | null,
reserved: Set<string>,
registry: Record<string, TimedAnimation>,
): TimelineRuntimeResult {
const warnings = new Set<string>();
const events: TimelineEvent[] = [];
const seen = new Set<TimedAnimation>();
const resolver = createRuntimeStartTimeResolver({
timelineRegistry: registry,
documentRef: scope.ownerDocument,
includeAuthoredTimingAttrs: true,
});
const rootElement = findRootCompositionElement(scope.ownerDocument);
const clocks = new Map<TimedAnimation, Element>();
for (const [id, timeline] of Object.entries(registry)) {
const host = scope.ownerDocument.querySelector(`[data-composition-id="${CSS.escape(id)}"]`);
if (host) clocks.set(timeline, host);
}
const clockFor = (animation: TimedAnimation, fallback: TimedAnimation) => {
const visited = new Set<TimedAnimation>();
let node: TimedAnimation | undefined = animation;
while (node && !visited.has(node)) {
if (clocks.has(node)) return node;
visited.add(node);
node = node.parent;
}
return fallback;
};
const toProjectTime = (clock: TimedAnimation, intervals: Interval[]): Interval[] => {
const host = clocks.get(clock);
if (!host || host === rootElement) return intervals;
const start = resolver.resolveStartForElement(host, 0);
const offset = readMediaStart(host);
const rate = readElementRateSpec(host);
if (!Number.isFinite(start)) {
warnings.add("Composition start could not be resolved; timing incomplete.");
return [];
}
return intervals
.filter((interval) => interval.end >= offset)
.map((interval) => ({
start: start + timeAtSourceTime(rate, Math.max(0, interval.start - offset)),
end: start + timeAtSourceTime(rate, interval.end - offset),
}));
};
const component = (el: Element) =>
describe(q.component ? scope : (el.closest("[data-composition-id]") ?? scope));
for (const root of roots)
for (const a of root.getChildren?.(true, true, false) ?? []) {
if (events.length >= 10000) {
warnings.add("Global event limit reached; narrow component/time query. Timing incomplete.");
break;
}
if (seen.has(a)) continue;
seen.add(a);
const clock = clockFor(a, root);
const internal = a.timeline;
if (
internal &&
a._ease &&
[0, 0.25, 0.5, 0.75, 1].some((t) => Math.abs(a._ease!(t) - t) > 1e-7)
) {
warnings.add("Nonlinear internal timeline easing is not mapped; timing incomplete.");
continue;
}
const pieces = internal?.getChildren?.(true, true, false) ?? [a];
for (const piece of pieces) {
const targets = (piece.targets?.() ?? []).filter(isElementNode);
if (!targets.some((el) => scope === el || scope.contains(el))) continue;
const properties = Object.keys(piece.vars ?? {}).filter(
(k) => !reserved.has(k) && !k.startsWith("on"),
);
const values = animationValues(
piece.vars ?? {},
properties,
internal && a.vars?.keyframes ? a.vars.ease : undefined,
);
const localIntervals = internal
? globalIntervals(
a,
clock,
warnings,
globalIntervals(piece, internal, warnings).map((i) => {
const scale = internal.duration() ? a.duration() / internal.duration() : 1;
return { start: i.start * scale, end: i.end * scale };
}),
)
: globalIntervals(a, clock, warnings);
const intervals = toProjectTime(clock, localIntervals);
for (const interval of intervals) {
if (events.length >= 10000) {
warnings.add("Global event limit reached; timing incomplete.");
break;
}
const relation = classify(interval, q);
if (!relation) continue;
for (const owner of new Set(
targets
.filter((el) => scope === el || scope.contains(el))
.map((el) => (q.component ? scope : (el.closest("[data-composition-id]") ?? scope))),
)) {
const stack = origin(a);
const existing = events.find(
(e) =>
e.kind === "animation" &&
e.stack === stack &&
stack !== null &&
e.start === interval.start &&
e.end === interval.end &&
e.component?.ref === describe(owner).ref &&
e.properties.join() === properties.join() &&
JSON.stringify(e.values) === JSON.stringify(values),
);
if (existing) {
for (const target of targets.map(describe))
if (!existing.targets.some((t) => t.ref === target.ref))
existing.targets.push(target);
} else
events.push({
...interval,
kind: "animation",
relation,
component: describe(owner),
targets: targets.map(describe),
properties,
values,
stack,
});
}
}
}
}
for (const el of [
scope,
...scope.querySelectorAll("[data-start],[data-duration],[data-end],[data-composition-id]"),
]) {
if (!el.matches("[data-start],[data-duration],[data-end],[data-composition-id]")) continue;
const media = el.tagName === "AUDIO" || el.tagName === "VIDEO";
const start = media
? resolver.resolveMediaStartForElement(el)
: resolver.resolveStartForElement(el, Number.NaN);
const duration = resolver.resolveDurationForElement(el);
if (!Number.isFinite(start) || duration == null || !Number.isFinite(duration) || duration < 0) {
warnings.add("Some HF item timing could not be resolved.");
continue;
}
const interval = { start, end: start + duration };
const relation = classify(interval, q);
if (!relation) continue;
events.push({
...interval,
kind: "item",
relation,
component: component(el),
targets: [describe(el)],
properties: [],
stack: null,
});
}
events.sort((a, b) => a.start - b.start || a.end - b.end);
return { status: "found", candidates: [describe(scope)], events, warnings: [...warnings] };
}