Files
hyperframes/packages/cli/src/utils/bundleWithLocalizedFonts.ts
T
Xuanru Li a39f7b37d9 feat(cli): check-review inspect attaches the inspector's report to each framed finding (#6409)
* feat(cli): skipContrastInMotion moves to HF_TOOL_CONTEXT check-review

The --skip-contrast-in-motion flag and HYPERFRAMES_CHECK_SKIP_CONTRAST_IN_MOTION
env give way to a check-review capability in HF_TOOL_CONTEXT, so only a harness
turns it on. The skill text and manifest go back to main.

* feat(cli): check-review findingFrames saves one plain frame per finding time

With HF_TOOL_CONTEXT check-review.findingFrames, every error/warning finding in
layout or contrast with a real bbox gets frameTime (the middle sample of its
longest held run, by the heldMs gap rule) and frame (the absolute path of an
unannotated full frame shared by every finding at that time). One seek and
screenshot per distinct time, capped at 60 times with errors first, into the
run's snapshot folder; not listed in snapshots, history or events. Without the
capability, output is unchanged.

* docs(cli): finding-frame comments name the check-review capability, not a flag

* fix(cli): validate finding frame times and preserve cancellation

* fix(cli): count finding frame progress toward the check deadline

* feat(cli): check-review inspect attaches the inspector's report to each framed finding

With findingFrames on, the finding-frames page is served with the
inspector's GSAP hooks. After each frame is captured, every finding framed
at that time is inspected by its data-hf-id, else its selector, and the
inspector's own report is attached as the finding's inspect field. A failed
inspection becomes that finding's { error } and never fails the check.
Without the capability nothing changes.

Drops the unused @types/mime-types devDependency that the dependency audit
flags once packages/cli/package.json is touched.

* fix(cli): stop finding inspections after cancellation

* fix(cli): reject ambiguous finding inspection targets

* fix(ci): build inspector before Windows CLI smoke

* fix(cli): parse viewport HTML with explicit server parser
2026-10-26 10:02:49 +00:00

96 lines
4.1 KiB
TypeScript

import type { BundleOptions } from "@hyperframes/core/compiler";
import { normalizeErrorMessage } from "./errorMessage.js";
import { c } from "../ui/colors.js";
/**
* Bundle a project to a single HTML string AND localize its fonts — fetch and
* embed `@font-face` rules for every requested family (including families
* declared only via a remote `<link>`, e.g. Google Fonts) as data URIs.
*
* Why the audit/snapshot paths need this: core's `bundleToSingleHtml` inlines
* only LOCAL stylesheets and leaves remote font `<link>`s as-is, so a snapshot
* depends on loading the remote font at capture time. The render pipeline
* instead localizes fonts in its compile stage, which is why a render embeds
* (say) League Gothic correctly while a snapshot of the same composition can
* fall back to an un-styled system sans when the remote font loses the race
* against the capture. Running the SAME localization the render path uses makes
* snapshot/check captures font-faithful and deterministic — no network race.
*/
export async function bundleWithLocalizedFonts(
projectDir: string,
// Injectable for tests. Production callers omit it and get the producer
// font-localization pass (see localizeWithProducer).
localizeFonts: (html: string) => Promise<string> = localizeWithProducer,
bundleOptions?: BundleOptions,
): Promise<string> {
const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
const html = await bundleToSingleHtml(projectDir, bundleOptions);
return localizeFonts(html);
}
type FontInjector = (html: string) => Promise<string>;
/**
* Load the render pipeline's `injectDeterministicFontFaces` through the CLI's
* canonical producer loader. That loader uses a literal dynamic import, which
* lets tsup see and inline producer into the published CLI bundle. A variable
* bare-package import is invisible to tsup and silently fails after `npm
* install`, because producer is intentionally only a workspace devDependency.
*
* Returns `null` (not a throw) when the module simply isn't available in this
* environment, so the caller can treat "producer absent" — a benign, expected
* condition — differently from "the injector itself failed".
*/
async function loadFontInjector(): Promise<FontInjector | null> {
try {
const { loadProducer } = await import("./producer.js");
const mod = (await loadProducer()) as {
injectDeterministicFontFaces?: FontInjector;
};
return mod.injectDeterministicFontFaces ?? null;
} catch {
return null;
}
}
const warnedFontLocalizationFailures = new Set<string>();
/** Reset the dedup latch — tests only. */
export function __resetFontLocalizationWarningsForTests(): void {
warnedFontLocalizationFailures.clear();
}
/**
* Localize fonts via the producer injector, distinguishing two failure modes:
*
* - **Module unavailable** (`loadInjector` yields `null`): benign — producer
* isn't in this environment. Return the HTML unchanged, silently; fonts
* declared via a remote `<link>` still load at capture time as before.
* - **Injector threw** (a fetch layer failed, a family errored past the
* injector's own per-family handling): unexpected — surface it ONCE per
* distinct message (snapshot/check re-bundle per grid point, so an
* un-deduped warning would spam), then fail open to the plain bundle.
*
* Per-family resolution failures inside a successful pass are already reported
* by the injector itself (producer's `warnUnresolvedFonts`); this layer only
* owns the module-vs-execution distinction and the dedup.
*/
export async function localizeWithProducer(
html: string,
loadInjector: () => Promise<FontInjector | null> = loadFontInjector,
warn: (message: string) => void = (m) => console.warn(` ${c.warn("⚠")} ${m}`),
): Promise<string> {
const inject = await loadInjector();
if (!inject) return html;
try {
return await inject(html);
} catch (err) {
const message = `Font localization failed; capturing with remote/fallback fonts instead: ${normalizeErrorMessage(err)}`;
if (!warnedFontLocalizationFailures.has(message)) {
warnedFontLocalizationFailures.add(message);
warn(message);
}
return html;
}
}