mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
* fix(capture): never silently render a webgpu composition blank A composition declaring data-requires-webgpu only got the Chrome WebGPU flag when hardware GPU auto-detection succeeded. On a software-GPU host it launched without the flag and rendered blank with no error. compositionRequiresWebGpu (static declaration check) and assertWebGpuAdapterAvailable (live per-page adapter probe) now live once in packages/engine's browserManager, the shared choke point every launch site already goes through. All six launch sites (frame capture, the four CLI diagnostic commands, the studio thumbnail server, and the render pipeline's capture-options builder) route through those two functions; the old CLI-only static-heuristic guard is deleted, not kept alongside the new one. A software host that cannot obtain any WebGPU adapter now fails loudly naming the requirement instead of producing a blank frame. * fix(capture): thread requiresWebGpu through the distributed chunk-render path The distributed renderChunk() path built its CaptureOptions without requiresWebGpu, so it fell through to frameCapture's own fetch-based detection, whose failure path silently treats "requires webgpu" as "doesn't" if that fetch ever fails. Every other launch site (frame capture, all four CLI diagnostic commands, the studio thumbnail server, and the in-process render pipeline) already reads the value from HTML already in memory or on disk instead of relying on that fallback. Reads the compiled composition's index.html the same way probeStage already does and derives requiresWebGpu from it before building CaptureOptions. Adds a regression test that pins the exact path renderChunk() reads at render time, since the composition doesn't actually exercise WebGPU so an end-to-end render can't distinguish the two cases on this host. * test(producer): observe the real CaptureOptions renderChunk() builds The previous regression test called plan() and compositionRequiresWebGpu() directly, bypassing renderChunk() entirely, so it could not detect a regression to the wiring it was meant to protect (confirmed: it stayed green with the fix reverted). Exports the existing createCaptureSession dependency seam so a test can substitute a spy that delegates to the real implementation while capturing the CaptureOptions object renderChunk() actually constructs. Verified non-vacuous by reverting the fix and confirming the test fails. * fix(gcp-cloud-run): resolve puppeteer-core from a real file in the webgpu probe The image build's WebGPU adapter probe imported puppeteer-core from an inline `bun -e` eval string. The eval's synthetic /app/[eval] location can't resolve the workspace-hoisted dependency, so every build of this stage failed closed with "Cannot find package 'puppeteer-core'" before the probe itself ever ran. Moves the probe into a real script file next to probe-beginframe.ts, which already imports puppeteer-core dynamically the same way and resolves fine from its real workspace location. Verified locally against a cached chrome-headless-shell binary. * fix(engine): bound the webgpu adapter probe so a stuck driver can't hang the caller requestAdapter() has no native timeout. A broken software GPU driver that never settles it would hang assertWebGpuAdapterAvailable indefinitely, including inside the GCP image build's probe RUN step, producing an opaque build timeout instead of a clean probe failure. Races the in-page request against a bounded timeout so a stuck adapter reads as unavailable and fails the same way a genuinely absent one does. * test(cli): mock the engine's webgpu exports in the browser-fallback test * test(producer): run the typegpu adapter fixture only on hosts with a hardware WebGPU adapter The fixture declares data-requires-webgpu, so a software-only host now refuses it instead of silently rendering the shader blank. The old golden had no shader in it. Tag it webgpu, skip that tag in the CI image and the test scripts, and re-record the golden from a Metal render with the shader visible. * fix(engine): bound the composition fetch that decides the webgpu flag createCaptureSession fetched the served page with no timeout before launching the browser, so a hung server stalled a render forever and hung a fake-timer test. Give it a five second limit, and let that test say it has no WebGPU requirement the way the producer does. * fix(capture): refuse a software fallback WebGPU adapter instead of rendering on it swiftshader reports a WebGPU adapter but cannot render canvas WebGPU, so a data-requires-webgpu composition on a software-only host crashed on its first frame. Refuse fallback adapters with the same clear WebGPU-unavailable error. The GCP image probe now serves its page over http (file:// hides navigator.gpu) and reports a software-only host instead of failing the image build. * fix(engine): parse the composition root tag without a backtracking regex * fix(engine): keep quoted attribute values whole when reading the composition root tag
662 lines
24 KiB
TypeScript
662 lines
24 KiB
TypeScript
import { failCommand, setCommandExitCode } from "../utils/commandResult.js";
|
||
import { defineCommand } from "citty";
|
||
import { existsSync, readFileSync } from "node:fs";
|
||
import { dirname, join } from "node:path";
|
||
import { fileURLToPath } from "node:url";
|
||
import type { Example } from "./_examples.js";
|
||
import { c } from "../ui/colors.js";
|
||
import { resolveProject } from "../utils/project.js";
|
||
import { resolveDiagnosticNavigationTimeoutMs } from "../utils/renderArgs.js";
|
||
import { normalizeErrorMessage } from "../utils/errorMessage.js";
|
||
import { serveStaticProjectHtml } from "../utils/staticProjectServer.js";
|
||
import { printDeprecationNotice, withMeta } from "../utils/updateCheck.js";
|
||
import {
|
||
buildLayoutSampleTimes,
|
||
buildTransitionSampleTimes,
|
||
collapseStaticLayoutIssues,
|
||
dedupeLayoutIssues,
|
||
formatLayoutIssue,
|
||
limitLayoutIssues,
|
||
mergeSampleTimes,
|
||
summarizeLayoutIssues,
|
||
type LayoutIssue,
|
||
} from "../utils/layoutAudit.js";
|
||
import {
|
||
ambiguousIssue,
|
||
collectSamplingTargets,
|
||
evaluateMotion,
|
||
type MotionFrame,
|
||
} from "../utils/motionAudit.js";
|
||
import { findMotionSpec, readMotionSpec, type MotionSpec } from "../utils/motionSpec.js";
|
||
import {
|
||
AUDIT_SEEK_OPTIONS,
|
||
installPageFunctionGuard,
|
||
seekCompositionTimeline,
|
||
waitForCompositionFonts,
|
||
type SeekCompositionTimelineOptions,
|
||
} from "../capture/captureCompositionFrame.js";
|
||
|
||
const __filename = fileURLToPath(import.meta.url);
|
||
const __dirname = dirname(__filename);
|
||
const LAYOUT_SEEK_OPTIONS: SeekCompositionTimelineOptions = AUDIT_SEEK_OPTIONS;
|
||
// All new envelope fields are optional (?); additive changes don't bump this.
|
||
const INSPECT_SCHEMA_VERSION = 1;
|
||
// Motion verification (#1437): dense sampling grid for the seeked-timeline checks.
|
||
const MOTION_FPS = 20;
|
||
const MOTION_MAX_SAMPLES = 300;
|
||
|
||
export const examples: Example[] = [
|
||
["Inspect visual layout across the current composition", "hyperframes layout"],
|
||
["Inspect a specific project", "hyperframes layout ./my-video"],
|
||
["Output agent-readable JSON", "hyperframes layout --json"],
|
||
["Use explicit hero-frame timestamps", "hyperframes layout --at 1.5,4.0,7.25"],
|
||
[
|
||
"Also sample at tween boundaries to catch transient overlaps",
|
||
"hyperframes layout --at-transitions",
|
||
],
|
||
[
|
||
"Verify motion intent (add a *.motion.json sidecar next to the composition)",
|
||
"hyperframes layout --json",
|
||
],
|
||
];
|
||
|
||
interface LayoutAuditResult {
|
||
duration: number;
|
||
samples: number[];
|
||
transitionSamples: number[];
|
||
transitionSamplesDropped: number;
|
||
rawIssues: LayoutIssue[];
|
||
motionSamples: number;
|
||
}
|
||
|
||
function buildMotionSampleTimes(duration: number): number[] {
|
||
if (!Number.isFinite(duration) || duration <= 0) return [];
|
||
const count = Math.min(MOTION_MAX_SAMPLES, Math.max(2, Math.ceil(duration * MOTION_FPS) + 1));
|
||
const step = duration / (count - 1);
|
||
return Array.from({ length: count }, (_, index) => Math.round(index * step * 1000) / 1000);
|
||
}
|
||
|
||
async function getCompositionDuration(page: import("puppeteer-core").Page): Promise<number> {
|
||
// Serialized into the page; the duration-source cascade cannot be split.
|
||
// fallow-ignore-next-line complexity
|
||
return page.evaluate(() => {
|
||
const win = window as unknown as {
|
||
__hf?: { duration?: number };
|
||
__player?: { duration?: number | (() => number) };
|
||
__timelines?: Record<string, { duration?: number | (() => number) }>;
|
||
};
|
||
if (typeof win.__hf?.duration === "number" && win.__hf.duration > 0) return win.__hf.duration;
|
||
const playerDuration = win.__player?.duration;
|
||
if (typeof playerDuration === "function") return playerDuration();
|
||
if (typeof playerDuration === "number" && playerDuration > 0) return playerDuration;
|
||
|
||
const root = document.querySelector("[data-composition-id][data-duration]");
|
||
const attrDuration = root ? parseFloat(root.getAttribute("data-duration") ?? "0") : 0;
|
||
if (attrDuration > 0) return attrDuration;
|
||
|
||
const timelines = win.__timelines;
|
||
if (timelines) {
|
||
for (const timeline of Object.values(timelines)) {
|
||
const duration = timeline.duration;
|
||
if (typeof duration === "function") return duration();
|
||
if (typeof duration === "number" && duration > 0) return duration;
|
||
}
|
||
}
|
||
|
||
return 0;
|
||
});
|
||
}
|
||
|
||
/**
|
||
* Collect every tween start/end boundary from the registered timelines,
|
||
* expressed in the registered timeline's own time (what seekTo consumes).
|
||
* GSAP-only: timelines without getChildren (Anime/Lottie/Three adapters) are
|
||
* skipped. Nested tween times are converted by climbing the parent chain,
|
||
* accounting for each ancestor's startTime and timeScale.
|
||
*/
|
||
async function collectTweenBoundaries(page: import("puppeteer-core").Page): Promise<number[]> {
|
||
return page.evaluate(() => {
|
||
type AnimLike = {
|
||
startTime?: () => number;
|
||
duration?: () => number;
|
||
timeScale?: () => number;
|
||
parent?: AnimLike | null;
|
||
getChildren?: (nested: boolean, tweens: boolean, timelines: boolean) => AnimLike[];
|
||
};
|
||
|
||
// GSAP getters read internal state through `this`, so the method must be
|
||
// invoked bound to its animation (an unbound call throws inside GSAP).
|
||
const callOr = (fn: (() => number) | undefined, self: AnimLike, fallback: number): number =>
|
||
typeof fn === "function" ? fn.call(self) : fallback;
|
||
|
||
const toTimelineTime = (root: AnimLike, anim: AnimLike, localTime: number): number => {
|
||
let time = localTime;
|
||
let node: AnimLike | null | undefined = anim;
|
||
while (node && node !== root) {
|
||
time = callOr(node.startTime, node, 0) + time / (callOr(node.timeScale, node, 1) || 1);
|
||
node = node.parent;
|
||
}
|
||
return time;
|
||
};
|
||
|
||
const tweenBoundaries = (root: AnimLike, tween: AnimLike): number[] => {
|
||
if (typeof tween.duration !== "function") return [];
|
||
const start = toTimelineTime(root, tween, 0);
|
||
const end = toTimelineTime(root, tween, tween.duration());
|
||
return [start, end].filter((time) => Number.isFinite(time));
|
||
};
|
||
|
||
const timelineBoundaries = (timeline: AnimLike): number[] => {
|
||
try {
|
||
const tweens = timeline.getChildren?.(true, true, false) ?? [];
|
||
return tweens.flatMap((tween) => tweenBoundaries(timeline, tween));
|
||
} catch {
|
||
return [];
|
||
}
|
||
};
|
||
|
||
const win = window as unknown as { __timelines?: Record<string, AnimLike> };
|
||
return Object.values(win.__timelines ?? {}).flatMap(timelineBoundaries);
|
||
});
|
||
}
|
||
|
||
async function bundleProjectHtml(projectDir: string): Promise<string> {
|
||
// `bundleToSingleHtml` now inlines the runtime IIFE by default, so the
|
||
// previous post-bundle runtime substitution is no longer needed.
|
||
const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
|
||
return bundleToSingleHtml(projectDir);
|
||
}
|
||
|
||
async function alignViewportToComposition(
|
||
page: import("puppeteer-core").Page,
|
||
url: string,
|
||
): Promise<void> {
|
||
const size = await page.evaluate(() => {
|
||
const root = document.querySelector("[data-composition-id][data-width][data-height]");
|
||
const width = root ? parseInt(root.getAttribute("data-width") ?? "", 10) : 0;
|
||
const height = root ? parseInt(root.getAttribute("data-height") ?? "", 10) : 0;
|
||
return {
|
||
width: Number.isFinite(width) && width > 0 ? Math.min(width, 4096) : 1920,
|
||
height: Number.isFinite(height) && height > 0 ? Math.min(height, 4096) : 1080,
|
||
};
|
||
});
|
||
|
||
await page.setViewport(size);
|
||
await page.goto(url, {
|
||
waitUntil: "domcontentloaded",
|
||
timeout: resolveDiagnosticNavigationTimeoutMs(),
|
||
});
|
||
}
|
||
|
||
async function runLayoutAudit(
|
||
projectDir: string,
|
||
opts: {
|
||
samples: number;
|
||
at?: number[];
|
||
atTransitions: boolean;
|
||
maxTransitionSamples?: number;
|
||
timeout: number;
|
||
tolerance: number;
|
||
motion?: MotionSpec;
|
||
},
|
||
): Promise<LayoutAuditResult> {
|
||
const { ensureBrowser } = await import("../browser/manager.js");
|
||
const puppeteer = await import("puppeteer-core");
|
||
const { buildChromeArgs } = await import("@hyperframes/engine");
|
||
const {
|
||
assertWebGpuAdapterAvailable,
|
||
compositionRequiresWebGpu,
|
||
resolveCaptureBrowserGpuMode,
|
||
resolveLocalBrowserGpuMode,
|
||
} = await import("../browser/gpuPolicy.js");
|
||
const html = await bundleProjectHtml(projectDir);
|
||
const server = await serveStaticProjectHtml(
|
||
projectDir,
|
||
html,
|
||
"Failed to bind local layout audit server",
|
||
);
|
||
let chromeBrowser: import("puppeteer-core").Browser | undefined;
|
||
|
||
try {
|
||
const browser = await ensureBrowser();
|
||
const requestedGpuMode = resolveLocalBrowserGpuMode();
|
||
const resolvedGpuMode = await resolveCaptureBrowserGpuMode(
|
||
requestedGpuMode,
|
||
browser.executablePath,
|
||
);
|
||
const requiresWebGpu = compositionRequiresWebGpu(html);
|
||
chromeBrowser = await puppeteer.default.launch({
|
||
headless: true,
|
||
executablePath: browser.executablePath,
|
||
args: buildChromeArgs(
|
||
{ width: 1920, height: 1080, captureMode: "screenshot", requiresWebGpu },
|
||
{ browserGpuMode: resolvedGpuMode },
|
||
),
|
||
});
|
||
|
||
const page = await chromeBrowser.newPage();
|
||
await installPageFunctionGuard(page);
|
||
await page.setViewport({ width: 1920, height: 1080 });
|
||
await page.goto(server.url, {
|
||
waitUntil: "domcontentloaded",
|
||
timeout: resolveDiagnosticNavigationTimeoutMs(),
|
||
});
|
||
await assertWebGpuAdapterAvailable(page, requiresWebGpu);
|
||
await alignViewportToComposition(page, server.url);
|
||
await page
|
||
.waitForFunction(() => !!(window as unknown as { __timelines?: unknown }).__timelines, {
|
||
timeout: opts.timeout,
|
||
})
|
||
.catch(() => {});
|
||
await waitForCompositionFonts(page, 750);
|
||
await new Promise((resolveSettle) => setTimeout(resolveSettle, 250));
|
||
|
||
const duration = await getCompositionDuration(page);
|
||
const baseSamples = buildLayoutSampleTimes({ duration, samples: opts.samples, at: opts.at });
|
||
let transitionSamples: number[] = [];
|
||
let transitionSamplesDropped = 0;
|
||
if (opts.atTransitions) {
|
||
const boundaries = await collectTweenBoundaries(page);
|
||
const transitions = buildTransitionSampleTimes({
|
||
duration,
|
||
boundaries,
|
||
cap: opts.maxTransitionSamples,
|
||
});
|
||
transitionSamples = transitions.times;
|
||
transitionSamplesDropped = transitions.dropped;
|
||
}
|
||
const samples = mergeSampleTimes(baseSamples, transitionSamples);
|
||
|
||
const issues = await collectLayoutIssues(page, samples, opts.tolerance);
|
||
|
||
let motionSamples = 0;
|
||
if (opts.motion) {
|
||
const motion = await runMotionPass(page, opts.motion, duration);
|
||
issues.push(...motion.issues);
|
||
motionSamples = motion.sampleCount;
|
||
}
|
||
|
||
return {
|
||
duration,
|
||
samples,
|
||
transitionSamples,
|
||
transitionSamplesDropped,
|
||
rawIssues: dedupeLayoutIssues(issues),
|
||
motionSamples,
|
||
};
|
||
} finally {
|
||
await chromeBrowser?.close().catch(() => {});
|
||
await server.close();
|
||
}
|
||
}
|
||
|
||
export function loadBrowserScript(name: string): string {
|
||
const candidates = [join(__dirname, name), join(__dirname, "commands", name)];
|
||
for (const candidate of candidates) {
|
||
if (existsSync(candidate)) return readFileSync(candidate, "utf-8");
|
||
}
|
||
throw new Error(`Missing browser script ${name}`);
|
||
}
|
||
|
||
function loadLayoutAuditScript(): string {
|
||
return loadBrowserScript("layout-audit.browser.js");
|
||
}
|
||
|
||
async function collectLayoutIssues(
|
||
page: import("puppeteer-core").Page,
|
||
samples: number[],
|
||
tolerance: number,
|
||
): Promise<LayoutIssue[]> {
|
||
if (samples.length === 0) return [];
|
||
await page.addScriptTag({ content: loadLayoutAuditScript() });
|
||
|
||
const issues: LayoutIssue[] = [];
|
||
for (const time of samples) {
|
||
await seekCompositionTimeline(page, time, LAYOUT_SEEK_OPTIONS);
|
||
const sampleIssues = await page.evaluate(
|
||
(auditOptions: { time: number; tolerance: number }) => {
|
||
const win = window as unknown as {
|
||
__hyperframesLayoutAudit?: (options: { time: number; tolerance: number }) => unknown[];
|
||
};
|
||
return win.__hyperframesLayoutAudit?.(auditOptions) ?? [];
|
||
},
|
||
{ time, tolerance },
|
||
);
|
||
issues.push(...(sampleIssues as LayoutIssue[]));
|
||
}
|
||
return issues;
|
||
}
|
||
|
||
/** Reject selectors matching multiple elements — first-match-only sampling silently passes for siblings. */
|
||
async function findAmbiguousSelectors(
|
||
page: import("puppeteer-core").Page,
|
||
selectors: string[],
|
||
): Promise<LayoutIssue[]> {
|
||
if (selectors.length === 0) return [];
|
||
const multiMatch = await page.evaluate(
|
||
(sels: string[]) =>
|
||
sels.filter((sel) => {
|
||
try {
|
||
return document.querySelectorAll(sel).length > 1;
|
||
} catch {
|
||
return false;
|
||
}
|
||
}),
|
||
selectors,
|
||
);
|
||
return multiMatch.map(ambiguousIssue);
|
||
}
|
||
|
||
async function collectMotionFrames(
|
||
page: import("puppeteer-core").Page,
|
||
times: number[],
|
||
selectors: string[],
|
||
livenessScopes: string[],
|
||
): Promise<MotionFrame[]> {
|
||
const frames: MotionFrame[] = [];
|
||
for (const time of times) {
|
||
await seekCompositionTimeline(page, time, LAYOUT_SEEK_OPTIONS);
|
||
const sample = await page.evaluate(
|
||
(options: { selectors: string[]; livenessScopes: string[] }) => {
|
||
const win = window as unknown as {
|
||
__hyperframesMotionSample?: (o: { selectors: string[]; livenessScopes: string[] }) => {
|
||
data: MotionFrame["data"];
|
||
liveness: Record<string, string>;
|
||
};
|
||
};
|
||
return win.__hyperframesMotionSample?.(options) ?? { data: {}, liveness: {} };
|
||
},
|
||
{ selectors, livenessScopes },
|
||
);
|
||
frames.push({ time, data: sample.data, liveness: sample.liveness });
|
||
}
|
||
return frames;
|
||
}
|
||
|
||
/**
|
||
* Motion verification (#1437): sample the asserted selectors on a dense grid
|
||
* against the same seeked timeline the renderer uses, then evaluate the spec's
|
||
* assertions in Node. Reuses the live page from the layout audit — no extra
|
||
* Chrome launch. Findings reuse the LayoutIssue shape.
|
||
*/
|
||
async function runMotionPass(
|
||
page: import("puppeteer-core").Page,
|
||
spec: MotionSpec,
|
||
duration: number,
|
||
): Promise<{ issues: LayoutIssue[]; sampleCount: number }> {
|
||
const times = buildMotionSampleTimes(spec.duration ?? duration);
|
||
if (times.length === 0) return { issues: [], sampleCount: 0 };
|
||
|
||
const { selectors, livenessScopes } = collectSamplingTargets(spec.assertions);
|
||
const ambiguous = await findAmbiguousSelectors(page, selectors);
|
||
if (ambiguous.length > 0) return { issues: ambiguous, sampleCount: 0 };
|
||
|
||
const canvas = await page.evaluate(() => ({
|
||
width: window.innerWidth,
|
||
height: window.innerHeight,
|
||
}));
|
||
await page.addScriptTag({ content: loadBrowserScript("motion-sample.browser.js") });
|
||
const frames = await collectMotionFrames(page, times, selectors, livenessScopes);
|
||
return { issues: evaluateMotion(frames, spec.assertions, canvas), sampleCount: frames.length };
|
||
}
|
||
|
||
/** Read + validate the motion sidecar; print the error and exit on a bad spec. */
|
||
function resolveMotionSpec(specPath: string, json: boolean): MotionSpec {
|
||
const parsed = readMotionSpec(specPath);
|
||
if (parsed.ok) return parsed.spec;
|
||
|
||
const message = `Invalid motion spec ${specPath}: ${parsed.errors.join("; ")}`;
|
||
if (json) {
|
||
console.log(
|
||
JSON.stringify(
|
||
withMeta(
|
||
{
|
||
schemaVersion: INSPECT_SCHEMA_VERSION,
|
||
ok: false,
|
||
error: message,
|
||
issues: [],
|
||
errorCount: 0,
|
||
warningCount: 0,
|
||
infoCount: 0,
|
||
issueCount: 0,
|
||
},
|
||
{ deprecated: true },
|
||
),
|
||
null,
|
||
2,
|
||
),
|
||
);
|
||
} else {
|
||
console.error(`${c.error("✗")} ${message}`);
|
||
}
|
||
failCommand();
|
||
}
|
||
|
||
export function parseAt(value: unknown): number[] | undefined {
|
||
if (!value) return undefined;
|
||
const times = String(value)
|
||
.split(",")
|
||
.map((entry) => parseFloat(entry.trim()))
|
||
.filter((time) => Number.isFinite(time) && time >= 0);
|
||
return times.length > 0 ? times : undefined;
|
||
}
|
||
|
||
export function createInspectCommand(commandName: "inspect" | "layout") {
|
||
return defineCommand({
|
||
meta: {
|
||
name: commandName,
|
||
description:
|
||
"Inspect rendered composition layout for text/container overflow, plus optional motion verification via a *.motion.json sidecar (deprecated, use check)",
|
||
},
|
||
args: {
|
||
dir: { type: "positional", description: "Project directory", required: false },
|
||
json: { type: "boolean", description: "Output agent-readable JSON", default: false },
|
||
samples: {
|
||
type: "string",
|
||
description: "Number of midpoint samples across the duration (default: 9)",
|
||
default: "9",
|
||
},
|
||
at: {
|
||
type: "string",
|
||
description: "Comma-separated timestamps in seconds (e.g., --at 1.5,4,7.25)",
|
||
},
|
||
"at-transitions": {
|
||
type: "boolean",
|
||
description:
|
||
"Also sample at every tween start/end boundary (plus segment midpoints) to catch transient overlaps at transition seams",
|
||
default: false,
|
||
},
|
||
"max-transition-samples": {
|
||
type: "string",
|
||
description:
|
||
"Optional cap on transition-derived samples; when it truncates, the omitted count is reported (default: unlimited)",
|
||
},
|
||
tolerance: {
|
||
type: "string",
|
||
description: "Allowed pixel overflow before reporting an issue (default: 2)",
|
||
default: "2",
|
||
},
|
||
timeout: {
|
||
type: "string",
|
||
description: "Ms to wait for runtime to initialize (default: 5000)",
|
||
default: "5000",
|
||
},
|
||
"max-issues": {
|
||
type: "string",
|
||
description: "Maximum issues to print or return after static collapse (default: 80)",
|
||
default: "80",
|
||
},
|
||
"collapse-static": {
|
||
type: "boolean",
|
||
description: "Collapse repeated static issues across samples (default: true)",
|
||
default: true,
|
||
},
|
||
strict: {
|
||
type: "boolean",
|
||
description: "Exit non-zero on warnings too",
|
||
default: false,
|
||
},
|
||
},
|
||
// Pre-existing command-run branching; U1 only swapped the seek internals.
|
||
// fallow-ignore-next-line complexity
|
||
async run({ args }) {
|
||
printDeprecationNotice(commandName);
|
||
const project = resolveProject(args.dir);
|
||
const samples = Math.max(1, parseInt(args.samples as string, 10) || 9);
|
||
const tolerance = Math.max(0, parseFloat(args.tolerance as string) || 2);
|
||
const timeout = Math.max(500, parseInt(args.timeout as string, 10) || 5000);
|
||
const maxIssues = Math.max(1, parseInt(args["max-issues"] as string, 10) || 80);
|
||
const at = parseAt(args.at);
|
||
const atTransitions = !!args["at-transitions"];
|
||
const maxTransitionSamplesRaw = parseInt(args["max-transition-samples"] as string, 10);
|
||
const maxTransitionSamples =
|
||
Number.isFinite(maxTransitionSamplesRaw) && maxTransitionSamplesRaw > 0
|
||
? maxTransitionSamplesRaw
|
||
: undefined;
|
||
const strict = !!args.strict;
|
||
const collapseStatic = args["collapse-static"] !== false;
|
||
|
||
// Motion verification (#1437): an optional `*.motion.json` sidecar opts the
|
||
// composition into seeked-timeline assertion checks. Absent → layout-only.
|
||
const motionSpecPath = findMotionSpec(project.dir);
|
||
const motionSpec = motionSpecPath
|
||
? resolveMotionSpec(motionSpecPath, !!args.json)
|
||
: undefined;
|
||
|
||
if (!args.json) {
|
||
const baseLabel = at ? `${at.length} explicit timestamp(s)` : `${samples} timeline samples`;
|
||
const sampleLabel = atTransitions ? `${baseLabel} + transition boundaries` : baseLabel;
|
||
const motionLabel = motionSpec
|
||
? ` + motion spec (${motionSpec.assertions.length} assertion(s))`
|
||
: "";
|
||
console.log(
|
||
`${c.accent("◆")} Inspecting layout for ${c.accent(project.name)} (${sampleLabel}${motionLabel})`,
|
||
);
|
||
}
|
||
|
||
try {
|
||
const result = await runLayoutAudit(project.dir, {
|
||
samples,
|
||
at,
|
||
atTransitions,
|
||
maxTransitionSamples,
|
||
timeout,
|
||
tolerance,
|
||
motion: motionSpec,
|
||
});
|
||
if (!args.json && result.transitionSamplesDropped > 0) {
|
||
console.log(
|
||
`${c.warn("⚠")} ${result.transitionSamplesDropped} transition sample(s) omitted by --max-transition-samples; raise or drop it to sample every boundary`,
|
||
);
|
||
}
|
||
const allIssues = collapseStatic
|
||
? collapseStaticLayoutIssues(result.rawIssues, result.samples.length)
|
||
: result.rawIssues;
|
||
const limited = limitLayoutIssues(allIssues, maxIssues);
|
||
const summary = summarizeLayoutIssues(allIssues);
|
||
const ok = summary.errorCount === 0 && (!strict || summary.warningCount === 0);
|
||
|
||
if (args.json) {
|
||
console.log(
|
||
JSON.stringify(
|
||
withMeta(
|
||
{
|
||
schemaVersion: INSPECT_SCHEMA_VERSION,
|
||
duration: result.duration,
|
||
samples: result.samples,
|
||
transitionSamples: atTransitions ? result.transitionSamples : undefined,
|
||
transitionSamplesDropped: atTransitions
|
||
? result.transitionSamplesDropped
|
||
: undefined,
|
||
tolerance,
|
||
strict,
|
||
collapseStatic,
|
||
motionSpec: motionSpec ? motionSpecPath : undefined,
|
||
motionSamples: motionSpec ? result.motionSamples : undefined,
|
||
...summary,
|
||
totalIssueCount: limited.totalIssueCount,
|
||
truncated: limited.truncated,
|
||
ok,
|
||
issues: limited.issues,
|
||
},
|
||
{ deprecated: true },
|
||
),
|
||
null,
|
||
2,
|
||
),
|
||
);
|
||
setCommandExitCode(ok ? 0 : 1);
|
||
return;
|
||
}
|
||
|
||
if (result.samples.length === 0) {
|
||
console.log();
|
||
console.log(
|
||
`${c.error("✗")} Could not determine composition duration — no layout samples run`,
|
||
);
|
||
failCommand();
|
||
}
|
||
|
||
console.log();
|
||
if (limited.issues.length === 0) {
|
||
console.log(
|
||
`${c.success("◇")} 0 layout issues across ${result.samples.length} sample(s)`,
|
||
);
|
||
return;
|
||
}
|
||
|
||
for (const issue of limited.issues) {
|
||
const icon =
|
||
issue.severity === "error"
|
||
? c.error("✗")
|
||
: issue.severity === "warning"
|
||
? c.warn("⚠")
|
||
: c.dim("ℹ");
|
||
const formatted = formatLayoutIssue(issue).replace(/\n/g, "\n ");
|
||
console.log(` ${icon} ${c.dim(formatted)}`);
|
||
}
|
||
|
||
console.log();
|
||
const parts = [
|
||
`${summary.errorCount} error(s)`,
|
||
`${summary.warningCount} warning(s)`,
|
||
`${summary.infoCount} info(s)`,
|
||
];
|
||
const suffix = limited.truncated ? c.dim(`, truncated at ${maxIssues} issue(s)`) : "";
|
||
console.log(`${ok ? c.success("◇") : c.error("◇")} ${parts.join(", ")}${suffix}`);
|
||
|
||
setCommandExitCode(ok ? 0 : 1);
|
||
return;
|
||
} catch (err) {
|
||
const message = normalizeErrorMessage(err);
|
||
if (args.json) {
|
||
console.log(
|
||
JSON.stringify(
|
||
withMeta(
|
||
{
|
||
schemaVersion: INSPECT_SCHEMA_VERSION,
|
||
ok: false,
|
||
error: message,
|
||
issues: [],
|
||
errorCount: 0,
|
||
warningCount: 0,
|
||
infoCount: 0,
|
||
issueCount: 0,
|
||
},
|
||
{ deprecated: true },
|
||
),
|
||
null,
|
||
2,
|
||
),
|
||
);
|
||
failCommand();
|
||
}
|
||
console.error(`${c.error("✗")} Inspect failed: ${message}`);
|
||
failCommand();
|
||
}
|
||
},
|
||
});
|
||
}
|
||
|
||
export default createInspectCommand("layout");
|