Skip to content

Commit 30ca51c

Browse files
committed
feat(engine): warn when a live map viewport is detected at capture init
1 parent 835fa89 commit 30ca51c

3 files changed

Lines changed: 75 additions & 1 deletion

File tree

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import { describe, expect, it } from "vitest";
2+
import { buildLiveMapWarning } from "./frameCapture.js";
3+
4+
describe("buildLiveMapWarning", () => {
5+
it("names every detected map library in the message and details", () => {
6+
const warning = buildLiveMapWarning(["Leaflet", "MapLibre GL"]);
7+
expect(warning.code).toBe("live_map_detected");
8+
expect(warning.message).toContain("Leaflet, MapLibre GL");
9+
expect(warning.details?.sources).toEqual(["Leaflet", "MapLibre GL"]);
10+
});
11+
12+
it("points the author at the bake pipeline instead of just describing the failure", () => {
13+
const warning = buildLiveMapWarning(["Leaflet"]);
14+
expect(warning.message).toContain("bake-basemap.mjs");
15+
expect(warning.message).toContain("deterministic-render");
16+
});
17+
18+
it("copies the libraries array so later mutation cannot alter the recorded warning", () => {
19+
const libraries = ["Leaflet"];
20+
const warning = buildLiveMapWarning(libraries);
21+
libraries.push("Mapbox GL");
22+
expect(warning.details?.sources).toEqual(["Leaflet"]);
23+
});
24+
});

‎packages/engine/src/services/frameCapture.ts‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1716,6 +1716,53 @@ function recordSubTimelineWarning(session: CaptureSession, timeoutMs: number): v
17161716
]);
17171717
}
17181718

1719+
/**
1720+
* Runtime-mounted map-viewport markers, keyed by the CSS selector each map
1721+
* library stamps on its live container. Selector presence means an actual map
1722+
* INSTANCE is rendering in the page — not merely that a map library script
1723+
* loaded — which keeps false positives low (a baked map video carries none of
1724+
* these).
1725+
*/
1726+
const LIVE_MAP_MARKERS: ReadonlyArray<{ selector: string; library: string }> = [
1727+
{ selector: ".leaflet-container", library: "Leaflet" },
1728+
{ selector: ".maplibregl-map", library: "MapLibre GL" },
1729+
{ selector: ".mapboxgl-map", library: "Mapbox GL" },
1730+
{ selector: ".gm-style", library: "Google Maps" },
1731+
{ selector: ".ol-viewport", library: "OpenLayers" },
1732+
];
1733+
1734+
/**
1735+
* Build the `live_map_detected` warning for the detected map libraries.
1736+
* A live tile map violates the deterministic-render contract (tiles are
1737+
* render-time network fetches): none of the readiness polls cover late-added
1738+
* tile images or map canvases, so frames captured before tiles arrive ship a
1739+
* blank/partial map with no error — the render exits success. Wild signature:
1740+
* PRINFRA-300 (blank hook scene, zero diagnostics, "fixed" by re-render).
1741+
*/
1742+
export function buildLiveMapWarning(libraries: readonly string[]): CaptureWarning {
1743+
return {
1744+
code: "live_map_detected",
1745+
message:
1746+
`Live map viewport(s) detected in the composition (${libraries.join(", ")}). ` +
1747+
`Map tiles load over the network at render time, which the deterministic-render ` +
1748+
`contract forbids — frames captured before tiles arrive ship a blank or partial map ` +
1749+
`with no error. Bake the map to a video first (see the motion-graphics maps skill / ` +
1750+
`bake-basemap.mjs) and use the baked file as the imagery layer.`,
1751+
details: { sources: [...libraries] },
1752+
};
1753+
}
1754+
1755+
/** Detect live map viewports in the page and record the warning. */
1756+
async function recordLiveMapWarning(session: CaptureSession, page: Page): Promise<void> {
1757+
const libraries = (await page.evaluate(
1758+
(markers: ReadonlyArray<{ selector: string; library: string }>) =>
1759+
markers.filter((m) => document.querySelector(m.selector) !== null).map((m) => m.library),
1760+
LIVE_MAP_MARKERS,
1761+
)) as string[];
1762+
if (libraries.length === 0) return;
1763+
recordCaptureWarnings(session, [buildLiveMapWarning(libraries)]);
1764+
}
1765+
17191766
// Force every successfully-loaded `<img>` to be GPU-uploaded before the first
17201767
// frame capture. `naturalWidth > 0` means the bitmap has been decoded into
17211768
// CPU memory, but compositor-side GPU upload can still happen lazily on first
@@ -2002,6 +2049,7 @@ export async function initializeSession(session: CaptureSession): Promise<void>
20022049
session,
20032050
await collectMediaReadinessWarnings(page, skipVideoIds, pageReadyTimeout),
20042051
);
2052+
await recordLiveMapWarning(session, page);
20052053

20062054
await recordSessionInitTelemetry(session, initStart);
20072055

@@ -2164,6 +2212,7 @@ export async function initializeSession(session: CaptureSession): Promise<void>
21642212
session,
21652213
await collectMediaReadinessWarnings(page, bfSkipVideoIds, pageReadyTimeout),
21662214
);
2215+
await recordLiveMapWarning(session, page);
21672216

21682217
await recordSessionInitTelemetry(session, initStart);
21692218

‎packages/engine/src/types.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@ export type CaptureWarningCode =
1818
| "media_load_failed"
1919
| "audio_processing_failed"
2020
| "sub_timeline_readiness_timeout"
21-
| "sub_timeline_script_failure";
21+
| "sub_timeline_script_failure"
22+
| "live_map_detected";
2223

2324
/** Structured correctness warning produced while preparing a capture session. */
2425
export interface CaptureWarning {

0 commit comments

Comments
 (0)